Node configuration

Reference for the .env variables, network ports, and data paths used by the Whitechain public-rpc-node stack.

Required variables

Variable	Description
`WHITECHAIN_NETWORK`	Subdirectory under `artifacts/`, for example `mainnet` or `testnet`.
`PUBLIC_IP`	Public IP of this host, advertised for op-reth and op-node P2P.
`WHITECHAIN_PUBLIC_RPC`	Public Whitechain RPC, used as `--rollup.sequencer-http` for transaction forwarding.
`L1_RPC_URL`	Your Ethereum L1 RPC endpoint.
`L1_BEACON_URL`	Your Ethereum L1 Beacon endpoint.

The full-snap-node profile also requires WHITECHAIN_RETH_TRUSTED_PEERS, a trusted reth enode to snap-sync from, in the form enode://<pubkey>@<ip>:30303.

Optional variables

Variable	Default	Description
`HTTP_API`	`eth,net,web3,rpc`	op-reth HTTP (`8545`) RPC namespaces, the same variable for all three profiles. Comma-separated, no spaces. See RPC namespaces.
`WS_API`	`eth,net,web3,rpc`	op-reth WebSocket (`8546`) RPC namespaces, the same variable for all three profiles. Same rules as `HTTP_API`.
`L1_RPC_KIND`	`basic`	One of `alchemy`, `quicknode`, `infura`, `parity`, `nethermind`, `debug_geth`, `erigon`, `standard`, `any` if your provider supports extra receipt methods.
`WHITECHAIN_PUBLIC_OP_NODE_P2P`	empty	Static op-node peer multiaddr, `/dns4/<host>/tcp/9222/p2p/<peerID>`.
`OP_NODE_ONLY_REQ_TO_STATIC`	`false`	Restrict unsafe-block requests to the static peer only.
`OP_RETH_IMAGE`	`op-reth:v2.3.3`	Override the pinned op-reth image.
`OP_NODE_IMAGE`	`op-node:v1.19.3`	Override the pinned op-node image.

Both example .env files set HTTP_API and WS_API explicitly to the read-only default, so the value you run is visible in your own configuration rather than inherited from the Compose file.

RPC namespaces

HTTP_API and WS_API drive every profile, archive-node included, so an archive node serves the same read-only set as the pruned profiles unless you widen it deliberately. The two ports are configured independently: widening HTTP_API does not change WebSocket, and the reverse. To enable tracing on an archive node, widen the HTTP set in .env and restart the profile:

HTTP_API=eth,net,web3,rpc,debug,trace,txpool,reth
WS_API=eth,net,web3,rpc

make reup PROFILE=archive-node

Add the wide set to WS_API only if you also need those methods over WebSocket. The wider set is pointless on the pruned profiles, which do not hold the history these methods read.

The stack ships no authentication, CORS, or vhost restriction on 8545 and 8546, and RPC_MAX_TRACING_REQUESTS bounds how many tracing calls run at once, not what one call costs. A single trace_block or debug_traceTransaction on a heavy block costs seconds of CPU and gigabytes of RAM. Enable debug, trace, txpool, and reth only behind a reverse proxy that allowlists methods and rate-limits clients, never on a port open to untrusted clients.

Archive-only RPC limits

Variable	Default
`RPC_MAX_CONNECTIONS`	`1000`
`RPC_MAX_LOGS_PER_RESPONSE`	`20000`
`RPC_MAX_BLOCKS_PER_FILTER`	`100000`
`RPC_MAX_TRACING_REQUESTS`	`8`

RPC_MAX_TRACING_REQUESTS only matters once debug or trace is enabled through HTTP_API or WS_API.

Network ports

Only one profile runs at a time, so all profiles share the same host ports. Each is remappable through the env var in parentheses.

Port	Default	Env var	Published on
HTTP RPC	`8545`	`HOST_HTTP_PORT`	All profiles
WebSocket RPC	`8546`	`HOST_WS_PORT`	All profiles
op-node RPC	`9545` (loopback `127.0.0.1` only)	`HOST_OP_NODE_RPC_PORT`	All profiles
op-node P2P (TCP+UDP)	`9222`	`HOST_OP_NODE_P2P_PORT`	All profiles
EL P2P (TCP+UDP)	`30303`	`HOST_EL_P2P_PORT`	`full-snap-node` only

The Engine API (8551) stays on the profile’s own Compose network and is never published. op-node RPC (9545) is bound to loopback only on every profile, so it is reachable for local monitoring on the host but never from the network. The EL P2P port is mapped only for full-snap-node, on all interfaces (0.0.0.0), TCP and UDP. That profile bootstraps over EL P2P: op-reth snap-syncs the state from the trusted reth peer and uses reth discovery (UDP 30303) and devp2p (TCP 30303) for it, so the port accepts inbound EL peers as well. It carries devp2p traffic only, no RPC and no admin surface. If you do not want inbound EL peering, remap it with HOST_EL_P2P_PORT or block it at the firewall. For full-node and archive-node the mapping is commented out in docker-compose.yml and the port is not published; those profiles sync over L1 derivation and libp2p only and never use EL P2P. To run two profiles side by side on one host, override one profile’s ports in .env.

Data layout

Each profile keeps its data in its own subtree, so profiles never clash:

data/
  full-snap-node/
    op-reth/    # execution db, static_files, blobstore
    op-node/    # peerstore, discovery, safedb
  full-node/
    op-reth/
    op-node/
  archive-node/
    op-reth/
    op-node/
keys/
  full-snap-node/jwt.txt
  full-node/jwt.txt
  archive-node/jwt.txt

Each profile also owns its Engine API secret in keys/<profile>/jwt.txt and its own Compose network (public_rpc_full_snap, public_rpc_full, public_rpc_archive), so two profiles share neither a credential nor a network path. make up generates the secret for the selected profile if it is missing.

Run a Node

Migration

Required variables

Optional variables

RPC namespaces

Archive-only RPC limits

Network ports

Data layout

​Required variables

​Optional variables

​RPC namespaces

​Archive-only RPC limits

​Network ports

​Data layout

​Related

Required variables

Optional variables

RPC namespaces

Archive-only RPC limits

Network ports

Data layout

Related