From c2cf57880e769e94ce0986ee2ad9b896054e0979 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 10 Sep 2024 16:40:26 +0500 Subject: [PATCH 1/4] docs: structural improvements to key-concepts.md --- .../getting-started/key-concepts.md | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/main/guides/orchestration/getting-started/key-concepts.md b/main/guides/orchestration/getting-started/key-concepts.md index 735e7d060..83ba8c6bd 100644 --- a/main/guides/orchestration/getting-started/key-concepts.md +++ b/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) -
- -
+[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. From 44dd1049db086c49d7af4f394c2465d01a8de706 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 10 Sep 2024 17:27:54 +0500 Subject: [PATCH 2/4] chore: merged key concepts and API in orch --- main/.vitepress/config.mjs | 35 ++++- .../orchestration/getting-started/api.md | 101 ------------ .../getting-started/key-concepts.md | 147 +++++++++++------- 3 files changed, 118 insertions(+), 165 deletions(-) delete mode 100644 main/guides/orchestration/getting-started/api.md diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index 2f6220b27..68cd129e3 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -126,13 +126,9 @@ export default defineConfig({ collapsed: true, items: [ { - text: 'Key Concepts', + text: 'Key Concepts and APIs', link: '/guides/orchestration/getting-started/key-concepts', }, - { - text: 'API', - link: '/guides/orchestration/getting-started/api', - }, { text: 'Contract Walkthroughs', link: '/guides/orchestration/getting-started/contract-walkthroughs', @@ -453,6 +449,35 @@ export default defineConfig({ }, ], }, + { + text: 'Orchestration', + link: '/guides/orchestration/', + collapsed: true, + items: [ + { + text: 'Key Concepts', + link: '/guides/orchestration/getting-started/key-concepts', + }, + { + text: 'Contract Walkthroughs', + link: '/guides/orchestration/getting-started/contract-walkthroughs', + items: [ + { + text: 'Cross-Chain Swap Example', + link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap', + }, + { + text: 'Cross-Chain Unbond Example', + link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond', + }, + { + text: 'Orchestration Basics', + link: '/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics', + } + ] + }, + ] + }, { text: 'JavaScript Framework', ariaLabel: 'JavaScript Framework', diff --git a/main/guides/orchestration/getting-started/api.md b/main/guides/orchestration/getting-started/api.md deleted file mode 100644 index 47ffb1271..000000000 --- a/main/guides/orchestration/getting-started/api.md +++ /dev/null @@ -1,101 +0,0 @@ -# Orchestration API - -The Agoric [Orchestration](/glossary/#orchestration) API enables developers to seamlessly manage and interact with accounts across multiple blockchain networks, simplifying the complexities of cross-chain operations. - -See [Orchestration API Spec](https://agoric-sdk.pages.dev/modules/_agoric_orchestration) - -## Orchestrator Interface - -The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a set of high-level methods to manage and interact with interchain accounts. Below are the primary methods: - -### getChain - -Retrieves the chain information and provides access to chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). - -```js -const chain = await orchestrator.getChain('chainName'); -``` - -### makeLocalAccount - -Creates a new `LocalChainAccount`. See [makeLocalAccount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#makeLocalAccount). - -```js -const localAccount = await orchestrator.makeLocalAccount(); -``` - -### getBrandInfo - -Returns information about a `denom`, including the equivalent local Brand, the chain where the denom is held, and the chain that issues the corresponding asset. See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). - -```js -const brandInfo = orchestrator.getBrandInfo('denom'); -``` - -### asAmount - -Converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount). - -```js -const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }); -``` - -## OrchestrationAccount - -An [`OrchestrationAccount`](https://agoric-sdk.pages.dev/types/_agoric_orchestration.OrchestrationAccount) is a type alias that combines the [`OrchestrationAccountI`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI) interface with additional methods. Below are the primary methods available: - -### getAddress - -Retrieves the address of the account on the remote chain. See [getAddress](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#getAddress). - -```js -const address = await orchestrationAccount.getAddress(); -``` - -### getBalances - -Returns an array of amounts for every balance in the account. See [getBalances](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#getBalances). - -```js -const balances = await orchestrationAccount.getBalances(); -``` - -### getBalance - -Retrieves the balance of a specific denom for the account. See [getBalance](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#getBalance). - -```js -const balance = await orchestrationAccount.getBalance('uatom'); -``` - -### send - -Transfers an amount to another account on the same chain. The promise settles when the transfer is complete. See [send](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#send). - -```js -await orchestrationAccount.send(receiverAddress, amount); -``` - -### transfer - -Transfers an amount to another account, typically on another chain. The promise settles when the transfer is complete. See [transfer](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#transfer). - -```js -await orchestrationAccount.transfer(amount, destinationAddress); -``` - -### transferSteps - -Transfers an amount to another account in multiple steps. The promise settles when the entire path of the transfer is complete. See [transferSteps](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI#transferSteps). - -```js -await orchestrationAccount.transferSteps(amount, transferMsg); -``` - -### deposit - -Deposits payment from Zoe to the account. For remote accounts, an IBC Transfer will be executed to transfer funds there. - -```js -await orchestrationAccount.deposit(payment); -``` diff --git a/main/guides/orchestration/getting-started/key-concepts.md b/main/guides/orchestration/getting-started/key-concepts.md index 83ba8c6bd..64e300433 100644 --- a/main/guides/orchestration/getting-started/key-concepts.md +++ b/main/guides/orchestration/getting-started/key-concepts.md @@ -1,103 +1,132 @@ -# Orchestration Key Concepts +# Orchestration Key Concepts and APIs -This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Interchain Accounts (ICA), ChainHub, and Orchestration Accounts. +This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub. ---- +## Orchestrator Interface -## Interchain Account (ICA) +The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a set of high-level methods to manage and interact with +local and remote chains. Below are the primary methods: -[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. +### Access Chain Object -#### 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. +- `getChain` retrieves a chain object for the given `chainName` to get access to + chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). -For more details on access control, refer to [Access Control with Objects](/guides/zoe/contract-access-control). - - -### Example: ICA Usage in a Smart Contract - -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'); - - const [omniAccount, localAccount] = await Promise.all([ - omni.makeAccount(), - agoric.makeAccount(), - ]); +```javascript +const chain = await orchestrator.getChain('chainName'); +``` - const omniAddress = omniAccount.getAddress(); +### Create an Account - // Deposit funds from user seat to LocalChainAccount - const transferMsg = orcUtils.makeOsmosisSwap({ ... }); +- `makeLocalAccount` creates a new account on local chain. See [makeLocalAccount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#makeLocalAccount). - try { - await localAccount.transferSteps(give.Stable, transferMsg); - await omniAccount.delegate(offerArgs.validator, offerArgs.staked); - } catch (e) { - console.error(e); - } -}; +```javascript +const localAccount = await orchestrator.makeLocalAccount(); ``` -## 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. +### Brand Utility Functions -It simplifies accessing and interacting with multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively. -ChainHub also allows dynamic registration and use of chain and connection information. +- `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, + the chain where the denom is held, and the chain that issues the corresponding asset. + See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). -```js -const chainHub = makeChainHub(remotePowers.agoricNames); +```javascript +const brandInfo = orchestrator.getBrandInfo('denom'); +``` -// Register a new chain with its information -chainHub.registerChain(chainKey, chainInfo); +- `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount). -// Register a connection between the Agoric chain and the new chain -chainHub.registerConnection( - agoricChainInfo.chainId, - chainInfo.chainId, - connectionInfo -); +```javascript +const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }); ``` -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 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. +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. -**1. Address Management** +### Address Management - `getAddress` retrieves the address of the account on the remote chain. -```js +```javascript const address = await orchestrationAccount.getAddress(); ``` -**2. Balance Management** +### Balance Management - `getBalances` returns an array of amounts for every balance in the account. - `getBalance` retrieves the balance of a specific denom for the account. -```js +```javascript const balances = await orchestrationAccount.getBalances(); const balance = await orchestrationAccount.getBalance('uatom'); ``` -**3. Funds Transfer** +### Funds Transfer - `send` transfers an amount to another account on the same chain. - `transfer` transfers an amount to another account, typically on another chain. - `transferSteps` transfers an amount in multiple steps, handling complex transfer paths. +- `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer + will be executed to transfer funds there. -```js +```javascript await orchestrationAccount.send(receiverAddress, amount); await orchestrationAccount.transfer(amount, destinationAddress); await orchestrationAccount.transferSteps(amount, transferMsg); +await orchestrationAccount.deposit(payment); ``` -To see the function the Orchestration API exposes, see [Orchestration API](/guides/orchestration/getting-started/api.html) +## ChainHub + +ChainHub is a centeralized registry of chains, connections, and denoms +that simplifies accessing and interacting with multiple chains, providing +a unified interface for the orchestration logic to manage cross-chain +operations effectively. A chainHub instance can be created using a call +to `makeChainHub` that makes a new ChainHub in the zone (or in the heap +if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. +It has no precious state. Its only state is a cache of queries to +`agoricNames` and the info provided in registration calls. When you +need a newer version you can simply make a hub and repeat the registrations. +ChainHub allows dynamic registration and use of chain and connection +information using the following API. + +### Registration APIs + +- `registerChain` register a new chain with `chainHub`. The name will override + a name in well known chain names. If a durable zone was not provided, + registration will not survive a reincarnation of the vat, and will have to be + registered again. +- `registerConnection` registers a connections between two given chain IDs. +- `registerAsset` registers an asset that may be held on a chain other than + the issuing chain. Both corresponding chains should already be registered + before this call. + +### Information Retrieval + +- `getChainInfo` takes a chain name to get chain info. +- `getConnectionInfo` returns `Vow` for two given chain IDs. +- `getChainsAndConnection` is used to get chain and connection info give primary and counter chain names. +- `getAsset` retrieves holding, issuing chain names etc. for a denom. +- `getDenom` retrieves denom (string) for a `Brand`. + +In the below example, `chainHub` is used to register a new chain and establish a connection +between the Agoric chain and the newly registered chain. + +```javascript +const chainHub = makeChainHub(privateArgs.agoricNames, vowTools); + +// Register a new chain with its information +chainHub.registerChain(chainKey, chainInfo); + +// Register a connection between the Agoric chain and the new chain +chainHub.registerConnection( + agoricChainInfo.chainId, + chainInfo.chainId, + connectionInfo, +); +``` From 50cf12ec9ddbc12be730c643691eb51df3b9cbad Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 24 Sep 2024 09:47:21 +0500 Subject: [PATCH 3/4] chore: update account creation section Co-authored-by: Mujahid Khan <106528609+mujahidkay@users.noreply.github.com> Co-authored-by: Mujahid Khan <106528609+mujahidkay@users.noreply.github.com> Co-authored-by: Mujahid Khan <106528609+mujahidkay@users.noreply.github.com> --- main/.vitepress/config.mjs | 2 +- .../getting-started/key-concepts.md | 113 +++++++++--------- 2 files changed, 57 insertions(+), 58 deletions(-) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index 68cd129e3..8077fa538 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -455,7 +455,7 @@ export default defineConfig({ collapsed: true, items: [ { - text: 'Key Concepts', + text: 'Key Concepts and APIs', link: '/guides/orchestration/getting-started/key-concepts', }, { diff --git a/main/guides/orchestration/getting-started/key-concepts.md b/main/guides/orchestration/getting-started/key-concepts.md index 64e300433..c210a313e 100644 --- a/main/guides/orchestration/getting-started/key-concepts.md +++ b/main/guides/orchestration/getting-started/key-concepts.md @@ -1,59 +1,64 @@ # Orchestration Key Concepts and APIs -This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub. +This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, +focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub. ## Orchestrator Interface -The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a set of high-level methods to manage and interact with -local and remote chains. Below are the primary methods: +The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a +set of high-level methods to manage and interact with local and remote chains. Below are the primary methods: ### Access Chain Object -- `getChain` retrieves a chain object for the given `chainName` to get access to - chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). +- `getChain` retrieves a chain object for the given `chainName` to get access to chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). ```javascript -const chain = await orchestrator.getChain('chainName'); -``` - -### Create an Account - -- `makeLocalAccount` creates a new account on local chain. See [makeLocalAccount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#makeLocalAccount). - -```javascript -const localAccount = await orchestrator.makeLocalAccount(); +const chain = await orchestrator.getChain('chainName') ``` ### Brand Utility Functions -- `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, - the chain where the denom is held, and the chain that issues the corresponding asset. - See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). +- `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, the chain where the denom is + held, and the chain that issues the corresponding asset. See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). ```javascript -const brandInfo = orchestrator.getBrandInfo('denom'); +const brandInfo = orchestrator.getBrandInfo('denom') ``` - `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount). ```javascript -const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }); +const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }) ``` ## 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. +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. + +### Account Creation + +- `makeAccount` (for a chain object) creates a new account on local and/or remote chain as below. + +```javascript +const [agoric, remoteChain] = await Promise.all([ + orch.getChain('agoric'), + orch.getChain(chainName) +]) +const [localAccount, remoteAccount] = await Promise.all([ + agoric.makeAccount(), + remoteChain.makeAccount() +]) +``` ### Address Management - `getAddress` retrieves the address of the account on the remote chain. ```javascript -const address = await orchestrationAccount.getAddress(); +const address = await orchestrationAccount.getAddress() ``` ### Balance Management @@ -62,8 +67,8 @@ const address = await orchestrationAccount.getAddress(); - `getBalance` retrieves the balance of a specific denom for the account. ```javascript -const balances = await orchestrationAccount.getBalances(); -const balance = await orchestrationAccount.getBalance('uatom'); +const balances = await orchestrationAccount.getBalances() +const balance = await orchestrationAccount.getBalance('uatom') ``` ### Funds Transfer @@ -71,62 +76,56 @@ const balance = await orchestrationAccount.getBalance('uatom'); - `send` transfers an amount to another account on the same chain. - `transfer` transfers an amount to another account, typically on another chain. - `transferSteps` transfers an amount in multiple steps, handling complex transfer paths. -- `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer - will be executed to transfer funds there. +- `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer will be executed to transfer + funds there. ```javascript -await orchestrationAccount.send(receiverAddress, amount); -await orchestrationAccount.transfer(amount, destinationAddress); -await orchestrationAccount.transferSteps(amount, transferMsg); -await orchestrationAccount.deposit(payment); +await orchestrationAccount.send(receiverAddress, amount) +await orchestrationAccount.transfer(amount, destinationAddress) +await orchestrationAccount.transferSteps(amount, transferMsg) +await orchestrationAccount.deposit(payment) ``` ## ChainHub -ChainHub is a centeralized registry of chains, connections, and denoms -that simplifies accessing and interacting with multiple chains, providing -a unified interface for the orchestration logic to manage cross-chain -operations effectively. A chainHub instance can be created using a call -to `makeChainHub` that makes a new ChainHub in the zone (or in the heap -if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. -It has no precious state. Its only state is a cache of queries to -`agoricNames` and the info provided in registration calls. When you -need a newer version you can simply make a hub and repeat the registrations. -ChainHub allows dynamic registration and use of chain and connection -information using the following API. +ChainHub is a centralized registry of chains, connections, and denoms that simplifies accessing and interacting with +multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively. +A chainHub instance can be created using a call to `makeChainHub` that makes a new ChainHub in the zone (or in the heap +if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. It has no +precious state. Its only state is a cache of queries to `agoricNames` and the info provided in registration calls. When +you need a newer version you can simply make a hub and repeat the registrations. ChainHub allows dynamic registration +and use of chain and connection information using the following APIs: ### Registration APIs -- `registerChain` register a new chain with `chainHub`. The name will override - a name in well known chain names. If a durable zone was not provided, - registration will not survive a reincarnation of the vat, and will have to be +- `registerChain` register a new chain with `chainHub`. The name will override a name in well-known chain names. If a + durable zone was not provided, registration will not survive a reincarnation of the vat, and will have to be registered again. - `registerConnection` registers a connections between two given chain IDs. -- `registerAsset` registers an asset that may be held on a chain other than - the issuing chain. Both corresponding chains should already be registered - before this call. +- `registerAsset` registers an asset that may be held on a chain other than the issuing chain. Both corresponding chains + should already be registered before this call. ### Information Retrieval - `getChainInfo` takes a chain name to get chain info. - `getConnectionInfo` returns `Vow` for two given chain IDs. -- `getChainsAndConnection` is used to get chain and connection info give primary and counter chain names. +- `getChainsAndConnection` is used to get chain and connection info given primary and counter chain names. - `getAsset` retrieves holding, issuing chain names etc. for a denom. - `getDenom` retrieves denom (string) for a `Brand`. -In the below example, `chainHub` is used to register a new chain and establish a connection -between the Agoric chain and the newly registered chain. +In the below example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and +the newly registered chain. ```javascript -const chainHub = makeChainHub(privateArgs.agoricNames, vowTools); +const chainHub = makeChainHub(privateArgs.agoricNames, vowTools) // Register a new chain with its information -chainHub.registerChain(chainKey, chainInfo); +chainHub.registerChain(chainKey, chainInfo) // Register a connection between the Agoric chain and the new chain chainHub.registerConnection( agoricChainInfo.chainId, chainInfo.chainId, - connectionInfo, -); + connectionInfo +) ``` From ecb07fbafcb1fe9497cf99311fbd899bc372f3bd Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Wed, 25 Sep 2024 15:21:03 +0500 Subject: [PATCH 4/4] chore: simplify `registerChain` --- .../getting-started/key-concepts.md | 50 +++++++++---------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/main/guides/orchestration/getting-started/key-concepts.md b/main/guides/orchestration/getting-started/key-concepts.md index c210a313e..411f356fa 100644 --- a/main/guides/orchestration/getting-started/key-concepts.md +++ b/main/guides/orchestration/getting-started/key-concepts.md @@ -12,8 +12,8 @@ set of high-level methods to manage and interact with local and remote chains. B - `getChain` retrieves a chain object for the given `chainName` to get access to chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). -```javascript -const chain = await orchestrator.getChain('chainName') +```js +const chain = await orchestrator.getChain('chainName'); ``` ### Brand Utility Functions @@ -21,14 +21,14 @@ const chain = await orchestrator.getChain('chainName') - `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, the chain where the denom is held, and the chain that issues the corresponding asset. See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). -```javascript -const brandInfo = orchestrator.getBrandInfo('denom') +```js +const brandInfo = orchestrator.getBrandInfo('denom'); ``` - `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount). -```javascript -const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }) +```js +const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }); ``` ## Orchestration Account @@ -42,23 +42,23 @@ interactions, providing a unified and simplified interface for developers. - `makeAccount` (for a chain object) creates a new account on local and/or remote chain as below. -```javascript +```js const [agoric, remoteChain] = await Promise.all([ orch.getChain('agoric'), orch.getChain(chainName) -]) +]); const [localAccount, remoteAccount] = await Promise.all([ agoric.makeAccount(), remoteChain.makeAccount() -]) +]); ``` ### Address Management - `getAddress` retrieves the address of the account on the remote chain. -```javascript -const address = await orchestrationAccount.getAddress() +```js +const address = await orchestrationAccount.getAddress(); ``` ### Balance Management @@ -66,9 +66,9 @@ const address = await orchestrationAccount.getAddress() - `getBalances` returns an array of amounts for every balance in the account. - `getBalance` retrieves the balance of a specific denom for the account. -```javascript -const balances = await orchestrationAccount.getBalances() -const balance = await orchestrationAccount.getBalance('uatom') +```js +const balances = await orchestrationAccount.getBalances(); +const balance = await orchestrationAccount.getBalance('uatom'); ``` ### Funds Transfer @@ -79,11 +79,11 @@ const balance = await orchestrationAccount.getBalance('uatom') - `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer will be executed to transfer funds there. -```javascript -await orchestrationAccount.send(receiverAddress, amount) -await orchestrationAccount.transfer(amount, destinationAddress) -await orchestrationAccount.transferSteps(amount, transferMsg) -await orchestrationAccount.deposit(payment) +```js +await orchestrationAccount.send(receiverAddress, amount); +await orchestrationAccount.transfer(amount, destinationAddress); +await orchestrationAccount.transferSteps(amount, transferMsg); +await orchestrationAccount.deposit(payment); ``` ## ChainHub @@ -98,9 +98,7 @@ and use of chain and connection information using the following APIs: ### Registration APIs -- `registerChain` register a new chain with `chainHub`. The name will override a name in well-known chain names. If a - durable zone was not provided, registration will not survive a reincarnation of the vat, and will have to be - registered again. +- `registerChain` register a new chain with `chainHub`. The name will override a name in well-known chain names. - `registerConnection` registers a connections between two given chain IDs. - `registerAsset` registers an asset that may be held on a chain other than the issuing chain. Both corresponding chains should already be registered before this call. @@ -116,16 +114,16 @@ and use of chain and connection information using the following APIs: In the below example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and the newly registered chain. -```javascript -const chainHub = makeChainHub(privateArgs.agoricNames, vowTools) +```js +const chainHub = makeChainHub(privateArgs.agoricNames, vowTools); // Register a new chain with its information -chainHub.registerChain(chainKey, chainInfo) +chainHub.registerChain(chainKey, chainInfo); // Register a connection between the Agoric chain and the new chain chainHub.registerConnection( agoricChainInfo.chainId, chainInfo.chainId, connectionInfo -) +); ```