Skip to content

Commit

Permalink
Merge pull request #1201 from Agoric/ms/update-orch-concepts
Browse files Browse the repository at this point in the history 
Improvements to Orchestration Key-Concepts Page
  • Loading branch information
@amessbee
amessbee authored Oct 2, 2024
2 parents 7cbb7c1 + ecb07fb commit 20a3ecf
Show file tree
Hide file tree
Showing 3 changed files with 112 additions and 165 deletions.
35 changes: 30 additions & 5 deletions main/.vitepress/config.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,13 +126,9 @@ export default defineConfig({
collapsed: true,
items: [
{
text: 'Key Concepts',
text: 'Key Concepts and APIs',
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',
Expand Down Expand Up @@ -453,6 +449,35 @@ export default defineConfig({
},
],
},
{
text: 'Orchestration',
link: '/guides/orchestration/',
collapsed: true,
items: [
{
text: 'Key Concepts and APIs',
link: '/guides/orchestration/getting-started/key-concepts',
},
{
text: 'Contract Walkthroughs',
link: '/guides/orchestration/getting-started/contract-walkthroughs',
items: [
{
text: 'Cross-Chain Swap Example',
link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap',
},
{
text: 'Cross-Chain Unbond Example',
link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond',
},
{
text: 'Orchestration Basics',
link: '/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics',
}
]
},
]
},
{
text: 'JavaScript Framework',
ariaLabel: 'JavaScript Framework',
Expand Down
101 changes: 0 additions & 101 deletions main/guides/orchestration/getting-started/api.md
View file

This file was deleted.

141 changes: 82 additions & 59 deletions main/guides/orchestration/getting-started/key-concepts.md
View file
Original file line number Diff line number Diff line change
@@ -1,87 +1,67 @@
# Orchestration Key Concepts
# Orchestration Key Concepts and APIs

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

### Interchain Account (ICA)
## Orchestrator Interface

[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.
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:

<br/>
<img src="../assets/icaoverview.png" width="100%" />
<br/>
### Access Chain Object

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

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](/guides/zoe/contract-access-control).
```js
const chain = await orchestrator.getChain('chainName');
```

### Example ICA Usage from a Smart Contract
### Brand Utility Functions

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

```js
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 brandInfo = orchestrator.getBrandInfo('denom');
```

### ChainHub

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.
- `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount).

```js
const chainHub = makeChainHub(remotePowers.agoricNames);
const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n });
```

// Register a new chain with its information
chainHub.registerChain(chainKey, chainInfo);
## Orchestration Account

// Register a connection between the Agoric chain and the new chain
chainHub.registerConnection(
agoricChainInfo.chainId,
chainInfo.chainId,
connectionInfo
);
```
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.

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

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

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.
```js
const [agoric, remoteChain] = await Promise.all([
orch.getChain('agoric'),
orch.getChain(chainName)
]);
const [localAccount, remoteAccount] = await Promise.all([
agoric.makeAccount(),
remoteChain.makeAccount()
]);
```

**1. Address Management**
### Address Management

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

```js
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.
Expand All @@ -91,16 +71,59 @@ 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.

```js
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 centralized 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 APIs:

### Registration APIs

- `registerChain` register a new chain with `chainHub`. The name will override a name in well-known chain names.
- `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<IBCConnectionInfo>` for two given chain IDs.
- `getChainsAndConnection` is used to get chain and connection info given 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.

```js
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
);
```

0 comments on commit 20a3ecf

Please sign in to comment.