Run a node

Deploy an external Whitechain RPC node on your own server. By the end of this guide you will have a running op-reth + op-node pair that follows the canonical L2 chain and exposes JSON-RPC and WebSocket endpoints.

Available on Testnet today; Mainnet at launch.

Prerequisites

Hardware

Component	`full-snap-node` / `full-node`	`archive-node`
CPU	4+ cores	8+ cores
RAM	16 GB	32 GB
Storage	NVMe SSD, 500 GB min / 1 TB recommended (2x current chain size + 20%)	NVMe SSD, sized for full history (1 TB+)
Network	100 Mbps+	1 Gbps

Disk usage grows with the chain. Restoring a snapshot saves the initial sync time but does not change steady-state growth.

Software

A Linux server with a public IP.
Docker with Compose v2.
make, git, openssl, curl, jq.
zstd and tar if you restore from a snapshot.

L1 RPC and Beacon

You need your own Ethereum L1 RPC and Beacon endpoints. op-node reads L1 batches through the RPC. It reads blob data through the Beacon API, since Whitechain batches are posted to L1 as EIP-4844 blobs, and blobs are only retrievable through the Beacon API, not the execution RPC. A regular execution-only endpoint is not enough; whatever you use must expose both. Run your own L1 node, or use a provider that offers a matching pair of endpoints for the network below. Not every provider exposes a Beacon API on its free tier, so confirm both endpoints respond before filling in .env.

Whitechain network	L1 chain
Whitechain mainnet	Ethereum mainnet
Whitechain Sepolia	Ethereum Sepolia

Files from the Whitechain team

genesis.json (L2 execution genesis) and rollup.json (OP rollup configuration) for your network. Both are published, with checksums and a regeneration recipe, in the whitechain-bootstrap repository. See Network artifacts.
WHITECHAIN_PUBLIC_RPC: the public Whitechain RPC URL, used as the transaction-forwarding target.
WHITECHAIN_RETH_TRUSTED_PEERS: a trusted reth enode to snap-sync from (required for full-snap-node).
WHITECHAIN_PUBLIC_OP_NODE_P2P (optional): a static op-node peer.
An op-reth database snapshot URL (optional, recommended for full-node and archive-node).

For testnet, the artifacts/testnet/ files and .env.testnet.example already ship with working values for all of these, byte for byte identical to the published artifacts. You only need to request values from the Whitechain team for mainnet, or if you need a fresh snapshot URL.

Set up the node

Get the public-rpc-node manifests onto your server, from the whitechain-labs/node repository.
Place the network artifacts under artifacts/<network>/. The folder name must match WHITECHAIN_NETWORK in .env. See Network artifacts for where to download them and how to verify them.
artifacts/testnet/genesis.json artifacts/testnet/rollup.json

Create your .env from the example and fill in the required values.

cp .env.testnet.example .env   # or .env.mainnet.example

WHITECHAIN_NETWORK=testnet
PUBLIC_IP=203.0.113.10
WHITECHAIN_PUBLIC_RPC=https://rpc.testnet.whitechain.io

L1_RPC_URL=https://your-l1-rpc.example.com
L1_BEACON_URL=https://your-l1-beacon.example.com
L1_RPC_KIND=basic

# required for full-snap-node
WHITECHAIN_RETH_TRUSTED_PEERS=enode://<pubkey>@<ip>:30303

For the full list of variables, see Node configuration.

To skip the long initial sync on full-node or archive-node, restore a snapshot first. See Restore from a snapshot. full-snap-node skips this step. It snap-syncs directly from WHITECHAIN_RETH_TRUSTED_PEERS.

Start the profile you chose.

make up-full-snap-node   # recommended default: pruned, snap-syncs from a trusted peer
# make up-full-node      # pruned, consensus-layer sync (re-executes from L1)
# make up-archive-node   # archive node

make up validates .env and the artifacts, generates keys/jwt.txt if missing, then runs docker compose --profile <profile> up -d.

Confirm the node responds on the profile’s HTTP port.

curl -s -X POST http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":1}'

For full-node and archive-node, initial sync from genesis re-executes every transaction and can take from minutes on a fresh testnet to many hours on a long-running chain. Restore a snapshot to cut this down, or use full-snap-node, which snap-syncs from its trusted peer instead and typically completes in about an hour on testnet.

Verify the sync

Watch the logs with make logs-full-snap-node (or logs-full-node / logs-archive-node). In op-node you should see Connected to L1 Beacon API and started p2p host with your local peerID early on. What follows depends on the profile’s sync method:

full-snap-node (execution-layer / snap): Starting EL sync, then repeating Inserting unsafe L2 execution payload to drive EL sync and Inserted new L2 unsafe block lines. These appear as blocks are pulled from the trusted peer and applied to op-reth.
full-node / archive-node (consensus-layer): repeating Advancing bq origin lines (L1 batch derivation), then Inserted new L2 unsafe block lines as op-reth re-executes each block.

Underneath this, op-reth runs its own staged sync pipeline (14 stages) independently of what op-node reports. The RPC keeps reporting block 0 until the pipeline finishes, which is expected, not a hang. Watch the op-reth container logs directly: docker logs -f whitechain-<profile>-op-reth 2>&1 | grep --line-buffered -iE "stage=|received headers|finished stage". Header download logs Received headers ... to_block=N; later stages log checkpoint=X target=Y.

In the first few minutes after start, the node may report no peers ready to handle block requests until the static peer handshake completes. Wait for a connected peer to appear before treating this as an error.

op-node RPC on 9545 is bound to loopback (127.0.0.1) only, on every profile. Query it from the host the node runs on, not over the network.

Check how far the node is behind the wall clock:

echo "behind by $((($(date +%s) - $( \
  curl -s -X POST http://127.0.0.1:9545 \
    -H 'Content-Type: application/json' \
    --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
  | jq -r .result.unsafe_l2.timestamp)) / 60)) minutes"

Check connected peers:

curl -s -X POST http://127.0.0.1:9545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"opp2p_peers","params":[true],"id":1}' \
  | jq '.result.totalConnected'

Migration

Run a node

Prerequisites

Hardware

Software

L1 RPC and Beacon

Files from the Whitechain team

Set up the node

Verify the sync

​Prerequisites

​Hardware

​Software

​L1 RPC and Beacon

​Files from the Whitechain team

​Set up the node

​Verify the sync

​Related

Prerequisites

Hardware

Software

L1 RPC and Beacon

Files from the Whitechain team

Set up the node

Verify the sync

Related