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 <[email protected]> * Update docs/apps/interchain-accounts/messages.md Co-authored-by: Carlos Rodriguez <[email protected]> * applying suggestions from review * updating future improvements section of active channels Co-authored-by: Charly <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]>
cosmos · Nov 2, 2022 · 47e1c9a · 47e1c9a
1 parent 393247b
commit 47e1c9a
Show file tree

Hide file tree

Showing 9 changed files with 175 additions and 62 deletions.
diff --git 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
@@ -1,15 +1,13 @@
 <!--
-order: 3
+order: 5
 -->
 
 # 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)
diff --git a/docs/apps/interchain-accounts/auth-modules.md b/docs/apps/interchain-accounts/auth-modules.md
@@ -1,9 +1,13 @@
 <!--
-order: 2
+order: 6
 -->
 
 # 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
@@ -1,5 +1,5 @@
 <!--
-order: 3
+order: 2
 -->
 
 # Integration

diff --git a/docs/apps/interchain-accounts/messages.md b/docs/apps/interchain-accounts/messages.md
@@ -0,0 +1,124 @@
+<!--
+order: 3
+-->
+
+# 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
@@ -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
@@ -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
diff --git a/docs/package-lock.json b/docs/package-lock.json