From 5c574c73ed052170e3d553ca2ab40ec01e50282b Mon Sep 17 00:00:00 2001 From: rabi-siddique Date: Tue, 9 Jul 2024 14:48:51 +0500 Subject: [PATCH 1/3] docs: add code examples --- main/guides/orchestration/chainhub.md | 86 +++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 4 deletions(-) diff --git a/main/guides/orchestration/chainhub.md b/main/guides/orchestration/chainhub.md index f35f7ab71..705e22940 100644 --- a/main/guides/orchestration/chainhub.md +++ b/main/guides/orchestration/chainhub.md @@ -1,22 +1,100 @@ -# Chain Hub +# ChainHub -This [code module](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is designed for managing chain and IBC connection information. It facilitate the registration and retrieval of chain and connection data. Let's break down the components and functionalities of this code. +The [ChainHub API](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is responsible managing chain and IBC connection information. It facilitate the registration and retrieval of chain and connection data. -The `makeChainHub` function accepts a NameHub reference (`agoricNames`) and an optional Zone for managing data durability. Inside the function two `MapStores` are created: +```js +const zone = makeDurableZone(baggage); +const { agoricNames } = remotePowers; +const chainHub = makeChainHub(agoricNames, zone); +``` + +The `makeChainHub` function accepts a `Remote` reference (`agoricNames`) and an optional `Zone` for managing data durability. The `makeChainHub` fuction creates a new `ChainHub` either in the specified zone or in the heap if no zone is provided. The resulting object is an Exo singleton, which means it has no previous state. Its state consists only of a cache of queries to `agoricNames` and the information provided in registration calls. + +The `ChainHub` objects maintains two `MapStores`: - `chainInfos`: for storing `CosmosChainInfo` objects. - `connectionInfos`: for storing `IBCConnectionInfo` objects. +These `MapStores` are not exposed directly. They are abstracted and used internally by the methods provided by the ChainHub. + # ChainHub Interface The core functionality is encapsulated within the `makeChainHub` function, which sets up a new ChainHub in the given zone. The ChainHub is responsible for: -- **Registering Chain Information (`registerChain`)**: Stores information about a blockchain inside the `chainInfos` mapstore, which can be used for quickly looking up details without querying a remote source. +- **Registering Chain Information (`registerChain`)**: Stores information about a chain inside the `chainInfos` mapstore, which can be used for quickly looking up details without querying a remote source. + +```js +const chainInfo = harden({ + chainId: 'agoric-3', + icaEnabled: false, + icqEnabled: false, + pfmEnabled: false, + ibcHooksEnabled: false, + stakingTokens: [{ denom: 'uist' }], +}); +let nonce = 0n; + +const chainKey = `${chainInfo.chainId}-${(nonce += 1n)}`; + +chainHub.registerChain(chainKey, chainInfo); +``` + +The function takes two parameters: `name`, which is a `string` representing the unique identifier of the chain, and `chainInfo`, which is an object structured according to the `CosmosChainInfo` format. - **Retrieving Chain Information (`getChainInfo`)**: Retrieves stored chain information from the `chainInfos` mapstore or fetches it from a remote source if not available locally. +```js +chainHub.getChainInfo('agoric-3'); +``` + +The function takes a single parameter, `chainName`, which is a `string` template type `K`, and returns a promise (`Vow`) that resolves to `ActualChainInfo`, providing detailed information about the specified chain based on its name. + - **Registering Connection Information (`registerConnection`)**: Stores information about a connection between two chains in `connectionInfos` mapstore, such as IBC connection details. +```js +const chainConnection = { + id: 'connection-0', + client_id: '07-tendermint-2', + counterparty: { + client_id: '07-tendermint-2', + connection_id: 'connection-1', + prefix: { + key_prefix: '', + }, + }, + state: 3 /* IBCConnectionState.STATE_OPEN */, + transferChannel: { + portId: 'transfer', + channelId: 'channel-1', + counterPartyChannelId: 'channel-1', + counterPartyPortId: 'transfer', + ordering: 1 /* Order.ORDER_UNORDERED */, + state: 3 /* IBCConnectionState.STATE_OPEN */, + version: 'ics20-1', + }, +}; + +chainHub.registerConnection('agoric-3', 'cosmoshub', chainConnection); +``` + +The function accepts three parameters: `chainId1` and `chainId2`, both of which are `strings` representing the identifiers of the two chains being connected, and `connectionInfo`, which is an object containing the details of the IBC connection as specified by the `IBCConnectionInfo` format + - **Retrieving Connection Information (`getConnectionInfo`)**: Retrieves stored connection information from `connectionInfos` mapstore or fetches it from a remote source if not available locally. +```js +const chainConnection = await E.when( + chainHub.getConnectionInfo('agoric-3', 'cosmoshub'), +); +``` + +The function takes two parameters, `chain1` and `chain2`, each of which can be either a `string` representing a chain identifier or an `object` with a `chainId` property, and it returns a promise (`Vow`) that resolves with an `IBCConnectionInfo` object detailing the connection between the two chains. + - **Retrieving Combined Chain and Connection Information (`getChainsAndConnection`)**: A composite function that fetches information about two chains and their connection simultaneously. + +```js +const [agoric3, cosmoshub, connectionInfo] = await E.when( + chainHub.getChainsAndConnection('agoric-3', 'cosmoshub'), +); +``` + +The function accepts two parameters, `chainName1` and `chainName2`, both of which are strings but defined as template types `C1` and `C2` respectively. It returns a promise (`Vow`) that resolves to a tuple containing the detailed information of both chains, `ActualChainInfo` and `ActualChainInfo`, along with their IBC connection information (`IBCConnectionInfo`). From bc40cca25e35db4a5eb1fb3f635f7bba91ca9411 Mon Sep 17 00:00:00 2001 From: rabi-siddique Date: Tue, 9 Jul 2024 15:04:40 +0500 Subject: [PATCH 2/3] chore: changes related to formatting --- main/guides/orchestration/chainhub.md | 30 ++++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/main/guides/orchestration/chainhub.md b/main/guides/orchestration/chainhub.md index 705e22940..5ec060a84 100644 --- a/main/guides/orchestration/chainhub.md +++ b/main/guides/orchestration/chainhub.md @@ -1,6 +1,6 @@ # ChainHub -The [ChainHub API](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is responsible managing chain and IBC connection information. It facilitate the registration and retrieval of chain and connection data. +The [ChainHub API](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is responsible managing chain and IBC connection information. It facilitates the registration and retrieval of chain and connection data. ```js const zone = makeDurableZone(baggage); @@ -8,20 +8,22 @@ const { agoricNames } = remotePowers; const chainHub = makeChainHub(agoricNames, zone); ``` -The `makeChainHub` function accepts a `Remote` reference (`agoricNames`) and an optional `Zone` for managing data durability. The `makeChainHub` fuction creates a new `ChainHub` either in the specified zone or in the heap if no zone is provided. The resulting object is an Exo singleton, which means it has no previous state. Its state consists only of a cache of queries to `agoricNames` and the information provided in registration calls. +The `makeChainHub` function accepts a `Remote` reference (`agoricNames`) and an optional `Zone` for managing data durability. The `makeChainHub` fuction creates a new `ChainHub` instance either in the specified zone or in the heap if no zone is provided. The resulting object is an Exo singleton, which means it has no previous state. Its state consists only of a cache of queries to `agoricNames` and the information provided in registration calls. The `ChainHub` objects maintains two `MapStores`: -- `chainInfos`: for storing `CosmosChainInfo` objects. -- `connectionInfos`: for storing `IBCConnectionInfo` objects. +- `chainInfos`: For storing `CosmosChainInfo` objects. +- `connectionInfos`: For storing `IBCConnectionInfo` objects. These `MapStores` are not exposed directly. They are abstracted and used internally by the methods provided by the ChainHub. # ChainHub Interface -The core functionality is encapsulated within the `makeChainHub` function, which sets up a new ChainHub in the given zone. The ChainHub is responsible for: +The core functionality is encapsulated within the `makeChainHub` function, which sets up a new `ChainHub` in the given zone. The `ChainHub` is responsible for: -- **Registering Chain Information (`registerChain`)**: Stores information about a chain inside the `chainInfos` mapstore, which can be used for quickly looking up details without querying a remote source. +## **Registering Chain Information (`registerChain`)** + +Stores information about a chain inside the `chainInfos` mapstore, which can be used for quickly looking up details without querying a remote source. ```js const chainInfo = harden({ @@ -41,7 +43,9 @@ chainHub.registerChain(chainKey, chainInfo); The function takes two parameters: `name`, which is a `string` representing the unique identifier of the chain, and `chainInfo`, which is an object structured according to the `CosmosChainInfo` format. -- **Retrieving Chain Information (`getChainInfo`)**: Retrieves stored chain information from the `chainInfos` mapstore or fetches it from a remote source if not available locally. +## **Retrieving Chain Information (`getChainInfo`)** + +Retrieves stored chain information from the `chainInfos` mapstore or fetches it from a remote source if not available locally. ```js chainHub.getChainInfo('agoric-3'); @@ -49,7 +53,9 @@ chainHub.getChainInfo('agoric-3'); The function takes a single parameter, `chainName`, which is a `string` template type `K`, and returns a promise (`Vow`) that resolves to `ActualChainInfo`, providing detailed information about the specified chain based on its name. -- **Registering Connection Information (`registerConnection`)**: Stores information about a connection between two chains in `connectionInfos` mapstore, such as IBC connection details. +## **Registering Connection Information (`registerConnection`)** + +Stores information about a connection between two chains in `connectionInfos` mapstore, such as IBC connection details. ```js const chainConnection = { @@ -79,7 +85,9 @@ chainHub.registerConnection('agoric-3', 'cosmoshub', chainConnection); The function accepts three parameters: `chainId1` and `chainId2`, both of which are `strings` representing the identifiers of the two chains being connected, and `connectionInfo`, which is an object containing the details of the IBC connection as specified by the `IBCConnectionInfo` format -- **Retrieving Connection Information (`getConnectionInfo`)**: Retrieves stored connection information from `connectionInfos` mapstore or fetches it from a remote source if not available locally. +## **Retrieving Connection Information (`getConnectionInfo`)** + +Retrieves stored connection information from `connectionInfos` mapstore or fetches it from a remote source if not available locally. ```js const chainConnection = await E.when( @@ -89,7 +97,9 @@ const chainConnection = await E.when( The function takes two parameters, `chain1` and `chain2`, each of which can be either a `string` representing a chain identifier or an `object` with a `chainId` property, and it returns a promise (`Vow`) that resolves with an `IBCConnectionInfo` object detailing the connection between the two chains. -- **Retrieving Combined Chain and Connection Information (`getChainsAndConnection`)**: A composite function that fetches information about two chains and their connection simultaneously. +## **Retrieving Combined Chain and Connection Information (`getChainsAndConnection`)** + +A composite function that fetches information about two chains and their connection simultaneously. ```js const [agoric3, cosmoshub, connectionInfo] = await E.when( From f2f4dd73f55393af5f0dca8ffeca76dfab1b9482 Mon Sep 17 00:00:00 2001 From: rabi-siddique Date: Tue, 9 Jul 2024 15:49:15 +0500 Subject: [PATCH 3/3] docs: API reference and formatting updates --- main/guides/orchestration/chainhub.md | 50 ++++++++++++++++----------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/main/guides/orchestration/chainhub.md b/main/guides/orchestration/chainhub.md index 5ec060a84..64b05f3ab 100644 --- a/main/guides/orchestration/chainhub.md +++ b/main/guides/orchestration/chainhub.md @@ -1,6 +1,6 @@ # ChainHub -The [ChainHub API](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is responsible managing chain and IBC connection information. It facilitates the registration and retrieval of chain and connection data. +The [ChainHub API](https://github.com/Agoric/agoric-sdk/blob/859d8c0d151ff6f686583db1eaf72efb89cc7648/packages/orchestration/src/exos/chain-hub.js#L99) is responsible for managing chain and IBC connection information. It facilitates the registration and retrieval of chain and connection information. ```js const zone = makeDurableZone(baggage); @@ -8,22 +8,25 @@ const { agoricNames } = remotePowers; const chainHub = makeChainHub(agoricNames, zone); ``` -The `makeChainHub` function accepts a `Remote` reference (`agoricNames`) and an optional `Zone` for managing data durability. The `makeChainHub` fuction creates a new `ChainHub` instance either in the specified zone or in the heap if no zone is provided. The resulting object is an Exo singleton, which means it has no previous state. Its state consists only of a cache of queries to `agoricNames` and the information provided in registration calls. +The `makeChainHub` function accepts a `Remote` reference (`agoricNames`) and an optional `Zone` to manage data durability. The `makeChainHub` function creates a new `ChainHub` instance either in the specified zone or in the heap if no zone is provided. The resulting object is an Exo singleton, meaning it has no previous state. Its state consists solely of a cache of queries to `agoricNames` and the information provided during registration calls. -The `ChainHub` objects maintains two `MapStores`: +The `ChainHub` object maintains two `MapStores`: - `chainInfos`: For storing `CosmosChainInfo` objects. - `connectionInfos`: For storing `IBCConnectionInfo` objects. These `MapStores` are not exposed directly. They are abstracted and used internally by the methods provided by the ChainHub. -# ChainHub Interface +# ChainHub APIs -The core functionality is encapsulated within the `makeChainHub` function, which sets up a new `ChainHub` in the given zone. The `ChainHub` is responsible for: +The core functionality is encapsulated within the `makeChainHub` function, which sets up a new `ChainHub` in the specified zone. The `ChainHub` provides the following APIs: -## **Registering Chain Information (`registerChain`)** +## **chainHub.registerChain(name, chainInfo)** -Stores information about a chain inside the `chainInfos` mapstore, which can be used for quickly looking up details without querying a remote source. +- name: **string** +- chainInfo: **CosmosChainInfo** + +Stores information about a chain in the `chainInfos` MapStore, enabling quick lookup of details without querying a remote source. ```js const chainInfo = harden({ @@ -41,21 +44,24 @@ const chainKey = `${chainInfo.chainId}-${(nonce += 1n)}`; chainHub.registerChain(chainKey, chainInfo); ``` -The function takes two parameters: `name`, which is a `string` representing the unique identifier of the chain, and `chainInfo`, which is an object structured according to the `CosmosChainInfo` format. +## **chainHub.getChainInfo(chainName)** -## **Retrieving Chain Information (`getChainInfo`)** +- chainName: **string** +- Returns: **Vow\\>** -Retrieves stored chain information from the `chainInfos` mapstore or fetches it from a remote source if not available locally. +Retrieves stored chain information from the `chainInfos` MapStore or fetches it from a remote source if not available locally. ```js chainHub.getChainInfo('agoric-3'); ``` -The function takes a single parameter, `chainName`, which is a `string` template type `K`, and returns a promise (`Vow`) that resolves to `ActualChainInfo`, providing detailed information about the specified chain based on its name. +## **chainHub.registerConnection(chainId1, chainId2)** -## **Registering Connection Information (`registerConnection`)** +- chainId1: **string** +- chainId2: **string** +- Returns: **IBCConnectionInfo** -Stores information about a connection between two chains in `connectionInfos` mapstore, such as IBC connection details. +Stores information about a connection between two chains in `connectionInfos` Mapstore, such as IBC connection details. ```js const chainConnection = { @@ -83,11 +89,13 @@ const chainConnection = { chainHub.registerConnection('agoric-3', 'cosmoshub', chainConnection); ``` -The function accepts three parameters: `chainId1` and `chainId2`, both of which are `strings` representing the identifiers of the two chains being connected, and `connectionInfo`, which is an object containing the details of the IBC connection as specified by the `IBCConnectionInfo` format +## **chainHub.getConnectionInfo(chain1, chain2)** -## **Retrieving Connection Information (`getConnectionInfo`)** +- chain1: **string** | { chainId: **string** } +- chain2: **string** | { chainId: **string** } +- Returns: **Vow\\>** -Retrieves stored connection information from `connectionInfos` mapstore or fetches it from a remote source if not available locally. +Retrieves stored connection information from `connectionInfos` Mapstore or fetches it from a remote source if not available locally. ```js const chainConnection = await E.when( @@ -95,16 +103,16 @@ const chainConnection = await E.when( ); ``` -The function takes two parameters, `chain1` and `chain2`, each of which can be either a `string` representing a chain identifier or an `object` with a `chainId` property, and it returns a promise (`Vow`) that resolves with an `IBCConnectionInfo` object detailing the connection between the two chains. +## **chainHub.getChainsAndConnection(chainName1, chainName2)** -## **Retrieving Combined Chain and Connection Information (`getChainsAndConnection`)** +- chainName1: **C1** extends **string** +- chainName2: **C2** extends **string** +- Returns: **Vow\<[ActualChainInfo\, ActualChainInfo\, IBCConnectionInfo]\>** -A composite function that fetches information about two chains and their connection simultaneously. +This method fetches information about two chains and their connection simultaneously. ```js const [agoric3, cosmoshub, connectionInfo] = await E.when( chainHub.getChainsAndConnection('agoric-3', 'cosmoshub'), ); ``` - -The function accepts two parameters, `chainName1` and `chainName2`, both of which are strings but defined as template types `C1` and `C2` respectively. It returns a promise (`Vow`) that resolves to a tuple containing the detailed information of both chains, `ActualChainInfo` and `ActualChainInfo`, along with their IBC connection information (`IBCConnectionInfo`).