Whitechain Node

https://github.com/whitechain-labs/node
Admin
A standalone Docker Compose stack for running an external Whitechain RPC node using op-reth and...
Tokens:11,798
Snippets:84
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create .env from example

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Create your .env file by copying the example. Fill in at least PUBLIC_IP, WHITECHAIN_PUBLIC_RPC, L1_RPC_URL, and L1_BEACON_URL; for full-snap-node also set WHITECHAIN_RETH_TRUSTED_PEERS.

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

--------------------------------

### Start node with make up-<profile>

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Start the profile you chose. make up-full-snap-node is the recommended default; it snap-syncs from a trusted peer. The commented alternatives are make up-full-node (pruned, consensus-layer sync) and make up-archive-node (archive node).

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

--------------------------------

### Start node profile with make up

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Start the node profile you want. make up validates .env and artifacts, generates keys/jwt.txt if missing, then runs docker compose --profile <profile> up -d. The commented lines show alternative profiles.

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

make logs-full-snap-node
```

--------------------------------

### Run generic Make targets with PROFILE

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Generic Make targets for the node stack. Set PROFILE to full-snap-node, full-node, or archive-node (default full-snap-node). Each command starts, stops, restarts, checks status, tails logs, or renders the merged compose config for the chosen profile.

```bash
make up PROFILE=archive-node     # start
make down PROFILE=archive-node   # stop
make reup PROFILE=archive-node   # down + up
make ps PROFILE=archive-node     # status
make logs PROFILE=archive-node   # tail logs
make config PROFILE=archive-node # render merged compose config
```

--------------------------------

### Backup op-reth datadir with make down, tar, and make up

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Stop the node to get a consistent on-disk database, archive and compress the op-reth datadir, then restart the node. The archive name should match the network and profile; a pruned (full-node) backup cannot serve archive queries.

```bash
make down PROFILE=full-node
```

```bash
tar -c -C data/full-node/op-reth . | zstd -o op-reth-mainnet-full.tar.zst
```

```bash
make up PROFILE=full-node
```

--------------------------------

### Watch node logs with make logs-full-snap-node

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Watch the node logs. In op-node you should see 'Connected to L1 Beacon API', 'started p2p host', 'Advancing bq origin', and 'Inserted new L2 unsafe block' lines. Wait for the static peer handshake with WHITECHAIN_PUBLIC_OP_NODE_P2P before treating no peers as an error.

```bash
make logs-full-snap-node # or logs-full-node / logs-archive-node
```

--------------------------------

### Wipe and resync full-node profile

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Wipes local state for the full-node profile and resyncs from genesis. This deletes the local chain database; the next start re-derives the chain from L1 and pulls unsafe blocks over P2P. Prefer restoring a snapshot for full-node/archive-node and avoid running against a production node without a maintenance window.

```bash
make down PROFILE=full-node
rm -rf data/full-node/op-reth data/full-node/op-node
make up PROFILE=full-node
```

--------------------------------

### reth Staged Sync Pipeline Log Output

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Example log output from op-reth during initial sync or large catch-up, showing the staged sync pipeline progress. The lines display the received headers count and the completion of stages 1-3 (Headers, Bodies, SenderRecovery) with their checkpoints and progress percentages.

```text
INFO Received headers total=1440 from_block=1440 to_block=1
INFO Finished stage pipeline_stages=1/14 stage=Headers checkpoint=2611440 target=None stage_progress=100.00%
INFO Finished stage pipeline_stages=2/14 stage=Bodies checkpoint=2611440 target=2611440 stage_progress=100.00%
INFO Finished stage pipeline_stages=3/14 stage=SenderRecovery checkpoint=2611440 target=2611440
```

--------------------------------

### Restore op-reth snapshot for full-node profile

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Restores a published op-reth DB snapshot for a full-node profile to skip the long initial sync. Stop the node, download and extract the snapshot archive into the matching data directory, then start the node and follow its logs. The snapshot must match the profile; only op-reth data is restored, while op-node data is rebuilt automatically.

```bash
make down PROFILE=full-node
```

```bash
# example layout – adjust the URL to the one the team gives you
mkdir -p data/full-node/op-reth
curl -L "<WHITECHAIN_SNAPSHOT_URL>/op-reth-mainnet-full.tar.zst" \
  | zstd -d \
  | tar -x -C data/full-node/op-reth
