docs: structural improvements to key-concepts.md

main/guides/orchestration/getting-started/key-concepts.md

@@ -1,28 +1,26 @@
 # Orchestration Key Concepts
 
-Here, we overview the fundamental concepts involved with building orchestration smart contracts.
+This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Interchain Accounts (ICA), ChainHub, and Orchestration Accounts.
 
-### Interchain Account (ICA)
+---
 
-[Interchain Accounts](/glossary/#interchain-account-ica) (ICAs) are an IBC feature used in Agoric’s Orchestration API. They enable an Agoric smart contract to control an account on another blockchain within the Cosmos ecosystem, facilitated by Agoric [Orchestration](/glossary/#orchestration) API. This feature leverages the [Inter-Blockchain Communication (IBC)](/glossary/#ibc) protocol to facilitate interactions and transactions across different blockchains seamlessly.
+## Interchain Account (ICA)
 
-<br/>
-<img src="../assets/icaoverview.png" width="100%" />
-<br/>
+[Interchain Accounts](/glossary/#interchain-account-ica) (ICAs) are an IBC feature utilized within Agoric’s Orchestration API. They enable an Agoric smart contract to control an account on another blockchain in the Cosmos ecosystem. The [Inter-Blockchain Communication (IBC)](/glossary/#ibc) protocol facilitates seamless interactions and transactions across different blockchains.
 
-Photo credit: [cosmos.network documentation](https://tutorials.cosmos.network/academy/3-ibc/8-ica.html)
+#### Benefits of ICAs
+- **Cross-chain Control**: ICAs allow a contract to manage accounts on other chains, treating them like any other (remotable) object.
+- **Access Control**: Only the contract that creates the ICA has full control over it but can delegate specific access permissions to clients.
 
-A key advantage of ICAs is that they make accounts on other chains look like any other (remotable) object. When a contract creates an ICA, it has sole access to and control over the account but can delegate certain forms of access to its clients.
+For more details on access control, refer to [Access Control with Objects](/guides/zoe/contract-access-control).
 
-For a detailed explanation of these access control rules, see [Access Control with Objects](/guides/zoe/contract-access-control).
 
-### Example ICA Usage from a Smart Contract
+### Example: ICA Usage in a Smart Contract
 
-This sample is taken from one of the [example contracts](https://github.com/Agoric/agoric-sdk/blob/master/packages/orchestration/src/examples/swapExample.contract.js)
+Here’s an example of ICA usage from one of the [sample contracts](https://github.com/Agoric/agoric-sdk/blob/master/packages/orchestration/src/examples/swapExample.contract.js):
 
 ```js
 const stakeAndSwapFn = async (orch, ...) => {
-// ...
   const omni = await orch.getChain('omniflixhub');
   const agoric = await orch.getChain('agoric');
 
@@ -33,8 +31,7 @@ const stakeAndSwapFn = async (orch, ...) => {
 
   const omniAddress = omniAccount.getAddress();
 
-  // deposit funds from user seat to LocalChainAccount
-// ...
+  // Deposit funds from user seat to LocalChainAccount
   const transferMsg = orcUtils.makeOsmosisSwap({ ... });
 
   try {
@@ -46,7 +43,7 @@ const stakeAndSwapFn = async (orch, ...) => {
 };
 ```
 
-### ChainHub
+## ChainHub
 
 The `makeChainHub` utility manages the connections and metadata for various blockchain networks. It creates a new `ChainHub` instance implementing the [`ChainHubI`](https://github.com/Agoric/agoric-sdk/blob/000693442f821c1fcea007a2df740733b1f75ebe/packages/orchestration/src/exos/chain-hub.js#L70-L80C4) interface.
 
@@ -69,7 +66,7 @@ chainHub.registerConnection(
 
 In this example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and the newly registered chain.
 
-### Orchestration Account
+## Orchestration Account
 
 Orchestration accounts are a key concept in the Agoric Orchestration API, represented by the [`OrchestrationAccountI`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI) interface. These accounts provide high-level operations for managing accounts on remote chains, allowing seamless interaction and management of interchain accounts. The orchestration accounts abstract the complexity of interchain interactions, providing a unified and simplified interface for developers.