Skip to main content
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):
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.
full-snap-node does not need this. It snap-syncs the state directly from WHITECHAIN_RETH_TRUSTED_PEERS.
  1. Stop the node if it is running.
  2. Download and extract the snapshot for your network and profile into the matching data directory.
    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.
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.
  2. Archive and compress the op-reth datadir (db, static_files, and related folders).
  3. Restart the node so it resumes following the chain.
  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:
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.

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

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