Skip to content

Commit 20a3ecf

Browse files
authored
Merge pull request #1201 from Agoric/ms/update-orch-concepts
Improvements to Orchestration Key-Concepts Page
2 parents 7cbb7c1 + ecb07fb commit 20a3ecf

File tree

3 files changed

+112
-165
lines changed

3 files changed

+112
-165
lines changed

main/.vitepress/config.mjs

+30-5
Original file line numberDiff line numberDiff line change
@@ -126,13 +126,9 @@ export default defineConfig({
126126
collapsed: true,
127127
items: [
128128
{
129-
text: 'Key Concepts',
129+
text: 'Key Concepts and APIs',
130130
link: '/guides/orchestration/getting-started/key-concepts',
131131
},
132-
{
133-
text: 'API',
134-
link: '/guides/orchestration/getting-started/api',
135-
},
136132
{
137133
text: 'Contract Walkthroughs',
138134
link: '/guides/orchestration/getting-started/contract-walkthroughs',
@@ -453,6 +449,35 @@ export default defineConfig({
453449
},
454450
],
455451
},
452+
{
453+
text: 'Orchestration',
454+
link: '/guides/orchestration/',
455+
collapsed: true,
456+
items: [
457+
{
458+
text: 'Key Concepts and APIs',
459+
link: '/guides/orchestration/getting-started/key-concepts',
460+
},
461+
{
462+
text: 'Contract Walkthroughs',
463+
link: '/guides/orchestration/getting-started/contract-walkthroughs',
464+
items: [
465+
{
466+
text: 'Cross-Chain Swap Example',
467+
link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap',
468+
},
469+
{
470+
text: 'Cross-Chain Unbond Example',
471+
link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond',
472+
},
473+
{
474+
text: 'Orchestration Basics',
475+
link: '/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics',
476+
}
477+
]
478+
},
479+
]
480+
},
456481
{
457482
text: 'JavaScript Framework',
458483
ariaLabel: 'JavaScript Framework',

main/guides/orchestration/getting-started/api.md

-101
This file was deleted.
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,67 @@
1-
# Orchestration Key Concepts
1+
# Orchestration Key Concepts and APIs
22

3-
Here, we overview the fundamental concepts involved with building orchestration smart contracts.
3+
This document provides an overview of the fundamental concepts involved in building orchestration smart contracts,
4+
focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub.
45

5-
### Interchain Account (ICA)
6+
## Orchestrator Interface
67

7-
[Interchain Accounts](/glossary/#interchain-account-ica) (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](/glossary/#orchestration) API. This feature leverages the [Inter-Blockchain Communication (IBC)](/glossary/#ibc) protocol to facilitate interactions and transactions across different blockchains seamlessly.
8+
The [`Orchestrator`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator) interface provides a
9+
set of high-level methods to manage and interact with local and remote chains. Below are the primary methods:
810

9-
<br/>
10-
<img src="../assets/icaoverview.png" width="100%" />
11-
<br/>
11+
### Access Chain Object
1212

13-
Photo credit: [cosmos.network documentation](https://tutorials.cosmos.network/academy/3-ibc/8-ica.html)
13+
- `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).
1414

15-
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.
16-
17-
For a detailed explanation of these access control rules, see [Access Control with Objects](/guides/zoe/contract-access-control).
15+
```js
16+
const chain = await orchestrator.getChain('chainName');
17+
```
1818

19-
### Example ICA Usage from a Smart Contract
19+
### Brand Utility Functions
2020

21-
This sample is taken from one of the [example contracts](https://github.com/Agoric/agoric-sdk/blob/master/packages/orchestration/src/examples/swapExample.contract.js)
21+
- `getBrandInfo` returns information about a `denom`, including the equivalent local Brand, the chain where the denom is
22+
held, and the chain that issues the corresponding asset. See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getBrandInfo).
2223

2324
```js
24-
const stakeAndSwapFn = async (orch, ...) => {
25-
// ...
26-
const omni = await orch.getChain('omniflixhub');
27-
const agoric = await orch.getChain('agoric');
28-
29-
const [omniAccount, localAccount] = await Promise.all([
30-
omni.makeAccount(),
31-
agoric.makeAccount(),
32-
]);
33-
34-
const omniAddress = omniAccount.getAddress();
35-
36-
// deposit funds from user seat to LocalChainAccount
37-
// ...
38-
const transferMsg = orcUtils.makeOsmosisSwap({ ... });
39-
40-
try {
41-
await localAccount.transferSteps(give.Stable, transferMsg);
42-
await omniAccount.delegate(offerArgs.validator, offerArgs.staked);
43-
} catch (e) {
44-
console.error(e);
45-
}
46-
};
25+
const brandInfo = orchestrator.getBrandInfo('denom');
4726
```
4827

49-
### ChainHub
50-
51-
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.
52-
53-
It simplifies accessing and interacting with multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively.
54-
ChainHub also allows dynamic registration and use of chain and connection information.
28+
- `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount).
5529

5630
```js
57-
const chainHub = makeChainHub(remotePowers.agoricNames);
31+
const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n });
32+
```
5833

59-
// Register a new chain with its information
60-
chainHub.registerChain(chainKey, chainInfo);
34+
## Orchestration Account
6135

62-
// Register a connection between the Agoric chain and the new chain
63-
chainHub.registerConnection(
64-
agoricChainInfo.chainId,
65-
chainInfo.chainId,
66-
connectionInfo
67-
);
68-
```
36+
Orchestration accounts are a key concept in the Agoric Orchestration API, represented by the [`OrchestrationAccountI`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI)
37+
interface. These accounts provide high-level operations for managing accounts on remote chains, allowing seamless
38+
interaction and management of interchain accounts. The orchestration accounts abstract the complexity of interchain
39+
interactions, providing a unified and simplified interface for developers.
6940

70-
In this example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and the newly registered chain.
41+
### Account Creation
7142

72-
### Orchestration Account
43+
- `makeAccount` (for a chain object) creates a new account on local and/or remote chain as below.
7344

74-
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+
```js
46+
const [agoric, remoteChain] = await Promise.all([
47+
orch.getChain('agoric'),
48+
orch.getChain(chainName)
49+
]);
50+
const [localAccount, remoteAccount] = await Promise.all([
51+
agoric.makeAccount(),
52+
remoteChain.makeAccount()
53+
]);
54+
```
7555

76-
**1. Address Management**
56+
### Address Management
7757

7858
- `getAddress` retrieves the address of the account on the remote chain.
7959

8060
```js
8161
const address = await orchestrationAccount.getAddress();
8262
```
8363

84-
**2. Balance Management**
64+
### Balance Management
8565

8666
- `getBalances` returns an array of amounts for every balance in the account.
8767
- `getBalance` retrieves the balance of a specific denom for the account.
@@ -91,16 +71,59 @@ const balances = await orchestrationAccount.getBalances();
9171
const balance = await orchestrationAccount.getBalance('uatom');
9272
```
9373

94-
**3. Funds Transfer**
74+
### Funds Transfer
9575

9676
- `send` transfers an amount to another account on the same chain.
9777
- `transfer` transfers an amount to another account, typically on another chain.
9878
- `transferSteps` transfers an amount in multiple steps, handling complex transfer paths.
79+
- `deposit` deposits payment from Zoe to the account. For remote accounts, an IBC Transfer will be executed to transfer
80+
funds there.
9981

10082
```js
10183
await orchestrationAccount.send(receiverAddress, amount);
10284
await orchestrationAccount.transfer(amount, destinationAddress);
10385
await orchestrationAccount.transferSteps(amount, transferMsg);
86+
await orchestrationAccount.deposit(payment);
10487
```
10588

106-
To see the function the Orchestration API exposes, see [Orchestration API](/guides/orchestration/getting-started/api.html)
89+
## ChainHub
90+
91+
ChainHub is a centralized registry of chains, connections, and denoms that simplifies accessing and interacting with
92+
multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively.
93+
A chainHub instance can be created using a call to `makeChainHub` that makes a new ChainHub in the zone (or in the heap
94+
if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. It has no
95+
precious state. Its only state is a cache of queries to `agoricNames` and the info provided in registration calls. When
96+
you need a newer version you can simply make a hub and repeat the registrations. ChainHub allows dynamic registration
97+
and use of chain and connection information using the following APIs:
98+
99+
### Registration APIs
100+
101+
- `registerChain` register a new chain with `chainHub`. The name will override a name in well-known chain names.
102+
- `registerConnection` registers a connections between two given chain IDs.
103+
- `registerAsset` registers an asset that may be held on a chain other than the issuing chain. Both corresponding chains
104+
should already be registered before this call.
105+
106+
### Information Retrieval
107+
108+
- `getChainInfo` takes a chain name to get chain info.
109+
- `getConnectionInfo` returns `Vow<IBCConnectionInfo>` for two given chain IDs.
110+
- `getChainsAndConnection` is used to get chain and connection info given primary and counter chain names.
111+
- `getAsset` retrieves holding, issuing chain names etc. for a denom.
112+
- `getDenom` retrieves denom (string) for a `Brand`.
113+
114+
In the below example, `chainHub` is used to register a new chain and establish a connection between the Agoric chain and
115+
the newly registered chain.
116+
117+
```js
118+
const chainHub = makeChainHub(privateArgs.agoricNames, vowTools);
119+
120+
// Register a new chain with its information
121+
chainHub.registerChain(chainKey, chainInfo);
122+
123+
// Register a connection between the Agoric chain and the new chain
124+
chainHub.registerConnection(
125+
agoricChainInfo.chainId,
126+
chainInfo.chainId,
127+
connectionInfo
128+
);
129+
```

0 commit comments

Comments
 (0)