> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How it Works

Kona brings together a powerful suite of `no-std` and `std` Rust components,
purpose-built for the OP Stack. At the heart of this ecosystem is the
`kona-node` — a modern, modular rollup node (L2 consensus node) that can
be used as a drop-in binary or as a foundation for custom services.

The `kona-node` is a fully compliant implementation of the ["Rollup Node"
Specifications][rollup-node] and is released as a [binary][package] in
the [kona repository][kona]. Whether you're running a production network,
building new rollup features, or experimenting with the OP Stack,
`kona-node` is built to be both robust and extensible.

### Background

A rollup node is responsible for deriving the canonical L2 chain from L1
blocks and their receipts. It validates these blocks using the
[Engine API][engine-api], passing them to the execution layer for processing.

Paired with an execution engine like op-reth or op-geth, `kona-node` tracks
the unsafe, safe, and finalized tips of the L2 OP Stack chain, ensuring the
node is always in sync with the latest state.

<Note>
  Rollup nodes hold minimal state. Unsafe and safe payloads alike are sent
  away to the execution engine client which holds the chain's db. This way,
  the rollup node holds a view of the tip of the chain - unsafe, safe, and
  finalized block info. All data otherwise needed is held in memory.
</Note>

There are a few core architectural pieces of the `kona-node`.

* **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][engine-api], abstracting away different EL clients.
* **P2P Networking:** Enables block gossip and peer discovery.

For an in-depth breakdown of these three pillars and a detailed design
of the `kona-node`, visit the [Node Design section](/node-operators/kona-node/design/intro).

Additionally, an RPC server exposes essential methods, including the
[L2 Output RPC method][l2o-rpc].

### Syncing

The `kona-node` syncs the L2 chain in two main phases:

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.

<Note>
  * `kona-node` does **not** support historical CL sync or backfilling
    L2 blocks from L1 for past chain history. It relies on the EL client
    to perform the initial sync of the L2 chain.
  * Only after the EL is fully synced does the node begin deriving and
    following new L2 blocks from L1.
</Note>

### Extensibility

The `kona-node` is designed as a modular, actor-based node SDK,
making it possible to extend or customize node behavior by adding
new actors or swapping out existing ones. This extensibility is
currently in **beta**, but the architecture is intentionally built
to support advanced use cases and custom integrations.

#### Actor Model

At the core of `kona-node` is the concept of **actors**: independent,
async services that communicate over channels. Each actor implements
the [`NodeActor` trait][node-actor], a minimal interface with a single
`step` method that the service drives in a loop until the actor reports
a fatal error or the node shuts down.

The [`RollupNode` service][node] builds and spawns a fixed set of
actors covering derivation, the execution engine and its read-only
engine RPC, the L1 watcher, P2P networking, the node's RPC server,
and, in sequencer mode, block building.

The [Node Design section](/node-operators/kona-node/design/intro) is
the canonical description of that actor set and of what each actor
does.

#### Extending with Custom Actors

You can write your own actor by implementing the `NodeActor` trait.
This allows you to introduce new background services, event
processors, or integrations with external systems.

The trait has one associated type and one method. Each call to `step`
handles a single inbound request, event, or scheduled tick. Returning
`Ok(())` means the actor is ready to be stepped again; returning an
error is fatal and stops the actor. Cancellation is handled by the
caller that drives the loop, so the actor itself does not own a
cancellation token.

**Example: Defining a Custom Actor**

```rust theme={null}
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

There is no trait-based extension point for swapping actors into the
standard node today. [`RollupNode`][node] is a concrete type rather
than a trait, its actor set is fixed in that type's `start` method,
and the helper that spawns and supervises those actors is internal to
the `kona-node-service` crate.

Running a custom actor therefore means composing the node yourself.
The built-in actors are public API of the `kona-node-service` crate.
The request and payload types they exchange over channels are public
too, spread across `kona-node-service`, sibling kona crates such as
`kona-rpc` and `kona-gossip`, and the shared alloy engine types. A
custom binary can therefore construct the actors it needs, wire them
together over channels, add its own `NodeActor` implementations, and
drive each actor's `step` method in its own task.

#### Programmatic Node Construction

The [`RollupNodeBuilder`][builder] provides a convenient way to
construct a standard node, but for advanced use cases, you can build
your own node by composing actors directly, or by implementing your
own builder pattern.

#### 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][node-actor] for details
  on implementing actors.
* Explore the [kona-node-service crate][service] for source code
  and more examples.

[cli-docs]: ../configuration.mdx

[subcommands]: ../subcommands.mdx

[service]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/node/service

[node-actor]: https://docs.rs/kona-node-service/latest/kona_node_service/trait.NodeActor.html

[node]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/node.rs

[builder]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/builder.rs

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[packages]: https://github.com/orgs/op-rs/packages?repo_name=kona

[rollup-node]: https://specs.optimism.io/protocol/rollup-node.html

[package]: https://github.com/ethereum-optimism/optimism/pkgs/container/kona%2Fkona-node

[pdocs]: https://github.com/ethereum-optimism/optimism/pkgs/container/kona%2Fkona-node/446969659?tag=latest

[buildx]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/docker

[engine-api]: https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md

[l2o-rpc]: https://specs.optimism.io/protocol/rollup-node.html#l2-output-rpc-method