Improvements to Orchestration Key-Concepts Page #1201
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,87 +1,67 @@ | ||
| # 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. | ||
|
|
||
| ## 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: | ||
|
|
||
Jovonni marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### 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). | ||
|
|
||
|
There was a problem hiding this comment. any reason we are removing this? |
||
| ```js | ||
| 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). | ||
|
|
||
| ```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 }); | ||
| ``` | ||
|
|
||
| ## 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. | ||
|
|
||
| ### Account Creation | ||
|
|
||
| - `makeAccount` (for a chain object) creates a new account on local and/or remote chain as below. | ||
|
|
||
| ```js | ||
| const [agoric, remoteChain] = await Promise.all([ | ||
| orch.getChain('agoric'), | ||
|
There was a problem hiding this comment. not sure its helpful, but I find myself being asked, "what does promise.all do?" more often that I expected when showing this 👀 |
||
| 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. | ||
|
|
||
| ```js | ||
| const address = await orchestrationAccount.getAddress(); | ||
| ``` | ||
|
|
||
| ### Balance Management | ||
|
|
||
|
There was a problem hiding this comment. What is happening under the hood here, is IF we invoke Example from orch dapp contract: const remoteChainBalance = await remoteAccount.getBalance('uosmo'); |
||
| - `getBalances` returns an array of amounts for every balance in the account. | ||
| - `getBalance` retrieves the balance of a specific denom for the account. | ||
|
|
@@ -91,16 +71,59 @@ const balances = await orchestrationAccount.getBalances(); | |
| const balance = await orchestrationAccount.getBalance('uatom'); | ||
| ``` | ||
|
|
||
| ### 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 | ||
| await orchestrationAccount.send(receiverAddress, amount); | ||
| await orchestrationAccount.transfer(amount, destinationAddress); | ||
| await orchestrationAccount.transferSteps(amount, transferMsg); | ||
| await orchestrationAccount.deposit(payment); | ||
| ``` | ||
|
|
||
| ## ChainHub | ||
|
|
||
|
There was a problem hiding this comment. Please make this section (ChainHub) consistent with previous two sections with regard to listing different APIs separately. For example I think you can add two sub-headings for registerChain and registerConnection in this section. There was a problem hiding this comment. i agree, and take the opportunity to explain each. This is a good set of api functions though There was a problem hiding this comment. @amessbee i'd say its good this is prob the only comment to address before merging. |
||
| 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. | ||
| - `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<IBCConnectionInfo>` for two given chain IDs. | ||
| - `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. | ||
|
|
||
| ```js | ||
| 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 | ||
| ); | ||
| ``` | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is there a reason why we are removing all education on interchain accounts? would like to understand this decision. If the team supports it then so be it, but I've found developers usually don't have an understanding on what an ICA is.
Although it can still be debated whether or not its useful, we have found it useful to explain it to them, and why its important. Other than that, orchestration accounts seem like magic.