Skip to main content
op-supernode is in active development. This page tracks the op-supernode/v0.2.2-rc.8 release candidate and the recommendations may evolve before the stable release. For background on what op-supernode is and why it exists, see the supernode explainer.
This guide covers the recommended settings and a starter configuration 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. For the complete per-flag catalogue, see the op-supernode configuration reference.

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

​
Configure EL retention for supernode backfill

The supernode reads historical block and receipt data from each chain’s execution client to backfill initiating-message logs after restarts or extended downtime. ELs that aggressively prune receipts will break the backfill path.
Configure each EL to retain at least 7 days of block and receipt history. A full archive is not required — see the op-reth configuration reference for the granular --prune.* flags that let you keep block and receipt history without enabling transaction indexing or world-state history. If you also run op-challenger for permissionless fault proofs, the same ELs additionally need historical proofs enabled — see Running op-reth with Historical Proofs.

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

​
Run an HA pool of supernodes behind a consensus-aware proxyd

For production reliability, OP Labs recommends running an HA pool of at least three op-supernode instances and fronting them with a consensus-aware proxyd configured with the consensus_aware_consensus_layer routing strategy. Point the Light CL fleet’s --l2.follow.source at the proxyd endpoint rather than at a single supernode. This hides individual supernode failures or reorgs from the Light CL fleet and lets the supernode tier roll between releases without downtime. An individual supernode going down inside the HA pool is masked by proxyd — Light CLs continue following the surviving instances. If the entire supernode tier becomes unreachable, Light CLs keep advancing the unsafe chain over P2P gossip and resume safe-head tracking automatically once the tier is restored. A single op-supernode is acceptable for evaluation, but treat it as a single point of failure for safe-head progression on every chain it hosts.

​
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.
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>. Every flag in the example — and everything else the binary accepts, including P2P, interop verification, JSON-RPC, logging, and metrics options — is catalogued with syntax, examples, and environment-variable names in the op-supernode configuration reference.

​
Where to go next