From 47e1c9a7373d279b2f372269a92421744f5a1b8c Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Wed, 2 Nov 2022 14:59:17 +0100 Subject: [PATCH] docs: ics27 v6 documentation updates (#2561) * WIP * updating messages doc * updating msgs doc * refactoring and organising ics27 docs * updating owner field validation docs * adding legacy api heading to auth modules doc * Update docs/apps/interchain-accounts/messages.md Co-authored-by: Charly * Update docs/apps/interchain-accounts/messages.md Co-authored-by: Carlos Rodriguez * applying suggestions from review * updating future improvements section of active channels Co-authored-by: Charly Co-authored-by: Carlos Rodriguez --- docs/.vuepress/config.js | 20 +-- .../interchain-accounts/active-channels.md | 17 ++- docs/apps/interchain-accounts/auth-modules.md | 8 +- docs/apps/interchain-accounts/integration.md | 2 +- docs/apps/interchain-accounts/messages.md | 124 ++++++++++++++++++ docs/apps/interchain-accounts/overview.md | 25 ++-- docs/apps/interchain-accounts/parameters.md | 2 +- docs/apps/interchain-accounts/transactions.md | 21 --- docs/package-lock.json | 18 +-- 9 files changed, 175 insertions(+), 62 deletions(-) create mode 100644 docs/apps/interchain-accounts/messages.md delete mode 100644 docs/apps/interchain-accounts/transactions.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index bcdce1d759e..e616b323169 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -203,29 +203,29 @@ module.exports = { path: "/apps/interchain-accounts/overview.html", }, { - title: "Authentication Modules", + title: "Integration", directory: false, - path: "/apps/interchain-accounts/auth-modules.html", + path: "/apps/interchain-accounts/integration.html", }, { - title: "Active Channels", + title: "Messages", directory: false, - path: "/apps/interchain-accounts/active-channels.html", + path: "/apps/interchain-accounts/messages.html", }, { - title: "Integration", + title: "Parameters", directory: false, - path: "/apps/interchain-accounts/integration.html", + path: "/apps/interchain-accounts/parameters.html", }, { - title: "Parameters", + title: "Active Channels", directory: false, - path: "/apps/interchain-accounts/parameters.html", + path: "/apps/interchain-accounts/active-channels.html", }, { - title: "Transactions", + title: "Authentication Modules", directory: false, - path: "/apps/interchain-accounts/transactions.html", + path: "/apps/interchain-accounts/auth-modules.html", }, ], }, diff --git a/docs/apps/interchain-accounts/active-channels.md b/docs/apps/interchain-accounts/active-channels.md index d387bdea038..92a16decfa6 100644 --- a/docs/apps/interchain-accounts/active-channels.md +++ b/docs/apps/interchain-accounts/active-channels.md @@ -1,15 +1,13 @@ # Understanding Active Channels The Interchain Accounts module uses [ORDERED channels](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics#ordering) to maintain the order of transactions when sending packets from a controller to a host chain. A limitation when using ORDERED channels is that when a packet times out the channel will be closed. -In the case of a channel closing, a controller chain needs to be able to regain access to the interchain account registered on this channel. `Active Channels` enable this functionality. Future versions of the ICS-27 protocol and the Interchain Accounts module will likely use a new -channel type that provides ordering of packets without the channel closing on timing out, thus removing the need for `Active Channels` entirely. - -When an Interchain Account is registered using the `RegisterInterchainAccount` API, a new channel is created on a particular port. During the `OnChanOpenAck` and `OnChanOpenConfirm` steps (controller & host chain) the `Active Channel` for this interchain account +In the case of a channel closing, a controller chain needs to be able to regain access to the interchain account registered on this channel. `Active Channels` enable this functionality. +When an Interchain Account is registered using `MsgRegisterInterchainAccount`, a new channel is created on a particular port. During the `OnChanOpenAck` and `OnChanOpenConfirm` steps (controller & host chain) the `Active Channel` for this interchain account is stored in state. It is possible to create a new channel using the same controller chain portID if the previously set `Active Channel` is now in a `CLOSED` state. This channel creation can be initialized programatically by sending a new `MsgChannelOpenInit` message like so: @@ -23,3 +21,12 @@ Alternatively, any relayer operator may initiate a new channel handshake for thi It is important to note that once a channel has been opened for a given Interchain Account, new channels can not be opened for this account until the currently set `Active Channel` is set to `CLOSED`. +## Future Improvements + +Future versions of the ICS-27 protocol and the Interchain Accounts module will likely use a new channel type that provides ordering of packets without the channel closing in the event of a packet timing out, thus removing the need for `Active Channels` entirely. +The following is a list of issues which will provide the infrastructure to make this possible: + +- [IBC Channel Upgrades](https://github.com/cosmos/ibc-go/issues/1599) +- [Implement ORDERED_ALLOW_TIMEOUT logic in 04-channel](https://github.com/cosmos/ibc-go/issues/1661) +- [Add ORDERED_ALLOW_TIMEOUT as supported ordering in 03-connection](https://github.com/cosmos/ibc-go/issues/1662) +- [Allow ICA channels to be opened as ORDERED_ALLOW_TIMEOUT](https://github.com/cosmos/ibc-go/issues/1663) \ No newline at end of file diff --git a/docs/apps/interchain-accounts/auth-modules.md b/docs/apps/interchain-accounts/auth-modules.md index 2c35062aaca..d945ec62068 100644 --- a/docs/apps/interchain-accounts/auth-modules.md +++ b/docs/apps/interchain-accounts/auth-modules.md @@ -1,9 +1,13 @@ # Building an authentication module +### Deprecation Notice + +**This document is deprecated and will be removed in future releases**. + Authentication modules play the role of the `Base Application` as described in [ICS30 IBC Middleware](https://github.com/cosmos/ibc/tree/master/spec/app/ics-030-middleware), and enable application developers to perform custom logic when working with the Interchain Accounts controller API. {synopsis} The controller submodule is used for account registration and packet sending. @@ -145,6 +149,8 @@ func (im IBCModule) OnRecvPacket( } ``` +### Legacy API + ## `RegisterInterchainAccount` The authentication module can begin registering interchain accounts by calling `RegisterInterchainAccount`: diff --git a/docs/apps/interchain-accounts/integration.md b/docs/apps/interchain-accounts/integration.md index 3010ba11984..8105d684276 100644 --- a/docs/apps/interchain-accounts/integration.md +++ b/docs/apps/interchain-accounts/integration.md @@ -1,5 +1,5 @@ # Integration diff --git a/docs/apps/interchain-accounts/messages.md b/docs/apps/interchain-accounts/messages.md new file mode 100644 index 00000000000..e71af0e9859 --- /dev/null +++ b/docs/apps/interchain-accounts/messages.md @@ -0,0 +1,124 @@ + + +# Messages + +## `MsgRegisterInterchainAccount` + +An Interchain Accounts channel handshake can be initated using `MsgRegisterInterchainAccount`: + +```go +type MsgRegisterInterchainAccount struct { + Owner string + ConnectionID string + Version string +} +``` + +This message is expected to fail if: + +- `Owner` is an empty string. +- `ConnectionID` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)). + +This message will construct a new `MsgChannelOpenInit` on chain and route it to the core IBC message server to initiate the opening step of the channel handshake. + +The controller module will generate a new port identifier and claim the associated port capability. The caller is expected to provide an appropriate application version string. For example, this may be an ICS27 JSON encoded [`Metadata`](https://github.com/cosmos/ibc-go/blob/v6.0.0-alpha1/proto/ibc/applications/interchain_accounts/v1/metadata.proto#L11) type or an ICS29 JSON encoded [`Metadata`](https://github.com/cosmos/ibc-go/blob/v6.0.0-alpha1/proto/ibc/applications/fee/v1/metadata.proto#L11) type with a nested application version. +If the `Version` string is omitted, the application will construct a default version string in the `OnChanOpenInit` handshake callback. + +```go +type MsgRegisterInterchainAccountResponse struct { + ChannelID string +} +``` + +The `ChannelID` is return in the message response. + +### CLI + +The following is an example usage of the controller CLI command used to register an interchain account. + +```bash +simd tx interchain-accounts controller register connection-0 --from cosmos1m9l358xunhhwds0568za49mzhvuxx9uxre5tud +``` + +## `MsgSendTx` + +An Interchain Accounts transaction can be executed on a remote host chain by sending a `MsgSendTx` from the corresponding controller chain: + +```go +type MsgSendTx struct { + Owner string + ConnectionID string + PacketData InterchainAccountPacketData + RelativeTimeout uint64 +} +``` + +This message is expected to fail if: + +- `Owner` is an empty string. +- `ConnectionID` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)). +- `PacketData` contains an `UNSPECIFIED` type enum, the length of `Data` bytes is zero or the `Memo` field exceeds 256 characters in length. +- `RelativeTimeout` is zero. + +This message will create a new IBC packet with the provided `PacketData` and send it via the channel associated with the `Owner` and `ConnectionID`. +The `PacketData` is expected to contain a list of serialized `[]sdk.Msg` in the form of `CosmosTx`. Please note the signer field of each `sdk.Msg` must be the interchain account address. +When the packet is relayed to the host chain, the `PacketData` is unmarshalled and the messages are authenticated and executed. + +```go +type MsgSendTxResponse struct { + Sequence uint64 +} +``` + +The packet `Sequence` is returned in the message response. + +### CLI + +The following is an example usage of the controller CLI command used to send a transaction to be executed using an interchain account on the corresponding host chain. + +```bash +simd tx interchain-accounts controller send-tx connection-0 packet-data.json --from cosmos1m9l358xunhhwds0568za49mzhvuxx9uxre5tud +``` + +See below for example contents of `packet-data.json`. The CLI handler will unmarshal the following into `InterchainAccountPacketData` appropriately. + +```json +{ + "type":"TYPE_EXECUTE_TX", + "data":"CqIBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEoEBCkFjb3Ntb3MxNWNjc2hobXAwZ3N4MjlxcHFxNmc0em1sdG5udmdteXU5dWV1YWRoOXkybmM1emowc3psczVndGRkehItY29zbW9zMTBoOXN0YzV2Nm50Z2V5Z2Y1eGY5NDVuanFxNWgzMnI1M3VxdXZ3Gg0KBXN0YWtlEgQxMDAw", + "memo":"" +} +``` + +Note the `data` field is a base64 encoded byte string as per the [proto3 JSON encoding specification](https://developers.google.com/protocol-buffers/docs/proto3#json). + +A helper CLI is provided in the host submodule which can be used to generate the packet data JSON using the counterparty chain's binary. +It accepts a list of `sdk.Msg`s which will be encoded into the outputs `data` field. + +```bash +simd tx interchain-accounts host generate-packet-data '[{ + "@type":"/cosmos.bank.v1beta1.MsgSend", + "from_address":"cosmos15ccshhmp0gsx29qpqq6g4zmltnnvgmyu9ueuadh9y2nc5zj0szls5gtddz", + "to_address":"cosmos10h9stc5v6ntgeygf5xf945njqq5h32r53uquvw", + "amount": [ + { + "denom": "stake", + "amount": "1000" + } + ] +}]' +``` + +The host submodule also provides a helper CLI to inspect the events of interchain accounts packets by providing the channel ID and packet sequence: + +```bash + simd q interchain-accounts host packet-events channel-0 100 +``` + +### Atomicity + +As the Interchain Accounts module supports the execution of multiple transactions using the Cosmos SDK `Msg` interface, it provides the same atomicity guarantees as Cosmos SDK-based applications, leveraging the [`CacheMultiStore`](https://docs.cosmos.network/main/core/store.html#cachemultistore) architecture provided by the [`Context`](https://docs.cosmos.network/main/core/context.html) type. + +This provides atomic execution of transactions when using Interchain Accounts, where state changes are only committed if all `Msg`s succeed. diff --git a/docs/apps/interchain-accounts/overview.md b/docs/apps/interchain-accounts/overview.md index dc015aaf1e3..3886bc413c3 100644 --- a/docs/apps/interchain-accounts/overview.md +++ b/docs/apps/interchain-accounts/overview.md @@ -4,35 +4,32 @@ order: 1 # Overview -Learn about what the Interchain Accounts module is, and how to build custom modules that utilize Interchain Accounts functionality {synopsis} - +Learn about what the Interchain Accounts module is {synopsis} ## What is the Interchain Accounts module? -Interchain Accounts is the Cosmos SDK implementation of the ICS-27 protocol, which enables cross-chain account management built upon IBC. Chains using the Interchain Accounts module can programmatically create accounts on other chains and control these accounts via IBC transactions. +Interchain Accounts is the Cosmos SDK implementation of the ICS-27 protocol, which enables cross-chain account management built upon IBC. -Interchain Accounts exposes a simple-to-use API which means IBC application developers do not require an in-depth knowledge of the underlying low-level details of IBC or the ICS-27 protocol. +- How does an interchain account differ from a regular account? -Developers looking to build upon Interchain Accounts must write custom logic in their own IBC application module, called authentication modules. +Regular accounts use a private key to sign transactions. Interchain Accounts are instead controlled programmatically by counterparty chains via IBC packets. -- How is an interchain account different than a regular account? +## Concepts -Regular accounts use a private key to sign transactions on-chain. Interchain Accounts are instead controlled programmatically by separate chains via IBC transactions. Interchain Accounts are implemented as sub-accounts of the interchain accounts module account. +`Host Chain`: The chain where the interchain account is registered. The host chain listens for IBC packets from a controller chain which should contain instructions (e.g. Cosmos SDK messages) for which the interchain account will execute. -## Concepts +`Controller Chain`: The chain registering and controlling an account on a host chain. The controller chain sends IBC packets to the host chain to control the account. -`Host Chain`: The chain where the interchain account is registered. The host chain listens for IBC packets from a controller chain which should contain instructions (e.g. cosmos SDK messages) for which the interchain account will execute. +`Interchain Account`: An account on a host chain created using the ICS-27 protocol. An interchain account has all the capabilities of a normal account. However, rather than signing transactions with a private key, a controller chain will send IBC packets to the host chain which signals what transactions the interchain account should execute. -`Controller Chain`: The chain registering and controlling an account on a host chain. The controller chain sends IBC packets to the host chain to control the account. A controller chain must have at least one interchain accounts authentication module in order to act as a controller chain. +#### Deprecated `Authentication Module`: A custom IBC application module on the controller chain that uses the Interchain Accounts module API to build custom logic for the creation & management of interchain accounts. For a controller chain to utilize the interchain accounts module functionality, an authentication module is required. -`Interchain Account`: An account on a host chain. An interchain account has all the capabilities of a normal account. However, rather than signing transactions with a private key, a controller chain's authentication module will send IBC packets to the host chain which signals what transactions the interchain account should execute. - ## SDK Security Model SDK modules on a chain are assumed to be trustworthy. For example, there are no checks to prevent an untrustworthy module from accessing the bank keeper. -The implementation of ICS27 on ibc-go uses this assumption in its security considerations. The implementation assumes the authentication module will not try to open channels on owner addresses it does not control. +The implementation of ICS-27 in ibc-go uses this assumption in its security considerations. -The implementation assumes other IBC application modules will not bind to ports within the ICS27 namespace. +The implementation assumes other IBC application modules will not bind to ports within the ICS-27 namespace. diff --git a/docs/apps/interchain-accounts/parameters.md b/docs/apps/interchain-accounts/parameters.md index c4da7e2fdbf..bf0b3122201 100644 --- a/docs/apps/interchain-accounts/parameters.md +++ b/docs/apps/interchain-accounts/parameters.md @@ -48,7 +48,7 @@ For example, a Cosmos SDK based chain that elects to provide hosted Interchain A "allow_messages": ["/cosmos.staking.v1beta1.MsgDelegate", "/cosmos.gov.v1beta1.MsgVote"] } ``` -There is also a special wildcard `"*"` message type which allows any type of message to be executed by the interchain account. This must be the only message in the `allow_messages` array. +There is also a special wildcard `"*"` value which allows any type of message to be executed by the interchain account. This must be the only value in the `allow_messages` array. ``` "params": { diff --git a/docs/apps/interchain-accounts/transactions.md b/docs/apps/interchain-accounts/transactions.md deleted file mode 100644 index e17571a6e00..00000000000 --- a/docs/apps/interchain-accounts/transactions.md +++ /dev/null @@ -1,21 +0,0 @@ - - -# Transactions - -Learn about Interchain Accounts transaction execution {synopsis} - -## Executing a transaction - -As described in [Authentication Modules](./auth-modules.md#trysendtx) transactions are executed using the interchain accounts controller API and require a `Base Application` as outlined in [ICS30 IBC Middleware](https://github.com/cosmos/ibc/tree/master/spec/app/ics-030-middleware) to facilitate authentication. The method of authentication remains unspecified to provide flexibility for the authentication module developer. - -Transactions are executed via the ICS27 [`SendTx` API](./auth-modules.md#trysendtx). This must be invoked through an Interchain Accounts authentication module and follows the outlined path of execution below. Packet relaying semantics provided by the IBC core transport, authentication, and ordering (IBC/TAO) layer are omitted for brevity. - -![send-tx-flow](../../assets/send-interchain-tx.png "Transaction Execution") - -## Atomicity - -As the Interchain Accounts module supports the execution of multiple transactions using the Cosmos SDK `Msg` interface, it provides the same atomicity guarantees as Cosmos SDK-based applications, leveraging the [`CacheMultiStore`](https://docs.cosmos.network/main/core/store.html#cachemultistore) architecture provided by the [`Context`](https://docs.cosmos.network/main/core/context.html) type. - -This provides atomic execution of transactions when using Interchain Accounts, where state changes are only committed if all `Msg`s succeed. diff --git a/docs/package-lock.json b/docs/package-lock.json index f5fbc42f9fe..552c3164446 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -13093,9 +13093,9 @@ } }, "node_modules/url-parse": { - "version": "1.5.4", - "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.4.tgz", - "integrity": "sha512-ITeAByWWoqutFClc/lRZnFplgXgEZr3WJ6XngMM/N9DMIm4K8zXPCZ1Jdu0rERwO84w1WC5wkle2ubwTA4NTBg==", + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", "dependencies": { "querystringify": "^2.1.1", "requires-port": "^1.0.0" @@ -21175,9 +21175,9 @@ } }, "minimist": { - "version": "1.2.5", - "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz", - "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw==" + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.7.tgz", + "integrity": "sha512-bzfL1YUZsP41gmu/qjrEk0Q6i2ix/cVeAhbCbqH9u3zYutS1cLg00qhrD0M2MVdCcx4Sc0UpP2eBWo9rotpq6g==" }, "mississippi": { "version": "3.0.0", @@ -24588,9 +24588,9 @@ } }, "url-parse": { - "version": "1.5.4", - "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.4.tgz", - "integrity": "sha512-ITeAByWWoqutFClc/lRZnFplgXgEZr3WJ6XngMM/N9DMIm4K8zXPCZ1Jdu0rERwO84w1WC5wkle2ubwTA4NTBg==", + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", "requires": { "querystringify": "^2.1.1", "requires-port": "^1.0.0"