Upgrades
This guide covers how to upgrade your Monolythium node.
Use monarch upgrade for the simplest upgrade experience. Monarch CLI handles binary downloads, verification, process restarts, and health checks automatically via OxidePM. See Monarch CLI for details.
Upgrade Types
| Type | Description | Process |
|---|---|---|
| Binary update | Bug fixes, minor changes | Replace binary, restart |
| Chain upgrade | Protocol changes | Coordinated at specific height |
| Emergency patch | Critical fixes | Immediate, coordinated |
Binary Updates (Non-Breaking)
For minor updates that don't change consensus:
Manual Process
# Clone repository
git clone https://github.com/monolythium/mono-chain.git
cd mono-chain
# Checkout release
git checkout <release-tag>
# Build and install
make install
sudo mv $(go env GOPATH)/bin/monod /usr/local/bin/
# Start node
sudo systemctl start monod
# Verify
monod version
Chain Upgrades (Breaking)
Protocol upgrades require all nodes to upgrade at a specific block height.
Upgrade Proposal Process
- Governance proposal submitted
- Voting period
- If passed, upgrade height is set
- Nodes prepare new binary
- At upgrade height, chain halts
- Nodes switch binary
- Chain resumes
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
# Clone repository
git clone https://github.com/monolythium/mono-chain.git
cd mono-chain
# Checkout release
git checkout <release-tag>
# Build and install
make install
sudo mv $(go env GOPATH)/bin/monod /usr/local/bin/
# Start node
sudo systemctl start monod
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:
- Check logs for specific errors
- Verify binary is correct version
- Check data directory permissions
- Consult community for known issues
- Wait for patch release if needed
Upgrade Checklist
Before Upgrade Height
- Monitor upgrade proposal
- Download and verify new binary
- 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
monarch upgrade) - 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:
- Team announces HALT
- Do not switch binary
- Wait for patched release
- Follow updated instructions
Stuck at Upgrade Height
If chain doesn't resume:
- Check community channels
- Verify you have correct binary
- Check logs for specific errors
- 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.
Related
- Monitoring - Monitor upgrade progress
- Best Practices - Operational procedures