Skip to content

Commit

Permalink
docs: use MsgRecoverClient in docs (#4580)
Browse files Browse the repository at this point in the history
* docs: recover client update

* Update docs/ibc/proposals.md

* Apply suggestions from code review

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>

---------

Co-authored-by: Carlos Rodriguez <carlos@interchain.io>
  • Loading branch information
colin-axner and Carlos Rodriguez authored Sep 6, 2023
1 parent a374631 commit ffcb06d
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 26 deletions.
9 changes: 7 additions & 2 deletions docs/architecture/adr-026-ibc-client-recovery-mechanisms.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
- 2021/05/20: Revision to simplify consensus state copying, remove initial height
- 2022/04/08: Revision to deprecate AllowUpdateAfterExpiry and AllowUpdateAfterMisbehaviour
- 2022/07/15: Revision to allow updating of TrustingPeriod
- 2023/09/05: Revision to migrate from gov v1beta1 to gov v1

## Status

Expand Down Expand Up @@ -44,16 +45,19 @@ We elect not to deal with chains which have actually halted, which is necessaril
1. `allow_update_after_misbehaviour` (boolean, default true). Note that this flag has been deprecated, it remains to signal intent but checks against this value will not be enforced.
1. Require Tendermint light clients (ICS 07) to expose the following additional state mutation functions
1. `Unfreeze()`, which unfreezes a light client after misbehaviour and clears any frozen height previously set
1. Add a new governance proposal type, `ClientUpdateProposal`, in the `x/ibc` module
1. Extend the base `Proposal` with two client identifiers (`string`).
1. Add a new governance proposal with `MsgRecoverClient`.
1. Create a new Msg with two client identifiers (`string`) and a signer.
1. The first client identifier is the proposed client to be updated. This client must be either frozen or expired.
1. The second client is a substitute client. It carries all the state for the client which may be updated. It must have identitical client and chain parameters to the client which may be updated (except for latest height, frozen height, and chain-id). It should be continually updated during the voting period.
1. If this governance proposal passes, the client on trial will be updated to the latest state of the substitute.
1. The signer must be the authority set for the ibc module.

Previously, `AllowUpdateAfterExpiry` and `AllowUpdateAfterMisbehaviour` were used to signal the recovery options for an expired or frozen client, and governance proposals were not allowed to overwrite the client if these parameters were set to false. However, this has now been deprecated because a code migration can overwrite the client and consensus states regardless of the value of these parameters. If governance would vote to overwrite a client or consensus state, it is likely that governance would also be willing to perform a code migration to do the same.

In addition, `TrustingPeriod` was initally not allowed to be updated by a client upgrade proposal. However, due to the number of situations experienced in production where the `TrustingPeriod` of a client should be allowed to be updated because of ie: initial misconfiguration for a canonical channel, governance should be allowed to update this client parameter.

In versions older than ibc-go v8, `MsgRecoverClient` was a governance proposal type `ClientUpdateProposal`. It has been removed and replaced by `MsgRecoverClient` in the migration from goverance v1beta1 to governacne v1.

Note that this should NOT be lightly updated, as there may be a gap in time between when misbehaviour has occured and when the evidence of misbehaviour is submitted. For example, if the `UnbondingPeriod` is 2 weeks and the `TrustingPeriod` has also been set to two weeks, a validator could wait until right before `UnbondingPeriod` finishes, submit false information, then unbond and exit without being slashed for misbehaviour. Therefore, we recommend that the trusting period for the 07-tendermint client be set to 2/3 of the `UnbondingPeriod`.

Note that clients frozen due to misbehaviour must wait for the evidence to expire to avoid becoming refrozen.
Expand Down Expand Up @@ -83,3 +87,4 @@ No neutral consequences.
- [Prior discussion](https://github.com/cosmos/ics/issues/421)
- [Epoch number discussion](https://github.com/cosmos/ics/issues/439)
- [Upgrade plan discussion](https://github.com/cosmos/ics/issues/445)
- [Migration from gov v1beta1 to gov v1](https://github.com/cosmos/ibc-go/issues/3672)
34 changes: 10 additions & 24 deletions docs/ibc/proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,6 @@ See also the relevant documentation: [ADR-026, IBC client recovery mechanisms](.
## Preconditions

- The chain is updated with ibc-go >= v1.1.0.
- There exists an active client (with a known client identifier) for the same counterparty chain as the expired client.
- The governance deposit.

Expand All @@ -76,11 +75,10 @@ The client is attached to the expected Akash `chain-id`. Note that although the

### Step 2

If the chain has been updated to ibc-go >= v1.1.0, anyone can submit the governance proposal to recover the client by executing this via CLI.
Anyone can submit the governance proposal to recover the client by executing the following via CLI.
If the chain is on an ibc-go version older than v8, please see the [relevant documentation](https://ibc.cosmos.network/v6.1.0/ibc/proposals.html).

> Note that the Cosmos SDK has updated how governance proposals are submitted in SDK v0.46, now requiring to pass a .json proposal file
- From SDK v0.46.x onwards
- From ibc-go v8 onwards

```shell
<binary> tx gov submit-proposal [path-to-proposal-json]
Expand All @@ -92,30 +90,20 @@ If the chain has been updated to ibc-go >= v1.1.0, anyone can submit the governa
{
"messages": [
{
"@type": "/ibc.core.client.v1.ClientUpdateProposal",
"title": "title_string",
"description": "description_string",
"@type": "/ibc.core.client.v1.MsgRecoverClient",
"subject_client_id": "expired_client_id_string",
"substitute_client_id": "active_client_id_string"
"substitute_client_id": "active_client_id_string",
"signer": "<gov-address>"
}
],
"metadata": "<metadata>",
"deposit": "10stake"
"title": "My proposal",
"summary": "A short summary of my proposal",
"expedited": false
}
```

Alternatively there's a legacy command (that is no longer recommended though):

```shell
<binary> tx gov submit-legacy-proposal update-client <expired-client-id> <active-client-id>
```

- Until SDK v0.45.x

```shell
<binary> tx gov submit-proposal update-client <expired-client-id> <active-client-id>
```

The `<expired-client-id>` identifier is the proposed client to be updated. This client must be either frozen or expired.

The `<active-client-id>` represents a substitute client. It carries all the state for the client which may be updated. It must have identical client and chain parameters to the client which may be updated (except for latest height, frozen height, and chain ID). It should be continually updated during the voting period.
Expand All @@ -124,6 +112,4 @@ After this, all that remains is deciding who funds the governance deposit and en

## Important considerations

Please note that from v1.0.0 of ibc-go it will not be allowed for transactions to go to expired clients anymore, so please update to at least this version to prevent similar issues in the future.

Please also note that if the client on the other end of the transaction is also expired, that client will also need to update. This process updates only one client.
Please note that if the client on the other end of the transaction is also expired, that client will also need to update. This process updates only one client.

0 comments on commit ffcb06d

Please sign in to comment.