-
Notifications
You must be signed in to change notification settings - Fork 39
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: merged key concepts and API in orch
- Loading branch information
Showing
3 changed files
with
88 additions
and
164 deletions.
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 was deleted.
Oops, something went wrong.
147 changes: 88 additions & 59 deletions
147
main/guides/orchestration/getting-started/key-concepts.md
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,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<IBCConnectionInfo>` 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, | ||
| ); | ||
| ``` |