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
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
Global Arguments
Chain ID Support
The--chain flag supports flexible chain identification using the alloy_chains crate:
Numeric Chain IDs:
alloy_chains (e.g., optimism, optimism-sepolia). Unknown numeric chain IDs are accepted for custom networks.
P2P Arguments
Advertised address
Other nodes find the node through the record that discovery publishes, its ENR. The record holds the TCP port for gossip, the UDP port for discovery, and the IP to reach both at, once the node knows it:
The TCP port is
--p2p.advertise.tcp if set, and otherwise the port LibP2P binds: --p2p.listen.tcp, or the port picked for a listen port of 0. The UDP port is --p2p.advertise.udp if set, and otherwise the port discovery listens on.
Without --p2p.advertise.ip, discovery learns the node’s address from the peers it finds through its bootnodes: each one it contacts reports the address it sees the node at. The bootnodes themselves don’t count. Once --p2p.discovery.ip-votes of them, 10 by default, report the same address, the node advertises it. Until then, a node without an IP in its record can’t be contacted, so other nodes don’t keep it. The peers it reached before then add it once they start a new session with it, or learn its record from another node.
On a network with fewer reachable nodes than that, not counting the node’s bootnodes, such as a devnet or a local test network, a node listening on all interfaces never learns its address, and other nodes can’t find it. Nodes that listen on all interfaces count only once they’ve learned their own address, so on a small network where most nodes do, none of them may. On such a network:
- Set
--p2p.advertise.ipto the address other nodes reach it at, or listen on that address with--p2p.listen.ip. - Or lower
--p2p.discovery.ip-votes. Fewer votes let fewer peers decide the address: two colluding peers could make the node unreachable, or point other nodes at another host. So keep the default on public networks.
--p2p.advertise.ip.
op-node never advertises its listen IP: without
--p2p.advertise.ip, it learns its address from the peers’ votes, with a fixed threshold of 10. So op-node needs --p2p.advertise.ip on small networks too, even when it listens on a specific address.Discovered addresses
Other nodes hand the node records that can name an address it can’t reach, such as another host’s127.0.0.1, or a host that isn’t a node at all. So the node follows two rules:
- Apart from its bootnodes, which it dials once at startup, it dials only nodes discovery has had a session with, and only if the TCP address in their record has the IP the session came from. It saves such records and the bootnodes of its chain in its bootstore, apart from private ones, see below. The saved records seed discovery: 30 at random at startup, the peers it dialed in the last week first, and 30 others every minute while discovery has fewer than 30 peers. A peer it dialed since startup and lost is dialed again every minute for a day. A bootnode that runs gossip without discovery is better listed in
--p2p.static-peers. A record that names another host is dropped. Static peers andopp2p_connectPeerare dialed as given. - Discovery uses only public addresses, unless
--p2p.discovery.privateis set. A record with a “this network” (0.0.0.0/8), loopback, private, link-local, shared (100.64.0.0/10), IETF protocol assignment (192.0.0.0/24), benchmarking (198.18.0.0/15), reserved (240.0.0.0/4), multicast, broadcast or documentation address isn’t contacted, kept in the discovery table, or saved, unless it starts a session with the node, see below, and the bootstore drops it at startup. Some clouds and labs use the benchmarking and reserved ranges for internal addresses. This applies to bootnodes, given as ENRs or enode URLs, so a devnet that uses loopback or LAN bootnodes needs the flag. The other special-purpose ranges, such as anycast and NAT64 addresses, count as public.
externalTrafficPolicy: Cluster, the default, packets from other nodes reach the node from a cluster node’s IP rather than their own. A node that starts a session with it then doesn’t match its record, so it isn’t dialed, and the node finds fewer peers than op-node does. Sessions the node starts itself are unaffected. Set externalTrafficPolicy: Local to keep the senders’ IPs.
Without --p2p.discovery.private, the node never reaches out to a private address first. A node at a private address that starts a session with it is neither dialed back nor saved: it can dial this node over gossip, which accepts it, and if it keeps the peers it found, as kona-node does in its bootstore, it can redial this node. To peer with private nodes, such as neighbours in a VPC, set the flag, or list them in --p2p.static-peers. Discovery also keeps a node it has a session with in its table, and passes its record on to nodes that look it up, as it can’t check a record against the node asking for it. Nodes that follow these rules don’t contact a private record they get this way.
To keep a node, such as a sequencer, behind public sentry nodes, run it with
--p2p.no-discovery, list the sentries in its --p2p.static-peers, and list it in theirs, see static peers and running without discovery. Static peers are dialed directly, redialed every minute, and never passed on through discovery.A node that ran discovery against its sentry instead would leak, and wouldn’t stay behind it: the sentry keeps it in its table, and passes its record, with its node ID and LAN address, on to every node that looks it up. The node also finds the sentry’s other peers through it, and connects to them directly.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.
Each entry is a TCP multiaddr that ends in the peer’s ID:
- 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.
--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 afteropp2p_unprotectPeer. - A static peer blocked with
opp2p_blockPeer, or at a blocked address or subnet, is disconnected and isn’t dialed again until it’s unblocked. Once unblocked, it’s dialed at the next check, within a minute. To connect it at once, callopp2p_connectPeer. The node logs a warning when a block covers a static peer: by its peer ID, by an IP address it’s configured with, or by the address of its open connection. It can’t tell for a static peer given by DNS name that isn’t connected. - 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.udpmay 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.
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:
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.Sequencer Arguments
Interop Arguments
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 Flag
The--l1-trust-rpc flag controls whether Kona verifies L1 RPC responses. Without L1 trust, Kona checks L1 headers against their block hashes, and L1 transactions and receipts against the header’s roots, and proves the unsafe block signer with eth_getProof, which the L1 RPC must therefore serve. The L2 engine is the node’s own execution client and is always trusted. For guidance on when to disable L1 trust and worked examples, see configure RPC trust.
Default Behavior
Unless overridden by the flags above, akona-node node run has the following defaults:
- The P2P stack is spun up. The libp2p swarm listens on TCP
9222to receive block gossip. Thediscv5discovery service runs on UDP port9223. Peer scoring is enabled. - An RPC server is exposed at
0.0.0.0:9545. It accepts both HTTP and WebSocket connections. - Prometheus metrics are disabled. Enable them with the
--metrics.enabledflag; metrics are then served on0.0.0.0:9090, configurable via the--metrics.portand--metrics.addrflags.
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.