Orchestration Key Concepts
Here, we overview the fundamental concepts involved with building orchestration smart contracts.
Interchain Account (ICA)
Interchain Accounts (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 API. This feature leverages the Inter-Blockchain Communication (IBC) protocol to facilitate interactions and transactions across different blockchains seamlessly.
![](/assets/icaoverview.9Cs6ZxOS.png)
Photo credit: cosmos.network documentation
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 a detailed explanation of these access control rules, see Access Control with Objects.
Example ICA Usage from a Smart Contract
This sample is taken from one of the example contracts
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);
}
};
ChainHub
The makeChainHub
utility manages the connections and metadata for various blockchain networks. It creates a new ChainHub
instance implementing the ChainHubI
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.
const chainHub = makeChainHub(remotePowers.agoricNames);
// 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,
);
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
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
getAddress
retrieves the address of the account on the remote chain.
const address = await orchestrationAccount.getAddress();
2. 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.
const balances = await orchestrationAccount.getBalances();
const balance = await orchestrationAccount.getBalance('uatom');
3. 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.
await orchestrationAccount.send(receiverAddress, amount);
await orchestrationAccount.transfer(amount, destinationAddress);
await orchestrationAccount.transferSteps(amount, transferMsg);
To see the function the Orchestration API exposes, see Orchestration API