Skip to main content

Upgrades

This guide covers how to upgrade your Monolythium node.

Upgrade Types​

TypeDescriptionProcess
Binary updateBug fixes, minor changesReplace binary, restart
Chain upgradeProtocol changesCoordinated at specific height
Emergency patchCritical fixesImmediate, coordinated

Binary Updates (Non-Breaking)​

For minor updates that don't change consensus:

Manual Process​

# Download new binary
wget https://github.com/monolythium/mono-core/releases/download/v1.x.x/monod-linux-amd64

# Stop node
sudo systemctl stop monod

# Replace binary
sudo mv monod-linux-amd64 /usr/local/bin/monod
sudo chmod +x /usr/local/bin/monod

# Start node
sudo systemctl start monod

# Verify
monod version

With Cosmovisor​

Cosmovisor handles binary upgrades automatically.

Chain Upgrades (Breaking)​

Protocol upgrades require all nodes to upgrade at a specific block height.

Upgrade Proposal Process​

  1. Governance proposal submitted
  2. Voting period
  3. If passed, upgrade height is set
  4. Nodes prepare new binary
  5. At upgrade height, chain halts
  6. Nodes switch binary
  7. Chain resumes

Preparing for Upgrade​

# Download new binary ahead of time
wget https://github.com/monolythium/mono-core/releases/download/v2.0.0/monod-linux-amd64
chmod +x monod-linux-amd64

# Verify checksum
sha256sum monod-linux-amd64
# Compare with published checksum

Manual Upgrade Process​

At the upgrade height, your node will halt with a message like:

UPGRADE "upgrade-name" NEEDED at height: 1000000

Then:

# Stop node
sudo systemctl stop monod

# Replace binary
sudo mv monod-linux-amd64 /usr/local/bin/monod

# Start node
sudo systemctl start monod

Cosmovisor automates upgrades:

Prepare Binary​

# Create upgrade directory
mkdir -p ~/.monod/cosmovisor/upgrades/upgrade-name/bin

# Place new binary
cp monod-linux-amd64 ~/.monod/cosmovisor/upgrades/upgrade-name/bin/monod
chmod +x ~/.monod/cosmovisor/upgrades/upgrade-name/bin/monod

Automatic Switch​

At upgrade height, Cosmovisor:

  1. Detects the upgrade
  2. Stops the current binary
  3. Switches to the new binary
  4. Restarts the node

No manual intervention needed.

Upgrade Monitoring​

Before Upgrade​

# Check current height
curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height'

# Check upgrade info
monod query upgrade plan

During Upgrade​

# Watch logs
sudo journalctl -u monod -f

# Look for upgrade message
# "UPGRADE "upgrade-name" NEEDED at height: XXXXXX"

After Upgrade​

# Verify version
monod version

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

# Verify block production resumed

Recovery​

!!! important "No State Reversions" Monolythium does not support chain state reversions. Recovery is always forward-only: HALT → PATCH → UPGRADE → RESTART.

If an upgrade fails:

  1. Check logs for specific errors
  2. Verify binary is correct version
  3. Check data directory permissions
  4. Consult community for known issues
  5. Wait for patch release if needed

Cosmovisor Setup​

Directory Structure​

~/.monod/cosmovisor/
├── current -> genesis (symlink, or upgrade-name after upgrade)
├── genesis/
│   └── bin/
│       └── monod
└── upgrades/
    └── upgrade-name/
        └── bin/
            └── monod

Environment Variables​

export DAEMON_NAME=monod
export DAEMON_HOME=$HOME/.monod
export DAEMON_ALLOW_DOWNLOAD_BINARIES=false
export DAEMON_RESTART_AFTER_UPGRADE=true
export DAEMON_POLL_INTERVAL=300ms

systemd with Cosmovisor​

[Service]
ExecStart=$(which cosmovisor) run start
Environment="DAEMON_NAME=monod"
Environment="DAEMON_HOME=/home/user/.monod"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"

Upgrade Checklist​

Before Upgrade Height​

  • Monitor upgrade proposal
  • Download and verify new binary
  • Place in Cosmovisor directory (if using)
  • Test binary works: ./monod version
  • Have team on standby
  • Know recovery procedures (forward-only)

At Upgrade Height​

  • Verify node halted correctly
  • Confirm binary switch (manual or Cosmovisor)
  • Monitor logs for errors
  • Verify node restarts

After Upgrade​

  • Confirm version is correct
  • Verify block production
  • Check validator is signing (if applicable)
  • Monitor for unusual behavior
  • Report any issues to community

Emergency Procedures​

Critical Bug Found​

If a critical bug is found during upgrade:

  1. Team announces HALT
  2. Do not switch binary
  3. Wait for patched release
  4. Follow updated instructions

Stuck at Upgrade Height​

If chain doesn't resume:

  1. Check community channels
  2. Verify you have correct binary
  3. Check logs for specific errors
  4. Wait for coordination

FAQ​

What if I miss the upgrade height?

Your node will halt. You can still upgrade after the fact once you notice. The chain continues without you; catch up after upgrading.

Can I upgrade early?

No. The upgrade only takes effect at the specified height. Running the new binary early may cause issues.

What happens to my stake if I don't upgrade?

Your validator won't sign blocks. Prolonged downtime may lead to jailing.

How do I know about upcoming upgrades?

Monitor official channels, governance proposals, and community announcements.