Overview

Learn how to manage chain upgrades for full nodes and validators. There are 3 different upgrade categories:

Planned or Unplanned: Chained upgrades can be scheduled at a given height via upgrade proposals.
BREAKING OR NON-BREAKING: Upgrades can be API or state machine breaking, which affects backwards compatibility. To fix this, the application state or genesis files need to be migrated in preparation for the upgrade.
DATA RESET UPGRADE: Some upgrades require a full data reset to clear the state. This sometimes happens with rollbacks or hard forks.

Additionally, validators can choose how upgrades are managed according to their preferences:

Automatic or manual upgrades: Validators can run the cosmovisor process to perform upgrades automatically or manually.

Plan to upgrade

A planned upgrade is a coordinated planned upgrade using the logic of the upgrade module. This facilitates smooth upgrades of Daodst to new (broken) software versions, as it automatically handles state migration for new versions.

Governance Proposal

Governance proposals are a mechanism to coordinate upgrades at a given height or time using SoftwareProposal.

📣 Tips: All governance proposals, including software upgrades, will need to wait until the voting period ends before the upgrade can be implemented. Please consider this duration when submitting software upgrade proposals.

If the proposal is passed, the upgrade plan for the specific upgrade logic to migrate the state will be persisted to the blockchain state and scheduled at a given upgrade height. Upgrades can be delayed or accelerated by updating Plan.Height in new proposals.

Hard Fork

A special type of planned upgrade is a hard-fork. In contrast to governance proposals, hard forks do not need to wait for the entire voting period. This makes them ideal for coordinating security holes and patches.

The upgraded (forked) block height is set in the application's BeginBlock (i.e. before processing transactions for the block). Once the blockchain reaches that height, it automatically schedules an upgrade "schedule" for the same height, which then triggers the upgrade process. After the upgrade, block operations (BeginBlock, transaction processing, and state Commit) continue to proceed normally.

📣 Tips: In order to perform an upgrade hard fork, one needs to first release patch-versions using the BeginBlock upgrade scheduling logic. After +2/3 of the validators have upgraded to the new patch version, their nodes will automatically stop and upgrade the binaries.

Unplanned upgrades

An unplanned upgrade is one in which all validators need to gracefully stop and shut down their nodes at the same point in the process. This can be done by setting the --halt-height flag when running the stcd start command.

If breaking changes occur during an unplanned upgrade (see below), validators will need to migrate state and origins before restarting their nodes.

📣 Tips: The main considerations for unplanned upgrades are the need to export the genesis state and the need to [reset] (#data-reset-upgrades) the blockchain data. This primarily affects infrastructure providers, tools, and clients such as block explorers and clients that must use archive nodes to serve queries for pre-upgrade heights.

Destructive and non-destructive upgrades

Upgrades can be classified as breaking or non-breaking/releases according to the semantic versioning (Semver) of the corresponding software release version )(ie vX.Y.Z):

Major Version (X): Backwards incompatible API and state machine breaking changes.
Minor Version (Y): New backward compatibility features. These may also be state machine interrupts.
Patch Release (Z): Backward compatible bug fixes, minor refactorings and improvements.

Major Versions

If the new version you are upgrading to has breaking changes, you will have to:

Migrating Genesis JSON
Migrate application state
Restart the node

This is required to prevent double-signing or stopping the chain during consensus.

To upgrade the genesis file, you can obtain it from a trusted source, or export it locally using the stcd export command.

Minor version

If the new version you are upgrading to has breaking changes, you will have to:

Migration status (if applicable)
Restart the node

Patch version

In order to update the patch:

Stop the node
Manually download the new release binaries
1. Restart the node

Data reset upgrade

Data reset upgrades require node operators to completely reset the blockchain state and restart their nodes from a clean state, but with the same validator keys.

Automatic or manual upgrade

For each new software release, we strongly recommend that full node and validator operators perform a software upgrade.

You can upgrade your node in any of the following ways:

auto upgrades the software version and restarts the node after the upgrade occurs, or
Download the new binaries and perform a manual upgrade

Follow the links in the options above to learn how to upgrade your node according to your preferred option.