Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.optimism.io/llms.txt

Use this file to discover all available pages before exploring further.

op-supernode is in active development. This page tracks the op-supernode/v0.2.2-rc.8 release candidate and the flag list may evolve before the stable release. For background on what op-supernode is and why it exists, see the supernode explainer.
This page lists all configuration options for op-supernode. op-supernode runs every chain in an interop dependency set together as virtual nodes inside one process, sharing the L1 client and beacon-chain plumbing across them. The following options are from the --help in op-supernode/v0.2.2-rc.8.

​
Recommendations

​
Share the JWT secret across virtual nodes with --vn.all.l2.jwt-secret

Each chain’s virtual node needs the JWT secret to authenticate with its execution client over the Engine API. When every chain in the dependency set uses the same secret, set it once at the supernode level and let every virtual node inherit it.
To share a single JWT secret across every virtual node, set --vn.all.l2.jwt-secret=<path> (or OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH) at the supernode level. This avoids repeating the per-chain --vn.<chainID>.l2.jwt-secret line for every chain in --chains. Use the per-chain form only when a chain’s execution client requires its own secret.

​
Configure a beacon archiver fallback with --l1.beacon-fallbacks

Ethereum beacon nodes prune blob sidecars after roughly 18 days. Without an archive fallback configured, a supernode that has been offline past the prune window cannot fetch the blobs it needs to derive missed L1 blocks, and chain containers will stall at the gap.
Configure --l1.beacon-fallbacks (or OP_SUPERNODE_L1_BEACON_FALLBACKS) with one or more beacon-API-compatible archive endpoints. Set them up from the start — once a primary beacon prunes a blob the supernode needs, only an archiver can recover it. The shared beacon client uses the fallbacks transparently when the primary beacon node returns 404 for an expired blob. The --l1.beacon-archiver alias points at the same flag and is accepted for compatibility with older deployment scripts. For options on what to point --l1.beacon-fallbacks at — running your own non-pruning beacon, running blob-archiver, or using a third-party service — see the blob archiver guide.

​
Pair op-supernode with a Light CL fleet

For operators running more than a handful of nodes, the deployable pattern is to concentrate the expensive multi-chain derivation work on supernodes and run the rest of the fleet as op-node or kona-node instances in Light CL mode. Each supernode (or HA pool of supernodes) acts as the safe source for a fleet of Light CLs. The fleet points at the supernode’s optimism_syncStatus RPC over the --l2.follow.source flag and inherits its safe and finalized view, while keeping its own unsafe-head progression over P2P. Larger operators often run several such supernode-plus-fleet groups for blast-radius isolation, regional placement, or staged rollouts. See the specialized op-node topology notice for the fleet side of this pattern, and the supernode explainer for the architecture overview. Set --disable-p2p=true on the supernode when the fleet handles unsafe-head P2P gossip on its own. Leave P2P enabled (the default) when the supernode is the only node in the topology.

​
Example configuration

This is a minimum viable configuration for an op-supernode acting as a verifier across OP Sepolia and Unichain Sepolia. The example uses environment variables; pass the equivalent --flag arguments instead if that fits your deployment better. Fill in the placeholders before starting the binary.
The example below assumes a two-chain dependency set of OP Sepolia (chain ID 11155420) and Unichain Sepolia (chain ID 1301). For a different dependency set, replace the chain IDs in OP_SUPERNODE_CHAINS and add or remove the matching OP_SUPERNODE_VN_<CHAINID>_NETWORK and OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_RPC pairs for each chain.
# Dependency set and storage
OP_SUPERNODE_CHAINS: "11155420,1301"          # OP Sepolia + Unichain Sepolia
OP_SUPERNODE_DATA_DIR: /var/lib/op-supernode  # default is ./datadir

# Shared L1 access
OP_SUPERNODE_L1_ETH_RPC: <your-l1-eth-rpc>
OP_SUPERNODE_L1_BEACON: <your-l1-beacon-rpc>
OP_SUPERNODE_L1_BEACON_FALLBACKS: <your-l1-beacon-archiver-rpc>

# Shared JWT secret for every virtual node's engine connection
OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH: /etc/op/jwt-secret.txt

# Per-chain: chain identity and engine RPC
OP_SUPERNODE_VN_11155420_NETWORK: op-sepolia
OP_SUPERNODE_VN_11155420_L2_ENGINE_RPC: <op-sepolia-engine-rpc>
OP_SUPERNODE_VN_1301_NETWORK: unichain-sepolia
OP_SUPERNODE_VN_1301_L2_ENGINE_RPC: <unichain-sepolia-engine-rpc>

# Top-level JSON-RPC server (per-chain namespaces under /<chainID>/)
OP_SUPERNODE_RPC_ADDR: 0.0.0.0
OP_SUPERNODE_RPC_PORT: "8545"

# Observability
OP_SUPERNODE_LOG_LEVEL: info
OP_SUPERNODE_METRICS_ENABLED: "true"
OP_SUPERNODE_METRICS_ADDR: 0.0.0.0
OP_SUPERNODE_METRICS_PORT: "7300"
For chains that are not in op-node’s built-in network registry, replace --vn.<chainID>.network with --vn.<chainID>.rollup.config=<path-to-rollup-config.json>.

