|
1 |
| -# Orchestration Key Concepts |
| 1 | +# Orchestration Key Concepts and APIs |
2 | 2 |
|
3 |
| -This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Interchain Accounts (ICA), ChainHub, and Orchestration Accounts. |
| 3 | +This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub. |
4 | 4 |
|
5 |
| ---- |
| 5 | +## Orchestrator Interface |
6 | 6 |
|
7 |
| -## Interchain Account (ICA) |
| 7 | +The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a set of high-level methods to manage and interact with |
| 8 | +local and remote chains. Below are the primary methods: |
8 | 9 |
|
9 |
| -[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. |
| 10 | +### Access Chain Object |
10 | 11 |
|
11 |
| -#### Benefits of ICAs |
12 |
| -- **Cross-chain Control**: ICAs allow a contract to manage accounts on other chains, treating them like any other (remotable) object. |
13 |
| -- **Access Control**: Only the contract that creates the ICA has full control over it but can delegate specific access permissions to clients. |
14 |
| - |
15 |
| -For more details on access control, refer to [Access Control with Objects](/guides/zoe/contract-access-control). |
| 12 | +- `getChain` retrieves a chain object for the given `chainName` to get access to |
| 13 | + chain-specific methods. See [getChain](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain). |
16 | 14 |
|
| 15 | +```javascript |
| 16 | +const chain = await orchestrator.getChain('chainName'); |
| 17 | +``` |
17 | 18 |
|
18 |
| -### Example: ICA Usage in a Smart Contract |
| 19 | +### Create an Account |
19 | 20 |
|
20 |
| -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): |
| 21 | +- `makeLocalAccount` creates a new account on local chain. See [makeLocalAccount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#makeLocalAccount). |
21 | 22 |
|
22 | 23 | ```javascript
|
23 |
| -const stakeAndSwapFn = async (orch, ...) => { |
24 |
| - const omni = await orch.getChain('omniflixhub'); |
25 |
| - const agoric = await orch.getChain('agoric'); |
26 |
| - |
27 |
| - const [omniAccount, localAccount] = await Promise.all([ |
28 |
| - omni.makeAccount(), |
29 |
| - agoric.makeAccount(), |
30 |
| - ]); |
31 |
| - |
32 |
| - const omniAddress = omniAccount.getAddress(); |
33 |
| - |
34 |
| - // Deposit funds from user seat to LocalChainAccount |
35 |
| - const transferMsg = orcUtils.makeOsmosisSwap({ ... }); |
36 |
| - |
37 |
| - try { |
38 |
| - await localAccount.transferSteps(give.Stable, transferMsg); |
39 |
| - await omniAccount.delegate(offerArgs.validator, offerArgs.staked); |
40 |
| - } catch (e) { |
41 |
| - console.error(e); |
42 |
| - } |
43 |
| -}; |
| 24 | +const localAccount = await orchestrator.makeLocalAccount(); |
44 | 25 | ```
|
45 | 26 |
|
46 |
| -## ChainHub |
| 27 | +### Brand Utility Functions |
47 | 28 |
|
48 |
| -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. |
49 |
| - |
50 |
| -It simplifies accessing and interacting with multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively. |
51 |
| -ChainHub also allows dynamic registration and use of chain and connection information. |
| 29 | +- `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, |
| 30 | + the chain where the denom is held, and the chain that issues the corresponding asset. |
| 31 | + See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo). |
52 | 32 |
|
53 | 33 | ```javascript
|
54 |
| -const chainHub = makeChainHub(remotePowers.agoricNames) |
| 34 | +const brandInfo = orchestrator.getBrandInfo('denom'); |
| 35 | +``` |
55 | 36 |
|
56 |
| -// Register a new chain with its information |
57 |
| -chainHub.registerChain(chainKey, chainInfo) |
| 37 | +- `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount). |
58 | 38 |
|
59 |
| -// Register a connection between the Agoric chain and the new chain |
60 |
| -chainHub.registerConnection( |
61 |
| - agoricChainInfo.chainId, |
62 |
| - chainInfo.chainId, |
63 |
| - connectionInfo |
64 |
| -) |
| 39 | +```javascript |
| 40 | +const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n }); |
65 | 41 | ```
|
66 | 42 |
|
67 |
| -In this example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and the newly registered chain. |
68 |
| - |
69 | 43 | ## Orchestration Account
|
70 | 44 |
|
71 |
| -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. |
| 45 | +Orchestration accounts are a key concept in the Agoric Orchestration API, represented by the |
| 46 | +[`OrchestrationAccountI`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI) interface. These accounts provide high-level operations for managing |
| 47 | +accounts on remote chains, allowing seamless interaction and management of interchain |
| 48 | +accounts. The orchestration accounts abstract the complexity of interchain interactions, |
| 49 | +providing a unified and simplified interface for developers. |
72 | 50 |
|
73 |
| -**1. Address Management** |
| 51 | +### Address Management |
74 | 52 |
|
75 | 53 | - `getAddress` retrieves the address of the account on the remote chain.
|
76 | 54 |
|
77 | 55 | ```javascript
|
78 |
| -const address = await orchestrationAccount.getAddress() |
| 56 | +const address = await orchestrationAccount.getAddress(); |
79 | 57 | ```
|
80 | 58 |
|
81 |
| -**2. Balance Management** |
| 59 | +### Balance Management |
82 | 60 |
|
83 | 61 | - `getBalances` returns an array of amounts for every balance in the account.
|
84 | 62 | - `getBalance` retrieves the balance of a specific denom for the account.
|
85 | 63 |
|
86 | 64 | ```javascript
|
87 |
| -const balances = await orchestrationAccount.getBalances() |
88 |
| -const balance = await orchestrationAccount.getBalance('uatom') |
| 65 | +const balances = await orchestrationAccount.getBalances(); |
| 66 | +const balance = await orchestrationAccount.getBalance('uatom'); |
89 | 67 | ```
|
90 | 68 |
|
91 |
| -**3. Funds Transfer** |
| 69 | +### Funds Transfer |
92 | 70 |
|
93 | 71 | - `send` transfers an amount to another account on the same chain.
|
94 | 72 | - `transfer` transfers an amount to another account, typically on another chain.
|
95 | 73 | - `transferSteps` transfers an amount in multiple steps, handling complex transfer paths.
|
| 74 | +- `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer |
| 75 | + will be executed to transfer funds there. |
96 | 76 |
|
97 | 77 | ```javascript
|
98 |
| -await orchestrationAccount.send(receiverAddress, amount) |
99 |
| -await orchestrationAccount.transfer(amount, destinationAddress) |
100 |
| -await orchestrationAccount.transferSteps(amount, transferMsg) |
| 78 | +await orchestrationAccount.send(receiverAddress, amount); |
| 79 | +await orchestrationAccount.transfer(amount, destinationAddress); |
| 80 | +await orchestrationAccount.transferSteps(amount, transferMsg); |
| 81 | +await orchestrationAccount.deposit(payment); |
101 | 82 | ```
|
102 | 83 |
|
103 |
| -To see the function the Orchestration API exposes, see [Orchestration API](/guides/orchestration/getting-started/api.html) |
| 84 | +## ChainHub |
| 85 | + |
| 86 | +ChainHub is a centeralized registry of chains, connections, and denoms |
| 87 | +that simplifies accessing and interacting with multiple chains, providing |
| 88 | +a unified interface for the orchestration logic to manage cross-chain |
| 89 | +operations effectively. A chainHub instance can be created using a call |
| 90 | +to `makeChainHub` that makes a new ChainHub in the zone (or in the heap |
| 91 | +if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. |
| 92 | +It has no precious state. Its only state is a cache of queries to |
| 93 | +`agoricNames` and the info provided in registration calls. When you |
| 94 | +need a newer version you can simply make a hub and repeat the registrations. |
| 95 | +ChainHub allows dynamic registration and use of chain and connection |
| 96 | +information using the following API. |
| 97 | + |
| 98 | +### Registration APIs |
| 99 | + |
| 100 | +- `registerChain` register a new chain with `chainHub`. The name will override |
| 101 | + a name in well known chain names. If a durable zone was not provided, |
| 102 | + registration will not survive a reincarnation of the vat, and will have to be |
| 103 | + registered again. |
| 104 | +- `registerConnection` registers a connections between two given chain IDs. |
| 105 | +- `registerAsset` registers an asset that may be held on a chain other than |
| 106 | + the issuing chain. Both corresponding chains should already be registered |
| 107 | + before this call. |
| 108 | + |
| 109 | +### Information Retrieval |
| 110 | + |
| 111 | +- `getChainInfo` takes a chain name to get chain info. |
| 112 | +- `getConnectionInfo` returns `Vow<IBCConnectionInfo>` for two given chain IDs. |
| 113 | +- `getChainsAndConnection` is used to get chain and connection info give primary and counter chain names. |
| 114 | +- `getAsset` retrieves holding, issuing chain names etc. for a denom. |
| 115 | +- `getDenom` retrieves denom (string) for a `Brand`. |
| 116 | + |
| 117 | +In the below example, `chainHub` is used to register a new chain and establish a connection |
| 118 | +between the Agoric chain and the newly registered chain. |
| 119 | + |
| 120 | +```javascript |
| 121 | +const chainHub = makeChainHub(privateArgs.agoricNames, vowTools); |
| 122 | + |
| 123 | +// Register a new chain with its information |
| 124 | +chainHub.registerChain(chainKey, chainInfo); |
| 125 | + |
| 126 | +// Register a connection between the Agoric chain and the new chain |
| 127 | +chainHub.registerConnection( |
| 128 | + agoricChainInfo.chainId, |
| 129 | + chainInfo.chainId, |
| 130 | + connectionInfo, |
| 131 | +); |
| 132 | +``` |
0 commit comments