Skip to main content
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. :::note For more details on each flag, see the inline help (kona-node node --help) or the source code. :::

​
Default Ports

ServiceDefault PortFlag/Env
RPC HTTP9545--port / KONA_NODE_RPC_PORT
RPC WebSocket9545(same as HTTP, enabled with --rpc.ws-enabled)
P2P TCP9222--p2p.listen.tcp / KONA_NODE_P2P_LISTEN_TCP_PORT
P2P UDP9223--p2p.listen.udp / KONA_NODE_P2P_LISTEN_UDP_PORT
Supervisor RPC9333--supervisor.port / KONA_NODE_SEQUENCER_PORT
Conductor RPC8547--conductor.rpc / KONA_NODE_CONDUCTOR_RPC

​
Core Node Arguments

FlagEnvDescriptionRequiredDefault
--mode <verifier/sequencer>KONA_NODE_MODEMode of operation for the nodeYesverifier
--l1-eth-rpc <URL>KONA_NODE_L1_ETH_RPCURL of the L1 execution client RPC APIYes-
--l1-trust-rpc <true/false>KONA_NODE_L1_TRUST_RPCWhether to trust the L1 RPC without verificationNotrue
--l1-beacon <URL>KONA_NODE_L1_BEACONURL of the L1 beacon APIYes-
--l2-engine-rpc <URL>KONA_NODE_L2_ENGINE_RPCURL of the engine API endpoint of an L2 execution clientYes-
--l2-trust-rpc <true/false>KONA_NODE_L2_TRUST_RPCWhether to trust the L2 RPC without verificationNotrue
--l2-engine-jwt-secret <PATH>KONA_NODE_L2_ENGINE_AUTHPath to file containing the hex-encoded JWT secret for the execution clientNo-
--l2-config-file <PATH>KONA_NODE_ROLLUP_CONFIGPath to a custom L2 rollup configuration fileNo-
--l1-runtime-config-reload-interval <SECONDS>KONA_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVALPoll interval for reloading runtime configNo600

​
Global Arguments

