Execution Engine

The kona-engine crate provides a modular execution engine implementation for the OP Stack rollup node. It serves as the bridge between the rollup protocol and the execution layer (EL), managing Engine API interactions through a sophisticated task queue system.

Architecture Overview

The execution engine is built around several key components:

• Engine Task Queue: A priority-ordered queue that manages Engine API operations
• Trait Abstractions: Extensible interfaces for tasks, errors, and state management
• Engine Client: HTTP client for communicating with the execution layer
• Actor Integration: Service layer integration through the EngineActor

Core Trait Abstractions

EngineTaskExt

The EngineTaskExt trait defines the interface for all engine tasks:

#[async_trait]
pub trait EngineTaskExt {
    type Output;
    type Error: EngineTaskError;

    async fn execute(&self, state: &mut EngineState) -> Result<Self::Output, Self::Error>;
}

This trait enables:

• Atomic operations over the EngineState
• Extensible task implementation for custom operations
• Async execution with proper error handling

EngineTaskError

The EngineTaskError trait provides sophisticated error handling with severity levels:

pub trait EngineTaskError {
    fn severity(&self) -> EngineTaskErrorSeverity;
}

pub enum EngineTaskErrorSeverity {
    Temporary,  // Retry the task
    Critical,   // Propagate to engine actor
    Reset,      // Request derivation reset
    Flush,      // Request derivation flush
}

This allows tasks to signal different recovery strategies based on the error type.

Task Queue System

The engine uses a priority-based task queue where tasks are ordered according to OP Stack synchronization requirements:

Task Priority (Highest to Lowest)

1. ForkchoiceUpdate - Synchronizes forkchoice state
2. Build - Builds new blocks (sequencer mode)
3. Insert - Inserts unsafe blocks from gossip
4. Consolidate - Advances safe chain via derivation
5. Finalize - Finalizes L2 blocks

Task Types

SynchronizeTask

Updates the execution layer’s forkchoice state:

pub struct SynchronizeTask {
    pub client: Arc<EngineClient>,
    pub rollup: Arc<RollupConfig>,
    pub envelope: Option<OpAttributesWithParent>,
    pub state_update: EngineSyncStateUpdate,
}

Handles:

• Forkchoice synchronization without payload attributes
• Payload building initiation with attributes
• EL sync status management

BuildTask

Builds new blocks in sequencer mode:

pub struct BuildTask {
    pub engine: Arc<EngineClient>,
    pub cfg: Arc<RollupConfig>,
    pub attributes: OpAttributesWithParent,
    pub is_attributes_derived: bool,
    pub payload_tx: Option<mpsc::Sender<OpExecutionPayloadEnvelope>>,
}

Handles:

• Payload building with engine_forkchoiceUpdated
• Payload retrieval with version-specific engine_getPayload calls
• Payload insertion and canonicalization

InsertTask

Inserts unsafe blocks received from gossip:

pub struct InsertTask {
    pub client: Arc<EngineClient>,
    pub rollup: Arc<RollupConfig>,
    pub envelope: OpExecutionPayloadEnvelope,
}

ConsolidateTask

Advances the safe chain through derivation:

pub struct ConsolidateTask {
    pub client: Arc<EngineClient>,
    pub rollup: Arc<RollupConfig>,
    pub attributes: OpAttributesWithParent,
}

FinalizeTask

Finalizes L2 blocks:

pub struct FinalizeTask {
    pub client: Arc<EngineClient>,
    pub rollup: Arc<RollupConfig>,
    pub l2_block: L2BlockInfo,
}

Engine State Management

The EngineState tracks the current state of the execution engine:

pub struct EngineState {
    pub current: L2BlockInfo,
    pub finalized: L2BlockInfo,
    pub safe: L2BlockInfo,
    pub sync_state: EngineSyncState,
    pub el_sync_finished: bool,
    // ... additional fields
}

State updates are communicated through watch channels, enabling reactive programming patterns across the system.

Integration with kona-node

The kona-node service layer integrates the engine through the EngineActor:

Actor Pattern

The EngineActor implements the NodeActor trait:

#[async_trait]
pub trait NodeActor: Send + 'static {
    type Error: std::fmt::Debug;
    type OutboundData: CancellableContext;
    type InboundData: Sized;
    type Builder;

    fn build(builder: Self::Builder) -> (Self::InboundData, Self);
    async fn start(self, inbound_context: Self::OutboundData) -> Result<(), Self::Error>;
}

Communication Channels

The EngineActor receives input through multiple channels:

• attributes_rx: Payload attributes from derivation
• unsafe_block_rx: Unsafe blocks from gossip
• reset_request_rx: Reset requests
• inbound_queries: Engine state queries
• runtime_config_rx: Runtime configuration updates
• build_request_rx: Block building requests (sequencer mode only)

Engine Queries

The engine supports queries for:

pub enum EngineQueries {
    Config(Sender<RollupConfig>),
    State(Sender<EngineState>),
    OutputAtBlock { block: BlockNumberOrTag, sender: Sender<(L2BlockInfo, OutputRoot, EngineState)> },
    StateReceiver(Sender<tokio::sync::watch::Receiver<EngineState>>),
}

Usage Patterns

Basic Engine Setup

// Create engine client
let client = EngineClient::new_http(
    engine_url,
    l2_rpc_url,
    l1_rpc_url,
    rollup_config,
    jwt_secret,
);

// Initialize engine state
let state = EngineState::default();
let (state_sender, state_receiver) = watch::channel(state);

// Create engine with task queue
let engine = Engine::new(state, state_sender);

Adding Tasks

// Add a forkchoice update task
let task = EngineTask::ForkchoiceUpdate(SynchronizeTask::new(
    client.clone(),
    rollup_config.clone(),
    state_update,
    None, // No payload attributes
));

engine.add_task(task);

Draining the Queue

// Process all pending tasks
match engine.drain().await {
    Ok(()) => info!("Tasks completed successfully"),
    Err(e) => match e.severity() {
        EngineTaskErrorSeverity::Reset => {
            // Request derivation reset
        },
        EngineTaskErrorSeverity::Critical => {
            // Handle critical error
        },
        _ => {
            // Handle other error types
        }
    }
}

Error Handling and Recovery

The engine provides robust error handling through:

Severity-Based Recovery

• Temporary errors: Automatically retried
• Critical errors: Propagated to the actor
• Reset errors: Trigger derivation pipeline reset
• Flush errors: Trigger derivation pipeline flush

State Consistency

Tasks operate atomically on the EngineState, ensuring consistency even during error conditions.

Version Support

The engine automatically selects appropriate Engine API versions based on hardfork activation:

• Pre-Ecotone: Uses engine_newPayloadV2 and engine_getPayloadV2
• Post-Ecotone: Uses engine_newPayloadV3 and engine_getPayloadV3
• Post-Isthmus: Uses engine_newPayloadV4 and engine_getPayloadV4

Metrics and Observability

When the metrics feature is enabled, the engine provides comprehensive metrics for:

• Task execution times
• Error rates by task type
• Engine state transitions
• API call latencies

Extensibility

The trait-based architecture allows for:

• Custom task implementations via EngineTaskExt
• Custom error handling via EngineTaskError
• Custom state management extensions
• Testing and mocking support

This modular design ensures the engine can adapt to future OP Stack protocol changes while maintaining backward compatibility.