Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Upgrade a node

Use this procedure to upgrade a Stable node while preserving its node-specific configuration and validator state. Always take the version, binary, and activation height from the history page for your network.

Before you start

You need:

  • Shell access to the node and permission to manage its service.
  • Enough disk space for a protected backup outside the active data directory.
  • The node home, service name, and installed binary path for your deployment.
  • The release entry from the Mainnet version history or Testnet version history.

The examples below use these paths. Change them to match your deployment:

export STABLED_HOME="/var/lib/stabled"
export STABLED_SERVICE="stabled"
export STABLED_BIN="/usr/local/bin/stabled"
export STABLED_ARCH="amd64" # Use arm64 on ARM hosts.
No output.

1. Check the running node

Record the current build and synchronization state before changing the node:

"$STABLED_BIN" version --long
curl -fsS http://localhost:26657/status \
  | jq '{catching_up: .result.sync_info.catching_up, latest_block_height: .result.sync_info.latest_block_height}'
<current build information>
{
  "catching_up": false,
  "latest_block_height": "<current height>"
}

Do not continue until catching_up is false.

2. Back up identity and configuration

Keep validator keys and signing state private. Store this backup on encrypted storage with permissions limited to the node operator.

export STABLED_BACKUP="/var/backups/stabled/pre-upgrade"
sudo install -d -m 0700 "$STABLED_BACKUP"
sudo cp -a "$STABLED_HOME/config" "$STABLED_BACKUP/config"
sudo cp -a "$STABLED_HOME/data/priv_validator_state.json" \
  "$STABLED_BACKUP/priv_validator_state.json"
sudo cp -a "$STABLED_BIN" "$STABLED_BACKUP/stabled"
printf 'Backup stored at %s\n' "$STABLED_BACKUP"
Backup stored at /var/backups/stabled/pre-upgrade

3. Download and inspect the release

Stable Mainnet activated v1.8.0 at block 36,976,000. Download the archive for your host architecture and inspect the reported build before installation:

export STABLED_RELEASE="v1.8.0"
export STABLED_ARCHIVE="/tmp/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz"
export STABLED_STAGE="/tmp/stabled-v1.8.0"
 
curl -fL \
  "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/binary/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" \
  -o "$STABLED_ARCHIVE"
mkdir -p "$STABLED_STAGE"
tar -xzf "$STABLED_ARCHIVE" -C "$STABLED_STAGE"
"$STABLED_STAGE/stabled" version --long
<build information for v1.8.0>

For another release or Testnet, copy the exact binary URL from the corresponding version-history table.

4. Prepare the v1.8.0 configuration

v1.8.0 adds required settings to both config.toml and app.toml. Download the Mainnet templates into a staging directory:

export STABLED_CONFIG_STAGE="/tmp/stable-v1.8.0-config"
mkdir -p "$STABLED_CONFIG_STAGE"
curl -fL \
  "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/config.toml" \
  -o "$STABLED_CONFIG_STAGE/config.toml"
curl -fL \
  "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/app.toml" \
  -o "$STABLED_CONFIG_STAGE/app.toml"
printf 'Configuration staged at %s\n' "$STABLED_CONFIG_STAGE"
Configuration staged at /tmp/stable-v1.8.0-config

Start from these templates, then restore every node-specific value from your backup. Check at least:

  • moniker and external_address.
  • Persistent peers, seeds, and private-peer settings.
  • API, JSON-RPC, gRPC, and metrics settings.
  • Organization-specific timeouts and resource limits.
  • Pruning settings for archive nodes.

The distributed app.toml uses default pruning. Pruned history cannot be reconstructed from the local node. v1.8.0 also forces inter-block-cache off.

5. Stop the node and install the files

For a coordinated future upgrade, wait until the node halts at the published height. The v1.8.0 Mainnet height is historical, so an older Mainnet node can be stopped before this installation.

sudo systemctl stop "$STABLED_SERVICE"
systemctl is-active "$STABLED_SERVICE" || true
inactive

Install the staged binary and the completed configuration files:

sudo install -m 0755 "$STABLED_STAGE/stabled" "$STABLED_BIN"
cp "$STABLED_CONFIG_STAGE/config.toml" "$STABLED_HOME/config/config.toml"
cp "$STABLED_CONFIG_STAGE/app.toml" "$STABLED_HOME/config/app.toml"
printf 'Installed %s\n' "$STABLED_RELEASE"
Installed v1.8.0

The v1.8.0 Mainnet upgrade did not require a state export, import, or snapshot reset.

6. Start and verify the node

Start the service, verify the installed build, and confirm the node resumes synchronization:

sudo systemctl start "$STABLED_SERVICE"
systemctl is-active "$STABLED_SERVICE"
"$STABLED_BIN" version --long
curl -fsS http://localhost:26657/status \
  | jq '{catching_up: .result.sync_info.catching_up, latest_block_height: .result.sync_info.latest_block_height}'
active
<build information for v1.8.0>
{
  "catching_up": false,
  "latest_block_height": "<current height>"
}

Check service logs for repeated panics, consensus failures, or configuration parsing errors before returning the node to normal operations.

Automate future upgrades with Cosmovisor

Cosmovisor can switch binaries when the on-chain upgrade handler reaches its configured height. Follow the Cosmovisor documentation and use the upgrade name from the applicable governance proposal.

Keep automatic binary downloads disabled unless your operating policy explicitly trusts the configured source. Stage and verify release binaries before the activation height.

Roll back only with release-specific instructions

If the new process fails before it executes an upgraded block, keep the service stopped and inspect the error. Restore the previous binary and configuration only when the release notes say that rollback is safe.

If the node has executed an upgraded block, coordinate recovery with the network operators. Recovery may require a release-specific binary or a trusted snapshot at an agreed height.

Where to go next

  • Network upgrades: Identify the compatibility and operator impact of each protocol release.
  • Monitor a node: Verify synchronization, peers, resource use, and service health after an upgrade.
  • Troubleshoot a node: Diagnose startup, networking, consensus, and storage failures.