Optimism Documentation

This document lists all CLI flags for the kona-node node subcommand, grouped by category. All flags can be provided as command-line arguments or via environment variables.

For more details on each flag, see the inline help (kona-node node --help) or the source code.

Default Ports

Service	Transport	Default Port	Flag/Env
RPC HTTP	TCP	9545	`--port` / `KONA_NODE_RPC_PORT`
RPC WebSocket	TCP	9545	(same as HTTP, available by default)
P2P TCP	TCP	9222	`--p2p.listen.tcp` / `KONA_NODE_P2P_LISTEN_TCP_PORT`
P2P UDP	UDP	9223	`--p2p.listen.udp` / `KONA_NODE_P2P_LISTEN_UDP_PORT`

HTTP and WebSocket RPC share one TCP listener. WebSocket connections begin with an HTTP upgrade request on that same address and port. kona-node does not run a supervisor RPC server: the binary has no --supervisor.* flag group. Its only interop flag, --interop.dependency-set (KONA_NODE_INTEROP_DEPENDENCY_SET), takes a path to a dependency-set JSON file rather than a port. --conductor.rpc (KONA_NODE_CONDUCTOR_RPC) is not a listening port either. It is the RPC endpoint URL of an external conductor service that the node dials out to, and it has no default value. Supplying it enables the conductor integration when the node runs in sequencer mode (--mode sequencer); in validator mode it has no effect.

Core Node Arguments

Flag	Env	Description	Required	Default
`--mode <validator/sequencer>`	`KONA_NODE_MODE`	Mode of operation for the node	No	`validator`
`--l1-eth-rpc <URL>`	`KONA_NODE_L1_ETH_RPC`	URL of the L1 execution client RPC API	Yes	-
`--l1-trust-rpc=<true/false>`	`KONA_NODE_L1_TRUST_RPC`	Whether to trust the L1 RPC without verification	No	`false`
`--l1-beacon <URL>`	`KONA_NODE_L1_BEACON`	URL of the L1 beacon API	Yes	-
`--l2-engine-rpc <URL>`	`KONA_NODE_L2_ENGINE_RPC`	URL of the engine API endpoint of an L2 execution client	Yes	-
`--l2-trust-rpc=<true/false>`	`KONA_NODE_L2_TRUST_RPC`	Whether to trust the L2 RPC without verification	No	`true`
`--l2-engine-jwt-secret <PATH>`	`KONA_NODE_L2_ENGINE_AUTH`	Path to file containing the hex-encoded JWT secret for the execution client	No	-
`--l2-config-file <PATH>`	`KONA_NODE_ROLLUP_CONFIG`	Path to a custom L2 rollup configuration file	No	-
`--l1-runtime-config-reload-interval <SECONDS>`	`KONA_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVAL`	Poll interval for reloading runtime config	No	`600`

Global Arguments

Flag	Env	Description	Required	Default
`--l2-chain-id <ID/NAME>` or `-c <ID/NAME>`	`KONA_NODE_L2_CHAIN_ID`	L2 chain ID (numeric) or chain name (string)	No	`10` (Optimism)

Chain ID Support

The --l2-chain-id flag supports flexible chain identification using the alloy_chains crate: Numeric Chain IDs:

kona-node --l2-chain-id 10 node [args...]      # Optimism mainnet
kona-node --l2-chain-id 8453 node [args...]    # Base mainnet
kona-node --l2-chain-id 1 node [args...]       # Ethereum mainnet

String Chain Names:

kona-node --l2-chain-id optimism node [args...]
kona-node --l2-chain-id base node [args...]
kona-node --l2-chain-id mainnet node [args...]

Short Flag and Environment Variable:

kona-node -c optimism node [args...]
export KONA_NODE_L2_CHAIN_ID=optimism && kona-node node [args...]

Supported chain names include all those recognized by alloy_chains (e.g., optimism, base, mainnet). Unknown numeric chain IDs are accepted for custom networks.

P2P Arguments

