Upgrade guide

Node upgrade procedures, upgrade types, and rollback strategies for Stable network version changes.

This guide covers the upgrade process for Stable nodes, including upgrade procedures and rollback strategies.

For complete version history and upgrade details, see Version History.

Upgrade types

Soft upgrades (non-breaking)

• Can be performed at any time
• Backward compatible

Hard upgrades (breaking)

• Requires upgrade at specific height
• Not backward compatible

Emergency upgrades

• Critical security fixes
• Immediate action required
• May require chain halt

Standard upgrade procedure

Step 1: preparation

# Check current version
stabled version --long

# Backup critical data
cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/

# For validators only: Backup validator state
cp ~/.stabled/data/priv_validator_state.json ~/stable-backup-$(date +%Y%m%d)/

# Check disk space (need 2x current data size)
df -h ~/.stabled

Step 2: download new binary

# For v1.2.0-rc1 upgrade (January 22, 2026)
# Choose your architecture:

# Linux AMD64
BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-amd64-testnet.tar.gz"

# OR Linux ARM64
BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-arm64-testnet.tar.gz"

# Download new binary
wget $BINARY_URL

# Extract to temporary location
tar -xvzf stabled-1.2.0-rc1-linux-*.tar.gz -C /tmp/

# Verify new version
/tmp/stabled version --long

Step 3: perform upgrade

For soft upgrades

# Stop node
sudo systemctl stop ${SERVICE_NAME}

# Backup current binary
sudo mv /usr/bin/stabled /usr/bin/stabled.backup

# Install new binary
sudo mv /tmp/stabled /usr/bin/stabled
sudo chmod +x /usr/bin/stabled

# Verify installation
stabled version --long

# Start node
sudo systemctl start ${SERVICE_NAME}

# Monitor logs
sudo journalctl -u ${SERVICE_NAME} -f

For hard upgrades

# Monitor for upgrade height
while true; do
    HEIGHT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height')
    echo "Current height: $HEIGHT"
    if [ $HEIGHT -ge $UPGRADE_HEIGHT ]; then
        break
    fi
    sleep 10
done

# Node will halt automatically at upgrade height
# Wait for halt message in logs
sudo journalctl -u ${SERVICE_NAME} -f | grep "UPGRADE"

# Once halted, perform upgrade
sudo systemctl stop ${SERVICE_NAME}
sudo mv /usr/bin/stabled /usr/bin/stabled.backup
sudo mv /tmp/stabled /usr/bin/stabled

# Start with new binary
sudo systemctl start ${SERVICE_NAME}

Step 4: post-upgrade verification

# Check node status
curl -s localhost:26657/status | jq '.result'

# Verify version
curl -s localhost:26657/status | jq '.result.node_info.version'

# Check peers
curl -s localhost:26657/net_info | jq '.result.n_peers'

# Monitor sync status
watch -n 2 'curl -s localhost:26657/status | jq ".result.sync_info"'

# Check for errors
sudo journalctl -u ${SERVICE_NAME} --since "10 minutes ago" | grep -i error

Cosmovisor setup (automated upgrades)

Cosmovisor automates the upgrade process for coordinated upgrades.

Installation

# Install cosmovisor
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

# Or download binary
wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.7.0/cosmovisor-v1.7.0-linux-amd64.tar.gz
tar -xzf cosmovisor-v1.7.0-linux-amd64.tar.gz
sudo mv cosmovisor /usr/bin/

Configuration

# Set environment variables
cat >> ~/.bashrc <<EOF
export DAEMON_NAME=stabled
export DAEMON_HOME=$HOME/.stabled
export DAEMON_RESTART_AFTER_UPGRADE=true
export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
export UNSAFE_SKIP_BACKUP=false
EOF

source ~/.bashrc

# Create directory structure
mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
mkdir -p $DAEMON_HOME/cosmovisor/upgrades

# Copy current binary to genesis
cp /usr/bin/stabled $DAEMON_HOME/cosmovisor/genesis/bin/

# Create systemd service
sudo tee /etc/systemd/system/cosmovisor.service > /dev/null <<EOF
[Unit]
Description=Cosmovisor daemon
After=network-online.target

[Service]
Environment="DAEMON_NAME=stabled"
Environment="DAEMON_HOME=$HOME/.stabled"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
User=$USER
ExecStart=/usr/bin/cosmovisor run start --chain-id stabletestnet_2201-1
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable cosmovisor
sudo systemctl start cosmovisor

Upgrade with Cosmovisor

# For each upgrade, create directory (use the upgrade name from the proposal)
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v1.2.0-rc1/bin

# Place new binary
cp /path/to/new/stabled $DAEMON_HOME/cosmovisor/upgrades/v1.2.0-rc1/bin/

# Cosmovisor will automatically switch at upgrade height

Rollback

# Stop node
sudo systemctl stop ${SERVICE_NAME}

# Backup current state (in case needed)
cp -r ~/.stabled/data ~/.stabled/data.failed

# Restore from snapshot before upgrade
cd ~/.stabled
rm -rf data/
tar -I lz4 -xf ~/snapshots/pre-upgrade-snapshot.tar.lz4

# Restore previous binary
sudo mv /usr/bin/stabled.backup /usr/bin/stabled

# Start node
sudo systemctl start ${SERVICE_NAME}

Emergency procedures

# If chain halts unexpectedly
# 1. Check Discord for instructions
# 2. Export state at last known good height
stabled export --height <last_good_height> > export.json

# 3. Wait for coordinated restart instructions

Next steps

• Version History - Complete upgrade history and release notes
• Monitor your node after upgrades
• Review Troubleshooting for common issues