> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.16.3 Upgrade Instructions

<Warning>
  These instructions are only applicable to **testnet**. Deployment dates will be communicated via official channels.
</Warning>

## Upgrade notes

No breaking changes to `node.toml` config. For validators and standard full nodes this is a rolling upgrade on top of v0.16.2.

**State Archive nodes may need one extra step** — see below.

### State Archive nodes: promote the page timeline after installing

**Does this apply to me?**

| Your State Archive node | Action |
| - | - |
| Did **not** upgrade to the v0.16.1 hot-fix | Run `--promote-secondary` **after installing v0.16.3**, before starting services |
| Already on the v0.16.1 hot-fix | Nothing extra — the page timeline is already promoted |

Validators and standard full nodes are unaffected either way.

<Warning>
  If it applies to you, run the promote **after** the package is installed and **before** the services are started:

  ```bash theme={null}
  monad-mpt --storage /dev/triedb --promote-secondary
  ```

  v0.16.3 asserts if the primary database's encoding type does not match the block's revision, so an affected archive node that starts without promoting will fail on startup.
</Warning>

Why this is needed: up to and including v0.16.1, archive nodes committed to **both** timelines past the MIP-8 fork, doubling the disk growth rate. v0.16.3 commits only to the page-encoded timeline past the fork, which removes that 2x write amplification. Reads are routed per requested block version, so historical queries below the cutoff continue to be served from the slot encoding.

The ordering is covered in the numbered steps below — stop services, install, promote, then start.

<Note>
  **This page takes precedence for v0.16.3.** [MIP-8 Activation and Page Storage Migration](/node-ops/upgrade-instructions/page-storage-mip-8-migration#state-archive-nodes) states that State Archive nodes skip Phase C and keep the slot timeline active permanently. That remains true for v0.16.1 and earlier, but an archive node that skipped the v0.16.1 hot-fix must run the promote step above when installing v0.16.3.
</Note>

<Warning>
  **RPC must be restarted whenever the database timeline setup changes.** The RPC process caches the timeline configuration at startup, so it must be restarted along with the other services during any timeline change such as `promote-secondary`. The procedure below already does this.
</Warning>

### Replaying history from genesis

If you are replaying the whole chain from genesis, the procedure has changed. Set the disk up with `monad-mpt --state-machine ethereum` and start the replay from genesis. The replay will hit an assertion when it crosses MONAD\_TEN (the MIP-8 fork); at that point complete migration Phases A and B to mirror state into the page-based secondary database, then run `monad-mpt --promote-secondary` before resuming the replay.

### Snapshots are not backward compatible

<Warning>
  Snapshots produced by v0.16.3 **cannot be restored by earlier binaries.** Every snapshot stream now carries an eight-byte versioned header, so an older loader aborts within about a second rather than misparsing the data. The target database is left untouched.
</Warning>

Snapshots written by earlier releases restore normally under v0.16.3 — the incompatibility is only in the forward direction. Coordinate with snapshot validation before snapshotters begin producing headered streams.

### Statesync

Statesync peers still speaking protocol v0 or v1 are now rejected with `BadVersion`. Protocol v2 is what is deployed, so this should be a no-op; confirm no node is below v2 before rolling out.

### Building from source

This release requires the system package `libsecp256k1-dev` at build time. The published Docker images already include it. This only affects operators building outside those images.

## 1. SSH into the node as `root` user

## 2. Stop services

```bash theme={null}
sudo systemctl stop monad-bft monad-execution monad-rpc
```

## 3. Upgrade monad package

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

```bash theme={null}
curl -fsSL https://pkg.category.xyz/keys/public-key.asc \
  | gpg --dearmor --yes -o /etc/apt/keyrings/category-labs.gpg
```

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.16.3 -y --allow-downgrades --allow-change-held-packages
sudo apt-mark hold monad
```

<Warning>
  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.
</Warning>

## 4. Promote the page timeline — State Archive nodes that skipped the v0.16.1 hot-fix

Skip this step entirely if the node is a validator or a standard full node, or if it is a State Archive node already running the v0.16.1 hot-fix. See [above](#state-archive-nodes-promote-the-page-timeline-after-installing).

```bash theme={null}
monad-mpt --storage /dev/triedb --promote-secondary
```

Verify the result:

```bash theme={null}
monad-mpt --storage /dev/triedb
```

## 5. Start services and verify

```bash theme={null}
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.

## 6. Verify the correct version is running

```bash theme={null}
monad-rpc -V
```

Expected output:

```json theme={null}
monad-rpc {"commit":"d12edcbc0152f903f19fbed23c4136f8851ce5b5","tag":"v0.16.3","branch":"","modified":true}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.