Optimism Documentation

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.

This page catalogues all configuration options for op-supernode, organized by functionality. The following options are from the --help in op-supernode/v0.2.2-rc.8. For recommended settings, deployment topologies, and a starter configuration, see the supernode configuration guide. For what op-supernode is and why it exists, see the supernode explainer.

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.

Syntax
Example
Environment Variable

--chains=<value>

--chains=11155420,1301

OP_SUPERNODE_CHAINS=

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.

Syntax
Example
Environment Variable

--data-dir=<value>

--data-dir=/var/lib/op-supernode

OP_SUPERNODE_DATA_DIR=

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.

Syntax
Example
Environment Variable

--l1=<value>

--l1=https://ethereum-rpc-endpoint.example.com

OP_SUPERNODE_L1_ETH_RPC=

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.

Syntax
Example
Environment Variable

--l1.beacon=<value>

--l1.beacon=https://ethereum-beacon-endpoint.example.com

OP_SUPERNODE_L1_BEACON=

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.

Syntax
Example
Environment Variable

--l1.beacon-fallbacks=<value>

--l1.beacon-fallbacks=https://archiver-1.example.com,https://archiver-2.example.com

OP_SUPERNODE_L1_BEACON_FALLBACKS=

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.

Syntax
Example
Environment Variable

--l1.http-poll-interval=<value>

--l1.http-poll-interval=12s

OP_SUPERNODE_L1_HTTP_POLL_INTERVAL=

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 this page 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.).

Syntax
Example
Environment Variable

--vn.<chainID>.network=<value>

--vn.11155420.network=op-sepolia

OP_SUPERNODE_VN_<CHAINID>_NETWORK=

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.

Syntax
Example
Environment Variable

--vn.<chainID>.rollup.config=<value>

--vn.420120037.rollup.config=/etc/op/rollup-config.json

OP_SUPERNODE_VN_<CHAINID>_ROLLUP_CONFIG=

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.

Syntax
Example
Environment Variable

--vn.<chainID>.l2=<value>

--vn.11155420.l2=http://op-sepolia-geth:8551

OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_RPC=

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.

Syntax
Example
Environment Variable

--vn.all.l2.jwt-secret=<value>

--vn.all.l2.jwt-secret=/etc/op/jwt-secret.txt

OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH=

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.

Syntax
Example
Environment Variable

--vn.<chainID>.l2.enginekind=<value>

--vn.11155420.l2.enginekind=reth

OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_KIND=

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.

Syntax
Example
Environment Variable

--disable-p2p=<value>

--disable-p2p=true

OP_SUPERNODE_DISABLE_P2P=

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.

Syntax
Example
Environment Variable

--interop.activation-timestamp=<value>

--interop.activation-timestamp=1735689600

OP_SUPERNODE_INTEROP_ACTIVATION_TIMESTAMP=

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).

Syntax
Example
Environment Variable

--interop.log-backfill-depth=<value>

--interop.log-backfill-depth=168h

OP_SUPERNODE_INTEROP_LOG_BACKFILL_DEPTH=

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.

Syntax
Example
Environment Variable

--rpc.addr=<value>

--rpc.addr=0.0.0.0

OP_SUPERNODE_RPC_ADDR=

rpc.port

Port the JSON-RPC server listens on. The default value is 8545.

Syntax
Example
Environment Variable

--rpc.port=<value>

--rpc.port=8545

OP_SUPERNODE_RPC_PORT=

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.

Syntax
Example
Environment Variable

--rpc.enable-admin=<value>

--rpc.enable-admin=true

OP_SUPERNODE_RPC_ENABLE_ADMIN=

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.

Syntax
Example
Environment Variable

--log.level=<value>

--log.level=info

OP_SUPERNODE_LOG_LEVEL=

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.

Syntax
Example
Environment Variable

--log.format=<value>

--log.format=json

OP_SUPERNODE_LOG_FORMAT=

log.color

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

Syntax
Example
Environment Variable

--log.color=<value>

--log.color=true

OP_SUPERNODE_LOG_COLOR=

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.

Syntax
Example
Environment Variable

--metrics.enabled=<value>

--metrics.enabled=true

OP_SUPERNODE_METRICS_ENABLED=

metrics.addr

Address the metrics server binds to. The default value is 0.0.0.0.

Syntax
Example
Environment Variable

--metrics.addr=<value>

--metrics.addr=0.0.0.0

OP_SUPERNODE_METRICS_ADDR=

metrics.port

Port the metrics server listens on. The default value is 7300.

Syntax
Example
Environment Variable

--metrics.port=<value>

--metrics.port=7300

OP_SUPERNODE_METRICS_PORT=

pprof.enabled

Enables the pprof profiling endpoint. The default value is false.

Syntax
Example
Environment Variable

--pprof.enabled=<value>

--pprof.enabled=true

OP_SUPERNODE_PPROF_ENABLED=

pprof.addr

Address the pprof server binds to. The default value is 0.0.0.0.

Syntax
Example
Environment Variable

--pprof.addr=<value>

--pprof.addr=0.0.0.0

OP_SUPERNODE_PPROF_ADDR=

pprof.port

Port the pprof server listens on. The default value is 6060.

Syntax
Example
Environment Variable

--pprof.port=<value>

--pprof.port=6060

OP_SUPERNODE_PPROF_PORT=

Where to go next

Follow the supernode configuration guide for recommended settings and a starter configuration.
Read the supernode explainer for what op-supernode is and why it exists.
Read the op-node configuration reference for the full set of flags available under the --vn.* namespace.
See the op-supernode source in the monorepo for implementation detail.

​Dependency set and storage

​chains

​data-dir

​Shared L1 access

​l1

​l1.beacon

​l1.beacon-fallbacks

​l1.http-poll-interval

​Per-chain virtual-node configuration

​vn.<chainID>.network

​vn.<chainID>.rollup.config

​vn.<chainID>.l2

​vn.all.l2.jwt-secret

​vn.<chainID>.l2.enginekind

​P2P

​disable-p2p

​Per-chain listen ports

​Interop verification

​interop.activation-timestamp

​interop.log-backfill-depth

​JSON-RPC server

​rpc.addr

​rpc.port

​rpc.enable-admin

​Logging

​log.level

​log.format

​log.color

​Metrics and profiling

​metrics.enabled

​metrics.addr

​metrics.port

​pprof.enabled

​pprof.addr

​pprof.port

​Where to go next

Dependency set and storage

chains

data-dir

Shared L1 access

l1

l1.beacon

l1.beacon-fallbacks

l1.http-poll-interval

Per-chain virtual-node configuration

vn.<chainID>.network

vn.<chainID>.rollup.config

vn.<chainID>.l2

vn.all.l2.jwt-secret

vn.<chainID>.l2.enginekind

P2P

disable-p2p

Per-chain listen ports

Interop verification

interop.activation-timestamp

interop.log-backfill-depth

JSON-RPC server

rpc.addr

rpc.port

rpc.enable-admin

Logging

log.level

log.format

log.color

Metrics and profiling

metrics.enabled

metrics.addr

metrics.port

pprof.enabled

pprof.addr

pprof.port

Where to go next