Skip to content
39 changes: 35 additions & 4 deletions rust/kona/crates/node/engine/src/task_queue/core.rs
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ impl Engine {

/// Attempts to drain the queue by executing all [`EngineTask`]s in-order. If any task returns
/// an error along the way, the error is returned and the task is not popped from the queue (in
/// case it must be retried), unless it is a flush error.
/// case it must be retried), unless it is a flush or skip error.
pub async fn drain(&mut self) -> Result<(), EngineTaskErrors> {
// Drain tasks in order of priority, halting on errors for a retry to be attempted.
loop {
Expand All @@ -155,9 +155,13 @@ impl Engine {
let result = task.execute(&mut self.state).await;

// A flush reports that the task replaced its block with a deposits-only block, so the
// task is done; retrying it would replace that block again.
// task is done; retrying it would replace that block again. A skip reports a task that
// no longer applies, so retrying it cannot succeed either.
if let Err(err) = &result &&
err.severity() != EngineTaskErrorSeverity::Flush
!matches!(
err.severity(),
EngineTaskErrorSeverity::Flush | EngineTaskErrorSeverity::Skip
)
{
return result;
}
Expand Down Expand Up @@ -197,7 +201,8 @@ impl EngineResetError {
mod recovery_tests {
use super::*;
use crate::{
ConsolidateInput, ConsolidateTask, InsertTask, NoopBlockSink,
ConsolidateInput, ConsolidateTask, FinalizeBlockId, FinalizeTask, InsertTask,
NoopBlockSink,
test_utils::{
TestAttributesBuilder, TestEngineStateBuilder, test_block_info, test_engine_client,
},
Expand Down Expand Up @@ -380,4 +385,30 @@ mod recovery_tests {
l1.assert_finished();
l2.assert_finished();
}

// A skipped task is dropped instead of being kept for a retry, so it cannot hold the queue.
#[tokio::test]
async fn skipped_task_is_dropped_from_the_queue() {
let config = Arc::new(RollupConfig::default());
let (client, l1, l2) = test_engine_client(config.clone());
let state = TestEngineStateBuilder::new()
.with_unsafe_head(test_block_info(20))
.with_finalized_head(test_block_info(10))
.build();
let (state_tx, _state_rx) = tokio::sync::watch::channel(state);
let mut engine = Engine::new(state, state_tx);
engine.enqueue(EngineTask::Finalize(Box::new(FinalizeTask::new(
Arc::new(client),
config,
FinalizeBlockId::ByNumber(5),
))));

let error = engine.drain().await.unwrap_err();

assert_eq!(error.severity(), EngineTaskErrorSeverity::Skip, "got {error:?}");
assert!(engine.is_empty());
assert_eq!(engine.state().sync_state, state.sync_state);
l1.assert_finished();
l2.assert_finished();
}
}
57 changes: 47 additions & 10 deletions rust/kona/crates/node/engine/src/task_queue/tasks/finalize/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,77 @@
use crate::{
EngineTaskError, SynchronizeTaskError, task_queue::tasks::task::EngineTaskErrorSeverity,
};
use alloy_eips::BlockNumHash;
use alloy_transport::{RpcError, TransportErrorKind};
use kona_protocol::FromBlockError;
use thiserror::Error;

/// An error that occurs when running the [`crate::FinalizeTask`].
#[derive(Debug, Error)]
pub enum FinalizeTaskError {
/// The block is not safe, and therefore cannot be finalized.
#[error("Attempted to finalize a block that is not yet safe")]
BlockNotSafe,
/// The target is below the finalized head, and finality never moves backward.
#[error("Finalization target {target} is behind the finalized head {finalized}")]
BehindFinalizedHead {
/// The number of the finalized head.
finalized: u64,
/// The number of the finalization target.
target: u64,
},
/// The block to finalize was not found.
#[error("The block to finalize was not found: Number {0}")]
BlockNotFound(u64),
/// The block is not safe, and therefore cannot be finalized.
#[error("Attempted to finalize a block that is not yet safe")]
BlockNotSafe,
/// The engine returned a block at a different height than the one requested.
#[error("Requested block {requested} to finalize, but the engine returned block {returned}")]
BlockNumberMismatch {
/// The requested block number.
requested: u64,
/// The number of the block the engine returned.
returned: u64,
},
/// The target is a different block at the finalized head's height.
#[error("Finalization target {target:?} conflicts with the finalized head {finalized:?}")]
ConflictsWithFinalizedHead {
/// The finalized head.
finalized: BlockNumHash,
/// The finalization target.
target: BlockNumHash,
},
/// The forkchoice update call to finalize the block failed.
#[error(transparent)]
ForkchoiceUpdateFailed(#[from] SynchronizeTaskError),
/// An error occurred while transforming the RPC block into [`L2BlockInfo`].
///
/// [`L2BlockInfo`]: kona_protocol::L2BlockInfo
#[error(transparent)]
FromBlock(#[from] FromBlockError),
/// The pinned target is not the engine's canonical block at its height.
#[error("Finalization target {target:?} is not canonical; the engine has {canonical:?}")]
NotCanonical {
/// The engine's canonical block at the target's height.
canonical: BlockNumHash,
/// The finalization target.
target: BlockNumHash,
},
/// A temporary RPC failure.
#[error(transparent)]
TransportError(#[from] RpcError<TransportErrorKind>),
/// The forkchoice update call to finalize the block failed.
#[error(transparent)]
ForkchoiceUpdateFailed(#[from] SynchronizeTaskError),
}

impl EngineTaskError for FinalizeTaskError {
fn severity(&self) -> EngineTaskErrorSeverity {
match self {
Self::BlockNotSafe | Self::BlockNotFound(_) | Self::FromBlock(_) => {
EngineTaskErrorSeverity::Critical
}
Self::TransportError(_) => EngineTaskErrorSeverity::Temporary,
Self::BehindFinalizedHead { .. } |
Self::ConflictsWithFinalizedHead { .. } |
Self::NotCanonical { .. } => EngineTaskErrorSeverity::Skip,
Self::BlockNotFound(_) |
Self::BlockNotSafe |
Self::BlockNumberMismatch { .. } |
Self::FromBlock(_) => EngineTaskErrorSeverity::Critical,
Self::ForkchoiceUpdateFailed(inner) => inner.severity(),
Self::TransportError(_) => EngineTaskErrorSeverity::Temporary,
}
}
}
10 changes: 5 additions & 5 deletions rust/kona/crates/node/engine/src/task_queue/tasks/finalize/id.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@ use alloy_eips::BlockNumHash;
/// authoritative source for the block at a given height (e.g. local L1-finality driven by
/// `L2Finalizer`). The number is sufficient because there is only one chain to consult.
/// - [`FinalizeBlockId::ByHash`] is used when an upstream supplies `(number, hash)` and the engine
/// must finalize the specific block identified by hash. If the engine does not have that hash,
/// the task must error rather than silently finalize the engine's canonical block at the same
/// height.
/// must finalize the specific block identified by hash. If the engine's canonical block at that
/// height has a different hash, the task skips the target rather than finalize the engine's block
/// in its place.
///
/// EL finalization is irreversible, so finalizing the wrong block is unrecoverable. Forcing every
/// caller to pick a variant prevents accidental hash-loss at the boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FinalizeBlockId {
/// Finalize whatever block the engine has at the given L2 block number.
ByNumber(u64),
/// Finalize the block matching the given `(number, hash)` pair. The task fails if the engine
/// does not have that hash.
/// Finalize the block matching the given `(number, hash)` pair, only once it is the engine's
/// canonical block at that height.
ByHash(BlockNumHash),
}

Expand Down
112 changes: 83 additions & 29 deletions rust/kona/crates/node/engine/src/task_queue/tasks/finalize/task.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ use crate::{
EngineClient, EngineState, ExecutableEngineTask, FinalizeBlockId, FinalizeTaskError,
state::EngineSyncStateUpdate, task_queue::synchronize,
};
use alloy_eips::BlockId;
use alloy_eips::BlockNumHash;
use async_trait::async_trait;
use derive_more::Constructor;
use kona_genesis::RollupConfig;
Expand All @@ -13,6 +13,10 @@ use std::sync::Arc;

/// The [`FinalizeTask`] fetches the [`L2BlockInfo`] identified by `block_id`, updates the
/// [`EngineState`], and dispatches a forkchoice update to finalize the block.
///
/// Finality only moves forward. A target behind the finalized head, a different block at the
/// finalized height, or a pinned hash that is not the engine's canonical block fails with an error
/// that skips the task and leaves the engine state unchanged.
#[derive(Debug, Clone, Constructor)]
pub struct FinalizeTask {
/// The engine client.
Expand All @@ -23,47 +27,97 @@ pub struct FinalizeTask {
pub block_id: FinalizeBlockId,
}

impl FinalizeTask {
/// Whether `target` is the finalized head itself; a different block at its height is an error.
fn is_already_finalized(
finalized_head: &L2BlockInfo,
target: BlockNumHash,
) -> Result<bool, FinalizeTaskError> {
let finalized = finalized_head.block_info.id();
if target == finalized {
debug!(target: "engine", ?target, "Target is already finalized");
return Ok(true);
}
// The default head means finality has not been established yet, so any target, including
// the configured genesis, may initialize it.
if *finalized_head != L2BlockInfo::default() && target.number == finalized.number {
return Err(FinalizeTaskError::ConflictsWithFinalizedHead { finalized, target });
}
Ok(false)
}

/// Fetches the engine's canonical block at the target's height.
///
/// A pinned hash must be that block: a forkchoice update cannot finalize a block off the
/// canonical chain, and finalizing the canonical block instead would finalize a block the
/// caller never named. The block's identity is checked before it is decoded, so a mismatch is
/// reported as such rather than as a decoding failure.
async fn fetch_canonical_block_info(&self) -> Result<L2BlockInfo, FinalizeTaskError> {
let requested = self.block_id.number();
debug!(target: "engine", block_id = ?self.block_id, "Fetching the block to finalize");
let block = self
.client
.get_l2_block(requested.into())
.full()
.await
.map_err(FinalizeTaskError::TransportError)?
.ok_or(FinalizeTaskError::BlockNotFound(requested))?;
Comment thread
einar-oplabs marked this conversation as resolved.
Resolved
let canonical = BlockNumHash { hash: block.header.hash, number: block.header.number };
debug!(target: "engine", ?canonical, "Fetched the block to finalize");

if canonical.number != requested {
return Err(FinalizeTaskError::BlockNumberMismatch {
requested,
returned: canonical.number,
});
}
if let FinalizeBlockId::ByHash(target) = self.block_id &&
target.hash != canonical.hash
{
return Err(FinalizeTaskError::NotCanonical { canonical, target });
}

L2BlockInfo::from_block_and_genesis(&block.into_consensus(), &self.cfg.genesis)
.map_err(FinalizeTaskError::FromBlock)
}
}

#[async_trait]
impl ExecutableEngineTask for FinalizeTask {
type Output = ();

type Error = FinalizeTaskError;

async fn execute(&self, state: &mut EngineState) -> Result<(), FinalizeTaskError> {
let block_number = self.block_id.number();
let finalized_head = state.sync_state.finalized_head();
let target_number = self.block_id.number();

// A lagging source can report an older finalized block, or one from another chain. A
// pinned hash is enough to detect either without asking the execution layer.
if target_number < finalized_head.block_info.number {
return Err(FinalizeTaskError::BehindFinalizedHead {
finalized: finalized_head.block_info.number,
target: target_number,
});
}
if let FinalizeBlockId::ByHash(target) = self.block_id &&
Self::is_already_finalized(&finalized_head, target)?
{
return Ok(());
}

// Sanity check that the block that is being finalized is at least safe.
if state.sync_state.safe_head().block_info.number < block_number {
if state.sync_state.safe_head().block_info.number < target_number {
return Err(FinalizeTaskError::BlockNotSafe);
Comment thread
einar-oplabs marked this conversation as resolved.
Resolved
}

// Look up by hash when the caller pinned a specific hash (delegated polling supplies
// `(number, hash)`); otherwise look up by number. Finalization is irreversible, so a stale
// hash must produce a hard error, not silently finalize whatever the engine has at the
// same height.
let lookup: BlockId = match self.block_id {
FinalizeBlockId::ByHash(id) => id.hash.into(),
FinalizeBlockId::ByNumber(n) => n.into(),
};
let block = self
.client
.get_l2_block(lookup)
.full()
.await
.map_err(FinalizeTaskError::TransportError)?
.ok_or(FinalizeTaskError::BlockNotFound(block_number))?
.into_consensus();
let block_info = L2BlockInfo::from_block_and_genesis(&block, &self.client.cfg().genesis)
.map_err(FinalizeTaskError::FromBlock)?;

// For ByHash, also assert the returned block's height matches the caller's claim. The
// engine should never serve a block at a different height for a given hash, but a height
// mismatch indicates either an upstream protocol bug or a misuse of the API and must
// never lead to silent finalization.
if let FinalizeBlockId::ByHash(id) = self.block_id &&
block_info.block_info.number != id.number
let block_info = self.fetch_canonical_block_info().await?;

// A by-number target only learns its hash from the lookup.
if matches!(self.block_id, FinalizeBlockId::ByNumber(_)) &&
Self::is_already_finalized(&finalized_head, block_info.block_info.id())?
{
return Err(FinalizeTaskError::BlockNotFound(id.number));
return Ok(());
}

// Dispatch a forkchoice update.
Expand Down
Loading
Loading