FlagEnvDescriptionRequiredDefault
--l2-chain-id <ID/NAME> or -c <ID/NAME>KONA_NODE_L2_CHAIN_IDL2 chain ID (numeric) or chain name (string)No10 (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

FlagEnvDescriptionDefault
--p2p.no-discoveryKONA_NODE_P2P_NO_DISCOVERYDisable Discv5 (node discovery)false
--p2p.priv.path <PATH>KONA_NODE_P2P_PRIV_PATHPath to hex-encoded 32-byte private key for peer ID-
--p2p.priv.raw <HEX>KONA_NODE_P2P_PRIV_RAWHex-encoded 32-byte private key for peer ID-
--p2p.advertise.ip <IP>KONA_NODE_P2P_ADVERTISE_IPIP to advertise to external peers-
--p2p.advertise.tcp <PORT>KONA_NODE_P2P_ADVERTISE_TCP_PORTTCP port to advertise0
--p2p.advertise.udp <PORT>KONA_NODE_P2P_ADVERTISE_UDP_PORTUDP port to advertise0
--p2p.listen.ip <IP>KONA_NODE_P2P_LISTEN_IPIP to bind LibP2P/Discv5 to0.0.0.0
--p2p.listen.tcp <PORT>KONA_NODE_P2P_LISTEN_TCP_PORTTCP port to bind LibP2P to9222
--p2p.listen.udp <PORT>KONA_NODE_P2P_LISTEN_UDP_PORTUDP port to bind Discv5 to9223
--p2p.peers.lo <N>KONA_NODE_P2P_PEERS_LOLow-tide peer count20
--p2p.peers.hi <N>KONA_NODE_P2P_PEERS_HIHigh-tide peer count30
--p2p.peers.grace <SECONDS>KONA_NODE_P2P_PEERS_GRACEGrace period for new peers30
--p2p.gossip.mesh.d <N>KONA_NODE_P2P_GOSSIP_MESH_DGossipSub mesh target count8
--p2p.gossip.mesh.lo <N>KONA_NODE_P2P_GOSSIP_MESH_DLOGossipSub mesh low watermark6
--p2p.gossip.mesh.dhi <N>KONA_NODE_P2P_GOSSIP_MESH_DHIGossipSub mesh high watermark12
--p2p.gossip.mesh.dlazy <N>KONA_NODE_P2P_GOSSIP_MESH_DLAZYGossipSub gossip target6
--p2p.gossip.mesh.floodpublishKONA_NODE_P2P_GOSSIP_FLOOD_PUBLISHPublish to all known peersfalse
--p2p.scoring <none or light>KONA_NODE_P2P_SCORINGPeer scoring strategylight
--p2p.ban.peersKONA_NODE_P2P_BAN_PEERSEnable peer banningfalse
--p2p.ban.threshold <N>KONA_NODE_P2P_BAN_THRESHOLDBan threshold-100
--p2p.ban.duration <MINUTES>KONA_NODE_P2P_BAN_DURATIONBan duration60
--p2p.discovery.interval <SECONDS>KONA_NODE_P2P_DISCOVERY_INTERVALPeer discovery interval5
--p2p.bootstore <PATH>KONA_NODE_P2P_BOOTSTOREDirectory to store the bootstore-
--p2p.redial <N>KONA_NODE_P2P_REDIALPeer redialing threshold500
--p2p.redial.period <MINUTES>KONA_NODE_P2P_REDIAL_PERIODPeer dial period60
--p2p.bootnodes <ENR,...>KONA_NODE_P2P_BOOTNODESList of bootnode ENRs-
--p2p.topic-scoringKONA_NODE_P2P_TOPIC_SCORINGEnable topic scoringfalse
--p2p.discovery.randomize <SECONDS>KONA_NODE_P2P_DISCOVERY_RANDOMIZERemove random peers from discovery-

​
RPC Arguments

FlagEnvDescriptionDefault
--rpc.disabledKONA_NODE_RPC_DISABLEDDisable the RPC serverfalse
--rpc.no-restartKONA_NODE_RPC_NO_RESTARTPrevent RPC server from restartingfalse
--rpc.addr <IP>KONA_NODE_RPC_ADDRRPC listening address0.0.0.0
--port <PORT>KONA_NODE_RPC_PORTRPC listening port9545
--rpc.enable-adminKONA_NODE_RPC_ENABLE_ADMINEnable the admin APIfalse
--rpc.admin-state <PATH>KONA_NODE_RPC_ADMIN_STATEFile path for admin state persistence-
--rpc.ws-enabledKONA_NODE_RPC_WS_ENABLEDEnable websocket RPC serverfalse

​
Sequencer Arguments

FlagEnvDescriptionDefault
--sequencer.stoppedKONA_NODE_SEQUENCER_STOPPEDStart sequencer in stopped statefalse
--sequencer.max-safe-lag <N>KONA_NODE_SEQUENCER_MAX_SAFE_LAGMax L2 safe/unsafe lag0
--sequencer.l1-confs <N>KONA_NODE_SEQUENCER_L1_CONFSL1 block confirmations for sequencer4
--sequencer.recoverKONA_NODE_SEQUENCER_RECOVERStrictly prepare next L1 origin and create empty L2 blocksfalse
--conductor.enabledKONA_NODE_CONDUCTOR_ENABLEDEnable the conductor servicefalse
--conductor.rpc <ADDR>KONA_NODE_CONDUCTOR_RPCConductor service RPC endpoint127.0.0.1:8547
--conductor.rpc.timeout <SECONDS>KONA_NODE_CONDUCTOR_RPC_TIMEOUTConductor service RPC timeout1

​
Supervisor Arguments

FlagEnvDescriptionDefault
--supervisor.rpc-enabledKONA_NODE_SUPERVISOR_RPC_ENABLEDEnable Supervisor Websocketfalse
--supervisor.ip.address <IP>KONA_NODE_SUPERVISOR_IPIP to bind Supervisor Websocket RPC server0.0.0.0
--supervisor.port <PORT>KONA_NODE_SUPERVISOR_PORTTCP port for supervisor RPC9333
--supervisor.jwt.secret <HEX>KONA_NODE_SUPERVISOR_JWT_SECRETJWT secret for supervisor websocket authentication-
--supervisor.jwt.secret.file <PATH>KONA_NODE_SUPERVISOR_JWT_SECRET_FILEPath to file containing JWT secret-

​
RPC Trust Configuration

The --l1-trust-rpc and --l2-trust-rpc flags control whether Kona performs additional verification on RPC responses to protect against malicious or faulty RPC providers.

​
Trust Modes

Default Behavior (trust enabled, true):
  • No additional block hash verification is performed
  • Optimized for performance
  • Suitable for local nodes and trusted infrastructure
  • Assumes the RPC provider is reliable and honest
Verification Mode (trust disabled, false):
  • All fetched blocks have their hashes verified against the requested hashes
  • Protects against malicious RPC providers returning incorrect blocks
  • Recommended for public or third-party RPC endpoints
  • Small performance overhead due to hash verification

​
Examples

Using trusted local RPCs (default): 
kona-node node \
  --l1-eth-rpc http://localhost:8545 \
  --l2-engine-rpc http://localhost:8551 \
  # trust-rpc defaults to true, no need to specify
Using untrusted public RPCs: 
kona-node node \
  --l1-eth-rpc https://public-eth-rpc.com \
  --l1-trust-rpc false \
  --l2-engine-rpc https://public-l2-rpc.com \
  --l2-trust-rpc false
Mixed trust configuration: 
kona-node node \
  --l1-eth-rpc https://public-eth-rpc.com \
  --l1-trust-rpc false \
  --l2-engine-rpc http://localhost:8551 \
  # L2 trust-rpc defaults to true for local engine

​
Security Recommendations

  1. Local Infrastructure: Keep the default true setting for RPCs you control
  2. Public RPCs: Always set --trust-rpc false when using third-party endpoints
  3. Shared Infrastructure: Consider setting --trust-rpc false as a precaution
  4. Performance Testing: The verification overhead is minimal but can be measured in high-throughput scenarios