Run Your Own Node

How to run an ADI external node and monitor sync.

The ADI Stack Setup repository provides a one-command setup for running an ADI (external) node (ZK rollup follower) plus two helper sidecars:

• external_node: replays L2 blocks from the canonical main node, maintains local state/RPC, and serves JSON-RPC + status/metrics.

• proof-sync: periodically syncs proving artifacts from the foundation-hosted Azure Blob storage into your local <chain>_data/db/shared.

What it does not do:

• It does not generate new proofs or participate as a validator/sequencer. It locally replays and verifies the chain state and serves RPC for your own queries. Proofs are downloaded, not produced.

• It does not sequence or produce blocks. That is the sequencer's role.

What it does do for transactions:

• It accepts eth_sendRawTransaction calls and adds transactions to its local mempool.

• It forwards transactions to the main node/sequencer through general_main_node_rpc_url.

• If the sequencer rejects a transaction, the node removes it from its mempool and returns the error. You can submit transactions to any external node and they will reach the network.

Requirements

• Docker + Docker Compose.

• An archive-capable Ethereum L1 RPC endpoint (required to fetch historical state for genesis/upgrade discovery).

• Sufficient disk space for <chain>_data (RocksDB + synced proofs).

Network Selection

• Default network: mainnet.

• Prefer CLI flags: --testnet / --network testnet. You may export NETWORK=testnet if you like, but the flag avoids lingering env state.

• Network-specific defaults (L2 RPC, replay host, proof storage URL, container prefix, data dir) are injected automatically; no need to swap compose files.

Quickstart (mainnet)

Single Command

1. Start the stack:

   ./external-node.sh start --l1-rpc-url <your-archive-l1-rpc>

Stepwise

1. Export an archive L1 RPC URL:

   export GENERAL_L1_RPC_URL="<your-archive-l1-rpc>"

2. (Optional) Prefetch proofs to speed first start:

   ./external-node.sh download

   If you skip this, the proof-sync sidecar will pull proofs automatically after start.

3. Start the stack:

   ./external-node.sh start

4. Watch logs (optional):

   ./external-node.sh logs

5. Check RPC tip matches the canonical RPC (requires ADI_RPC_URL):

   curl -s -X POST -H 'Content-Type: application/json' \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
     http://localhost:3050
   curl -s -X POST -H 'Content-Type: application/json' \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
     $ADI_RPC_URL

   When both hex values match, you are synced.

Quickstart (testnet)

Testnet may upgrade frequently; join Discord for announcements.

Single Command

1. Start with testnet flag:

   ./external-node.sh --testnet start --l1-rpc-url <your-archive-l1-rpc>

   (Optional) If you prefer envs: export NETWORK=testnet then run the same commands without the flag.

Stepwise

1. Provide an archive L1 RPC URL:

   export GENERAL_L1_RPC_URL="<your-archive-l1-rpc>"

2. (Optional) Prefetch proofs (respects the selected network):

   ./external-node.sh --testnet download

3. Start:

   ./external-node.sh --testnet start

Transaction forwarding

The Docker Compose setting general_main_node_rpc_url controls the transaction forwarding target. The default points to the ADI sequencer endpoint.

When this setting is unset, the node accepts transactions into its local mempool. It does not forward them, so they remain local-only.

Monitoring

• JSON-RPC: http://localhost:3050

  • eth_syncing → should return false when caught up.

  • eth_blockNumber → compare with the ADI RPC.

• Metrics: http://localhost:3312/metrics (Prometheus text format). Search for replay, last_block, state_block_range, or tree_last_block to infer replay progress.

• Logs: look for Replay block <n> lines; once they stop and eth_blockNumber matches, the node is at tip.

Data Locations

• CHAIN_DATA_DIR defaults per network (./mainnet_data or ./testnet_data); overridable via env. Mapped to /chain in the containers.

• Proofs: chain_data/db/shared (synced by proof-sync).

• RocksDB state: chain_data/db/node1/....

Common Issues

• Pruned L1 RPC: startup panics with ... state at block is pruned ... then use an archive L1 RPC.

• Permissions: ensure the host data directory is writable (the script ensure_container_dir sets permissive permissions).

• Behind on replay: allow time to catch up (monitor via eth_blockNumber and logs).

What This Node Provides You

• A self-hosted ADI L2 RPC endpoint, backed by locally replayed and verified state.

• Locally stored proofs (synced from the foundation blob), not generated locally.

• No participation in sequencing, proving, or validator duties; it is for verification, data availability, and private querying.