v0.16.1 Upgrade Instructions

These instructions apply to mainnet and testnet. Always verify which network you are operating before proceeding.

Upgrade notes

No breaking changes to node.toml config for v0.16.1.

Metrics endpoint enabled by default. Since v0.16.0, the metrics endpoint is enabled by default on port 9143/TCP, listening on 0.0.0.0. If you have firewall rules restricting the metrics port, verify they are configured as expected.

MONAD_TEN activation on mainnet (MIP-8: page-encoded storage)

v0.16.1 activates MONAD_TEN on mainnet at timestamp 1788359400 (2026-09-02 14:30 UTC).

Every mainnet node must be running v0.16.1 before that timestamp. A node still on v0.16.0 or earlier will continue applying MONAD_NINE rules after activation and will diverge from the network.

All nodes must also be in dual-db mode (Phase A complete) before upgrading. See MIP-8 Activation and Page Storage Migration for details.

Nodes that have not completed Phase A (dual-db activation) will fail to start on v0.16.1. v0.16.1 extends the page-encoded timeline assertion from testnet to mainnet — if neither a page-encoded primary (Phase C) nor an active secondary timeline (Phase A/B) is detected, the node aborts at startup with:

live monad requires a page-encoded timeline (as primary or secondary) on monad_mainnet; primary_is_page=0 secondary_active=0

Note that this failure surfaces at upgrade time, not at the activation timestamp. Verify dual-db status across your fleet before you begin.

1. SSH into the node as root user

2. Verify dual-db mode (Phase A)

Before upgrading, confirm your node has completed Phase A (dual-db activation). Nodes without an active page-encoded timeline will fail to start on v0.16.1.

monad-mpt --storage /dev/triedb

You should see both Primary and Secondary timelines:

Active timelines:
     Primary:
        State machine kind: ethereum
     Secondary:
        State machine kind: monad

If you only see a single ethereum Primary timeline, complete the Phase A migration before proceeding.

3. Stop services

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

4. Upgrade monad package

If you encounter issues with the GPG signature (e.g. signatures were invalid), please renew the keys with the command below.

curl -fsSL https://pkg.category.xyz/keys/public-key.asc \
  | gpg --dearmor --yes -o /etc/apt/keyrings/category-labs.gpg

sudo apt update && sudo apt install --reinstall monad=0.16.1 -y --allow-downgrades --allow-change-held-packages
sudo apt-mark hold monad

The apt-mark hold monad command prevents the monad package from being upgraded automatically by apt-get upgrade. Without it, unattended system upgrades can install a newer version of monad that has not been approved for your network, causing version mismatch issues.

5. Start services and verify

sudo systemctl start monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l

All services should show Active: active (running). Confirm the node rejoins and advances blocks.

If monad-execution exits immediately, check the journal for the page-encoded timeline assertion described in the upgrade notes above — that indicates Phase A was not completed on this node.

6. Verify the correct version is running

monad-rpc -V

Expected output:

monad-rpc {"commit":"12b7017d61e888a62d89978d623fed182297e7af","tag":"v0.16.1","branch":"","modified":true}