⬆️ Upgrade

All upgrades should be treated as critical operations and performed only after official announcements from the Monad team.

1. Version Information

Check Installed Monad Versions

monad-node --version
monad-rpc --version

Example output:

monad-node {
  "commit":"c0cdcaae8eb527e44d72c4638c1f1335025a5132",
  "tag":"v0.12.2-rc",
  "branch":"",
  "modified":true
}

⚠️ The modified: true flag indicates local changes and should be avoided on production validators.

Check Available CLI Commands

monad --help
monad-bft --help
monad-rpc --help

Do not change CLI flags unless explicitly instructed in release notes.

2. Pre-Upgrade Checklist

Before upgrading, ensure:

• Node is fully synced

• Validator is not jailed

• TrieDB usage < 80%

• Latest state is safely written to disk

Recommended:

monad-status

3. Graceful Shutdown

Always stop services cleanly to avoid state corruption.

sudo systemctl stop monad-bft
sudo systemctl stop monad-execution
sudo systemctl stop monad-rpc

Verify services are stopped:

systemctl status monad-bft monad-execution monad-rpc

4. Upgrade Monad Package

Update System Repositories

sudo apt update

Install New Monad Version

sudo apt install monad

If a specific version is required:

sudo apt install monad=0.12.7

Lock version after upgrade:

sudo apt-mark hold monad

5. Restart Services

Start services in correct order:

sudo systemctl start monad-execution
sudo systemctl start monad-bft
sudo systemctl start monad-rpc

Confirm all services are running:

systemctl status monad-bft monad-execution monad-rpc --no-pager

6. Post-Upgrade Validation

Confirm Version

monad-node --version

Monitor Logs

journalctl -fu monad-bft
journalctl -fu monad-execution

Watch for:

• replay errors

• consensus warnings

• TrieDB compaction messages

Verify Block Height

curl http://localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Ensure the node continues producing / validating blocks.

7. Hard Fork & Mandatory Upgrades

Some upgrades are mandatory and tied to:

• protocol forks

• consensus changes

• TrieDB layout updates

In such cases:

• Validator must upgrade before fork height

• Late upgrades may result in:

  • missed blocks

  • jailing

  • forced resync

Always follow official Monad announcements.

8. Rollback Strategy (Emergency)

If issues appear after upgrade:

sudo apt install monad=<previous-version>
sudo systemctl restart monad-execution monad-bft monad-rpc

⚠️ Rollbacks are not guaranteed safe after state migrations.

9. Operator Notes

• Never upgrade blindly

• Avoid custom builds on validators

• Keep at least 1 hour monitoring window after upgrade

• Snapshot backups are strongly recommended before major releases