Crate kona_engine

kona-engine

An extensible implementation of the OP Stack rollup node engine client.

Overview

The kona-engine crate provides a task-based engine client for interacting with Ethereum execution layers. It implements the Engine API specification and manages the execution layer state through a priority-driven task queue system.

Key Components

• Engine - Main task queue processor that executes engine operations atomically
• EngineClient - HTTP client for Engine API communication with JWT authentication
• EngineState - Tracks the current state of the execution layer
• Task Types - Specialized tasks for different engine operations:
  • InsertTask - Insert new payloads into the execution engine
  • BuildTask - Build new payloads with automatic forkchoice synchronization
  • ConsolidateTask - Consolidate unsafe payloads to advance the safe chain
  • FinalizeTask - Finalize safe payloads on L1 confirmation
  • SynchronizeTask - Internal task for execution layer forkchoice synchronization

Architecture

The engine implements a task-driven architecture where forkchoice synchronization is handled automatically:

• Automatic Forkchoice Handling: The BuildTask automatically performs forkchoice updates during block building, eliminating the need for explicit forkchoice management in user code.
• Internal Synchronization: SynchronizeTask handles internal execution layer synchronization and is primarily used by other tasks rather than directly by users.
• Priority-Based Execution: Tasks are executed in priority order to ensure optimal sequencer performance and block processing efficiency.

Usage

use kona_engine::{Engine, EngineClient, EngineState};
use kona_genesis::RollupConfig;
use alloy_rpc_types_engine::JwtSecret;
use url::Url;
use std::sync::Arc;

// Create an engine client
let engine_url = Url::parse("http://localhost:8551")?;
let l1_url = Url::parse("http://localhost:8545")?;
let config = Arc::new(RollupConfig::default());
let jwt = JwtSecret::from_hex("0xabcd")?;

let client = EngineClient::new_http(engine_url, l1_url, config, jwt);

// Initialize engine state
let state = EngineState::default();

// Create task queue watchers
let (state_sender, _) = tokio::sync::watch::channel(state);
let (queue_sender, _) = tokio::sync::watch::channel(0);

// Create the engine
let engine = Engine::new(state, state_sender, queue_sender);

Engine API Compatibility

The crate supports multiple Engine API versions with automatic version selection based on the rollup configuration:

• Engine Forkchoice Updated: V2, V3
• Engine New Payload: V2, V3, V4
• Engine Get Payload: V2, V3, V4

Version selection follows Optimism hardfork activation times (Bedrock, Canyon, Delta, Ecotone, Isthmus).

Features

• metrics - Enable Prometheus metrics collection (optional)

Architecture

The engine operates as a task-driven system where operations are queued and executed atomically:

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Engine    │◄───┤  Task Queue  │◄───┤  Engine     │
│   Client    │    │   (Priority) │    │  Tasks      │
└─────────────┘    └──────────────┘    └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ Engine API  │    │ Engine State │    │ Rollup      │
│ (HTTP/JWT)  │    │   Updates    │    │ Config      │
└─────────────┘    └──────────────┘    └─────────────┘

Module Organization

• Task Queue - Core engine task queue and execution logic via Engine
• Client - HTTP client for Engine API communication via EngineClient
• State - Engine state management and synchronization via EngineState
• Versions - Engine API version selection via EngineForkchoiceVersion, EngineNewPayloadVersion, EngineGetPayloadVersion
• Attributes - Payload attribute validation via AttributesMatch
• Kinds - Engine client type identification via EngineKind
• Query - Engine query interface via EngineQueries
• Metrics - Optional Prometheus metrics collection via Metrics

Structs

BuildTask

Task for building new blocks with automatic forkchoice synchronization.

ConsolidateTask

The ConsolidateTask attempts to consolidate the engine state using the specified payload attributes and the oldest unsafe head.

Engine

The Engine task queue.

EngineClient

An Engine API client that provides authenticated HTTP communication with an execution layer.

EngineState

The chain state viewed by the engine controller.

EngineSyncState

The synchronization state of the execution layer across different safety levels.

EngineSyncStateUpdate

Specifies how to update the sync state of the engine.

FinalizeTask

The FinalizeTask fetches the L2BlockInfo at block_number, updates the EngineState, and dispatches a forkchoice update to finalize the block.

InsertTask

The task to insert a payload into the execution engine.

Metrics

Metrics container with constants for Prometheus metric collection.

SynchronizeTask

Internal task for execution layer forkchoice synchronization.

Enums

AttributesMatch

Result of validating payload attributes against an execution layer block.

AttributesMismatch

An enum over the type of mismatch between OpAttributesWithParent and a Block.

BuildTaskError

An error that occurs when running the crate::SynchronizeTask.

ConsolidateTaskError

An error that occurs when running the crate::ConsolidateTask.

EngineBuildError

An error that occurs during payload building within the engine.

EngineClientError

An error that occurred in the EngineClient.

EngineForkchoiceVersion

Engine API version for engine_forkchoiceUpdated method calls.

EngineGetPayloadVersion

Engine API version for engine_getPayload method calls.

EngineKind

Identifies the type of execution layer client for behavior customization.

EngineNewPayloadVersion

Engine API version for engine_newPayload method calls.

EngineQueries

Query types supported by the engine for external communication.

EngineQueriesError

An error that can occur when querying the engine.

EngineResetError

An error occurred while attempting to reset the Engine.

EngineTask

Tasks that may be inserted into and executed by the Engine.

EngineTaskErrorSeverity

The severity of an engine task error.

EngineTaskErrors

An error that may occur during an EngineTask’s execution.

FinalizeTaskError

An error that occurs when running the crate::FinalizeTask.

InsertTaskError

An error that occurs when running the InsertTask.

SynchronizeTaskError

An error that occurs when running the crate::SynchronizeTask.

Traits

EngineTaskError

The interface for an engine task error.

EngineTaskExt

The interface for an engine task.

Type Aliases

EngineQuerySender

Channel sender for submitting EngineQueries to the engine.