Skip to content

Commit 9550bc3

Browse files
committed
chore: merged key concepts and API in orch
1 parent d7a84d6 commit 9550bc3

File tree

2 files changed

+89
-64
lines changed

2 files changed

+89
-64
lines changed

main/.vitepress/config.mjs

-4
Original file line numberDiff line numberDiff line change
@@ -429,10 +429,6 @@ export default defineConfig({
429429
text: 'Key Concepts',
430430
link: '/guides/orchestration/getting-started/key-concepts',
431431
},
432-
{
433-
text: 'API',
434-
link: '/guides/orchestration/getting-started/api',
435-
},
436432
{
437433
text: 'Contract Walkthroughs',
438434
link: '/guides/orchestration/getting-started/contract-walkthroughs',
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,132 @@
1-
# Orchestration Key Concepts
1+
# Orchestration Key Concepts and APIs
22

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.
44

5-
---
5+
## Orchestrator Interface
66

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:
89

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
1011

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).
1614

15+
```javascript
16+
const chain = await orchestrator.getChain('chainName');
17+
```
1718

18-
### Example: ICA Usage in a Smart Contract
19+
### Create an Account
1920

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).
2122

2223
```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();
4425
```
4526

46-
## ChainHub
27+
### Brand Utility Functions
4728

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).
5232

5333
```javascript
54-
const chainHub = makeChainHub(remotePowers.agoricNames)
34+
const brandInfo = orchestrator.getBrandInfo('denom');
35+
```
5536

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).
5838

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 });
6541
```
6642

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-
6943
## Orchestration Account
7044

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.
7250

73-
**1. Address Management**
51+
### Address Management
7452

7553
- `getAddress` retrieves the address of the account on the remote chain.
7654

7755
```javascript
78-
const address = await orchestrationAccount.getAddress()
56+
const address = await orchestrationAccount.getAddress();
7957
```
8058

81-
**2. Balance Management**
59+
### Balance Management
8260

8361
- `getBalances` returns an array of amounts for every balance in the account.
8462
- `getBalance` retrieves the balance of a specific denom for the account.
8563

8664
```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');
8967
```
9068

91-
**3. Funds Transfer**
69+
### Funds Transfer
9270

9371
- `send` transfers an amount to another account on the same chain.
9472
- `transfer` transfers an amount to another account, typically on another chain.
9573
- `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.
9676

9777
```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);
10182
```
10283

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

Comments
 (0)