Hermes CLI for upgrading client

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

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
+ }
+ }
+ }
+ ]
+ }
+ ```

modules/src/events.rs

@@ -34,6 +34,7 @@ pub enum IbcEvent {
 
  CreateClient(ClientEvents::CreateClient),
  UpdateClient(ClientEvents::UpdateClient),
+ UpgradeClient(ClientEvents::UpgradeClient),
  ClientMisbehavior(ClientEvents::ClientMisbehavior),
 
  OpenInitConnection(ConnectionEvents::OpenInit),
@@ -111,6 +112,7 @@ impl IbcEvent {
  IbcEvent::NewBlock(ev) => ev.set_height(height),
  IbcEvent::CreateClient(ev) => ev.set_height(height),
  IbcEvent::UpdateClient(ev) => ev.set_height(height),
+ IbcEvent::UpgradeClient(ev) => ev.set_height(height),
  IbcEvent::ClientMisbehavior(ev) => ev.set_height(height),
  IbcEvent::OpenInitConnection(ev) => ev.set_height(height),
  IbcEvent::OpenTryConnection(ev) => ev.set_height(height),

modules/src/ics02_client/context.rs

@@ -6,7 +6,7 @@ use crate::ics02_client::client_consensus::AnyConsensusState;
 use crate::ics02_client::client_state::AnyClientState;
 use crate::ics02_client::client_type::ClientType;
 use crate::ics02_client::error::Error;
-use crate::ics02_client::handler::ClientResult::{self, Create, Update};
+use crate::ics02_client::handler::ClientResult::{self, Create, Update, Upgrade};
 use crate::ics24_host::identifier::ClientId;
 use crate::Height;
 
@@ -47,6 +47,9 @@ pub trait ClientKeeper {
  )?;
  Ok(())
  }
+ Upgrade(_) => {
+ unimplemented!()
+ }
  }
  }
 

modules/src/ics02_client/error.rs

@@ -2,6 +2,8 @@ use anomaly::{BoxError, Context};
 use thiserror::Error;
 
 use crate::ics02_client::client_type::ClientType;
+use crate::ics23_commitment::error::Kind as Ics23Kind;
+use crate::ics24_host::error::ValidationKind;
 use crate::ics24_host::identifier::ClientId;
 use crate::Height;
 
@@ -21,6 +23,9 @@ pub enum Kind {
  #[error("client not found: {0}")]
  ClientNotFound(ClientId),
 
+ #[error("client is frozen: {0}")]
+ ClientFrozen(ClientId),
+
  #[error("consensus state not found at: {0} at height {1}")]
  ConsensusStateNotFound(ClientId, Height),
 
@@ -54,8 +59,8 @@ pub enum Kind {
  #[error("invalid raw client consensus state")]
  InvalidRawConsensusState,
 
- #[error("invalid identifer")]
- InvalidIdentifier,
+ #[error("invalid client identifier: validation error: {0}")]
+ InvalidClientIdentifier(ValidationKind),
 
  #[error("invalid raw header")]
  InvalidRawHeader,
@@ -66,6 +71,12 @@ pub enum Kind {
  #[error("invalid address")]
  InvalidAddress,
 
+ #[error("invalid proof for the upgraded client state")]
+ InvalidUpgradeClientProof(Ics23Kind),
+
+ #[error("invalid proof for the upgraded consensus state")]
+ InvalidUpgradeConsensusStateProof(Ics23Kind),
+
  #[error("mismatch between client and arguments types, expected: {0:?}")]
  ClientArgsTypeMismatch(ClientType),
 

modules/src/ics02_client/events.rs

@@ -12,6 +12,7 @@ use std::convert::{TryFrom, TryInto};
 /// The content of the `type` field for the event that a chain produces upon executing the create client transaction.
 const CREATE_EVENT_TYPE: &str = "create_client";
 const UPDATE_EVENT_TYPE: &str = "update_client";
+const UPGRADE_EVENT_TYPE: &str = "upgrade_client";
 
 /// The content of the `key` field for the attribute containing the client identifier.
 const CLIENT_ID_ATTRIBUTE_KEY: &str = "client_id";
@@ -30,6 +31,9 @@ pub fn try_from_tx(event: &tendermint::abci::Event) -> Option<IbcEvent> {
  UPDATE_EVENT_TYPE => Some(IbcEvent::UpdateClient(UpdateClient(
  extract_attributes_from_tx(event),
  ))),
+ UPGRADE_EVENT_TYPE => Some(IbcEvent::UpgradeClient(UpgradeClient(
+ extract_attributes_from_tx(event),
+ ))),
  _ => None,
  }
 }
@@ -77,7 +81,7 @@ impl From<NewBlock> for IbcEvent {
  }
 }
 
-#[derive(Debug, Deserialize, Serialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Attributes {
  pub height: Height,
  pub client_id: ClientId,
@@ -214,3 +218,19 @@ impl From<ClientMisbehavior> for IbcEvent {
  IbcEvent::ClientMisbehavior(v)
  }
 }
+
+/// Signals a recent upgrade of an on-chain client (IBC Client).
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize, Serialize)]
+pub struct UpgradeClient(Attributes);
+
+impl UpgradeClient {
+ pub fn set_height(&mut self, height: Height) {
+ self.0.height = height;
+ }
+}
+
+impl From<Attributes> for UpgradeClient {
+ fn from(attrs: Attributes) -> Self {
+ UpgradeClient(attrs)
+ }
+}

modules/src/ics02_client/handler.rs

@@ -7,11 +7,13 @@ use crate::ics02_client::msgs::ClientMsg;
 
 pub mod create_client;
 pub mod update_client;
+pub mod upgrade_client;
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum ClientResult {
  Create(create_client::Result),
  Update(update_client::Result),
+ Upgrade(upgrade_client::Result),
 }
 
 /// General entry point for processing any message related to ICS2 (client functions) protocols.
@@ -22,5 +24,6 @@ where
  match msg {
  ClientMsg::CreateClient(msg) => create_client::process(ctx, msg),
  ClientMsg::UpdateClient(msg) => update_client::process(ctx, msg),
+ ClientMsg::UpgradeClient(msg) => upgrade_client::process(ctx, msg),
  }
 }

modules/src/ics02_client/handler/update_client.rs

@@ -80,7 +80,7 @@ mod tests {
  use crate::ics02_client::client_state::AnyClientState;
  use crate::ics02_client::error::Kind;
  use crate::ics02_client::handler::dispatch;
- use crate::ics02_client::handler::ClientResult::{Create, Update};
+ use crate::ics02_client::handler::ClientResult::Update;
  use crate::ics02_client::header::Header;
  use crate::ics02_client::msgs::update_client::MsgUpdateAnyClient;
  use crate::ics02_client::msgs::ClientMsg;
@@ -128,7 +128,7 @@ mod tests {
  )))
  )
  }
- Create(_) => panic!("update handler result has type CreateResult"),
+ _ => panic!("update handler result has incorrect type"),
  }
  }
  Err(err) => {