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

# Node configuration

> Environment variables, network ports, data layout, and RPC limits for Whitechain RPC node profiles.

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

<Accordion title="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](#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. |
</Accordion>

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:

```bash theme={null}
HTTP_API=eth,net,web3,rpc,debug,trace,txpool,reth
WS_API=eth,net,web3,rpc
```

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## Archive-only RPC limits

<Accordion title="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` |
</Accordion>

`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:

```text theme={null}
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.

## Related

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.