Context

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 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 via network governance.

Additionally, these software upgrades are discussed off-chain on and on .

Upgrade Process

You can find more details on the actual upgrade process under in our

Previous software upgrade guides

lists previous software upgrade proposals and specific instructions on how to execute them.

This document offers the information and instructions required for node operators complete an upgrade with a fresh installation.

We decided to remove the debian package as an installtion artifact and use our own installation tool. The main reason for this is to help our current and future node operators join the cheqd network or complete an upgrade in a more intuitive, simpler and less time intensive way.

For this upgrade from 0.5.0 to 0.6.0 there are 2 possible scenario:

• upgrade by installing Cosmovisor

• upgrade only cheqd-noded binary.

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 . 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

As the installation and setting up the Cosmovisor can be difficult, and requires some additional steps for setting up the systemd service, we injected all this steps into our interactive installer.

The flow for installtion is:

Stop the systemd service

Make sure that it was definitely stopped by using:

The output should be:

the main focus here: Active: inactive (dead)

Remove current debian package

Download interactive installer and run it

The next answers are needed for upgrading cheqd-noded binary with the Cosmovisor installation

IMPORTANT For running an Upgrade scenario you'll be required to setup a current home directory for a cheqd user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:. This is because the upgrade scenario will only be used if this directory exists.

WARNING Please make sure that you answered yes for questions about overwriting existing configuration. It's very important when making a new installation with Cosmovisor.

Start new systemd service

Upgrade only binary

If you are updating a current installation the next steps can be used:

Stop the systemd service

and make sure that it was really stopped by:

Output should be like:

the main focus here: Active: inactive (dead)

Remove current debian package

Download interactive installer and run it

Answers for interactive installer

IMPORTANT For running an Upgrade scenario you'll be required to setup a current home directory for a cheqd user as an answer on question Set path for cheqd user's home directory [default: /home/cheqd]:. This is because the upgrade scenario will only be used if this directory exists.

WARNING. IF you are keeping just standalone a cheqd-noded, without Cosmovisor, it's crucial you keep your systemd service files without overwriting them. Please make sure that your answers were no.

Similar to what was previously in place, for starting the service only the next command is needed

Context

This section lists previous software upgrade proposals and specific instructions on how to execute them.

• v0.6.0 Upgrade Guide

• 100x increases in gas prices, with minimum gas price going up from 50ncheq to 5000ncheq (as discussed on the governance forum)

• This change incorporates looser restrictions on DID Document properties such as assertionMethod, allowing developers to specify additional details for keys which might not necessarily be used for authentication/controller purposes (e.g., BBS+ keys for credential issuance.)

What's Changed

• build(deps): Sync go workspace dependencies, bump NPM packages, bump bufbuild/buf-setup-action from 1.45.0 to 1.47.2 by @dependabot in

• chore(deps): Bump cosmossdk.io/math from 1.3.0 to 1.4.0 by @dependabot in

• fix: Update interactive installer to handle syslog deprecation [DEV-4630] by @filipdjokic in

• build: Bump direct + address vulnerable dependencies by @Eengineer1 in

New Contributors

• @davidwoood made their first contribution in

Full Changelog:

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:

This will return output similar to:

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:

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:

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:

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 . 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 , so in case you're running cheqd node in Docker, you can always find the latest image there.

This upgrade moved cheqd to support Cosmos SDK v0.50 "Eden".

Cosmos SDK v0.50 is a long-term support version bringing major improvements in performance, developer experience, and modularity. Key features include ABCI++ for more flexible and efficient consensus and IAVL 1.0 for faster and more efficient data storage. It also adds Optimistic Execution to reduce block times and Sign Mode Textual for clearer, more secure transaction signing. This release sets a solid foundation for building faster, more customizable applications on cheqd.

We also enhanced our DIDs to support a more flexible service section, enabling direct connections to did:cheqd DIDs using DIDComm. This enhancement brings full cheqd support for DIDComm endpoint discovery, making it easier for apps and SDKs like ACA-Py and Credo to integrate seamless messaging and communication.

You can find more technical details about this upgrade on our .

Important notes

1. Any validators upgrading should have before attempting this upgrade

