v0.15.2 Upgrade Instructions

This page contains upgrade instructions for testnet and mainnet. Always verify which network the instructions apply to.

Upgrade notes

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

Page-encoded timeline support

v0.15.2 introduces dual-timeline storage. Every node will eventually activate and populate a secondary page-encoded timeline. This is a one-time procedure requiring approximately 8 minutes offline per node. See MIP-8 Activation and Page Storage Migration for details.

PLEASE WAIT FOR OFFICIAL ANNOUNCEMENT BEFORE RUNNING THE PHASE-A MIGRATION

eth_call revert error code changed. eth_call execution revert error code changed from -32603 to 3. If your integration checks for -32603 on reverts, update to expect 3.

Optional: If you previously used --prometheus-addr or related CLI flags on monad-bft, these are now configured in the [prometheus] section of node.toml. Remove the CLI flag and add:

[prometheus]
addr = "0.0.0.0:9090"

Note: If you have a custom full_node_raptorcast.round_span value in node.toml, verify it is ≤ 960. Values above this cap are now rejected at startup.

monad-sign-name-record flag change. The --address ip:port flag has been replaced with separate --ip, --tcp-port, and --udp-port flags. Update any scripts that call monad-sign-name-record.

- monad-sign-name-record --address 1.2.3.4:30000 ...
+ monad-sign-name-record --ip 1.2.3.4 --tcp-port 30000 --udp-port 30000 ...

1. SSH into the node as root user

2. Stop services

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

3. 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.15.2 -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.

4. 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.

5. Verify the correct version is running

monad-rpc -V

Expected output:

monad-rpc {"commit":"6373056bfa14318d2a6d7a371cc43c636bf0aab6","tag":"v0.15.2","branch":"","modified":true}