Flag	Env	Description	Default
`--p2p.no-discovery`	`KONA_NODE_P2P_NO_DISCOVERY`	Disable Discv5 (node discovery), see running without discovery	`false`
`--p2p.priv.path <PATH>`	`KONA_NODE_P2P_PRIV_PATH`	Path to hex-encoded 32-byte private key for peer ID	-
`--p2p.priv.raw <HEX>`	`KONA_NODE_P2P_PRIV_RAW`	Hex-encoded 32-byte private key for peer ID	-
`--p2p.advertise.ip <IP>`	`KONA_NODE_P2P_ADVERTISE_IP`	IP to advertise to external peers	-
`--p2p.advertise.tcp <PORT>`	`KONA_NODE_P2P_ADVERTISE_TCP_PORT`	TCP port to advertise	`0`
`--p2p.advertise.udp <PORT>`	`KONA_NODE_P2P_ADVERTISE_UDP_PORT`	UDP port to advertise	`0`
`--p2p.listen.ip <IP>`	`KONA_NODE_P2P_LISTEN_IP`	IP to bind LibP2P/Discv5 to	`0.0.0.0`
`--p2p.listen.tcp <PORT>`	`KONA_NODE_P2P_LISTEN_TCP_PORT`	TCP port to bind LibP2P to	`9222`
`--p2p.listen.udp <PORT>`	`KONA_NODE_P2P_LISTEN_UDP_PORT`	UDP port to bind Discv5 to	`9223`
`--p2p.peers.lo <N>`	`KONA_NODE_P2P_PEERS_LO`	Low-tide peer count	`20`
`--p2p.peers.hi <N>`	`KONA_NODE_P2P_PEERS_HI`	High-tide peer count	`30`
`--p2p.peers.grace <SECONDS>`	`KONA_NODE_P2P_PEERS_GRACE`	Grace period for new peers	`30`
`--p2p.gossip.mesh.d <N>`	`KONA_NODE_P2P_GOSSIP_MESH_D`	GossipSub mesh target count	`8`
`--p2p.gossip.mesh.lo <N>`	`KONA_NODE_P2P_GOSSIP_MESH_DLO`	GossipSub mesh low watermark	`6`
`--p2p.gossip.mesh.dhi <N>`	`KONA_NODE_P2P_GOSSIP_MESH_DHI`	GossipSub mesh high watermark	`12`
`--p2p.gossip.mesh.dlazy <N>`	`KONA_NODE_P2P_GOSSIP_MESH_DLAZY`	GossipSub gossip target	`6`
`--p2p.gossip.mesh.floodpublish`	`KONA_NODE_P2P_GOSSIP_FLOOD_PUBLISH`	Publish to all known peers	`false`
`--p2p.scoring <none or light>`	`KONA_NODE_P2P_SCORING`	Peer scoring strategy	`light`
`--p2p.ban.peers`	`KONA_NODE_P2P_BAN_PEERS`	Enable peer banning	`false`
`--p2p.ban.threshold <N>`	`KONA_NODE_P2P_BAN_THRESHOLD`	Ban threshold	`-100`
`--p2p.ban.duration <MINUTES>`	`KONA_NODE_P2P_BAN_DURATION`	Ban duration	`60`
`--p2p.discovery.interval <SECONDS>`	`KONA_NODE_P2P_DISCOVERY_INTERVAL`	Peer discovery interval	`5`
`--p2p.bootstore <PATH>`	`KONA_NODE_P2P_BOOTSTORE`	Directory to store the bootstore	-
`--p2p.redial <N>`	`KONA_NODE_P2P_REDIAL`	Peer redialing threshold	`500`
`--p2p.redial.period <MINUTES>`	`KONA_NODE_P2P_REDIAL_PERIOD`	Peer dial period	`60`
`--p2p.bootnodes <ENR,...>`	`KONA_NODE_P2P_BOOTNODES`	List of bootnode ENRs or enode URLs	-
`--p2p.static-peers <MULTIADDR,...>`	`KONA_NODE_P2P_STATIC_PEERS`	Peers to dial at startup and keep connected, see static peers. Alias: `--p2p.static`	-
`--p2p.topic-scoring`	`KONA_NODE_P2P_TOPIC_SCORING`	Enable topic scoring	`false`
`--p2p.discovery.randomize <SECONDS>`	`KONA_NODE_P2P_DISCOVERY_RANDOMIZE`	Remove random peers from discovery	-
`--p2p.sequencer.key <HEX>`	`KONA_NODE_P2P_SEQUENCER_KEY`	Hex-encoded private key that signs gossiped blocks. A sequencer needs this, `--p2p.sequencer.key.path`, or a remote signer	-
`--p2p.sequencer.key.path <PATH>`	`KONA_NODE_P2P_SEQUENCER_KEY_PATH`	Path to a file with the hex-encoded private key that signs gossiped blocks	-
`--p2p.signer.endpoint <URL>`	`KONA_NODE_P2P_SIGNER_ENDPOINT`	Remote op-signer that signs gossiped blocks. Requires `--p2p.signer.address`	-
`--p2p.signer.address <ADDRESS>`	`KONA_NODE_P2P_SIGNER_ADDRESS`	Address of the remote signer’s key	-

