Skip to main content
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
  • No coordination required
  • Backward compatible

​
Hard Upgrades (Breaking)

  • Requires coordinated upgrade at specific height
  • All validators must upgrade
  • 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

# Monitor announcements
# - Discord: #node-operators
# - GitHub: releases page
# - Telegram: validators group

# Backup critical data
cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/
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 testnet-v7 upgrade (October 2, 2025)
# Choose your architecture:

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

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

# Download new binary
wget $BINARY_URL

# Extract to temporary location
tar -xvzf stabled-0.7.2-testnet-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 (Coordinated)

# 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

​
Preparing for Upgrades with Cosmovisor

# For each upgrade, create directory
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v8/bin

# Place new binary
cp /path/to/new/stabled $DAEMON_HOME/cosmovisor/upgrades/v8/bin/

# Cosmovisor will automatically switch at upgrade height

​
Rollback Procedures

​
Immediate Rollback

# Stop node
sudo systemctl stop ${SERVICE_NAME}

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

# Start node
sudo systemctl start ${SERVICE_NAME}

# Verify rollback
stabled version
sudo journalctl -u ${SERVICE_NAME} -f

​
Data 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}

​
Best Practices

​
Pre-Upgrade Checklist

  • Read upgrade announcement and instructions
  • Check breaking changes and required actions
  • Backup configuration and validator keys
  • Test upgrade on testnet/devnet first
  • Ensure sufficient disk space (2x current usage)
  • Notify team/community of upgrade schedule
  • Prepare rollback plan
  • Monitor Discord/Telegram for updates

​
During Upgrade

  • Monitor logs continuously
  • Check node catches up after restart
  • Verify peer connections restored
  • Confirm consensus participation (validators)
  • Test RPC/API endpoints

​
Post-Upgrade

  • Verify all services operational
  • Check metrics and monitoring
  • Update documentation
  • Clean up backup files (after confirmation)
  • Report any issues to team

​
Emergency Procedures

​
Chain Halt Recovery

# If chain halts unexpectedly
# 1. Check Discord/Telegram 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