​
All configuration variables

Environment-variable names don’t always derive mechanically from the CLI flag name. Some env-var suffixes keep op-node’s source-level spelling even when the CLI flag was renamed (for example, --vn.<chainID>.l2 is set by OP_SUPERNODE_VN_<chainID>_L2_ENGINE_RPC, not OP_SUPERNODE_VN_<chainID>_L2). The per-flag entries below show the correct env-var name alongside the CLI form. When in doubt, run op-supernode --chains=<chainIDs> --help for the authoritative name of any flag.

​
Dependency set and storage

​
chains

The list of chain IDs that this supernode hosts. Required. Accepts a comma-separated list or a repeatable flag. Each chain ID must have a matching set of per-chain --vn.<chainID>.* flags that configure the chain’s network identity and execution-client connection.
--chains=<value>

​
data-dir

Data directory for op-supernode. Each chain’s SafeDB and P2P state is stored in a chain-<chainID> subdirectory under this path so the chains cannot collide. The default value is ./datadir.
--data-dir=<value>

​
Shared L1 access

The supernode shares one L1 client and one beacon client across every chain in the dependency set. These are the supernode’s own in-process clients (caching layers in front of remote endpoints), not the remote L1 node and beacon node themselves — the supernode connects to existing endpoints rather than running its own. Configure these flags at the top level only — the per-chain namespace also includes --vn.<chainID>.l1 and --vn.<chainID>.l1.beacon (because the supernode mechanically clones every op-node flag into the namespace), but the supernode discards them at startup.

​
l1

Address of the L1 user JSON-RPC endpoint. Required. The eth namespace must be enabled on the endpoint.
--l1=<value>

​
l1.beacon

Address of the L1 beacon-node HTTP endpoint. Required for any chain that depends on blob-derived L1 data, which covers every post-Ecotone OP Stack chain.
--l1.beacon=<value>

​
l1.beacon-fallbacks

Addresses of L1 beacon-API-compatible HTTP fallback endpoints. Used to fetch blob sidecars not available at the primary --l1.beacon endpoint, including blobs that have aged past a regular beacon node’s prune window. The --l1.beacon-archiver alias points at the same flag. Accepts a comma-separated list or a repeatable flag.
--l1.beacon-fallbacks=<value>

​
l1.http-poll-interval

Polling interval for the shared L1 HTTP RPC subscription. The default value is 12s. This flag controls the supernode’s own L1 client. Per-chain --vn.<chainID>.l1.http-poll-interval settings are ignored because the shared client owns the resource.
--l1.http-poll-interval=<value>

​
Per-chain virtual-node configuration

Every chain in --chains runs as a virtual node inside the supernode. The supernode reproduces the full op-node flag set under two prefixes so you can configure each chain.
  • --vn.<chainID>.<flag> sets <flag> for one specific chain.
  • --vn.all.<flag> sets <flag> for every chain in the dependency set.
The environment-variable form follows the same prefix rule: OP_SUPERNODE_VN_<CHAINID>_<SUFFIX> for one chain and OP_SUPERNODE_VN_ALL_<SUFFIX> for every chain. The <SUFFIX> is the op-node flag’s source-level environment-variable name (see the note at the top of All configuration variables for why it doesn’t always match the CLI flag).
A few flags are owned by the supernode rather than by individual virtual nodes. Setting them under --vn.<chainID>.* or --vn.all.* has no effect.
  • --l1 and --l1.beacon: the shared L1 plumbing replaces any per-chain L1 setting at startup.
  • --l1.http-poll-interval: the shared L1 client owns the polling cadence; the supernode logs a warning if a per-chain value is set.
  • --log.*: the supernode and every virtual node share one logger; top-level --log.* configures it. Per-chain --vn.*.log.* flags appear in the namespace but are silently ignored. (--metrics.* is different: top-level configures the supernode’s own metrics service, but per-chain --vn.*.metrics.* configures each virtual node’s own metrics, which are fanned into the same endpoint with per-chain Prometheus labels.)
  • P2P listen ports: see the P2P section.
The flags most operators need to set per chain are listed below. For the full set of op-node flags available under the --vn.* namespace, see the op-node configuration reference and the consensus client configuration page.

​
vn.<chainID>.network

Names the chain’s known network configuration so the supernode can load the matching rollup config from op-node’s built-in registry. Use this for any chain registered with op-node (op-mainnet, op-sepolia, unichain-sepolia, etc.).
--vn.<chainID>.network=<value>

​
vn.<chainID>.rollup.config

Path to a rollup configuration JSON file for chains that are not in op-node’s built-in network registry. Use this instead of --vn.<chainID>.network for custom devnets or any chain you have a rollup config file for.
--vn.<chainID>.rollup.config=<value>

​
vn.<chainID>.l2

Address of the engine-API endpoint for the chain’s execution client. Each chain needs its own execution client; one execution client cannot back two chains.
--vn.<chainID>.l2=<value>

