diff --git a/SUMMARY.md b/SUMMARY.md index 78a1b58..39772c7 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -23,9 +23,11 @@ * [Move validator to a different machine](docs/validator-guide/move-validator.md) * [Backup and restore node keys with Hashicorp Vault](docs/validator-guide/backup-and-restore.md) * [Network-wide Software Upgrades](docs/upgrades/README.md) - * [Upgrade to v0.6.x](docs/upgrades/v0.6-upgrade.md) + * [Previous Upgrade Guides](docs/upgrades/upgrade-guides/README.md) + * [Upgrade to v0.6.x](docs/upgrades/upgrade-guides/v0.6-upgrade.md) + * [Recommended Ubuntu 24.04 LTS Upgrade](docs/upgrades/upgrade-guides/v2.0.2-upgrade.md) * [Creating a software upgrade proposal](docs/upgrades/propose-software-upgrade.md) - * [Recommended Ubuntu 24.04 LTS Upgrade](docs/upgrades/v2.0.2-upgrade.md) + * [Upgrade Guide](docs/upgrades/upgrade.md) ## 🧑‍💻 Developing on cheqd diff --git a/docs/upgrades/README.md b/docs/upgrades/README.md index 443b7ba..c55f0e0 100644 --- a/docs/upgrades/README.md +++ b/docs/upgrades/README.md @@ -4,14 +4,18 @@ Updates to the ledger code running on cheqd mainnet/testnet is voted in via governance proposals on-chain for "breaking" software changes. -We use [semantic versioning](https://semver.org/) to define our software release versions. The latest software version running on chain is in the **v1.x.x** family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be **compatible** within the family and **does not require** an on-chain upgrade proposal to be made. - -## Latest on-chain software upgrade +We use [semantic versioning](https://semver.org/) to define our software release versions. The latest software version running on chain is in the **v2.x.x** family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be **compatible** within the family and **does not require** an on-chain upgrade proposal to be made. ## Creating a new software upgrade proposal Network-wide software upgrades are typically initiated by the core development team behind the cheqd project. The process followed for the network upgrade is defined in our [guide on creating a Software Upgrade proposal](propose-software-upgrade.md) via network governance. -## Legacy software upgrade proposals +Additionally, these software upgrades are discussed off-chain on [our discussion forum](https://commonwealth.im/cheqd/discussions) and on [our Discord server](http://cheqd.link/discord-github). + +## Upgrade + +You can find more details on the actual upgrade process under in our [Upgrade Guide](upgrade.md) + +## Previous software upgrade guides -This section lists **previous** software upgrade proposals which are no longer valid for the active mainnet/testnet. +[This section](upgrade-guides) lists **previous** software upgrade proposals and specific instructions on how to execute them. diff --git a/docs/upgrades/propose-software-upgrade.md b/docs/upgrades/propose-software-upgrade.md index 2533f7d..2298b6e 100644 --- a/docs/upgrades/propose-software-upgrade.md +++ b/docs/upgrades/propose-software-upgrade.md @@ -25,14 +25,26 @@ The next steps are describing the general flow for making a proposal: #### Command for sending proposal ```bash -cheqd-noded tx gov submit-proposal software-upgrade upgrade_to_0.3 --title "Upgrade to 0.3 version" --description "This proposal is about new version of our application." --upgrade-height --from --chain-id +cheqd-noded tx gov submit-legacy-proposal software-upgrade \ + --title "" \ + --description "" \ + --upgrade-height \ + --upgrade-info \ + --deposit 8000000000000ncheq \ + --from \ + --chain-id cheqd-mainnet-1 \ + --gas auto \ + --gas-adjustment 1.4 \ + --gas-prices 50ncheq ``` The main parameters here are: -- `upgrade_to_0.3` - name of proposal which will be used in `UpgradeHandler` in the new application, -- `--upgrade-height` - height when upgrade process will be occurred, -- `--from` - alias of a key which will be used for signing proposal, +- `proposal_name` - name of proposal which will be used in `UpgradeHandler` in the new application, +- `proposal_description` - proposal description; limited to 255 characters; you can use json markdown to provide links, +- `upgrade_height` - height when upgrade process will be occurred. Keep in mind that this needs to be after voting period has ended. +- `upgrade_info` - link to the upgrade info file, containing new binaries. Needs to contain sha256 checksum. See example - `https://raw.githubusercontent.com/cheqd/cheqd-node/refs/heads/main/networks/mainnet/upgrades/upgrade-v3.json?checksum=sha256:5989f7d5bca686598c315eb74e8eb507d7f9f417d71008a31a6b828c48ce45eb` +- `operator_alias` - alias of a key which will be used for signing proposal, - `` - identifier of chain which will be used while creating the blockchain. In case of successful submitting the next command can be used for getting `proposal_id`: @@ -42,29 +54,6 @@ cheqd-noded query gov proposals ``` This command will return list of all proposals. It's needed to find the last one with corresponding `name` and `title`. -Please, remember this `proposal_id` because it will be used in next steps. - -Also, the next command is very useful for getting information about proposal status: - -```bash -cheqd-noded query gov proposal -``` - -Expected result for this state is `PROPOSAL_STATUS_DEPOSIT_PERIOD`, It means, that pool is in waiting for the first deposit state. - -#### Sending deposit - -Since getting proposal, the `DEPOSIT` should be set to the pool.It will be return after finishing voting_preiod. -For setting deposit the next command is used: - -```bash -cheqd-noded tx gov deposit 10000000ncheq --from --chain-id -``` - -Parameters: - -- `` - proposal identifier from [step](#Command for sending proposal) - In this example, amount of deposit is equal to current `min-deposit` value. ### Voting process @@ -74,12 +63,13 @@ After getting deposit from the previous step, the `VOTING_PERIOD` will be starte For setting vote, the next command can be used: ```bash -cheqd-noded tx gov vote yes --from --chain-id +cheqd-noded tx gov vote --from --chain-id --gas auto --gas-adjustment 1.5 --gas-prices 50ncheq ``` The main parameters here: - `` - proposal identifier from [step](#Command for sending proposal) +- `` - the actual vote (it can be `yes`, `no`, `abstain`, `no_with_veto`) Votes can be queried by sending request: @@ -91,28 +81,3 @@ cheqd-noded query gov votes At the end of voting period, after `voting_end_time`, the state of proposal with `` should be changed to `PROPOSAL_STATUS_PASSED`, if there was enough votes Also, deposits should be refunded back to the operators. - -## Upgrade - -After getting proposal status as passed, upgrade plan will be active. It can be requested by: - -```bash -$ cheqd-noded query upgrade plan --chain-id cheqd -testnet-2 0 [19:06:50] -height: "1000" -info: "" -name: -``` - -It means, that at height 1000 `BeginBlocker` will be set and node will be out of consensus and wait for moving to the new version of application. - -It will be stopped and the next messages in log are expected: - -```bash -5:17PM ERR UPGRADE "" NEEDED at height: 1000: -5:17PM ERR UPGRADE "" NEEDED at height: 1000: -panic: UPGRADE "" NEEDED at height: 1000: -``` - -After setting up new version of application node will continue ordering process. - -Instructions on setting up a new node/version can be found in [our installation guide](../setup-and-configure/README.md). diff --git a/docs/upgrades/upgrade-guides/README.md b/docs/upgrades/upgrade-guides/README.md new file mode 100644 index 0000000..1ac45ef --- /dev/null +++ b/docs/upgrades/upgrade-guides/README.md @@ -0,0 +1,5 @@ +# Specific Upgrade Guides + +## Context + +This section lists **previous** software upgrade proposals and specific instructions on how to execute them. diff --git a/docs/upgrades/v0.6-upgrade.md b/docs/upgrades/upgrade-guides/v0.6-upgrade.md similarity index 99% rename from docs/upgrades/v0.6-upgrade.md rename to docs/upgrades/upgrade-guides/v0.6-upgrade.md index ae4a0ba..5609c7b 100644 --- a/docs/upgrades/v0.6-upgrade.md +++ b/docs/upgrades/upgrade-guides/v0.6-upgrade.md @@ -11,7 +11,7 @@ For this upgrade from `0.5.0` to `0.6.0` there are 2 possible scenario: [Cosmovisor](https://docs.cosmos.network/main/tooling/cosmovisor) is a tool from the `cosmos-sdk` team which is able to make an upgrade in a full-auto mode. It can download and exchange binary without any actions from a node operator. Beginning with version `0.6.0`, and with all subsequent versions, we will leverage Cosmosvisor as a tool to handling our upgrade process. -For [more information about interactive installer please see this documentation](../setup-and-configure/README.md). +For [more information about interactive installer please see this documentation](../../setup-and-configure/README.md). You will find answers to common questions within this document, however of course feel free to reach out to the team on Slack or Discord. ## Upgrade with installing Cosmovisor diff --git a/docs/upgrades/v2.0.2-upgrade.md b/docs/upgrades/upgrade-guides/v2.0.2-upgrade.md similarity index 100% rename from docs/upgrades/v2.0.2-upgrade.md rename to docs/upgrades/upgrade-guides/v2.0.2-upgrade.md diff --git a/docs/upgrades/upgrade.md b/docs/upgrades/upgrade.md new file mode 100644 index 0000000..14368fd --- /dev/null +++ b/docs/upgrades/upgrade.md @@ -0,0 +1,64 @@ +# Upgrade + +After the proposal status is marked as passed, the upgrade plan will become active. You can query the upgrade plan details using the following command: + +```bash +cheqd-noded query upgrade plan --chain-id cheqd-mainnet-1 +``` + +This will return output similar to: + +```bash +height: "1000" +info: "" +name: +``` + +At block height 1000, the `BeginBlocker` will be triggered. At this point, the node will be out of consensus, awaiting the upgrade to the new version. + +The log messages like these should be expected: + +```bash +5:17PM ERR UPGRADE "" NEEDED at height: 1000: +5:17PM ERR UPGRADE "" NEEDED at height: 1000: +panic: UPGRADE "" NEEDED at height: 1000: +``` + +Once the new application version is installed and running and 1/3 of the voting power on the network is restored, the node will resume normal operations. + +## Automatic upgrades with Cosmovisor + +If your node is configured to use **Cosmovisor**, the upgrade action will be performed **automatically** at the specified block height. + +To check if your node is configured to run with Cosmovisor, run the following command: + +```bash +systemctl status cheqd-cosmovisor.service +``` + +If there's a running systemd service, running this sub-process `/usr/bin/cosmovisor run start`, then your node is using Cosmovisor. + +Additionally, you should make sure that in your cheqd-cosmovisor systemd service configuration file, you have these environment variables set to true: + +```conf +Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" +Environment="DAEMON_RESTART_AFTER_UPGRADE=true" +``` + +By default, the configuration file can be found at this location - `/usr/lib/systemd/system/cheqd-cosmovisor.service;`. + +## Manual Upgrades for Standalone Nodes + +For **standalone nodes**, follow the instructions in [our installation guide](../setup-and-configure/README.md). Make sure to choose the release suggested in the software upgrade proposal. + +## Node Built from Source Code + +If you are running a node built from source, you will need to: + +1. Refer to the upgrade proposal details. +2. Check out the **git tag** corresponding to the latest release. This is important in cases code in our **main** branch doesn't match the latest release. +3. Build the updated binary. + +## Docker Users + +Additionally, we're also publishing the docker images in our [GitHub Container Registry](https://github.com/cheqd/cheqd-node/pkgs/container/cheqd-node), so in case you're running cheqd node in Docker, you can always find the latest image there. diff --git a/docs/validator-guide/unjail.md b/docs/validator-guide/unjail.md index c25b80a..479b3d8 100644 --- a/docs/validator-guide/unjail.md +++ b/docs/validator-guide/unjail.md @@ -41,7 +41,7 @@ The expected response will be the latest cheqd-noded software release. At the ti ## Step 2: Upgrading to latest software -If your node is not up to date, please [follow the instructions here](../upgrades/v0.6-upgrade.md) +If your node is not up to date, please [follow the instructions here](../upgrades/upgrade-guides/v0.6-upgrade.md) ## Step 3: Confirming the Node is up to date