How it Works

​

Background

• Derivation Pipeline: Constructs L2 payload attributes from L1 blocks, forming the backbone of rollup logic.
• Execution Engine Integration: Executes L2 payload attributes via the Engine API, abstracting away different EL clients.
• P2P Networking: Enables block gossip and peer discovery.

​

Syncing

1. Execution Layer (EL) Sync: When starting, the node initially has an empty engine task queue. Once an unsafe block is received from P2P gossip, an InsertTask is executed. That task inserts the payload and sends a forkchoice update through the engine api. Since the engine state is lazily initialized (the safe and finalized heads are zero), the forkchoice update kicks off EL sync on the execution layer (EL) client (such as op-reth or op-geth). EL sync instructs the execution client to fetch and sync L2 blocks directly from peers. During this phase, the kona-node effectively waits for the EL client to reach the chain tip, when it returns that it is synced. No L2 blocks are derived from L1 during this period.
2. Consensus Layer (CL) Sync: Once the EL client is fully synced to the tip, the node transitions to consensus layer (CL) sync. In this phase, kona-node begins deriving new L2 payload attributes from the L1 chain, following the rollup derivation process. OpAttributesWithParent values derived this way are executed as an engine task which submits the payloads to the execution engine for validation and execution.

​

Extensibility

​

Actor Model

​

Extending with Custom Actors

use async_trait::async_trait;
use kona_node_service::NodeActor;

struct MyCustomActor;

#[async_trait]
impl NodeActor for MyCustomActor {
    type Error = std::io::Error;

    async fn step(&mut self) -> Result<(), Self::Error> {
        // Your actor logic for one step here.
        Ok(())
    }
}

​

Running Custom Actors

​

Programmatic Node Construction

​

Current Limitations

• The actor and service APIs are beta and may change.
• The standard RollupNode exposes no hook for overriding an individual actor or pipeline, so extending the node means composing actors in your own binary rather than wrapping RollupNode.
• Documentation and examples for advanced extensibility are still evolving—contributions and feedback are welcome!

​

Learn More

• See the NodeActor trait documentation for details on implementing actors.
• Explore the kona-node-service crate for source code and more examples.