diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 9bc81257d31..6749f710c16 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -1,7 +1,7 @@ --- name: Bug Report about: Create a report to help us squash bugs! - +labels: bug, needs-triage --- + +# Closing criteria + + + + +# Problem details + + + +# Task list + +```[tasklist] +### Must have + +``` + +```[tasklist] +### Nice to have + +``` \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature-readiness.md b/.github/ISSUE_TEMPLATE/feature-readiness.md deleted file mode 100644 index d1e61f21163..00000000000 --- a/.github/ISSUE_TEMPLATE/feature-readiness.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: Cosmos Hub Feature Proposal Checklist -about: Create a checklist for a feature proposal - ---- - -## Cosmos Hub Feature Epic - -# - -- [ ] Copy Gaia ADR for this feature - -Hub Module Readiness Checklist: - -Check mark each item if it has been completed and added to the readiness file. If not added yet, create an issue for each item and mark complete once it has been added to the readiness file. - -- [ ] ADR/Specification -- [ ] Repository -- [ ] Readme/Documentation -- [ ] Light Paper/Blog Post -- [ ] Demo/Tutorial - -Continuity - - [ ] Developer: - - [ ] Maintainer: - - [ ] Handoff requirements: - - [ ] Support and training requirements: - -Integrations - - [ ] Gaia integration - - [ ] Integration partner: - - [ ] Downstream user impact report - - [ ] Upstream partner impact report - - [ ] Inter-module dependence, e.g., pegs - -Governance - - [ ] Hub governance proposal - - [ ] Core community governance - - [ ] Steering community - - [ ] Timelines and Roadmap - -Research - - [ ] Working Group/Interest Group and Charter - - [ ] Questions - - [ ] Formalisms - - [ ] Experiments - -Support - - [ ] Technical - - [ ] Marketing - - [ ] Education - -Development -- [ ] [Integration requirements](https://github.com/regen-network/regen-ledger/issues/253) - - [ ] CLI -- [ ] Testing - - [ ] Simulations - - [ ] Testing by core dev teams - - [ ] Testing by partners -- [ ] Audits - - [ ] Internal developer review - - [ ] Third-party review - - [ ] Bug bounty -- [ ] Networks - - [ ] Testnets - - [ ] Productionnets - - [ ] Mainnets diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index f6162628f42..80d6faf7c33 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -1,7 +1,7 @@ --- name: Feature Request about: Create a proposal to request a feature - +labels: enhancement, needs-triage --- + +# Problem + + + +# Closing criteria + + + + +# Problem details + + diff --git a/.github/ISSUE_TEMPLATE/module-readiness.md b/.github/ISSUE_TEMPLATE/module-readiness.md deleted file mode 100644 index 778b1fb5ecd..00000000000 --- a/.github/ISSUE_TEMPLATE/module-readiness.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: Cosmos Hub Feature Proposal Checklist -about: Create a checklist for a feature proposal - ---- - -## Cosmos Hub Feature Epic - -# - -- [ ] Copy Gaia ADR for this feature - -Hub Module Readiness Checklist: - -Check mark each item if it has been completed and added to the readiness file. If not added yet, create an issue for each item and mark complete once it has been added to the readiness file. - -- [ ] ADR/Specification -- [ ] Repository -- [ ] Readme/Documentation -- [ ] Light Paper/Blog Post -- [ ] Demo/Tutorial - -Continuity - - [ ] Developer: - - [ ] Maintainer: - - [ ] Handoff requirements: - - [ ] Support and training requirements: - -Integrations - - [ ] Gaia integration - - [ ] Integration partner: - - [ ] [IBC Readiness](https://github.com/cosmos/stargate-launch/blob/master/ibc_readiness_matrix.md) - - [ ] Downstream user impact report - - [ ] Upstream partner impact report - - [ ] Inter-module dependence, e.g., pegs - -Governance - - [ ] Hub governance proposal - - [ ] Core community governance - - [ ] Steering community - - [ ] Timelines and Roadmap - -Research - - [ ] Working Group/Interest Group and Charter - - [ ] Questions - - [ ] Formalisms - - [ ] Experiments - -Support - - [ ] Technical - - [ ] Marketing - - [ ] Education - -Development -- [ ] [Integration requirements](https://github.com/regen-network/regen-ledger/issues/253) - - [ ] CLI -- [ ] Testing - - [ ] Simulations - - [ ] Testing by core dev teams - - [ ] Testing by partners -- [ ] Audits - - [ ] Internal developer review - - [ ] Third-party review - - [ ] Bug bounty -- [ ] Networks - - [ ] Testnets - - [ ] Productionnets - - [ ] Mainnets diff --git a/.github/ISSUE_TEMPLATE/tech-debt.md b/.github/ISSUE_TEMPLATE/tech-debt.md index 0fb517431fc..781cd9e000d 100644 --- a/.github/ISSUE_TEMPLATE/tech-debt.md +++ b/.github/ISSUE_TEMPLATE/tech-debt.md @@ -1,6 +1,7 @@ --- name: Tech Debt about: Create an issue to address and reduce technical debt +label: technical-debt, needs-triage --- diff --git a/.github/ISSUE_TEMPLATE/upgrade-checklist.md b/.github/ISSUE_TEMPLATE/upgrade-checklist.md index 752f3aeb70a..dc51ec5db77 100644 --- a/.github/ISSUE_TEMPLATE/upgrade-checklist.md +++ b/.github/ISSUE_TEMPLATE/upgrade-checklist.md @@ -1,57 +1,72 @@ --- name: Cosmos Hub Upgrade Checklist about: Create a checklist for an upgrade - +labels: epic, needs-triage --- ## Cosmos Hub Upgrade Epic # -Check mark each item if it has been completed and ready for the upgrade. If not added yet, create an issue for each item and mark complete once it has been done and integrated. +**Create an issue for each item** and mark complete once it has been done. + + +```[tasklist] +### Communication (during entire lifecycle) +- [ ] Signaling proposal (before development starts) +- [ ] Testnet blog post - target validators on Cosmos Medium +- [ ] Tweet link to testnet upgrade blog - @ cosmohub +- [ ] Testnet upgrade info (discord only) +- [ ] Tweet updates on proposal status - @ cosmohub +- [ ] Mainnet blog post - target wider audience on Cosmos Medium +- [ ] Tweet link to mainnet upgrade blog - @ cosmos @ cosmoshub +- [ ] Link to mainnet upgrade instructions (all channels - Discord, Telegram, Slack) +- [ ] Tweet upgrade countdown during voting period - @ cosmos @ cosmoshub +- [ ] Tweet upgrade success story - @ cosmos @ cosmoshub +``` + +```[tasklist] +### Library dependencies - [ ] Upgrade to SDK version - [ ] Upgrade to IBC version +- [ ] Upgrade to ICS version +- [ ] Upgrade to PFM version +- [ ] Upgrade to Liquidity version - [ ] Integrate new modules ([checklist](https://github.com/cosmos/hub-eng/blob/main/module_qa/module_checklist.md)) +``` -- [ ] Testnet - - [ ] Communication prep - - [ ] Docs: - - [ ] https://github.com/cosmos/testnets - - [ ] `gaia/docs/hub-tutorials/join-testnet.md` - - [ ] Release candidate - - [ ] Create testnet proposal - - [ ] Run testnet for one week - - [ ] Final Release - +```[tasklist] +### Testnet +- [ ] Communication prep - [ ] Docs: - - [ ] Prepare upgrade-docs branch to merge post upgrade - - [ ] https://github.com/cosmos/gaia - - [ ] `gaia/docs/hub-tutorials/join-mainnet.md` - - [ ] `gaia/docs/getting-started/quickstart.md` - - [ ] `README.md` - - [ ] `changelog.md` - - [ ] Breaking REST api changes - - [ ] Breaking CLI api changes - - [ ] https://github.com/cosmos/mainnet - -- [ ] Mainnet Proposal - - [ ] Predict block height for target date - - [ ] Create forum post - - [ ] Submit on-chain proposal - -- [ ] Communication - - [ ] Blogposts - - [ ] Testnet - target validators on Interchain Medium - - [ ] Mainnet - target wider audience on Cosmos Medium - - [ ] Twitter - - [ ] Link to testnet upgrade blog - @ cosmohub - - [ ] Link to mainnet upgrade blog - @ cosmos @ cosmoshub - - [ ] Upgrade countdown - @ cosmos @ cosmoshub - - [ ] Upgrade success story - @ cosmos @ cosmoshub - - [ ] Discord, Telegram, Slack - - [ ] Testnet upgrade info (discord only) - - [ ] Link to mainnet upgrade instructions (all channels) - - [ ] Validator email list - - [ ] Upgrade instructions + link to mainnet blog - one week before upgrade - - [ ] Update chain registry after upgrade + - [ ] [testnets](https://github.com/cosmos/testnets) updated with most recent rc + - [ ] [join-testnet](https://github.com/cosmos/gaia/blob/main/docs/hub-tutorials/join-testnet.md) +- [ ] Release candidate +- [ ] Create testnet proposal +- [ ] Run testnet for one week +- [ ] Final Release +``` + +```[tasklist] +### Docs +- On release branch + - [ ] Quickstart in `docs/getting-started/quickstart.md` + - [ ] Join mainnet in `docs/hub-tutorials/join-mainnet.md` + - [ ] Migration docs in `docs/migration/` + - [ ] Update `CHANGELOG.md` + - [ ] Breaking REST api changes + - [ ] Breaking CLI api changes +- Post Upgrade + - [ ] [chain-registry.json](https://github.com/cosmos/chain-registry/blob/master/cosmoshub/chain.json) + - [ ] Update [cosmos mainnet repo](https://github.com/cosmos/mainnet) +``` + +```[tasklist] +### Mainnet Proposal +- [ ] Predict block height for target date +- [ ] Create forum post +- [ ] Submit on-chain proposal +``` + + diff --git a/README.md b/README.md index 73bf45df8db..40541d3240c 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ If you're interested in running a node on the current Cosmos Hub, check out the ___ -If you want to participate and help secure Cosmos Hub, check out becoming a validator. Information on what a validator is and how to participate as one can be found at the [Validator FAQ](https://hub.cosmos.network/main/validators/validator-faq.html#). If you're running a validator node on the Cosmos Hub, reach out to a Janitor on the [Cosmos Developers Discord](https://discord.gg/cosmosnetwork) to join the `#validators-verified` channel. +If you want to participate and help secure Cosmos Hub, check out becoming a validator. Information on what a validator is and how to participate as one can be found at the [Validator FAQ](https://hub.cosmos.network/main/validators/validator-faq.html#). If you're running a validator node on the Cosmos Hub, reach out to a Janitor on the [Cosmos Developers Discord](https://discord.gg/cosmosnetwork) to join the `#cosmos-hub-validators-verified` channel.