Static peers

--p2p.static-peers lists peers that the node connects to directly and keeps connected, whatever discovery finds. Use it to make sure that a node, such as a sequencer, stays connected to the nodes it trusts.

Static peers don’t turn discovery off. On a chain in the superchain registry, discovery starts from the chain’s built-in bootnodes, even with no --p2p.bootnodes, and the node dials the peers saved in its bootstore. So the node still finds other nodes and connects to them, and they can find it. To connect only to static peers, also set --p2p.no-discovery, see running without discovery.

Each entry is a TCP multiaddr that ends in the peer’s ID:

kona-node node --p2p.static-peers /dns4/node-1.example.com/tcp/9222/p2p/16Uiu2HAm...,/dns4/node-2.example.com/tcp/9222/p2p/16Uiu2HAk...

Prefer /dns4/... addresses to /ip4/... ones. The name is resolved on every dial, so the list keeps working when a peer’s IP changes.
Repeat the flag, or give it a comma-separated list, as the environment variable needs. Spaces around entries are ignored, and an empty environment variable means no static peers.
The node doesn’t start if an address isn’t TCP or doesn’t end in /p2p/<peer id>.
Several addresses with the same peer ID make one peer, dialed at whichever address connects first.
The node ignores entries with its own peer ID, so every node in a group can use the same list.

A peer ID is derived from the node’s P2P private key. Give every static peer a fixed key with --p2p.priv.path or --p2p.priv.raw; without one, a node generates a new key, and so a new peer ID, each time it starts. To find a running node’s address, call opp2p_self: addresses lists its listen addresses with /p2p/<peer id> at the end. Replace the IP with the name or address other nodes reach it at. The node also logs its peer ID when it starts listening. To get the peer ID of a key file without running the node, use op-node p2p priv2id < key.txt, which works for kona keys too. The node treats its static peers as follows:

It dials them at startup, and once a minute dials those that aren’t connected. A static peer that disconnects is dialed again about a second later.
Static peers are exempt from the redial limit (--p2p.redial), are never banned for a low score, and stay protected after opp2p_unprotectPeer.
A static peer blocked with opp2p_blockPeer, or at a blocked address or subnet, isn’t dialed until it’s unblocked.
The node never passes its static peers on through discovery, so other nodes can’t find a static peer through it. A static peer can still be found if it runs discovery itself.

op-node calls this flag --p2p.static, which kona-node accepts too. The environment variable is KONA_NODE_P2P_STATIC_PEERS, not KONA_NODE_P2P_STATIC.

Running without discovery

With --p2p.no-discovery, the node doesn’t run Discv5:

It binds no UDP port, so --p2p.listen.udp may be in use by another process, and publishes no ENR.
It ignores --p2p.bootnodes, the chain’s built-in bootnodes and the bootstore.
It connects only to its static peers, to peers that dial it, and to peers added with opp2p_connectPeer. Other nodes can’t find it, so only the nodes given its address dial it.

It still exchanges blocks over gossip with the peers it’s connected to. A node can relay blocks between peers that aren’t connected to each other, such as the hub of a group whose members list only the hub as a static peer. The P2P RPC methods still answer. As op-node’s do when discovery is off, opp2p_self returns no ENR, opp2p_peerStats returns a table of 0, and opp2p_discoveryTable returns the error discovery disabled. opp2p_peerCount, which op-node doesn’t have, returns null for connectedDiscovery, and opp2p_peers returns no ENR and a chainID of 0 for each peer. op-conductor’s health check reads connected from opp2p_peerStats, which counts static peers. With discovery on, the node stops if discovery fails to start or stops later, even if it has static peers. The node finds its peers as follows:

Discovery	Bootnodes	Static peers	Behavior
On	None, chain in the registry	Any	Connects to the peers it finds from the chain’s built-in bootnodes, to the peers saved in its bootstore, and to its static peers.
On	None, chain not in the registry	Any	Connects to the peers saved in its bootstore, if any, and to its static peers. Otherwise it finds nobody until other nodes bootstrap from it, as the first bootnode of a new network does.
On	Set	Any	Connects to the peers it finds from the bootnodes given and the built-in ones, to the peers saved in its bootstore, and to its static peers.
Off	Ignored	Set	Connects only to its static peers and the peers that dial it. A static peer that’s down is dialed again once a minute, so a node can start before its peers.
Off	Ignored	None	Connects only to peers that dial it, or that are added with `opp2p_connectPeer`, as the hub of a group does.