​
vn.all.l2.jwt-secret

Path to the JWT secret used to authenticate every virtual node’s engine connection to its execution client. Set this at the vn.all.* level when every execution client in the dependency set shares one secret. Use the per-chain --vn.<chainID>.l2.jwt-secret form only when a chain’s execution client requires its own secret.
--vn.all.l2.jwt-secret=<value>

​
vn.<chainID>.l2.enginekind

Selects the engine-client variant so the supernode can apply engine-API behavior tailored to each. Set to reth when the chain’s execution client is op-reth; leave at the default for op-geth. Supported values are geth and reth. The default value is geth.
--vn.<chainID>.l2.enginekind=<value>

​
P2P

P2P is enabled at the supernode level for every chain, or disabled for every chain. Per-chain enable/disable is not supported.

​
disable-p2p

Disables P2P for every chain. The default value is false. Use this in topologies where unsafe-head P2P gossip is handled by other nodes in the fleet (for example, a Light CL fleet) and the supernode only needs to derive from L1.
--disable-p2p=<value>

​
Per-chain listen ports

When P2P is enabled, each virtual node’s P2P listen port defaults to 0 (dynamic) to prevent port collisions across chains. Setting --vn.all.p2p.listen.tcp or --vn.all.p2p.listen.udp to a non-zero value is rejected because the same port cannot be reused across virtual nodes. To pin static ports per chain, set both the TCP (RLPx) and UDP (discovery v5) ports with the per-chain form: 
--vn.11155420.p2p.listen.tcp=9222 \
--vn.11155420.p2p.listen.udp=9222 \
--vn.1301.p2p.listen.tcp=9223 \
--vn.1301.p2p.listen.udp=9223

​
Interop verification

The interop activity is the part of op-supernode that decides when a chain’s blocks have satisfied their cross-chain dependencies. For background on how the activity decides between wait, advance, invalidate, and rewind, see the supernode explainer.

​
interop.activation-timestamp

Overrides the interop activation timestamp derived from the loaded rollup configs. The default value is 0 (use the value from the rollup config). Set this only when activating interop on a custom devnet whose rollup config does not yet carry the activation timestamp.
--interop.activation-timestamp=<value>

​
interop.log-backfill-depth

Extends initiating-message log ingestion backward from the L2 tip by this duration, clamped to the interop activation timestamp. Validation still starts only beyond the local safe head; the backfill pre-ingests logs so they are available when validation needs them. Requires the interop activation timestamp to be known, either from the rollup config or via --interop.activation-timestamp. The default value is 0s (no backfill).
--interop.log-backfill-depth=<value>

​
JSON-RPC server

The supernode exposes a single JSON-RPC server that multiplexes activity methods and every chain’s op-node RPC under one HTTP endpoint. Per-chain RPC namespaces are mounted under a /<chainID>/ path prefix on the same server. For example, POST /11155420/ reaches the OP Sepolia op-node RPC surface. Activity RPC methods (superroot_atTimestamp, supernode_syncStatus, heartbeat_check) are exposed at the root. For example, POST / with method superroot_atTimestamp reaches the SuperRoot activity.

​
rpc.addr

Address the JSON-RPC server binds to. The default value is 0.0.0.0.
--rpc.addr=<value>

​
rpc.port

Port the JSON-RPC server listens on. The default value is 8545.
--rpc.port=<value>

​
rpc.enable-admin

Enables admin-namespace RPC methods. The default value is false. Enable this only on endpoints that are not exposed to untrusted networks.
--rpc.enable-admin=<value>

​
Logging

Logging is configured at the top level. The supernode and every virtual node share one logger; per-chain --vn.*.log.* flags appear in the namespace but are silently ignored.

​
log.level

Minimum log severity to emit. Valid values are trace, debug, info, warn, error, crit. The default value is info.
--log.level=<value>

​
log.format

Log output format. Valid values are text, terminal, logfmt, logfmtms, json, jsonms (the *ms variants append millisecond timestamps). The default value is text. Set logfmt or json when ingesting logs into a structured-log pipeline; the default text is for hand-reading.
--log.format=<value>

​
log.color

Forces ANSI color codes in text log output regardless of whether the stream is a terminal. The default value is false.
--log.color=<value>

​
Metrics and profiling

Metrics and profiling endpoints are configured at the top level. The metrics server fans in counters from every chain container and exposes them on one endpoint with per-chain Prometheus labels.

​
metrics.enabled

Enables the Prometheus metrics server. The default value is false.
--metrics.enabled=<value>

​
metrics.addr

Address the metrics server binds to. The default value is 0.0.0.0.
--metrics.addr=<value>

​
metrics.port

Port the metrics server listens on. The default value is 7300.
--metrics.port=<value>

​
pprof.enabled

Enables the pprof profiling endpoint. The default value is false.
--pprof.enabled=<value>

​
pprof.addr

Address the pprof server binds to. The default value is 0.0.0.0.
--pprof.addr=<value>

​
pprof.port

Port the pprof server listens on. The default value is 6060.
--pprof.port=<value>

​
Where to go next