Skip to content

Commit 1b0bf9c

Browse files
committed
docs: updated chainHub sections
1 parent c623eaa commit 1b0bf9c

File tree

1 file changed

+37
-57
lines changed

1 file changed

+37
-57
lines changed

main/guides/orchestration/getting-started/key-concepts.md

+37-57
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Orchestration Key Concepts and APIs
22

3-
This document provides an overview of the fundamental concepts involved in building orchestration smart contracts, focusing on Orchestrator Interface, Orchestration Accounts, ChainHub, and Interchain Accounts (ICA).
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

55

66
## Orchestrator Interface
@@ -32,7 +32,7 @@ See [getBrandInfo](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration
3232
const brandInfo = orchestrator.getBrandInfo('denom');
3333
```
3434

35-
- `asAmount`converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount).
35+
- `asAmount` converts a denom amount to an `Amount` with a brand. See [asAmount](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#asAmount).
3636

3737
```javascript
3838
const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n });
@@ -81,15 +81,43 @@ await orchestrationAccount.deposit(payment);
8181

8282
## ChainHub
8383

84-
The `makeChainHub` utility manages the connections and metadata for various blockchain
85-
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.
86-
87-
It simplifies accessing and interacting with multiple chains, providing a unified interface
88-
for the orchestration logic to manage cross-chain operations effectively.
89-
ChainHub also allows dynamic registration and use of chain and connection information.
84+
ChainHub is a centeralized registry of chains, connections, and denoms
85+
that simplifies accessing and interacting with multiple chains, providing
86+
a unified interface for the orchestration logic to manage cross-chain
87+
operations effectively. A chainHub instance can be created using a call
88+
to `makeChainHub` that makes a new ChainHub in the zone (or in the heap
89+
if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton.
90+
It has no precious state. Its only state is a cache of queries to
91+
`agoricNames` and the info provided in registration calls. When you
92+
need a newer version you can simply make a hub and repeat the registrations.
93+
ChainHub allows dynamic registration and use of chain and connection
94+
information using the following API.
95+
96+
97+
### Registration APIs
98+
99+
- `registerChain` register a new chain with `chainHub`. The name will override
100+
a name in well known chain names. If a durable zone was not provided,
101+
registration will not survive a reincarnation of the vat, and will have to be
102+
registered again.
103+
- `registerConnection` registers a connections between two given chain IDs.
104+
- `registerAsset` registers an asset that may be held on a chain other than
105+
the issuing chain. Both corresponding chains should already be registered
106+
before this call.
107+
108+
### Information Retrieval
109+
110+
- `getChainInfo` takes a chain name to get chain info.
111+
- `getConnectionInfo` returns `Vow<IBCConnectionInfo>` for two given chain IDs.
112+
- `getChainsAndConnection` is used to get chain and connection info give primary and counter chain names.
113+
- `getAsset` retrieves holding, issuing chain names etc. for a denom.
114+
- `getDenom` retrieves denom (string) for a `Brand`.
115+
116+
In the below example, `chainHub` is used to register a new chain and establish a connection
117+
between the Agoric chain and the newly registered chain.
90118

91119
```javascript
92-
const chainHub = makeChainHub(remotePowers.agoricNames);
120+
const chainHub = makeChainHub(privateArgs.agoricNames, vowTools);
93121

94122
// Register a new chain with its information
95123
chainHub.registerChain(chainKey, chainInfo);
@@ -101,51 +129,3 @@ chainHub.registerConnection(
101129
connectionInfo,
102130
);
103131
```
104-
105-
In this example, `chainHub` is used to register a new chain and establish a connection
106-
between the Agoric chain and the newly registered chain.
107-
108-
## Interchain Account (ICA)
109-
110-
[Interchain Accounts](/glossary/#interchain-account-ica) (ICAs) are an IBC feature utilized
111-
within Agoric’s Orchestration API. They enable an Agoric smart contract to control an
112-
account on another blockchain in the Cosmos ecosystem. The [Inter-Blockchain Communication (IBC)](/glossary/#ibc) protocol facilitates seamless interactions and transactions across
113-
different blockchains.
114-
115-
#### Benefits of ICAs
116-
- **Cross-chain Control**: ICAs allow a contract to manage accounts on other chains,
117-
treating them like any other (remotable) object.
118-
- **Access Control**: Only the contract that creates the ICA has full control over it but
119-
can delegate specific access permissions to clients.
120-
121-
For more details on access control, refer to [Access Control with Objects](/guides/zoe/contract-access-control).
122-
123-
124-
### Example: ICA Usage in a Smart Contract
125-
126-
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):
127-
128-
```javascript
129-
const stakeAndSwapFn = async (orch, ...) => {
130-
const omni = await orch.getChain('omniflixhub');
131-
const agoric = await orch.getChain('agoric');
132-
133-
const [omniAccount, localAccount] = await Promise.all([
134-
omni.makeAccount(),
135-
agoric.makeAccount(),
136-
]);
137-
138-
const omniAddress = omniAccount.getAddress();
139-
140-
// Deposit funds from user seat to LocalChainAccount
141-
const transferMsg = orcUtils.makeOsmosisSwap({ ... });
142-
143-
try {
144-
await localAccount.transferSteps(give.Stable, transferMsg);
145-
await omniAccount.delegate(offerArgs.validator, offerArgs.staked);
146-
} catch (e) {
147-
console.error(e);
148-
}
149-
};
150-
```
151-

0 commit comments

Comments
 (0)