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 procedure may evolve before the stable release. For background on what op-supernode is and why it exists, see the supernode explainer.
This guide stands up a single op-supernode process from scratch: build the binary, wire each chain’s execution client over the engine API, start the process, and verify that every chain in the dependency set is syncing. At the end, one op-supernode acts as the consensus layer for every chain it hosts, replacing a separate op-node per chain. This page covers getting to a running, verified process. For recommended production settings — beacon archiver fallbacks, execution-client retention, Light CL fleets, and HA pools — continue with the supernode configuration guide. Every flag used below is catalogued in the op-supernode configuration reference.

​
Before you start

You need:
  • One execution client per chain. Each chain in the dependency set needs its own execution client with the engine API (authrpc) enabled; one execution client cannot back two chains. See the execution client configuration guide for client options, and the run a node from source tutorial for a full execution-client walkthrough.
  • L1 endpoints. An L1 JSON-RPC endpoint with the eth namespace enabled and an L1 beacon-node HTTP endpoint, shared by every chain. A beacon archiver fallback is strongly recommended — see configuring a blob archiver.
  • The chain IDs of every chain the supernode will host. For chains in op-node’s built-in network registry (for example op-sepolia, unichain-sepolia), the network name is enough. For any other chain, you need a rollup configuration JSON file per chain.

​
Build op-supernode

The binary is built from the Optimism Monorepo. The build environment is managed through mise, which installs the toolchains needed to build the monorepo — see mise.toml at the monorepo root.
1

Clone the monorepo and check out the release tag

2

Build the binary

The binary is written to op-supernode/bin/op-supernode.
3

Confirm the build

The flag set is generated dynamically from the --chains list, so to inspect the full help output for your chains, run ./bin/op-supernode --chains=<chainIDs> --help.

​
Create the JWT secret and wire the engine API

Each chain’s virtual node authenticates to that chain’s execution client over the engine API using a shared JWT secret.
1

Generate the secret

2

Start each execution client with the secret

Start every chain’s execution client with its authrpc listening and pointed at the same secret file — for op-reth, --authrpc.jwtsecret=<path>. Start the execution clients before the supernode; they simply won’t receive blocks until the supernode connects.
3

Note the engine-API endpoint of each execution client

You will pass each chain’s engine-API endpoint (port 8551 by convention) to the supernode as --vn.<chainID>.l2 in the next section. The supernode side of the secret is a single --vn.all.l2.jwt-secret=<path> flag when every execution client shares one secret; use the per-chain --vn.<chainID>.l2.jwt-secret form only when a client needs its own.

​
Start op-supernode

Start the supernode with the list of chain IDs, the shared L1 endpoints, and each chain’s network identity and engine-API endpoint. The example below hosts OP Sepolia (chain ID 11155420) and Unichain Sepolia (chain ID 1301) with op-reth execution clients. Fill in the placeholders, and add or remove the per-chain --vn.<chainID>.* groups to match your dependency set.
A few notes on the flags:
  • For a chain that is not in op-node’s built-in network registry, replace --vn.<chainID>.network with --vn.<chainID>.rollup.config=<path-to-rollup-config.json>.
  • The --vn.<chainID>.l2.enginekind=reth lines tell the supernode the execution client is op-reth; the default is geth, so drop them if you run op-geth.
  • P2P is enabled by default, with each virtual node’s listen port chosen dynamically to avoid collisions. Set --disable-p2p=true when other nodes in your topology handle unsafe-head gossip — see pair op-supernode with a Light CL fleet.
  • The JSON-RPC server listens on 0.0.0.0:8545 by default (--rpc.addr / --rpc.port). Like the op-node RPC, it is not meant to be exposed to the public internet.
  • Every flag has an environment-variable equivalent (OP_SUPERNODE_*) — the configuration guide’s example configuration shows the same kind of setup in environment-variable form, and the configuration reference lists the exact name for every flag.

​
Verify the supernode is working

1

Watch the logs

The heartbeat activity logs a heartbeat message every 10 seconds as a basic sign that the process is alive and its activities are running.
2

Check liveness over RPC

The heartbeat_check method at the RPC root returns a random hex value as a sign of life:
3

Check aggregate sync status

The supernode_syncStatus method at the RPC root returns the per-chain op-node sync status for every hosted chain, plus dependency-set-wide fields: the chain IDs, the highest fully derived and verified L1 block, and the safe, local-safe, and finalized L2 timestamps across the set.
Confirm that every chain ID you configured appears in the response and that the reported heads advance between calls.
4

Check an individual chain

Each chain’s full op-node RPC surface is mounted under a /<chainID>/ path prefix on the same server, so any op-node JSON-RPC method works per chain:
A chain’s endpoint becomes available once its chain container has started; requests to a chain ID that is not configured return 404 Not Found.
5

Check metrics

With --metrics.enabled=true, every chain’s metrics are fanned into a single Prometheus endpoint at /metrics on the metrics port (default 7300), labeled per chain:

​
Next steps