@@ -119,6 +119,7 @@ We have active, helpful communities on Twitter, Discord, and Telegram. | -- | -- | | Cosmos Developers Discord | Discord | | Cosmos Twitter | Tweet | +| Cosmos Gov Twitter | Tweet | | Cosmos Telegram | Telegram | For updates on the Cosmos Hub team's activities follow us on the [Cosmos Hub Twitter](https://twitter.com/cosmoshub) account. diff --git a/contrib/generate_release_note/main.go b/contrib/generate_release_note/main.go index 2d712b915d2..e241f99d75f 100644 --- a/contrib/generate_release_note/main.go +++ b/contrib/generate_release_note/main.go @@ -30,7 +30,7 @@ func main() { } note := strings.Builder{} - note.WriteString(fmt.Sprintf("#Gaia %s Rlease Notes\n", args[1])) + note.WriteString(fmt.Sprintf("#Gaia %s Release Notes\n", args[1])) note.WriteString(changelog) note.WriteString("```\n") note.Write(buildReport) diff --git a/docs/.vuepress/styles/index.styl b/docs/.vuepress/styles/index.styl index 900ea06695d..061c497f0d6 100644 --- a/docs/.vuepress/styles/index.styl +++ b/docs/.vuepress/styles/index.styl @@ -25,6 +25,16 @@ ul.tabs-component-tabs margin-bottom -1px !important +.custom-block.warning { + background-color: rgba(255,229,100,.3); + border-color: #e7c000; + color: #6b5900; + padding: 0.1rem 1.5rem; + border-left-width: 0.5rem; + border-left-style: solid; + margin: 1rem 0; +} + .tabs-component-tab color #999 font-size 14px diff --git a/docs/hub-overview/overview.md b/docs/hub-overview/overview.md index 82daf7cb5d9..a93435e0f0c 100644 --- a/docs/hub-overview/overview.md +++ b/docs/hub-overview/overview.md @@ -3,6 +3,15 @@ order: 1 title: Introduction --- +::: warning +### **v9-Lambda Upgrade** +Cosmos Hub will upgrade at height: **14,470,501** + +Upgrade is estimated to take place around **2023-03-15 12:00 UTC** + +Upgrade guide is available [**here**](../migration/cosmoshub-4-v9-Lambda-upgrade.md) +::: + ![Welcome to the Cosmos Hub](../images/cosmos-hub-image.jpg) # Introduction diff --git a/docs/migration/cosmoshub-4-v9-Lambda-upgrade.md b/docs/migration/cosmoshub-4-v9-Lambda-upgrade.md new file mode 100644 index 00000000000..94462b50435 --- /dev/null +++ b/docs/migration/cosmoshub-4-v9-Lambda-upgrade.md @@ -0,0 +1,297 @@ +--- +title: Cosmos Hub 4, Lambda Upgrade +order: 1 +--- + +# Cosmos Hub 4, v9-Lambda Upgrade, Instructions + +This document describes the steps for validator and full node operators for the successful execution of the [v9-Lambda Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#v9-lambda-upgrade-expected-q1-2023), which contains the following main new features/improvement: + +- [Interchain-Security](https://github.com/cosmos/interchain-security) [v1.0.0](https://github.com/cosmos/interchain-security/releases/tag/v1.0.0) provider module. See the [ICS Spec](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md) for more details. +- [cosmos-sdk](https://github.com/cosmos/cosmos-sdk) to [v0.45.13-ics](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.13-ics). See [CHANGELOG.md](https://github.com/cosmos/cosmos-sdk/blob/releases/tag/v0.45.13-ics) for details. +- [ibc-go](https://github.com/cosmos/ibc-go) to [v4.2.0](https://github.com/cosmos/ibc-go/blob/release/v4.2.x/CHANGELOG.md). See [v4.2 Release Notes](https://github.com/cosmos/ibc-go/releases/tag/v4.2.0) for details. +- [tendermint](https://github.com/informalsystems/tendermint) to [0.34.26](https://github.com/informalsystems/tendermint/tree/v0.34.26). See [CHANGELOG.md](https://github.com/informalsystems/tendermint/blob/v0.34.26/CHANGELOG.md#v03426) for details. +- [packet-forward-middleware](https://github.com/strangelove-ventures/packet-forward-middleware) to [v4.0.4](https://github.com/strangelove-ventures/packet-forward-middleware/releases/tag/v4.0.4). +- [E2E ccv tests](https://github.com/cosmos/gaia/blob/main/tests/e2e/e2e_gov_test.go#L138). Tests covering new functionality introduced by the provider module to add and remove a consumer chain via governance proposal. +- [integration ccv tests](https://github.com/cosmos/gaia/blob/main/tests/ics/interchain_security_test.go). Imports Interchain-Security's `TestCCVTestSuite` and implements Gaia as the provider chain. + +TOC: + +- [Cosmos Hub 4, v9-Lambda Upgrade, Instructions](#cosmos-hub-4-v9-lambda-upgrade-instructions) + - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) + - [Upgrade will take place March 15, 203](#upgrade-will-take-place-march-15-2023) + - [Chain-id will remain the same](#chain-id-will-remain-the-same) + - [Preparing for the upgrade](#preparing-for-the-upgrade) + - [System requirement](#system-requirement) + - [Backups](#backups) + - [Testing](#testing) + - [Current runtime, cosmoshub-4 (pre-v9-Lambda upgrade) is running Gaia v8.0.1](#current-runtime-cosmoshub-4-pre-v9-lambda-upgrade-is-running-gaia-v801) + - [Target runtime, cosmoshub-4 (post-v9-Lambda upgrade) will run Gaia v9.0.0](#target-runtime-cosmoshub-4-post-v9-lambda-upgrade-will-run-gaia-v900) + - [v9-Lambda upgrade steps](#v9-Lambda-upgrade-steps) + - [Method I: Manual Upgrade](#method-i-manual-upgrade) + - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) + - [Manually preparing the binary](#manually-preparing-the-gaia-v900-binary) + - [Preparation](#preparation) + - [Expected upgrade result](#expected-upgrade-result) + - [Auto-Downloading the Gaia v9.0.0 binary (not recommended!)](#auto-downloading-the-gaia-v900-binary-not-recommended) + - [Preparation](#preparation-1) + - [Expected result](#expected-result) + - [Upgrade duration](#upgrade-duration) + - [Rollback plan](#rollback-plan) + - [Communications](#communications) + - [Risks](#risks) + - [Reference](#reference) + +## On-chain governance proposal attains consensus + +[Proposal #187](https://www.mintscan.io/cosmos/proposals/187) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. + +## Upgrade will take place March 14-16, 2023 + +The upgrade will take place at a block height of `14470501`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/14470501) page. + +## Chain-id will remain the same + +The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. + +## Preparing for the upgrade + +### System requirement + +32GB RAM is recommended to ensure a smooth upgrade. + +If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can +allow your machine to run the binary than it could run in RAM alone. + +```shell +sudo fallocate -l 16G /swapfile +sudo chmod 600 /swapfile +sudo mkswap /swapfile +sudo swapon /swapfile +``` + +### Backups + +Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. +If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) section. + +It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. + +### Testing + +For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v8-Rho local testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [v9-Lambda public-testnet](https://github.com/cosmos/testnets/tree/master/public). + +### Current runtime, cosmoshub-4 (pre-v9-Lambda upgrade) is running Gaia v8.0.1 + +The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v8.0.1](https://github.com/cosmos/gaia/releases/v8.0.1). We anticipate that operators who are running on v8.0.1, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.18`. + +### Target runtime, cosmoshub-4 (post-v9-Lambda upgrade) will run Gaia v9.0.0 + +The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v9.0.0](https://github.com/cosmos/gaia/releases/tag/v9.0.0). Operators _MUST_ use this version post-upgrade to remain connected to the network. + +## v9-Lambda upgrade steps + +There are 2 major ways to upgrade a node: + +- Manual upgrade +- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) + - Either by manually preparing the new binary + - Or by using the auto-download functionality (this is not yet recommended) + +If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. + +### Method I: Manual Upgrade + +Make sure Gaia v9.0.0 is installed by either downloading a [compatable binary](https://github.com/cosmos/gaia/releases/tag/v9.0.0), or building from source. Building from source requires go 1.18. + +Run Gaia v8.0.1 till upgrade height, the node will panic: + +```shell +ERR UPGRADE "v9-Lambda" NEEDED at height: 14470501: upgrade to v9-Lambda and applying upgrade "v9-Lambda" at height:14470501 +``` + +Stop the node, and switch the binary to Gaia v9.0.0 and re-start by `gaiad start`. + +It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. + +### Method II: Upgrade using Cosmovisor + +::: warning +**Please Read Before Proceeding**
+Using Cosmovisor 1.2.0 and higher requires a lowercase naming convention for upgrade version directory. For Cosmovisor 1.1.0 and earlier, the upgrade version is not lowercased. +::: + +> **For Example:**
+> **Cosmovisor =< `1.1.0`: `/upgrades/v9-Lambda/bin/gaiad`**
+> **Cosmovisor >= `1.2.0`: `/upgrades/v9-lambda/bin/gaiad`**
+ +| Cosmovisor Version | Binary Name in Path | +|--------------------|---------------------| +| 1.3 | v9-lambda | +| 1.2 | v9-lambda | +| 1.1 | v9-Lambda | +| 1.0 | v9-Lambda | + + +### _Manually preparing the Gaia v9.0.0 binary_ + +##### Preparation + +Install the latest version of Cosmovisor (`1.3.0`): + +```shell +go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest +``` + +**Verify Cosmovisor Version** +```shell +cosmovisor version +cosmovisor version: v1.3.0 +``` + +Create a cosmovisor folder: + +create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v8.0.1 into `$GAIA_HOME/cosmovisor/genesis/bin` + +```shell +mkdir -p $GAIA_HOME/cosmovisor/genesis/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin +```` + +build Gaia v9.0.0, and move gaiad v9.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin` + +```shell +mkdir -p $GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin +``` + +Then you should get the following structure: + +```shell +. +├── current -> genesis or upgrades/ +├── genesis +│ └── bin +│ └── gaiad #v8.0.1 +└── upgrades + └── v9-lambda + └── bin + └── gaiad #v9.0.0 +``` + +Export the environmental variables: + +```shell +export DAEMON_NAME=gaiad +# please change to your own gaia home dir +# please note `DAEMON_HOME` has to be absolute path +export DAEMON_HOME=$GAIA_HOME +export DAEMON_RESTART_AFTER_UPGRADE=true +``` + +Start the node: + +```shell +cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME +``` + +Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. + +#### Expected upgrade result + +When the upgrade block height is reached, Gaia will panic and stop: + +This may take 7 minutes to a few hours. +After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. + +### _Auto-Downloading the Gaia v9.0.0 binary (not recommended!)_ +#### Preparation + +Install the latest version of Cosmovisor (`1.3.0`): + +```shell +go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest +``` + +Create a cosmovisor folder: + +create a cosmovisor folder inside gaia home and move gaiad v8.0.1 into `$GAIA_HOME/cosmovisor/genesis/bin` + +```shell +mkdir -p $GAIA_HOME/cosmovisor/genesis/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin +``` + +```shell +. +├── current -> genesis or upgrades/ +└── genesis + └── bin + └── gaiad #v8.0.1 +``` + +Export the environmental variables: + +```shell +export DAEMON_NAME=gaiad +# please change to your own gaia home dir +export DAEMON_HOME=$GAIA_HOME +export DAEMON_RESTART_AFTER_UPGRADE=true +export DAEMON_ALLOW_DOWNLOAD_BINARIES=true +``` + +Start the node: + +```shell +cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME +``` + +Skipping the invariant checks can help decrease the upgrade time significantly. + +#### Expected result + +When the upgrade block height is reached, you can find the following information in the log: + +```shell +ERR UPGRADE "v9-Lambda" NEEDED at height: 14470501: upgrade to v9-Lambda and applying upgrade "v9-Lambda" at height:14470501 +``` + +Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin` and download the Gaia v9.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal 97. +This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. + +_Please Note:_ + +- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. +- Users should use run node on v8.0.1 if they use the cosmovisor v1.3.0 with auto-download enabled for upgrade process. + +## Upgrade duration + +The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. + +## Rollback plan + +During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. + +Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v8.0.1 binary using the following command: + +> gaiad start --unsafe-skip-upgrade 14470501 + +Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. + +Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. + +## Communications + +Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. + +## Risks + +As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. + +The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. + +## Reference + +[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) + + diff --git a/docs/modules/gov.md b/docs/modules/gov.md deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/docs/readiness/README.md b/docs/readiness/README.md index 3d2813eaba3..77fb64c1930 100644 --- a/docs/readiness/README.md +++ b/docs/readiness/README.md @@ -38,11 +38,11 @@ If recorded decisions turned out to be lacking, convene a discussion, record the ### Process 1. Copy the `template.md` file. Use the following filename pattern: `adr-next_number-title.md` -2. Link the ADR in the related [feature epic](../../.github/ISSUE_TEMPLATE/feature-readiness.md) -2. Create a draft Pull Request if you want to get early feedback. -3. Make sure the context and a solution is clear and well documented. -4. Add an entry to a list in the README file [Table of Contents](#ADR-Table-of-Contents). -5. Create a Pull Request to publish the ADR proposal. +2. Link the ADR in the related feature epic +3. Create a draft Pull Request if you want to get early feedback. +4. Make sure the context and a solution is clear and well documented. +5. Add an entry to a list in the README file [Table of Contents](#ADR-Table-of-Contents). +6. Create a Pull Request to publish the ADR proposal. ### Life cycle