Hermes CLI for upgrading client (informalsystems#723)

* Added domain type def. Also cleaned-up the documentation, which looked very sloppy. https://docs.rs/ibc/0.1.1/ibc/ics02_client/msgs/index.html * Added partial handler & command * Added upgrade proto files. Added Cargo.lock for proto-compiler * Prep for query_upgraded_client_state * Method & support for querying ugpraded client state * Support for querying the upgraded consensus state * Minor dev scripts enhancements & bugs * Added guide. Uses patched Go relayer * Proto conversion for upgrade msg. Refactored upgrade() impl * Fix missing signer bug * Update msg bf. upgrade. Event parsing * Changelog. Revised guide * Aesthetic nits based on file review * Clarifications in the test instructions * Documented Go relayer version in testing instructions * Possible fix for informalsystems#734 * changelog & method documentation * Apply suggestions from code review Co-authored-by: Romain Ruetschi <romain@informal.systems> * Added more derived trait bounds on module events * Adapt to newer Ics02 structure. * Added Protobuf impl for MsgUpgradeAnyClient * FMT * Added upgrade-chain CLI and updated instructions * Remove a clone and turn zero_custom_fields into a static method * Whitespace and nitpick * Remove obsolete TODO Co-authored-by: Romain Ruetschi <romain@informal.systems> Co-authored-by: Anca Zamfir <zamfiranca@gmail.com>
hu55a1n1 · Mar 23, 2021 · 8247868 · 8247868
1 parent 2f0d1d0
commit 8247868
Show file tree

Hide file tree

Showing 19 changed files with 801 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,7 @@
 - [ibc-relayer-cli]
   - Added `create connection` CLI ([#630])
   - Proposed ADR 006 to describe Hermes v0.2.0 use-cases ([#637])
+  - Added `client-upgrade` CLI ([#357])
   - Update gaia to version 4.1.0 for e2e tests on CI ([#702])
 
 ### IMPROVEMENTS
@@ -33,7 +34,7 @@
   - [nothing yet]
 
 - [ibc-relayer-cli]
-  - [nothing yet]
+  - Clarified success path for updating a client that is already up-to-date ([#734])
 
 ### BUG FIXES
 
@@ -61,6 +62,7 @@
   - [nothing yet]
 
 [#352]: https://github.com/informalsystems/ibc-rs/issues/352
+[#357]: https://github.com/informalsystems/ibc-rs/issues/357
 [#416]: https://github.com/informalsystems/ibc-rs/issues/416
 [#561]: https://github.com/informalsystems/ibc-rs/issues/561
 [#599]: https://github.com/informalsystems/ibc-rs/issues/599
@@ -72,6 +74,7 @@
 [#699]: https://github.com/informalsystems/ibc-rs/issues/699
 [#700]: https://github.com/informalsystems/ibc-rs/pull/700
 [#702]: https://github.com/informalsystems/ibc-rs/issues/702
+[#734]: https://github.com/informalsystems/ibc-rs/issues/734
 [#736]: https://github.com/informalsystems/ibc-rs/issues/736
 [#740]: https://github.com/informalsystems/ibc-rs/issues/740
 [#752]: https://github.com/informalsystems/ibc-rs/issues/752

diff --git a/guide/src/upgrade_test.md b/guide/src/upgrade_test.md
@@ -0,0 +1,166 @@
+## Prerequisites
+
+- gaiad `(v4.1.*)`, for example:
+
+```shell
+$ gaiad version --long | head -n4
+name: gaia
+server_name: gaiad
+version: 4.1.2
+commit: 95b07e641d1f69ee12dd911e92b1679f2c64d385
+```
+
+## Testing procedure
+
+1. Start two gaia instances and initialize hermes:
+
+    ```shell
+    $ ./scripts/dev-env ~/.hermes/config.toml ibc-0 ibc-1
+    ```
+    The `one-chain` script is invoked for each chain and modifies the `genesis.json` file to use a short window for governance proposals (`200s` for `max_deposit_period` and `voting_period`). Therefore, an upgrade proposal can be submitted, voted on and accepted within a short time.
+
+2. Create one client on `ibc-1` for `ibc-0`:
+
+    ```shell
+    $ hermes tx raw create-client ibc-1 ibc-0
+    ```
+
+3. Create and submit an upgrade plan for chain `ibc-0`:
+
+    Use the hermes test command to make an upgrade proposal. In the example below a software upgrade proposal is made for `ibc-0`, for the height `300` blocks from latest height. `10000000stake` is deposited.
+    The proposal includes the upgraded client state constructed from the state of `07-tendermint-0` client on `ibc-1` that was created in the previous step. In addition, the `unbonding_period` of the client is set to some new value (`400h`)
+
+    ```shell
+    $ hermes tx raw upgrade-chain ibc-0 ibc-1 07-tendermint-0 10000000 300
+    ```
+
+    Note that the height offset should be picked such that the proposal plan height is reached after the `200s` voting period.
+
+ 4. Verify that the proposal was accepted:
+
+    Query the upgrade plan to check that it was submitted correctly. Note the `height` at which the proposal will take effect (chain halts). Also `status: PROPOSAL_STATUS_VOTING_PERIOD`.
+
+    ```shell
+    $ gaiad query gov proposal 1 --home data/ibc-0/
+
+    content:
+      '@type': /cosmos.upgrade.v1beta1.SoftwareUpgradeProposal
+      description: upgrade the chain software and unbonding period
+      plan:
+        height: "382"
+        info: upgrade the chain software and unbonding period
+        name: test
+        time: "0001-01-01T00:00:00Z"
+        upgraded_client_state:
+          '@type': /ibc.lightclients.tendermint.v1.ClientState
+          allow_update_after_expiry: false
+          allow_update_after_misbehaviour: false
+          chain_id: ibc-0
+          frozen_height:
+            revision_height: "0"
+            revision_number: "0"
+          latest_height:
+            revision_height: "383"
+            revision_number: "0"
+          max_clock_drift: 0s
+          proof_specs:
+    ...
+          trust_level:
+            denominator: "0"
+            numerator: "0"
+          trusting_period: 0s
+          unbonding_period: 1440000s
+          upgrade_path:
+          - upgrade
+          - upgradedIBCState
+      title: upgrade_ibc_clients
+    deposit_end_time: "2021-03-23T17:25:42.543572Z"
+    final_tally_result:
+      abstain: "0"
+      "no": "0"
+      no_with_veto: "0"
+      "yes": "0"
+    proposal_id: "1"
+    status: PROPOSAL_STATUS_VOTING_PERIOD
+    submit_time: "2021-03-23T17:22:22.543572Z"
+    total_deposit:
+    - amount: "10000000"
+      denom: stake
+    voting_end_time: "2021-03-23T17:25:42.543572Z"
+    voting_start_time: "2021-03-23T17:22:22.543572Z"
+    ```
+
+ 5. Vote on the proposal
+
+    The parameter `1` should match the `proposal_id:` from the upgrade proposal submitted at step 3. This command must be issued while the proposal status is `PROPOSAL_STATUS_VOTING_PERIOD`.
+
+    ```shell
+    gaiad tx gov vote 1 yes --home data/ibc-0/data/ --keyring-backend test --keyring-dir data/ibc-0/ --chain-id ibc-0 --from validator
+    ```
+
+    Wait approximately 200 seconds until the proposal changes status to `PROPOSAL_STATUS_PASSED`. Note the `final tally_result` that includes the vote submitted in previous step.
+
+    ```shell
+    $ gaiad query gov proposal 1 --home data/ibc-0/
+
+    content:
+      '@type': /cosmos.upgrade.v1beta1.SoftwareUpgradeProposal
+      description: upgrade the chain software and unbonding period
+      plan:
+    ...
+    final_tally_result:
+      abstain: "0"
+      "no": "0"
+      no_with_veto: "0"
+      "yes": "100000000000"
+    proposal_id: "1"
+    status: PROPOSAL_STATUS_PASSED
+    submit_time: "2021-03-23T17:22:22.543572Z"
+    total_deposit:
+    - amount: "10000000"
+      denom: stake
+    voting_end_time: "2021-03-23T17:25:42.543572Z"
+    voting_start_time: "2021-03-23T17:22:22.543572Z"
+    ```
+
+6. Test the `upgrade-client` CLI
+
+    The following command performs the upgrade for client `07-tendermint-0`. It outputs two events, one for the updated client state, and another for the upgraded state.
+
+    ```shell
+    $ hermes tx raw upgrade-client ibc-1 ibc-0 07-tendermint-0
+
+    {
+      "status": "success",
+      "result": [
+        {
+          "UpdateClient": {
+            "client_id": "07-tendermint-0",
+            "client_type": "Tendermint",
+            "consensus_height": {
+              "revision_height": 332,
+              "revision_number": 0
+            },
+            "height": {
+              "revision_height": 404,
+              "revision_number": 1
+            }
+          }
+        },
+        {
+          "UpgradeClient": {
+            "client_id": "07-tendermint-0",
+            "client_type": "Tendermint",
+            "consensus_height": {
+              "revision_height": 333,
+              "revision_number": 0
+            },
+            "height": {
+              "revision_height": 404,
+              "revision_number": 1
+            }
+          }
+        }
+      ]
+    }
+    ```
diff --git a/relayer-cli/src/commands/tx.rs b/relayer-cli/src/commands/tx.rs
@@ -1,13 +1,14 @@
 //! `tx` subcommand
 use abscissa_core::{Command, Help, Options, Runnable};
 
-use crate::commands::tx::client::{TxCreateClientCmd, TxUpdateClientCmd};
+use crate::commands::tx::client::{TxCreateClientCmd, TxUpdateClientCmd, TxUpgradeClientCmd};
 
 mod channel;
 mod client;
 mod connection;
 mod packet;
 mod transfer;
+mod upgrade;
 
 /// `tx` subcommand
 #[derive(Command, Debug, Options, Runnable)]
@@ -35,6 +36,10 @@ pub enum TxRawCommands {
     #[options(help = "Update the specified client on destination chain")]
     UpdateClient(TxUpdateClientCmd),
 
+    /// The `tx raw upgrade-client` subcommand. Submits a MsgUpgradeClient in a transaction to a chain.
+    #[options(help = "Upgrade the specified client on destination chain")]
+    UpgradeClient(TxUpgradeClientCmd),
+
     /// The `tx raw conn-init` subcommand
     #[options(help = "Initialize a connection (ConnectionOpenInit)")]
     ConnInit(connection::TxRawConnInitCmd),
@@ -86,4 +91,8 @@ pub enum TxRawCommands {
     /// The `tx raw packet-ack` subcommand
     #[options(help = "Relay acknowledgment packets")]
     PacketAck(packet::TxRawPacketAckCmd),
+
+    /// The `tx raw upgrade-chain` subcommand
+    #[options(help = "Send an upgrade plan")]
+    UpgradeChain(upgrade::TxUpgradeChainCmd),
 }
diff --git a/relayer-cli/src/commands/tx/client.rs b/relayer-cli/src/commands/tx/client.rs
@@ -1,4 +1,5 @@
 use abscissa_core::{Command, Options, Runnable};
+use tracing::info;
 
 use ibc::events::IbcEvent;
 use ibc::ics24_host::identifier::{ChainId, ClientId};
@@ -7,7 +8,7 @@ use ibc_relayer::foreign_client::ForeignClient;
 
 use crate::application::app_config;
 use crate::commands::cli_utils::{ChainHandlePair, SpawnOptions};
-use crate::conclude::Output;
+use crate::conclude::{exit_with_unrecoverable_error, Output};
 use crate::error::{Error, Kind};
 
 #[derive(Clone, Command, Debug, Options)]
@@ -101,3 +102,52 @@ impl Runnable for TxUpdateClientCmd {
         }
     }
 }
+
+#[derive(Clone, Command, Debug, Options)]
+pub struct TxUpgradeClientCmd {
+    #[options(free, required, help = "identifier of the destination chain")]
+    dst_chain_id: ChainId,
+
+    #[options(
+        free,
+        required,
+        help = "identifier of the chain which underwent upgrade (source chain)"
+    )]
+    src_chain_id: ChainId,
+
+    #[options(
+        free,
+        required,
+        help = "identifier of the client to be upgraded on destination chain"
+    )]
+    dst_client_id: ClientId,
+}
+
+impl Runnable for TxUpgradeClientCmd {
+    fn run(&self) {
+        let config = app_config();
+
+        let spawn_options = SpawnOptions::override_store_config(StoreConfig::memory());
+        let chains = ChainHandlePair::spawn_with(
+            spawn_options,
+            &config,
+            &self.src_chain_id,
+            &self.dst_chain_id,
+        )
+        .unwrap_or_else(exit_with_unrecoverable_error);
+
+        info!("Started the chain runtimes");
+
+        // Instantiate the client hosted on the destination chain, which is targeting headers for
+        // the source chain.
+        let client = ForeignClient::find(chains.src, chains.dst, &self.dst_client_id)
+            .unwrap_or_else(exit_with_unrecoverable_error);
+
+        let outcome = client.upgrade();
+
+        match outcome {
+            Ok(receipt) => Output::success(receipt).exit(),
+            Err(e) => Output::error(format!("{}", e)).exit(),
+        }
+    }
+}