With discovery off, the node logs a warning at startup if no static peers are set, and if bootnodes are set, since it ignores them.

RPC Arguments

The RPC server starts once. If it stops unexpectedly, the node shuts down with an error.

Flag	Env	Description	Default
`--rpc.disabled`	`KONA_NODE_RPC_DISABLED`	Disable the RPC server	`false`
`--rpc.addr <IP>`	`KONA_NODE_RPC_ADDR`	RPC listening address	`0.0.0.0`
`--port <PORT>`	`KONA_NODE_RPC_PORT`	RPC listening port	`9545`
`--rpc.enable-admin`	`KONA_NODE_RPC_ENABLE_ADMIN`	Enable the admin API	`false`
`--rpc.admin-state <PATH>`	`KONA_NODE_RPC_ADMIN_STATE`	File path for admin state persistence	-

Sequencer Arguments

Flag	Env	Description	Default
`--sequencer.stopped`	`KONA_NODE_SEQUENCER_STOPPED`	Start sequencer in stopped state	`false`
`--sequencer.l1-confs <N>`	`KONA_NODE_SEQUENCER_L1_CONFS`	L1 block confirmations for sequencer	`4`
`--sequencer.recover`	`KONA_NODE_SEQUENCER_RECOVER`	Strictly prepare next L1 origin and create empty L2 blocks	`false`
`--conductor.rpc <URL>`	`KONA_NODE_CONDUCTOR_RPC`	RPC endpoint URL of an external conductor service. Supplying it enables the conductor integration in sequencer mode; it has no effect in validator mode.	-
`--conductor.rpc.timeout <SECONDS>`	`KONA_NODE_CONDUCTOR_RPC_TIMEOUT`	Conductor service RPC timeout	`1`

Interop Arguments

Flag	Env	Description	Default
`--interop.dependency-set <PATH>`	`KONA_NODE_INTEROP_DEPENDENCY_SET`	Path to the JSON file describing the interop dependency set for this chain. Required when the rollup config schedules the Lagoon hardfork.	-
`--safedb.path <PATH>`	`KONA_NODE_SAFEDB_PATH`	Directory of the safe head database, which records the L2 safe head reached as of each L1 block and backs `optimism_safeHeadAtL1Block` and `superroot_atTimestamp`. Needed by op-challenger, op-proposer and op-dispute-mon. Nothing is recorded when unset.	-

kona-node does not run a supervisor RPC server, so there is no --supervisor.* flag group. --interop.dependency-set is the node’s only interop flag.

RPC Trust Flags

The --l1-trust-rpc and --l2-trust-rpc flags control whether Kona verifies the block hashes of RPC responses. For guidance on when to disable trust and worked examples for trusted, untrusted, and mixed provider setups, see configure RPC trust.

Default Behavior

Unless overridden by the flags above, a kona-node node run has the following defaults:

The P2P stack is spun up. The libp2p swarm listens on TCP 9222 to receive block gossip. The discv5 discovery service runs on UDP port 9223. Peer scoring is enabled.
An RPC server is exposed at 0.0.0.0:9545. Websocket connections are disabled by default.
Prometheus metrics are disabled. Enable them with the --metrics.enabled flag; metrics are then served on 0.0.0.0:9090, configurable via the --metrics.port and --metrics.addr flags.

Rollup Configuration Loading

If a file path to a rollup config is not specified via the --l2-config-file cli flag, the Rollup Config will be loaded via the superchain registry. A custom rollup config can either be specified through the --l2-config-file flag, or specific values may be overridden using a set of override flags provided by the kona-node. Override flags (for example --canyon-override) can be viewed in the help menu by running kona-node node --help. The only overrides currently supported are hardfork timestamps in seconds.

Run a node

Guides

Tutorials

Clients

Reference

Kona Node CLI Reference

Default Ports

Core Node Arguments

Global Arguments

Chain ID Support

P2P Arguments

Static peers

Running without discovery

RPC Arguments

Sequencer Arguments

Interop Arguments

RPC Trust Flags

Default Behavior

Rollup Configuration Loading

​Default Ports

​Core Node Arguments

​Global Arguments

​Chain ID Support

​P2P Arguments

​Static peers

​Running without discovery

​RPC Arguments

​Sequencer Arguments

​Interop Arguments

​RPC Trust Flags

​Default Behavior

​Rollup Configuration Loading

Default Ports

Core Node Arguments

Global Arguments

Chain ID Support

P2P Arguments

Static peers

Running without discovery

RPC Arguments

Sequencer Arguments

Interop Arguments

RPC Trust Flags

Default Behavior

Rollup Configuration Loading