docs: Add more details for the upgrade instructions [DEV-4637] (#47)

* docs: Add more details for the upgrade instructions

* Re-organize upgrade-related docs

* Update instructions for submitting proposals

* Update upgrade docs

* Fix mlc error

* Fix mlc error

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
 

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.

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 <upgrade height> --from <operator alias> --chain-id <chain_id>
+cheqd-noded tx gov submit-legacy-proposal software-upgrade <proposal_name> \
+  --title "<proposal_title>" \
+  --description "<proposal_description>" \
+  --upgrade-height <upgrade_height> \
+  --upgrade-info <upgrade_info> \
+  --deposit 8000000000000ncheq \
+  --from <operator_alias> \
+  --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,
 - `<chain_id>` - 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 <proposal_id>
-```
-
-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 <proposal_id> 10000000ncheq --from <operator_alias> --chain-id <chain_id>
-```
-
-Parameters:
-
-- `<proposal_id>` - 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 <proposal_id> yes --from <operator_alias> --chain-id <chain_id>
+cheqd-noded tx gov vote <proposal_id> <vote_option> --from <operator_alias> --chain-id <chain_id> --gas auto --gas-adjustment 1.5 --gas-prices 50ncheq
 ```
 
 The main parameters here:
 
 - `<proposal_id>` - proposal identifier from [step](#Command for sending proposal)
+- `<vote_option>` - 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 <proposal_id>
 
 At the end of voting period, after `voting_end_time`, the state of proposal with `<proposal_id>` 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: <name of proposal>
-```
-
-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 "<proposed upgrade name>" NEEDED at height: 1000:
-5:17PM ERR UPGRADE "<proposed upgrade name>" NEEDED at height: 1000:
-panic: UPGRADE "<proposed upgrade name>" 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).

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.

docs/upgrades/v0.6-upgrade.md → 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

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: <name of proposal>
+```
+
+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 "<proposed upgrade name>" NEEDED at height: 1000:
+5:17PM ERR UPGRADE "<proposed upgrade name>" NEEDED at height: 1000:
+panic: UPGRADE "<proposed upgrade name>" 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.

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