transfer (total escrow): add documentation and migration docs (#3509)

* add docs for total escrow feature * revert change * fix tag * Update docs/migrations/v7-to-v7_1.md --------- Co-authored-by: colin axnér <[email protected]>
cosmos · Apr 27, 2023 · a448960 · a448960
1 parent 0d9d697
commit a448960
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 3 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -343,6 +343,11 @@ module.exports = {
                   directory: false,
                   path: "/apps/transfer/authorizations.html",
                 },
+                {
+                  title: "Client",
+                  directory: false,
+                  path: "/apps/transfer/client.html",
+                },
               ],
             },
           ],

diff --git a/docs/apps/transfer/authorizations.md b/docs/apps/transfer/authorizations.md
@@ -1,3 +1,7 @@
+<!--
+order: 8
+-->
+
 # `TransferAuthorization`
 
 `TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.MsgTransfer`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `x/authz` module.

diff --git a/docs/apps/transfer/client.md b/docs/apps/transfer/client.md
@@ -0,0 +1,66 @@
+<!--
+order: 9
+-->
+
+# Client
+
+## CLI
+
+A user can query and interact with the `transfer` module using the CLI. Use the `--help` flag to discover the available commands:
+
+### Query
+
+The `query` commands allow users to query `transfer` state.
+
+```shell
+simd query ibc-transfer --help
+```
+
+#### `total-escrow`
+
+The `total-escrow` command allows users to query the total amount in escrow for a particular coin denomination regardless of the transfer channel from where the coins where sent out.
+
+```shell
+simd query ibc-transfer total-escrow [denom] [flags]
+```
+
+Example:
+
+```shell
+simd query ibc-transfer total-escrow samoleans
+```
+
+Example Output:
+
+```shell
+amount: "100"
+```
+
+## gRPC
+
+A user can query the `transfer` module using gRPC endpoints.
+
+### `TotalEscrowForDenom`
+
+The `TotalEscrowForDenom` endpoint allows users to query the total amount in escrow for a particular coin denomination regardless of the transfer channel from where the coins where sent out.
+
+```shell
+ibc.applications.transfer.v1.Query/TotalEscrowForDenom
+```
+
+Example:
+
+```shell
+grpcurl -plaintext \
+  -d '{"denom":"samoleans"}' \
+  localhost:9090 \
+  ibc.applications.transfer.v1.Query/TotalEscrowForDenom
+```
+
+Example output:
+
+```shell
+{
+  "amount": "100"
+}
+```
diff --git a/docs/migrations/v7-to-v7_1.md b/docs/migrations/v7-to-v7_1.md
@@ -14,15 +14,17 @@ There are four sections based on the four potential user groups of this document
 
 ## Chains
 
+### 09-localhost migration
+
 In the previous release of ibc-go, the localhost `v1` light client module was deprecated and removed. The ibc-go `v7.1.0` release introduces `v2` of the 09-localhost light client module.
 
 <!-- TODO: Update the links to use release version instead of feat branch -->
-An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/09-localhost/modules/core/module.go#L133-L145) is configured in the core IBC module to set the localhost `ClientState` and sentinel `ConnectionEnd` in state.
+An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/release/v7.1.x/modules/core/module.go#L127-L145) is configured in the core IBC module to set the localhost `ClientState` and sentinel `ConnectionEnd` in state.
 
 In order to use the 09-localhost client chains must update the `AllowedClients` parameter in the 02-client submodule of core IBC. This can be configured directly in the application upgrade handler or alternatively updated via the legacy governance parameter change proposal.
 We __strongly__ recommend chains to perform this action so that intra-ledger communication can be carried out using the familiar IBC interfaces.
 
-See the upgrade handler code sample provided below or [follow this link](https://github.com/cosmos/ibc-go/blob/09-localhost/testing/simapp/upgrades/upgrades.go#L85) for the upgrade handler used by the ibc-go simapp.
+See the upgrade handler code sample provided below or [follow this link](https://github.com/cosmos/ibc-go/blob/release/v7.1.x/testing/simapp/upgrades/upgrades.go#L85) for the upgrade handler used by the ibc-go simapp.
 
 ```go
 func CreateV7LocalhostUpgradeHandler(
@@ -41,7 +43,9 @@ func CreateV7LocalhostUpgradeHandler(
 }
 ```
 
-[For more information please refer to the 09-localhost light client module documentation](../ibc/light-clients/localhost/overview.md).
+### Transfer migration
+
+An automatic migration handler (TODO: add link after backport to v7.1.x is merged) is configured in the transfer module to set the total amount in escrow for all denominations of coins that have been sent out. For each denomination a state entry is added with the total amount of coins in escrow regardless of the channel from which they were transferred.
 
 ## IBC Apps