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

# Node maintenance

> Operate, update, snapshot, and restore a Whitechain RPC node: make targets, snapshot procedures, upgrade workflow, and security notes.

Day-to-day operations for a running Whitechain RPC node: start/stop commands, snapshot restoration, upgrades, and security practices.

## Operate the node

Generic targets take `PROFILE=full-snap-node|full-node|archive-node` (default `full-snap-node`):

```bash theme={null}
make up PROFILE=archive-node     # start
make down PROFILE=archive-node   # stop
make reup PROFILE=archive-node   # down + up
make ps PROFILE=archive-node     # status
make logs PROFILE=archive-node   # tail logs
make config PROFILE=archive-node # render merged compose config
```

Per-profile shortcuts exist for each, for example `make up-full-snap-node`, `make logs-archive-node`, `make reup-full-node`. `make ensure-jwt` generates `keys/jwt.txt` manually, and `make help` lists every target.

## Restore from a snapshot

This applies to the non-snap profiles, `full-node` and `archive-node`. They sync in consensus-layer mode, re-executing every transaction from genesis, which is slow on a long-running chain. The Whitechain team publishes periodic `op-reth` database snapshots. Restoring one lets you start near a recent block and derive only the gap since the snapshot was taken.

<Note>
  `full-snap-node` does not need this. It snap-syncs the state directly from `WHITECHAIN_RETH_TRUSTED_PEERS`.
</Note>

1. Stop the node if it is running.

   ```bash theme={null}
   make down PROFILE=full-node
   ```

2. Download and extract the snapshot for your network and profile into the matching data directory.

   ```bash theme={null}
   mkdir -p data/full-node/op-reth
   curl -L "<WHITECHAIN_SNAPSHOT_URL>/op-reth-testnet-full.tar.zst" \
     | zstd -d \
     | tar -x -C data/full-node/op-reth
   ```

   After extraction you should have `data/full-node/op-reth/db`, `data/full-node/op-reth/static_files`, and related folders.

3. Start the node and watch it catch up.

   ```bash theme={null}
   make up-full-node
   make logs-full-node
   ```

Match the snapshot to the profile: a pruned (`full-node`) snapshot cannot serve archive queries, so restore an archive snapshot into `data/archive-node/op-reth` for an archive node. Restore only the `op-reth` data; the `op-node` directory (`peerstore`, `discovery`, `safedb`) is rebuilt automatically. You still need a working L1 RPC and Beacon to derive everything after the snapshot block.

## Create a snapshot

This is the procedure the Whitechain team uses to produce the published `op-reth` snapshots, and the same steps you can follow to take your own backup of a `full-node` or `archive-node` datadir. Back up only the `op-reth` data; the `op-node` directory rebuilds itself.

1. Stop the node to get a consistent on-disk database.

   ```bash theme={null}
   make down PROFILE=full-node
   ```

2. Archive and compress the `op-reth` datadir (`db`, `static_files`, and related folders).

   ```bash theme={null}
   tar -c -C data/full-node/op-reth . | zstd -o op-reth-testnet-full.tar.zst
   ```

3. Restart the node so it resumes following the chain.

   ```bash theme={null}
   make up PROFILE=full-node
   ```

4. Copy the archive to wherever clients download snapshots from (object storage, mirror, and so on).

Match the archive name to the network and profile it was taken from. A pruned (`full-node`) snapshot cannot serve archive queries.

## Update the node

Image versions are pinned in `docker-compose.yml`. To upgrade:

```bash theme={null}
git pull
docker compose pull
make reup PROFILE=full-snap-node
```

<Warning>
  The Whitechain team announces hardforks in advance. If an upgrade includes a hardfork, replace `artifacts/<network>/rollup.json` (and `genesis.json` if it changed) with the published version before `make reup`, and apply it before the activation timestamp to avoid a chain-divergence stall.
</Warning>

## Wipe and resync from genesis

To wipe local state and resync a profile from genesis, run `make down PROFILE=<profile>`, then `rm -rf data/<profile>/op-reth data/<profile>/op-node`, then `make up PROFILE=<profile>`.

<Warning>
  This deletes the local chain database for that profile. For `full-node` and `archive-node`, prefer restoring a snapshot over a full genesis resync, and do not run this against a production node without a maintenance window.
</Warning>

## Security

* The Engine API on `8551` stays on the internal Compose network and is never published to the host.
* op-node RPC on `9545` is bound to loopback (`127.0.0.1`) only, on every profile, so it is reachable from the host but never from the network. The `admin` namespace is not enabled, so it serves only the read-only `optimism`, `superroot`, and `opp2p` namespaces.
* `op-reth` exposes no `admin` namespace on any profile. The public JSON-RPC (`8545`) and WebSocket (`8546`) ports serve only read-only namespaces.
* `keys/jwt.txt` is generated locally and used only between `op-node` and `op-reth` in this stack. It does not need to match anything outside.
* The node holds no project-side private keys. Operate it as a read-and-forward node.
* Restrict inbound access to the JSON-RPC ports you choose to expose. Put them behind a firewall, reverse proxy, or rate limiter before serving untrusted clients.

## Related

* [Node operators overview](/operate/run-a-node/overview)
* [Run a node](/operate/run-a-node/run-a-node)
* [Node configuration](/operate/run-a-node/configuration)
* [Troubleshooting](/operate/run-a-node/troubleshooting)