Skip to main content
:::note If you haven’t already built the kona-node binary, head over to the Installation guide. ::: kona-node is an L2 consensus client (also called a “rollup node”). This means that the node is a consensus-layer client, which needs a corresponding execution-layer client in order to sync and follow the L2 chain. A number of L2 execution layer clients are available, since the OP Stack uses a minimal diff approach to L1 execution clients, including op-reth and op-geth. This section will illustrate running the kona-node with an instance of op-reth. Out of the box, the kona-node can be used for any OP Stack chain that is part of the superchain-registry. In order to use an out-of-band OP Stack chain, for example a new devnet, you’ll need to specify the rollup config using the custom --l2-config-file cli flag. More on that in the More Detailed Node Docs Section.
This tutorial walks through running the kona-node as a binary. To use docker, head over to the Docker Guide which uses a docker-compose setup provided by kona. The docker-compose setup automatically bootstraps the kona-node with op-reth, provisioning grafana dashboards and a default Prometheus configuration. It is encouraged to follow the Docker Guide to avoid misconfigurations.
The kona-node requires a few CLI flags.
  • --l1-eth-rpc <L1_ETH_RPC> URL of the L1 execution client RPC API.
  • --l1-beacon <L1_BEACON> URL of the L1 beacon API.
  • --l2-engine-rpc <L2_ENGINE_RPC> URL of the engine API endpoint of an L2 execution client.
The L2 engine RPC points to the execution layer client’s engine API, op-reth. An L1 beacon endpoint and rpc endpoint are also required to fetch the L1 chain data that the L2 chain is derived from. First, start an instance of op-reth. The op-reth docs provide very detailed instructions for running op-reth nodes for OP Stack chains (L2). For this demo, we’ll use base, but any other OP Stack chain will do. 
op-reth node \
    --chain base \
    --rollup.sequencer-http https://mainnet-sequencer.base.org \
    --http \
    --ws \
    --authrpc.port 9551 \
    --authrpc.jwtsecret /path/to/jwt.hex
Kona has a generate-jwt justfile target that can be used to create the jwt.hex file. Run just generate-jwt.
The JWT token file path passed into --authrpc.jwtsecret MUST be the same as the one passed into the kona-node.This JWT token is how the op-reth client authenticates requests made by the kona-node to the engine rpc.By default, the kona-node will attempt to read a JWT token from a jwt.hex file in the local directory. If it cannot find one, it will create a JWT token in a new jwt.hex file.To specify the path to the file that contains the JWT token, pass the file path into the --l2.jwt-secret CLI flag or use the KONA_NODE_L2_ENGINE_AUTH environment variable.
Then, run the kona-node using Base’s chain id - 8453. 
kona-node node \
    --chain 8453 \
    --l1-eth-rpc <L1_RPC_URL> \
    --l1-beacon <L1_BEACON_URL> \
    --l2-engine-rpc http://127.0.0.1:9551 \
That’s it! Your node should connect to P2P and start syncing quickly.

​
RPC Trust Configuration

By default, kona-node trusts RPC providers and doesn’t perform additional verification. This is suitable for local nodes but should be changed when using public RPC endpoints: 
kona-node node \
    --chain 8453 \
    --l1-eth-rpc https://public-eth-rpc.com \
    --l1-trust-rpc false \
    --l1-beacon https://public-beacon-api.com \
    --l2-engine-rpc http://127.0.0.1:9551 \
    # L2 trust-rpc defaults to true for local engine
The --l1-trust-rpc false flag enables block hash verification for the L1 RPC, protecting against malicious or faulty public RPC providers.

​
Debugging

kona-node provides a -v (or --v) flag as a way to set the “verbosity” level for logs. By default, the verbosity level is set to 3, which is the INFO level. The level ranges from 0 being no logs to 5 which includes trace logs. Log levels are listed below, with each level including the one below it.
  • 5: TRACE - very verbose logs that provide a detailed trace
  • 4: DEBUG - logs meant to print debugging information
  • 3: INFO - informational logs
  • 2: WARN - includes warning and error logs
  • 1: ERROR - only error logs are shown
  • 0: No logs
The default verbosity level is -vvv which is the 3 or INFO level. To set the kona-node to print DEBUG logs or level 4, run the node like so: kona-node node -vvvv. By default, the kona-node initializes its tracing (logging) using the default environment variable filter provided by the tracing_subscriber crate. This uses the value in the RUST_LOG environment variable to set the tracing level for specific targets. Effectively, RUST_LOG allows you to bypass the default log level for the whole node or specific log targets. For example, by prepending RUST_LOG=engine=debug to the kona-node command (or setting that as an environment variable), only INFO logs will be displayed except for the engine log target which will also print DEBUG logs. This comes in handy say for when we would like to debug Kona’s P2P stack, we could prepend RUST_LOG=discv5=debug,libp2p=debug to view debug logs from only discv5 and libp2p targets.

​
More Detailed Node Docs

There are a number of important defaults.
  • The node will poll and update the runtime config every 10 minutes. Configurable via the --l1.runtime-config-reload-interval flag.
  • 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.
  • Metrics are enabled, serving prometheus metrics on 0.0.0.0:9090. This can be configured using the --metrics.enabled, --metrics.port, and --metrics.addr cli flags.
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.
A set of CLI flags relating to the sequencer and supervisor are also available to the kona-node binary. Now, when the kona-node starts up, it should immediately spin up the P2P stack. It will begin discovering valid peers on the network with the same chain id (base - 8453) and OP Stack enr key “opstack”. When valid peers are discovered, they are sent to the libp2p swarm which attempts to connect to them and listen for block gossip. Depending on the chain, and the P2P network topology, it may take longer for the kona-node to establish a strong set of peers and begin receiving block gossip. For larger, more mature chains like OP Mainnet and Base, peer discovery should happen quickly via the chain’s P2P bootnodes. Once the first unsafe L2 payload attributes (block) is received from peers in the libp2p swarm, it is sent off to the kona-node’s engine actor which will kick off execution layer sync on the op-reth execution client. When this happens, the op-reth logs will start to show that it is fetching past L2 blocks to sync the chain to tip. Once EL sync is finished, kona-node’s derivation actor will kick off the derivation pipeline and begin deriving the L2 chain. All the while, the P2P stack is separately receiving unsafe L2 blocks from the chain’s sequencer, and sending them off to the engine actor to insert into the chain.

​
Configuring a Dockerfile

To learn more about running a kona-node using docker, check out the docker guide.