add genesis restart docs (#247)

* add genesis restart docs * add small note
cosmos · Jul 14, 2021 · 484cedc · 484cedc
1 parent fa404e5
commit 484cedc
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 4 deletions.
diff --git a/docs/ibc/upgrades/genesis-restart.md b/docs/ibc/upgrades/genesis-restart.md
@@ -0,0 +1,49 @@
+<!--
+order: 3
+-->
+
+# Genesis Restart Upgrades
+
+Learn how to upgrade your chain and counterparty clients using genesis restarts. {synopsis}
+
+**NOTE**: Regular genesis restarts are currently unsupported by relayers!
+
+### IBC Client Breaking Upgrades
+
+IBC client breaking upgrades are possible using genesis restarts. 
+It is highly recommended to use the in-place migrations instead of a genesis restart.
+Genesis restarts should be used sparingly and as backup plans. 
+
+Genesis restarts still require the usage of an IBC upgrade proposal in order to correctly upgrade counterparty clients.
+
+#### Step-by-Step Upgrade Process for SDK Chains
+
+If the IBC-connected chain is conducting an upgrade that will break counterparty clients, it must ensure that the upgrade is first supported by IBC using the [IBC Client Breaking Upgrade List](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/upgrades/quick-guide.md#ibc-client-breaking-upgrades) and then execute the upgrade process described below in order to prevent counterparty clients from breaking.
+
+1. Create a 02-client [`UpgradeProposal`](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/proto-docs.md#upgradeproposal) with an `UpgradePlan` and a new IBC ClientState in the `UpgradedClientState` field. Note that the `UpgradePlan` must specify an upgrade height **only** (no upgrade time), and the `ClientState` should only include the fields common to all valid clients and zero out any client-customizable fields (such as TrustingPeriod).
+2. Vote on and pass the `UpgradeProposal`
+3. Halt the node after successful upgrade. 
+4. Export the genesis file.
+5. Swap to the new binary.
+6. Run migrations on the genesis file.
+7. Remove the `UpgradeProposal` plan from the genesis file. This may be done by migrations.
+8. Change desired chain-specific fields (chain id, unbonding period, etc). This may be done by migrations.
+8. Reset the node's data.
+9. Start the chain.
+
+Upon the `UpgradeProposal` passing, the upgrade module will commit the UpgradedClient under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedClient`. On the block right before the upgrade height, the upgrade module will also commit an initial consensus state for the next chain under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedConsState`.
+
+Once the chain reaches the upgrade height and halts, a relayer can upgrade the counterparty clients to the last block of the old chain. They can then submit the proofs of the `UpgradedClient` and `UpgradedConsensusState` against this last block and upgrade the counterparty client.
+
+#### Step-by-Step Upgrade Process for Relayers Upgrading Counterparty Clients
+
+These steps are identical to the regular [IBC client breaking upgrade process](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/upgrades/quick-guide.md#step-by-step-upgrade-process-for-relayers-upgrading-counterparty-clients).
+
+### Non-IBC Client Breaking Upgrades
+
+While ibc-go supports genesis restarts which do not break IBC clients, relayers do not support this upgrade path. 
+Here is a tracking issue on [Hermes](https://github.com/informalsystems/ibc-rs/issues/1152).
+Please do not attempt a regular genesis restarts unless you have a tool to update counterparty clients correctly.
+
+
+
diff --git a/docs/ibc/upgrades/quick-guide.md b/docs/ibc/upgrades/quick-guide.md
@@ -30,10 +30,10 @@ Note: Since upgrades are only implemented for Tendermint clients, this doc only
 
 If the IBC-connected chain is conducting an upgrade that will break counterparty clients, it must ensure that the upgrade is first supported by IBC using the list above and then execute the upgrade process described below in order to prevent counterparty clients from breaking.
 
-1. Create a `SoftwareUpgradeProposal` with an `UpgradePlan` that includes the new IBC ClientState in the `UpgradedClientState`. Note that the `UpgradePlan` must specify an upgrade height **only** (no upgrade time), and the `ClientState` should only include the fields common to all valid clients and zero out any client-customizable fields (such as TrustingPeriod).
-2. Vote on and pass the `SoftwareUpgradeProposal`
+1. Create a 02-client [`UpgradeProposal`](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/proto-docs.md#upgradeproposal) with an `UpgradePlan` and a new IBC ClientState in the `UpgradedClientState` field. Note that the `UpgradePlan` must specify an upgrade height **only** (no upgrade time), and the `ClientState` should only include the fields common to all valid clients and zero out any client-customizable fields (such as TrustingPeriod).
+2. Vote on and pass the `UpgradeProposal`
 
-Upon the `SoftwareUpgradeProposal` passing, the upgrade module will commit the UpgradedClient under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedClient`. On the block right before the upgrade height, the upgrade module will also commit an initial consensus state for the next chain under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedConsState`.
+Upon the `UpgradeProposal` passing, the upgrade module will commit the UpgradedClient under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedClient`. On the block right before the upgrade height, the upgrade module will also commit an initial consensus state for the next chain under the key: `upgrade/UpgradedIBCState/{upgradeHeight}/upgradedConsState`.
 
 Once the chain reaches the upgrade height and halts, a relayer can upgrade the counterparty clients to the last block of the old chain. They can then submit the proofs of the `UpgradedClient` and `UpgradedConsensusState` against this last block and upgrade the counterparty client.
 
@@ -51,4 +51,4 @@ Thus, the upgrade process for relayers trying to upgrade the counterparty client
 
 The Tendermint client on the counterparty chain will verify that the upgrading chain did indeed commit to the upgraded client and upgraded consensus state at the upgrade height (since the upgrade height is included in the key). If the proofs are verified against the upgrade height, then the client will upgrade to the new client while retaining all of its client-customized fields. Thus, it will retain its old TrustingPeriod, TrustLevel, MaxClockDrift, etc; while adopting the new chain-specified fields such as UnbondingPeriod, ChainId, UpgradePath, etc. Note, this can lead to an invalid client since the old client-chosen fields may no longer be valid given the new chain-chosen fields. Upgrading chains should try to avoid these situations by not altering parameters that can break old clients. For an example, see the UnbondingPeriod example in the supported upgrades section.
 
-The upgraded consensus state will serve purely as a basis of trust for future `UpdateClientMsgs` and will not contain a consensus root to perform proof verification against. Thus, relayers must submit an `UpdateClientMsg` with a header from the new chain so that the connection can be used for proof verification again.
+The upgraded consensus state will serve purely as a basis of trust for future `UpdateClientMsgs` and will not contain a consensus root to perform proof verification against. Thus, relayers must submit an `UpdateClientMsg` with a header from the new chain so that the connection can be used for proof verification again.