```

```bash
make up PROFILE=full-node
make logs PROFILE=full-node
```

--------------------------------

### Use per-profile Make shortcuts and utility targets

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Per-profile shortcuts for each node type (full-snap-node, full-node, archive-node) covering up, down, reup, ps, and logs. Also includes make ensure-jwt to generate keys/jwt.txt if missing and make help to list all targets.

```bash
make up-full-snap-node   make down-full-snap-node   make reup-full-snap-node   make ps-full-snap-node   make logs-full-snap-node
make up-full-node        make down-full-node        make reup-full-node        make ps-full-node        make logs-full-node
make up-archive-node     make down-archive-node     make reup-archive-node     make ps-archive-node     make logs-archive-node

make ensure-jwt    # generate keys/jwt.txt if missing
make help          # list all targets
```

--------------------------------

### Place artifacts under artifacts/<network>/

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Place the published artifacts under the artifacts/<network>/ directory. The folder name must match WHITECHAIN_NETWORK in .env; for testnet use artifacts/testnet/.

```text
artifacts/mainnet/genesis.json
artifacts/mainnet/rollup.json
```

--------------------------------

### Check op-node sync status with optimism_syncStatus

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Check op-node sync status via its RPC on loopback port 9545. Run this on the host. Uses the optimism_syncStatus method.

```bash
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}'
```

--------------------------------

### Required .env values

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Required values for the .env file. L1_RPC_KIND is basic by default; set it to one of alchemy, quicknode, infura, parity, nethermind, debug_geth, erigon, standard, or any if your provider supports extra receipt-fetching methods.

```text
WHITECHAIN_NETWORK=mainnet
PUBLIC_IP=203.0.113.10
WHITECHAIN_PUBLIC_RPC=https://rpc.whitechain.io

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

--------------------------------

### Data directory layout for profiles

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Shows the directory layout under `data/` for each profile. Each profile keeps its own subtree so profiles never clash; snapshots are restored into `data/<profile>/op-reth/`.

```text
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/

```

--------------------------------

### Upgrade node with git pull, docker compose pull, make reup

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Upgrade the node by pulling the latest repository changes, pulling updated container images, and running the reup command with the full-snap-node profile. If the upgrade includes a new hardfork, replace the rollup.json (and genesis.json if changed) artifacts before running make reup to avoid a chain-divergence stall.

```bash
git pull
docker compose pull
make reup PROFILE=full-snap-node
```

--------------------------------

### Monitor op-reth Sync Progress with docker logs and grep

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Command to monitor the op-reth sync progress by filtering Docker logs for stage-related lines. Use this to watch the pipeline progress; when the Status line switches from 'stage=...' to 'latest_block=<height>', the pipeline is done and the RPC is serving live data.

```bash
docker logs -f whitechain-<profile>-op-reth 2>&1 | grep --line-buffered -iE "stage=|received headers|finished stage"
```

--------------------------------

### Set WHITECHAIN_RETH_TRUSTED_PEERS for full-snap-node

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Additional setting required for the full-snap-node profile. It specifies the trusted peer used for snap-syncing.

```text
WHITECHAIN_RETH_TRUSTED_PEERS=enode://<pubkey>@<ip>:30303
```

--------------------------------

### Check connected peers via opp2p_peers

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Checks the number of connected peers via the opp2p_peers RPC method on the op-node loopback endpoint.

```bash
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'
```

--------------------------------

### Verify node with curl eth_getBlockByNumber

Source: https://github.com/whitechain-labs/node/blob/main/RUNBOOK.md

Confirm your node responds by sending an eth_getBlockByNumber request to the profile's HTTP port (here 8545).

```bash
curl -d '{"id":0,"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest", false]}' \
  -H 'Content-Type: application/json' http://127.0.0.1:8545
```

--------------------------------

### Send raw transaction with eth_sendRawTransaction

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Send a raw transaction to the local op-reth HTTP port. The node forwards it to WHITECHAIN_PUBLIC_RPC, which routes to the closed sequencer; no direct sequencer access is needed.

```bash
curl -s -X POST http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x..."],"id":1}'
```

--------------------------------

### Check execution client health with eth_getBlockByNumber

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Health check for the execution client. Use the profile's HTTP port (here 8545). Sends a JSON-RPC request to eth_getBlockByNumber to verify the node is responding.

```bash
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]}'
```

--------------------------------

### Check node with eth_blockNumber curl

Source: https://github.com/whitechain-labs/node/blob/main/README.md

Confirm the node responds by sending an eth_blockNumber JSON-RPC request to the profile's HTTP port (here 8545).

```bash
curl -s -X POST http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```
Tokens:
Raw