docs: channel upgrades tutorial (#5746)

* docs: channel upgrades tutorial * update title * add section about sending an incentivized packet * Apply suggestions from code review Co-authored-by: srdtrk <[email protected]> * lint fixes * added more here-be-dragons warnings regarding hermes version that will support the feature * address review comments * lint * Update docs/tutorials/02-channel-upgrades/02-setup-env.md Co-authored-by: DimitrisJim <[email protected]> --------- Co-authored-by: srdtrk <[email protected]> Co-authored-by: DimitrisJim <[email protected]>
cosmos · Jul 4, 2024 · 3696423 · 3696423
1 parent b99dccc
commit 3696423
Show file tree

Hide file tree

Showing 7 changed files with 713 additions and 0 deletions.
diff --git a/docs/tutorials/02-channel-upgrades/01-intro.md b/docs/tutorials/02-channel-upgrades/01-intro.md
@@ -0,0 +1,38 @@
+---
+title: Introduction
+sidebar_label: Introduction
+sidebar_position: 1
+slug: /channel-upgrades/intro
+---
+
+import HighlightTag from '@site/src/components/HighlightTag';
+import HighlightBox from '@site/src/components/HighlightBox';
+
+# Introduction
+
+<HighlightTag type="ibc-go" version="v8.1"/> <HighlightTag type="cosmos-sdk" version="v0.50"/>
+
+This is a tutorial for upgrading an existing ICS 20 transfer channel to wrap it with the ICS 29 Fee Middleware.
+
+<HighlightBox type="prerequisite" title="Prerequisites">
+
+- Basic Knowledge of Cosmos SDK.
+    - If you are new to Cosmos SDK, we recommend you to go through the first two categories of the [Developer Portal](https://tutorials.cosmos.network/academy/1-what-is-cosmos/).
+- Basic Knowledge of [the Fee Middleware module](https://ibc.cosmos.network/main/middleware/ics29-fee/overview).
+- Basic knowledge of [channel upgrades](https://ibc.cosmos.network/main/ibc/channel-upgrades).
+
+</HighlightBox>
+
+## Scope
+
+This tutorial will cover the process of upgrading an existing ICS 20 transfer channel to add packet incentivization using the Fee Middleware.
+
+<HighlightBox type="learning" title="Learning Goals">
+
+In this tutorial, you will:
+
+- Run two IBC-enabled blockchains locally.
+- Open an ICS 20 transfer channel using the Hermes relayer.
+- Upgrade the ICS 20 transfer channel to add ICS-29 Fee Middleware.
+
+</HighlightBox>
diff --git a/docs/tutorials/02-channel-upgrades/02-setup-env.md b/docs/tutorials/02-channel-upgrades/02-setup-env.md
@@ -0,0 +1,75 @@
+---
+title: Set Up Your Work Environment
+sidebar_label: Set Up Your Work Environment
+sidebar_position: 2
+slug: /channel-upgrades/setup-env
+---
+
+import HighlightBox from '@site/src/components/HighlightBox';
+
+# Set up your work environment
+
+On this page, you can find helpful links to set up your work environment.
+
+<HighlightBox type="info" title="Dependencies">
+
+In this section, you can find all you need to install:
+
+- [jq](https://jqlang.github.io/jq/)
+- [gm](https://github.com/informalsystems/gm/)
+- [ibc-go simd](https://github.com/cosmos/ibc-go/)
+- [Hermes v1.9.0](https://hermes.informal.systems/)
+
+</HighlightBox>
+
+## jq
+
+Install `jq` following the instructions on [its website](https://jqlang.github.io/jq/download/). Test if it is installed by running the following command:
+
+```bash
+jq --version
+```
+
+At the moment of writing this tutorial, the version of `jq` used was 1.6.
+
+## gm
+
+The [gaiad manager](https://github.com/informalsystems/gm) (`gm`) is a configurable command-line tool (CLI) that helps manage local gaiad networks. It can be used to easily and quickly run a local setup of multiple blockchains. Follow the installation steps [here](https://github.com/informalsystems/gm#how-to-run).
+
+## ibc-go simd
+
+Download the simd binary from the [v8.1.0 release](https://github.com/cosmos/ibc-go/releases/tag/v8.1.0). This chain binary has the Fee Middleware already wired up and wrapping the ICS 20 transfer application. If you want to know how to wire up the Fee Middleware, please read [this section](../01-fee/04-wire-feeibc-mod.md) from the Fee Middleware tutorial.
+
+## Hermes
+
+Install Hermes relayer version `v1.9.0` via cargo following the instructions on the [Hermes website](https://hermes.informal.systems/quick-start/installation.html#install-via-cargo) or by using the command below.
+
+```bash
+cargo install ibc-relayer-cli --version 1.9.0 --bin hermes --locked
+```
+
+Test if Hermes is installed by running the following command:
+
+```bash
+hermes version
+```
+
+# Folder structure
+
+This tutorial assumes the following folder structure:
+
+```text
+testing
+├── bin
+│   ├── chain1
+│   │   ├── simd
+│   │   └── proposal.json
+│   └── chain2
+│       └── simd
+├── gm
+└── hermes
+    ├── hermes
+    └── config.toml
+```
+
+`simd` if the chain binary that will be used to run 2 blockchains (`chain1` and `chain2`). THe folder `gm` will contain the data folders for both blockchains.
diff --git a/docs/tutorials/02-channel-upgrades/03-run-chains.md b/docs/tutorials/02-channel-upgrades/03-run-chains.md
@@ -0,0 +1,110 @@
+---
+title: Run 2 Cosmos SDK Blockchains Locally
+sidebar_label: Run 2 Cosmos SDK Blockchains Locally
+sidebar_position: 3
+slug: /channel-upgrades/run-chains
+---
+
+# Run 2 Cosmos SDK blockchains locally
+
+The gm tool uses a [configuration file](https://github.com/informalsystems/gm/blob/master/gm.toml). This tutorial uses the following configuration file for gm:
+
+```yaml title="gm.toml"
+[global]
+add_to_hermes=true
+home_dir="~/testing/gm"
+
+[global.hermes]
+binary="~/testing/hermes/hermes"
+config="~/testing/hermes/config.toml"
+
+[chain1]
+  gaiad_binary="~/testing/bin/chain1/simd"  
+  ports_start_at=27000
+
+[chain2]
+  gaiad_binary="~/testing/bin/chain2/simd" 
+  ports_start_at=27010
+```
+
+The configuration file needs to be placed in `$HOME/.gm`. This configuration file sets up 2 blockchains (`chain1` and `chain2`), each with 2 accounts (1 validator, 1 wallet). The ports where the CometBFT RPC interface for each chain is 27000 for `chain1` and 27010 for `chain2`.
+
+In order to shorten the voting period of governance proposal, we are going to change some of the `x/gov` module parameters in the `genesis.json` file, so that we can complete the upgrade faster. These are the changes needed in the `genesis.json` of `chain1`:
+
+```json title="genesis.json"
+"gov": {
+  "starting_proposal_id": "1",
+  "deposits": [],
+  "votes": [],
+  "proposals": [],
+  "deposit_params": null,
+  "voting_params": null,
+  "tally_params": null,
+  "params": {
+    "min_deposit": [
+      {
+        "denom": "stake",
+// minus-diff-line
+-       "amount": "10000000"
+// plus-diff-line
++       "amount": "100"
+      }
+    ],
+    "max_deposit_period": "172800s",
+// minus-diff-line
+-   "voting_period": "172800s",
+// plus-diff-line
++   "voting_period": "180s",
+    "quorum": "0.334000000000000000",
+// minus-diff-line
+-   "threshold": "0.500000000000000000",
+// plus-diff-line
++   "threshold": "0.300000000000000000",
+    "veto_threshold": "0.334000000000000000",
+    "min_initial_deposit_ratio": "0.000000000000000000",
+    "proposal_cancel_ratio": "0.500000000000000000",
+    "proposal_cancel_dest": "",
+    "expedited_voting_period": "86400s",
+    "expedited_threshold": "0.667000000000000000",
+    "expedited_min_deposit": [
+      {
+        "denom": "stake",
+        "amount": "50000000"
+      }
+    ],
+    "burn_vote_quorum": false,
+    "burn_proposal_deposit_prevote": false,
+    "burn_vote_veto": true,
+    "min_deposit_ratio": "0.010000000000000000"
+  },
+  "constitution": ""
+}
+```
+
+We start both blockchains by running the following command:
+
+```bash
+gm start
+```
+
+For convenience, we are going to store a few account addresses as variables in the current shell environment. Execute the following commands to store the relayer addresses on chains `chain1` and `chain2`, respectively:
+
+```bash
+export RLY_CHAIN1=$(simd keys show wallet -a \
+--keyring-backend test \
+--home ../../gm/chain1) && echo $RLY_CHAIN1;
+export RLY_CHAIN2=$(simd keys show wallet -a \
+--keyring-backend test \
+--home ../../gm/chain2) && echo $RLY_CHAIN2;
+```
+
+And execute also the following commands to store the validator account addresses on chains `chain1` and `chain2` that we will use throughout this tutorial:
+
+```bash
+export VALIDATOR_CHAIN1=$(simd keys show validator -a \
+--keyring-backend test \
+--home ../../gm/chain1) && echo $VALIDATOR_CHAIN1;
+export VALIDATOR_CHAIN2=$(simd keys show validator -a \
+--keyring-backend test \
+--home ../../gm/chain2) && echo $VALIDATOR_CHAIN2;
+```
diff --git a/docs/tutorials/02-channel-upgrades/04-open-transfer-channel.md b/docs/tutorials/02-channel-upgrades/04-open-transfer-channel.md
@@ -0,0 +1,167 @@
+---
+title: Open transfer channel
+sidebar_label: Open transfer channel
+sidebar_position: 4
+slug: /channel-upgrades/open-channel
+---
+
+# Open an ICS 20 transfer channel
+
+The relayer needs to submit transactions on both blockchains, so we run the following command to add the keys for the accounts on `chain1` and `chain2` that the relayer can use to submit transactions:
+
+```bash
+gm hermes keys
+```
+
+The relayer also needs a [configuration file](https://github.com/informalsystems/hermes/blob/master/config.toml). In this tutorial we will have the configuration file in the same folder as the relayer binary and specify it using the `--config` flag in each command.
+
+You can generate a default configuration by running:
+
+```bash
+gm hermes config
+```
+
+This tutorial has been completed with the following configuration file:
+
+```yaml
+[global]
+log_level = 'trace'
+
+[telemetry]
+enabled = true
+host = '127.0.0.1'
+port = 3001
+
+# Specify the mode to be used by the relayer. [Required]
+[mode]
+
+# Specify the client mode.
+[mode.clients]
+
+# Whether or not to enable the client workers. [Required]
+enabled = true
+
+# Whether or not to enable periodic refresh of clients. [Default: true]
+# Note: Even if this is disabled, clients will be refreshed automatically if
+#      there is activity on a connection or channel they are involved with.
+refresh = true
+
+# Whether or not to enable misbehaviour detection for clients. [Default: false]
+misbehaviour = true
+
+# Specify the connections mode.
+[mode.connections]
+
+# Whether or not to enable the connection workers for handshake completion. [Required]
+enabled = true
+
+[mode.channels]
+enabled = true
+
+# Specify the packets mode.
+[mode.packets]
+
+# Whether or not to enable the packet workers. [Required]
+enabled = true
+
+clear_interval = 1
+
+[[chains]]
+id = 'chain1'
+type = 'CosmosSdk'
+rpc_addr = 'http://localhost:27000'
+grpc_addr = 'http://localhost:27002'
+event_source = { mode = 'push', url = 'ws://127.0.0.1:27000/websocket', batch_delay = '500ms' }
+rpc_timeout = '15s'
+account_prefix = 'cosmos'
+key_name = 'wallet'
+store_prefix = 'ibc'
+gas_price = { price = 0.001, denom = 'stake' }
+max_gas = 1000000
+clock_drift = '5s'
+trusting_period = '14days'
+trust_threshold = { numerator = '1', denominator = '3' }
+
+[[chains]]
+id = 'chain2'
+type = 'CosmosSdk'
+rpc_addr = 'http://localhost:27010'
+grpc_addr = 'http://localhost:27012'
+event_source = { mode = 'push', url = 'ws://127.0.0.1:27010/websocket', batch_delay = '500ms' }
+rpc_timeout = '15s'
+account_prefix = 'cosmos'
+key_name = 'wallet'
+store_prefix = 'ibc'
+gas_price = { price = 0.001, denom = 'stake' }
+max_gas = 1000000
+clock_drift = '5s'
+trusting_period = '14days'
+trust_threshold = { numerator = '1', denominator = '3' }
+```
+
+With both blockchains running, we can run the following command in hermes to establish a connection and an ICS 20 transfer channel:
+
+```bash
+hermes --config config.toml create channel --a-chain chain1 \
+--b-chain chain2 \
+--a-port transfer \
+--b-port transfer \
+--new-client-connection
+```
+
+When both the connection and channel handshakes complete, the output on the console looks like this:
+
+```bash
+SUCCESS Channel {
+  ordering: Unordered,
+  a_side: ChannelSide {
+    chain: BaseChainHandle {
+      chain_id: ChainId {
+        id: "chain1",
+        version: 0,
+      },
+      runtime_sender: Sender { .. },
+    },
+    client_id: ClientId(
+      "07-tendermint-0",
+    ),
+    connection_id: ConnectionId(
+      "connection-0",
+    ),
+    port_id: PortId(
+      "transfer",
+    ),
+    channel_id: Some(
+      ChannelId(
+        "channel-0",
+      ),
+    ),
+    version: None,
+  },
+  b_side: ChannelSide {
+    chain: BaseChainHandle {
+      chain_id: ChainId {
+        id: "chain2",
+        version: 0,
+      },
+      runtime_sender: Sender { .. },
+    },
+    client_id: ClientId(
+      "07-tendermint-0",
+    ),
+    connection_id: ConnectionId(
+      "connection-0",
+    ),
+    port_id: PortId(
+      "transfer",
+    ),
+    channel_id: Some(
+      ChannelId(
+        "channel-0",
+      ),
+    ),
+    version: None,
+  },
+  connection_delay: 0ns,
+}
+```