Skip to main content
Day-to-day operations for a running Whitechain RPC node: start and stop commands, datadir backups, 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/<profile>/jwt.txt manually, and make help lists every target.

​
Back up and restore the datadir

There are no published op-reth database snapshots. full-snap-node bootstraps from its trusted reth peer, and full-node and archive-node sync by re-executing the chain from L1. What you can keep is your own backup of a full-node or archive-node datadir, so a disk failure or a corrupted database does not cost you a full resync from genesis. Back up only the op-reth data; the op-node directory (peerstore, discovery, safedb) 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.
To restore: stop the profile, replace data/<profile>/op-reth with the extracted archive, and start the profile again. The node derives everything after the backup point from L1 and catches up the unsafe head over P2P, so it still needs a working L1 RPC and Beacon. A backup only fits the profile it was taken from: a pruned (full-node) datadir cannot serve archive queries. Keep the network and the profile in the archive name.

​
Update the node

op-reth and op-node image versions are pinned in docker-compose.yml, and OP_RETH_IMAGE and OP_NODE_IMAGE in .env override the pin. To upgrade:
The Whitechain team announces hardforks in advance. If an upgrade includes a hardfork, pull the new rollup.json (and genesis.json if it changed) from whitechain-bootstrap, check it against the SHA-256 hashes published there, copy it into artifacts/<network>/, and only then run make reup. The published hashes change whenever a hardfork changes the artifacts, so verify again on every such update. Apply the new artifacts before the activation timestamp to avoid a chain-divergence stall. See Network artifacts.

​
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. On full-node and archive-node the next start re-executes the chain from genesis, so do not run this against a production node without a maintenance window. Restoring your own backup is the cheaper recovery when you have one.

​
Security

  • The Engine API on 8551 stays on the profile’s own Compose network (public_rpc_full_snap, public_rpc_full, or public_rpc_archive) 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, by default eth, net, web3, and rpc on every profile, archive-node included. debug, trace, txpool, and reth are off unless you add them to HTTP_API or WS_API. They are read-only too, but expensive enough to be a denial-of-service vector, so put a method-allowlisting, rate-limiting proxy in front before enabling them. See RPC namespaces.
  • On full-snap-node the EL P2P port 30303 is published on all interfaces, TCP and UDP, because op-reth needs it to snap-sync and to peer over devp2p. It carries no RPC and no administrative methods. full-node and archive-node do not publish it.
  • keys/<profile>/jwt.txt is generated locally and used only between the op-node and op-reth of that profile. Each profile has its own secret and its own Compose network, so one profile’s Engine API credential never grants access to another’s. It does not need to match anything outside. If you upgraded from a version that used a single keys/jwt.txt, the next make up generates the per-profile secret and recreates both containers with it, and the old file can be deleted.
  • 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.