diff --git a/docs/docs/changelogs/README.md b/docs/docs/changelogs/README.md new file mode 100644 index 00000000000..8da65c84f06 --- /dev/null +++ b/docs/docs/changelogs/README.md @@ -0,0 +1,6 @@ +--- +title: Changelogs +order: 1 +--- + +This folder documents and clarifies important API and other changes introduced to the Cosmos Hub blockchain as a result of a software upgrade. Most changes are a result of updating cosmos-sdk, ibc-go and cometbft versions. diff --git a/docs/docs/changelogs/_category_.json b/docs/docs/changelogs/_category_.json new file mode 100644 index 00000000000..2e6ba716c1b --- /dev/null +++ b/docs/docs/changelogs/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Changelogs", + "position": 16, + "link": { "type": "doc", "id": "changelogs/README" } +} \ No newline at end of file diff --git a/docs/docs/changelogs/v15.1.0.md b/docs/docs/changelogs/v15.1.0.md new file mode 100644 index 00000000000..d2a367ee143 --- /dev/null +++ b/docs/docs/changelogs/v15.1.0.md @@ -0,0 +1,133 @@ +--- +title: v15.1.0 +order: 1 +--- + +This document outlines API breaking changes that were introduced in `gaia v15.1.0`. + +This release is based on cosmos-sdk `v0.47.x` and ibc-go `v7.x`. + +You can find the comprehensive API docs at: +* https://docs.cosmos.network/api + +Module reference manuals (with CLI instructions) can be found at: +* https://docs.cosmos.network/v0.47/build/modules + +Comprehensive list of changes: +* https://github.com/cosmos/gaia/blob/release/v15.1.x/CHANGELOG.md#api-breaking + +## Supported modules: +cosmos-sdk `v0.47.10-ics-lsm` +* x/auth +* x/authz +* x/bank +* x/capability +* x/consensus +* x/crisis +* x/distribution +* x/evidence +* x/feegrant +* x/gov +* x/mint +* x/params +* x/slashing +* x/staking (with LSM changes) +* x/upgrade + +ibc-go `v7.x` +* transfer +* ica (host) + +interchain-security/provider `v3.3.x` + +packetforward `v7.x` + +gaia +* x/globalfee `v15.x` +* x/metaprotocols `v15.x` + + +# Important changes +Changes are outlined compared to `gaiad <= v14.x` + +## Behaviour changes + +Starting `v15.1.0` all users must have at least `1 ATOM` staked in order to cast a vote on a governance proposal. + +Votes from accounts whose staked amounts are `< 1 ATOM` will be rejected. + +## REST/RPC Changes + +### DenomOwners + +The `DenomOwners` query is not supported on the Cosmos Hub chain. +* querying `.cosmos/bank/v1beta1/denom_owners/{denom}` always returns an empty result. + + +### Querying latest block + +`curl /blocks/latest` no longer works and returns `{"code":12,"message":"Not Implemented","details":[]}` + +The endpoint was moved to: `/cosmos/base/tendermint/v1beta1/blocks/latest` + + +# CLI Changes + +## Genesis commands + +`gaiad` no longer uses a custom genesis commands and instead relies on the commands defined in the [x/genutil module](https://docs.cosmos.network/v0.47/build/modules/genutil). + +These queries no longer work: +```shell +gaiad gentx +gaiad collect-gentx +gaiad validate-genesis +gaiad add-genesis-account +``` + +Use the `genesis` subcommands instead: +```shell +gaiad genesis gentx +gaiad genesis collect-gentx +gaiad genesis validate-genesis +gaiad genesis add-genesis-account +gaiad genesis migrate +``` + +## Governance commands + +Governance commands are aligned with cosmos-sdk v0.47.x [x/gov module](https://docs.cosmos.network/v0.47/build/modules/gov). + +### submit-legacy-proposal + +Some proposal types can be submitted using the `gaiad tx gov submit-legacy-proposal` command: +```sh +gaiad tx gov submit-legacy-proposal + +Available Commands: + cancel-software-upgrade Cancel the current software upgrade proposal + change-reward-denoms Submit a change reward denoms proposal + consumer-addition Submit a consumer addition proposal + consumer-removal Submit a consumer chain removal proposal + ibc-upgrade Submit an IBC upgrade proposal + param-change Submit a parameter change proposal + software-upgrade Submit a software upgrade proposal + update-client Submit an update IBC client proposal +``` + +Most cosmos-sdk modules no longer allow their parameters to be upgraded using a `param-change` proposal. Use the corresponding `MsgUpgradeParams` message instead and create a JSON file proposal using `draft-proposal` (listed below). + +List of proposals available for submission via `submit-legacy-proposal` will be further decreased in subsequent releases. + +More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-legacy-proposal). + +### draft-proposal + +`gaiad tx gov draft-proposal` command is available. You can use this command to create a draft proposal in JSON format. +* more information is available in the cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#draft-proposal) + +### submit-proposal + +`gaiad tx gov submit-proposal` command is available. Use `draft-proposal` (listed above) to create a proposal JSON and submit it as a transaction. + +More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-proposal) diff --git a/docs/docs/governance/proposal-types/README.md b/docs/docs/governance/proposal-types/README.md index 35933469f34..747f722f462 100644 --- a/docs/docs/governance/proposal-types/README.md +++ b/docs/docs/governance/proposal-types/README.md @@ -9,7 +9,7 @@ parent: - [**Text**](../proposal-types/text-prop.md) - [**Community Pool Spend**](../proposal-types/community-pool-spend.md) - [**Parameter Change**](../proposal-types/param-change.md) -- **Software Upgrade** +- [**Software Upgrade**](../proposal-types/software-upgrade.md) - **IBC Client Update** ## Drafting a Proposal diff --git a/docs/docs/governance/proposal-types/_category_.json b/docs/docs/governance/proposal-types/_category_.json index aed8fc74465..68ce8ce7cde 100644 --- a/docs/docs/governance/proposal-types/_category_.json +++ b/docs/docs/governance/proposal-types/_category_.json @@ -1,5 +1,5 @@ { - "label": "Parameter Changes", + "label": "Common proposals", "position": 1, "link": { "type": "doc", "id": "governance/proposal-types/README" } } \ No newline at end of file diff --git a/docs/docs/governance/proposal-types/software-upgrade.md b/docs/docs/governance/proposal-types/software-upgrade.md new file mode 100644 index 00000000000..4c5c35dc479 --- /dev/null +++ b/docs/docs/governance/proposal-types/software-upgrade.md @@ -0,0 +1,70 @@ +--- +order: 2 +parent: + order: 2 +--- + +# Software Upgrade + +Software upgrade proposals are submitted to signal that a Cosmos Hub release with new features, bugfixes and various other improvements is available and ready for production deployment. + +Software upgrade proposals should be submitted by the development teams tasked with stewarding the Cosmos Hub development. + +## Procedure + +Use `draft-proposal` command to create a draft proposal and populate it with required information. + +```sh +✗ gaiad tx gov draft-proposal +Use the arrow keys to navigate: ↓ ↑ → ← +? Select proposal type: + text + community-pool-spend + ▸ software-upgrade # choose this + cancel-software-upgrade + other + +# populate all steps (displaying all for demonstration purposes) +Enter proposal title: Upgrade v15 +Enter proposal authors: Stewards +Enter proposal summary: Upgrade to v15 +Enter proposal details: +Enter proposal proposal forum url: / +Enter proposal vote option context: Vote YES to support running this binary on the Cosmos Hub mainnet. +Enter proposal deposit: 100001uatom +Enter msg authority: cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn +``` + +In your `draft_proposal.json` populate the `height` with your desired upgrade height and populate the `info` field with additional information (must be a valid JSON string): +```json +{ + "binaries": { + "darwin/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-amd64?checksum=sha256:7157f03fbad4f53a4c73cde4e75454f4a40a9b09619d3295232341fec99ad138", + "darwin/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-darwin-arm64?checksum=sha256:09e2420151dd22920304dafea47af4aa5ff4ab0ddbe056bb91797e33ff6df274", + "linux/amd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-amd64?checksum=sha256:236b5b83a7674e0e63ba286739c4670d15d7d6b3dcd810031ff83bdec2c0c2af", + "linux/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-linux-arm64?checksum=sha256:b055fb7011e99d16a3ccae06443b0dcfd745b36480af6b3e569e88c94f3134d3", + "windows/armd64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-amd64.exe?checksum=sha256:f0224ba914cad46dc27d6a9facd8179aec8a70727f0b1e509f0c6171c97ccf76", + "windows/arm64": "https://github.com/cosmos/gaia/releases/download/v15.0.0/gaiad-v15.0.0-windows-arm64.exe?checksum=sha256:cbbce5933d501b4d54dcced9b097c052bffdef3fa8e1dfd75f29b34c3ee7de86" + } +} +``` + +Upload your `draft_metadata.json` to a distribution platform of your choice. `draft_proposal.json` is used to submit a governance proposal using `submit-proposal`. + +```sh +gaiad tx gov submit-proposal + --from \ + --chain-id cosmoshub-4 \ + --gas \ + --fees \ + --node \ +``` + +## Using x/upgrading + +Software upgrade proposals can be submitted using the [x/upgrade module](https://docs.cosmos.network/v0.47/build/modules/upgrade#transactions). The end effect will be the same since the `x/gov` module routes the message to `x/upgrade` module. + +## Additional information + +Additional instructions with debugging information is available on the [submitting](../submitting.md) page. + diff --git a/docs/docs/governance/proposal-types/text-prop.md b/docs/docs/governance/proposal-types/text-prop.md index 6ce64b99391..944cc211857 100644 --- a/docs/docs/governance/proposal-types/text-prop.md +++ b/docs/docs/governance/proposal-types/text-prop.md @@ -35,11 +35,53 @@ Technically, nothing happens on-chain. No code executes, and this 'unenforceable * The community might be more informed about a topic than they previously were. * The community might feel confident that we are aligned on a particular definition or social norm. - - - - - - - - +## Submitting a text proposal + +Follow the instructions below to create a text proposal and submit it to the blockchain. + +```sh +➜ gaiad tx gov draft-proposal + +Use the arrow keys to navigate: ↓ ↑ → ← +? Select proposal type: + ▸ text # choose this + community-pool-spend + software-upgrade + cancel-software-upgrade + other +``` + +Choose `text` from the `draft-proposal` menu and populate all the available fields. +```sh +✔ text +Enter proposal title: Title +Enter proposal authors: Author +Enter proposal summary: Proposal summary +Enter proposal details: Details, all the details +Enter proposal proposal forum url: / +Enter proposal vote option context: Vote yes if <...> +Enter proposal deposit: 100001uatom +``` + +Check `draft_proposal.json`, your result should be similar to this: +```json +{ + "metadata": "ipfs://CID", + "deposit": "100001uatom", + "title": "Title", + "summary": "Proposal summary" +} +``` + +Upload your `draft_metadata.json` to a distribution platform of your choice. `draft_proposal.json` is used to submit a governance proposal using `submit-proposal`. + +```sh +gaiad tx gov submit-proposal + --from \ + --chain-id cosmoshub-4 \ + --gas \ + --fees \ + --node \ +``` + +Additional instructions with debugging information is available on the [submitting](../submitting.md) page. diff --git a/docs/docs/governance/proposals/_category_.json b/docs/docs/governance/proposals/_category_.json index 962fb26c902..d387ce6e489 100644 --- a/docs/docs/governance/proposals/_category_.json +++ b/docs/docs/governance/proposals/_category_.json @@ -1,4 +1,4 @@ { "label": "Proposals", - "position": 1 + "position": 6 } \ No newline at end of file diff --git a/docs/docs/governance/submitting.md b/docs/docs/governance/submitting.md index 35cd7841038..bafdaa4af69 100644 --- a/docs/docs/governance/submitting.md +++ b/docs/docs/governance/submitting.md @@ -256,4 +256,4 @@ You may want to submit your proposal to the testnet chain before the mainnet for 1. To see what the proposal description will look like. 2. To signal that your proposal is about to go live on the mainnet. 3. To share what the proposal will look like in advance with stakeholders. -4. To test the functionality of the governance features. \ No newline at end of file +4. To test the functionality of the governance features. diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 32ef05b7b2b..1089720e382 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -7,10 +7,10 @@ import { currentParams } from '@site/docs/governance/current-parameters.js'; import { PlainVar } from '@site/src/js/Var'; :::tip -### **v14 Upgrade** -Cosmos Hub will be upgraded to [v14.1](https://github.com/cosmos/gaia/releases/tag/v14.1.0) at block height: **[18,262,000](https://www.mintscan.io/cosmos/blocks/18262000)** +### **v15.1 Upgrade** +Cosmos Hub will be upgraded to [v15.1](https://github.com/cosmos/gaia/releases/tag/v15.1.0) at block height: **[19,639,600](https://www.mintscan.io/cosmos/blocks/19639600)** -To upgrade from v13 check the [**upgrade guide**](/migration/cosmoshub-4-v14-upgrade.md) +To upgrade from v14 check the [**upgrade guide**](/migration/cosmoshub-4-v15-upgrade.md) ::: ![Welcome to the Cosmos Hub](images/cosmos-hub-image.jpg) diff --git a/docs/docs/migration/cosmoshub-4-v15-upgrade.md b/docs/docs/migration/cosmoshub-4-v15-upgrade.md new file mode 100644 index 00000000000..151499c6298 --- /dev/null +++ b/docs/docs/migration/cosmoshub-4-v15-upgrade.md @@ -0,0 +1,223 @@ +--- +title: Cosmos Hub 4, Gaia v15.1 Upgrade +order: 10 +--- + + +# Upgrading Gaia + +This guide provides instructions for upgrading Gaia from v14.2.x to v15.1.x. + +This document describes the steps for validators, full node operators and relayer operators, to upgrade successfully for the Gaia v15 release. + +For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v15.1.0) + +**Relayer Operators** for the Cosmos Hub and consumer chains, will also need to update to use [Hermes v1.8.0](https://github.com/informalsystems/hermes/releases/tag/v1.8.0) or higher. You may need to restart your relayer software after a major chain upgrade. + +## Release Binary + +Please use the correct release binary: `v15.1.0`. + +## Instructions + +- [Upgrading Gaia](#upgrading-gaia) + - [Release Binary](#release-binary) + - [Instructions](#instructions) + - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) + - [Upgrade date](#upgrade-date) + - [Preparing for the upgrade](#preparing-for-the-upgrade) + - [System requirements](#system-requirements) + - [An Important Note for Node Operators](#an-important-note-for-node-operators) + - [Backups](#backups) + - [Testing](#testing) + - [Current runtime](#current-runtime) + - [Target runtime](#target-runtime) + - [Upgrade steps](#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-binary) + - [Preparation](#preparation) + - [Expected upgrade result](#expected-upgrade-result) + - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) + - [Upgrade duration](#upgrade-duration) + - [Rollback plan](#rollback-plan) + - [Communications](#communications) + - [Risks](#risks) + - [Reference](#reference) + +## On-chain governance proposal attains consensus + +Once a software upgrade governance proposal is submitted to the Cosmos Hub, both a reference to this proposal and an `UPGRADE_HEIGHT` are added to the [release notes](https://github.com/cosmos/gaia/releases/tag/v15.1.0). +If and when this proposal reaches consensus, the upgrade height will be used to halt the "old" chain binaries. You can check the proposal on one of the block explorers or using the `gaiad` CLI tool. +Neither core developers nor core funding entities control the governance. + +## Upgrade date + +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 by checking the estimated time until the block is produced at one of the block explorers (e.g. https://www.mintscan.io/cosmos/blocks/`UPGRADE_HEIGHT`). + +## Preparing for the upgrade + +### System requirements + +#### An Important Note for Node Operators + +We recommend validators to temporarily upgrade their hardware before attempting the upgrade to offset any risk associated with migrating from cosmos-sdk v45 to v47. + +These are the recommended revised hardware requirements for the upgrade: + +- Minimum: 64GB RAM + 32GB swap +- Recommended: 128GB RAM +- **Bare minimum** 32GB RAM + 64GB swap + +Optimal CPU performance:  2.50GHz, 8 cores (eg Intel Xeon Gold 6248 or equivalent consumer grade processor). + +It is paramount that the operators set enough SWAP to cover all cases. SWAP partitions can be used to supplement the RAM requirement but they will increase the upgrade time. + +After the upgrade you can revert your hardware setting to the recommended system requirements for normal [day-to-day operations](../getting-started/system-requirements.md). + +### 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 using cosmovisor](#method-ii-upgrade-using-cosmovisor) 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 [v15 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). + +### Current runtime + +The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v14.2.0](https://github.com/cosmos/gaia/releases/v14.2.0). We anticipate that operators who are running on v14.2.0, 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 and if building from source, building with the appropriate `go` version. + +### Target runtime + +The Cosmos Hub mainnet network, `cosmoshub-4`, will run **[Gaia v15.1.0](https://github.com/cosmos/gaia/releases/tag/v15.1.0)**. Operators _**MUST**_ use this version post-upgrade to remain connected to the network. The new version requires `go v1.21` to build successfully. + +## Upgrade steps + +There are 2 major ways to upgrade a node: + +- Manual upgrade +- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/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 v14.2.0** is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v14.2.0), or building from source. Check the required version to build this binary in the `Makefile`. + +Run Gaia v14.2.0 till upgrade height, the node will panic: + +```shell +ERR UPGRADE "v15" NEEDED at height: : upgrade to v15 and applying upgrade "v15" at height: +``` + +Stop the node, and switch the binary to **Gaia v15.1.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 + +#### Manually preparing the binary + +##### Preparation + +- Install the latest version of Cosmovisor (`1.5.0`): + +```shell +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +cosmovisor version +# cosmovisor version: v1.5.0 +``` + +- Create a `cosmovisor` folder inside `$GAIA_HOME` and move Gaia `v14.2.0` into `$GAIA_HOME/cosmovisor/genesis/bin`: + +```shell +mkdir -p $GAIA_HOME/cosmovisor/genesis/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin +``` + +- Build Gaia `v15.1.0`, and move gaiad `v15.1.0` to `$GAIA_HOME/cosmovisor/upgrades/v15/bin` + +```shell +mkdir -p $GAIA_HOME/cosmovisor/upgrades/v15/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v15/bin +``` + +At this moment, you should have the following structure: + +```shell +. +├── current -> genesis or upgrades/ +├── genesis +│ └── bin +│ └── gaiad # old: v14.2.0 +└── upgrades + └── v15 + └── bin + └── gaiad # new: v15.1.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 a few 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 binary + +**This method is not recommended!** + +## 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) v14.2.0 binary using the following command: + +```shell +gaiad start --unsafe-skip-upgrade +``` + +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)