2. After this upgrade, Keplr Wallet unfortunately cannot support dynamic fee lookups for Cosmos SDK chains that are not natively integrated into their wallet. Therefore, we recommend users to .

Background

Ubuntu's standard support for Ubuntu 20.04 LTS ("Long Term Support") version ends in April 2025. Ubuntu 20.04 LTS is currently the default Linux operating system used to build and run the binaries for our cheqd-node. To ensure continued stability and security, we need to upgrade to the latest Long-Term Support (LTS) version, Ubuntu 24.04.

Additionally, to ensure compatibility with Ubuntu 24.04, you'll need to upgrade to cheqd-noded v2.0.2. This upgrade will address any existing security vulnerabilities and ensure that we are running on the most up-to-date software and distribution, providing a secure and reliable environment.

Please follow the guide to transition both the operating system and our node software smoothly.

Prerequisites

• Backup critical data (e.g., keys, config files).

• Be prepared for the expected downtime of your node (approx 1 hour)

• Ensure all dependencies and software running on your node (except cheqd-node) support the latest Ubuntu LTS.

Step 1: Prepare the Current System

1. Stop and disable the cheqd-cosmovisor.service:

2. Update sources list and upgrade existing packages:

3. You'll probably need to restart your server after this step (you'll see the message if you run the do-release-upgrade command):

Step 2: Upgrade to the Ubuntu 22.04

1. Trigger distribution upgrade

2. During the process, you'll be prompted for a lot of answers, here are the most important ones:

   Feel free to continue over ssh, since this shouldn't cause any issues for most of the cloud providers.

   This is required, so continue.

   After you agree with this, the actual upgrade process will start.

   There will be some configuration changes and you'll probably be asked if you want to install a new version of certain software (see the screenshots and examples below). In most cases, it is completely fine to overwrite configuration changes, but be cautious if you have some custom configurations, since these actions will overwrite them:

After you ssh again, you can check your distribution version, which should match Ubuntu 22.04 LTS if the upgrade was performed successfully.

Step 3: Upgrade to Ubuntu 24.04 LTS

1. Trigger another distribution upgrade:

2. The remaining steps should be the same as in Step 2, although you won't be asked the same questions as in the first upgrade.

3. Note that it's possible that you won't be able to proceed with this due to some package incompatibility:

   On one of our nodes, it was the postgres-client-15.

   We resolved this issue by removing this package and installing it again after a successful upgrade:

Step 4: Upgrade cheqd-node to v2.0.2

1. Download the latest version of the interactive installer:

2. Run the installer:

3. Select the first option UPGRADE existing installation and proceed by choosing the v2.0.2 version from the list.

4. For the remaining questions, answer based on your previous setup and complete the binary upgrade.

Step 5: Confirm your node caught up with the network

The final step would be to make sure that your node is up and running and that it managed to sync with the network.

Run cheqd-noded status and check for "catching_up":false and also check if the latest_block_height and latest_block_time looks good to you.

Upgrade process includes 2 main parts:

• Sending a SoftwareUpgradeProposal to the network

• Moving to the new binary manually

Sending SoftwareUpgradeProposal

In general, this proposal is the document which includes some additional information for operators about improvements in new version of application or another additional remarks. There are not any requirements for proposal text, just recommendations and information for operators. And also, please make sure that this proposal will be stored in the ledger in case of success voting process in the future.

Steps for making proposal

The next steps are describing the general flow for making a proposal:

• Send proposal command to the pool;

• After getting it, ledger will be in the PROPOSAL_STATUS_DEPOSIT_PERIOD;

• After sending the first deposit from one of other operators, proposal status will be moved to PROPOSAL_STATUS_VOTING_PERIOD and voting period (2 weeks for now) will be started;

Command for sending proposal

The main parameters here are:

• 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.

In case of successful submitting the next command can be used for getting proposal_id:

This command will return list of all proposals. It's needed to find the last one with corresponding name and title.

Voting process

Send votes

After getting deposit from the previous step, the VOTING_PERIOD will be started. For now, we have 2 weeks for making some discussions and collecting needed vote count. For setting vote, the next command can be used:

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:

Finish voting period

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.