From 9550bc30f0d643224d751f480a98875b54497c70 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 10 Sep 2024 17:27:54 +0500 Subject: [PATCH] chore: merged key concepts and API in orch --- main/.vitepress/config.mjs | 4 - .../getting-started/key-concepts.md | 149 +++++++++++------- 2 files changed, 89 insertions(+), 64 deletions(-) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index fa59b5ce7..4f97f61be 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -429,10 +429,6 @@ export default defineConfig({ text: 'Key Concepts', 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', diff --git a/main/guides/orchestration/getting-started/key-concepts.md b/main/guides/orchestration/getting-started/key-concepts.md index 17bca28c6..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. - -For more details on access control, refer to [Access Control with Objects](/guides/zoe/contract-access-control). +- `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'); +``` -### Example: ICA Usage in a Smart Contract +### Create an Account -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): +- `makeLocalAccount` creates a new account on local chain. See [makeLocalAccount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#makeLocalAccount). ```javascript -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(), - ]); - - const omniAddress = omniAccount.getAddress(); - - // Deposit funds from user seat to LocalChainAccount - const transferMsg = orcUtils.makeOsmosisSwap({ ... }); - - try { - await localAccount.transferSteps(give.Stable, transferMsg); - await omniAccount.delegate(offerArgs.validator, offerArgs.staked); - } catch (e) { - console.error(e); - } -}; +const localAccount = await orchestrator.makeLocalAccount(); ``` -## ChainHub +### Brand Utility Functions -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. - -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). ```javascript -const chainHub = makeChainHub(remotePowers.agoricNames) +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. ```javascript -const address = await orchestrationAccount.getAddress() +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. ```javascript -const balances = await orchestrationAccount.getBalances() -const balance = await orchestrationAccount.getBalance('uatom') +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. ```javascript -await orchestrationAccount.send(receiverAddress, amount) -await orchestrationAccount.transfer(amount, destinationAddress) -await orchestrationAccount.transferSteps(amount, transferMsg) +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, +); +```