Skip to main content

Chain Upgrades and Cosmovisor

Osmosis upgrades through governance: a software-upgrade proposal sets an upgrade height, and at that height every node must switch to the new osmosisd binary. If your node is still running the old binary at the upgrade height, it halts. Cosmovisor automates the binary swap so you do not have to be awake at the block.

Take the upgrade name, height, and binary version for each upgrade from the governance proposal and the Osmosis releases page. A release may also carry upgrade-specific instructions; read those before staging.

How an upgrade works​

  1. A software-upgrade proposal passes governance, naming an upgrade name and a target height.
  2. The chain runs normally until that height.
  3. At the height, the node needs the new binary. Cosmovisor detects the upgrade and swaps the binary automatically; a manually-run node must be stopped and restarted on the new binary by the operator.

Cosmovisor layout​

Cosmovisor expects binaries under a directory structure rooted at DAEMON_HOME (typically ~/.osmosisd):

$DAEMON_HOME/cosmovisor/
  genesis/bin/osmosisd            # the current binary
  upgrades/<upgrade-name>/bin/osmosisd   # the binary for each named upgrade

The key environment variables:

export DAEMON_NAME=osmosisd
export DAEMON_HOME=$HOME/.osmosisd
export DAEMON_ALLOW_DOWNLOAD_BINARIES=false   # pre-stage binaries yourself for production
export DAEMON_RESTART_AFTER_UPGRADE=true
caution

DAEMON_ALLOW_DOWNLOAD_BINARIES=true lets Cosmovisor auto-download the upgrade binary from the proposal's metadata. For a production validator, prefer false and pre-stage the verified binary into upgrades/<name>/bin/ yourself, so you are not trusting a download at the upgrade height. Confirm the binary checksum against the release.

Preparing for an upgrade​

  1. When a software-upgrade proposal passes, note the upgrade name and height.
  2. Build or download the new osmosisd for that release (verify the version against the releases page).
  3. Place it at $DAEMON_HOME/cosmovisor/upgrades/<upgrade-name>/bin/osmosisd.
  4. Confirm Cosmovisor is the process supervising your node (typically under systemd).

At the upgrade height Cosmovisor stops the node, swaps to the staged binary, and restarts.

Verifying the binary​

Whether you build from source or download a release artifact, confirm what you are about to run before staging it. Each Osmosis release publishes checksums alongside the binaries:

# Compare against the checksum published on the release page.
sha256sum osmosisd

# Confirm the staged binary reports the version you expect.
~/.osmosisd/cosmovisor/upgrades/<UPGRADE_NAME>/bin/osmosisd version

A binary that reports an unexpected version is the most common cause of an upgrade that halts anyway. Verify snapshots the same way, against the checksum the snapshot provider publishes.

Recovering from a missed upgrade​

A node that misses an upgrade halts cleanly at the upgrade height, so no state recovery is needed. Install the correct release binary (or stage it at $DAEMON_HOME/cosmovisor/upgrades/<upgrade-name>/bin/osmosisd if running Cosmovisor) and restart: the upgrade handler runs on startup and the node continues from the halt height. Verify the binary version against the releases page before restarting.

Reference​