Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion rust/kona/crates/node/engine/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ mod versions;
pub use versions::{EngineForkchoiceVersion, EngineGetPayloadVersion, EngineNewPayloadVersion};

mod state;
pub use state::{EngineState, EngineSyncState, EngineSyncStateUpdate};
pub use state::{EngineState, EngineSyncState, EngineSyncStateUpdate, FinalityViolation};

mod kinds;
pub use kinds::EngineKind;
Expand Down
16 changes: 14 additions & 2 deletions rust/kona/crates/node/engine/src/state/core.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
//! The internal state of the engine controller.

use crate::Metrics;
use alloy_eips::BlockNumHash;
use alloy_rpc_types_engine::ForkchoiceState;
use kona_protocol::L2BlockInfo;
use serde::{Deserialize, Serialize};
Expand Down Expand Up @@ -54,6 +55,12 @@ impl EngineSyncState {
self.finalized_head
}

/// Returns the id of the finalized head once finality is established. The default finalized
/// head means it is not yet, so no block pins finality.
pub fn established_finalized_head(&self) -> Option<BlockNumHash> {
(self.finalized_head != L2BlockInfo::default()).then(|| self.finalized_head.block_info.id())
}
Comment thread
joshklop marked this conversation as resolved.
Resolved

/// Creates a `ForkchoiceState`
///
/// - `head_block` = `unsafe_head`
Expand Down Expand Up @@ -127,8 +134,10 @@ pub struct EngineSyncStateUpdate {
/// The chain state viewed by the engine controller.
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq)]
pub struct EngineState {
/// The sync state of the engine.
pub sync_state: EngineSyncState,
/// Whether the execution layer answered `VALID` to the last forkchoice update the engine sent,
/// so its canonical chain is the engine's. Unlike `el_sync_finished`, a later `SYNCING` answer
/// clears it.
pub el_applied_last_forkchoice: bool,
Comment thread
joshklop marked this conversation as resolved.
Resolved

/// Whether or not the EL has finished syncing.
pub el_sync_finished: bool,
Expand All @@ -139,6 +148,9 @@ pub struct EngineState {
/// because engine may forgot backupUnsafeHead or backupUnsafeHead is not part
/// of the chain.
pub need_fcu_call_backup_unsafe_reorg: bool,

/// The sync state of the engine.
pub sync_state: EngineSyncState,
Comment thread
joshklop marked this conversation as resolved.
Resolved
}

impl EngineState {
Expand Down
126 changes: 126 additions & 0 deletions rust/kona/crates/node/engine/src/state/finality.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
//! Checks that keep a label from moving below finality.

use crate::EngineSyncState;
use alloy_eips::BlockNumHash;
use thiserror::Error;

/// A block that a label cannot move to, because it would move the label below finality.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
pub enum FinalityViolation {
/// The block is below the finalized head.
#[error("Block {target} is behind the finalized head {finalized:?}")]
BehindFinalizedHead {
/// The finalized head.
finalized: BlockNumHash,
/// The number of the block.
target: u64,
},
/// The block is a different block at the finalized head's height.
#[error("Block {target:?} conflicts with the finalized head {finalized:?}")]
ConflictsWithFinalizedHead {
/// The finalized head.
finalized: BlockNumHash,
/// The block.
target: BlockNumHash,
},
}

impl EngineSyncState {
/// Rejects a block number below the established finalized head.
pub fn ensure_not_behind_finality(&self, target: u64) -> Result<(), FinalityViolation> {
match self.established_finalized_head() {
Some(finalized) if target < finalized.number => {
Err(FinalityViolation::BehindFinalizedHead { finalized, target })
}
_ => Ok(()),
}
}

/// Rejects a different block at the established finalized head's height. Before finality is
/// established no block pins it, so any block, including the configured genesis, passes.
pub fn ensure_no_conflict_with_finality(
&self,
target: BlockNumHash,
) -> Result<(), FinalityViolation> {
match self.established_finalized_head() {
Some(finalized)
if target.number == finalized.number && target.hash != finalized.hash =>
{
Err(FinalityViolation::ConflictsWithFinalizedHead { finalized, target })
}
_ => Ok(()),
}
}

/// Rejects a block below the established finalized head or conflicting with it.
pub fn ensure_respects_finality(&self, target: BlockNumHash) -> Result<(), FinalityViolation> {
self.ensure_not_behind_finality(target.number)?;
self.ensure_no_conflict_with_finality(target)
}
}

#[cfg(test)]
mod tests {
use super::*;
use crate::EngineSyncStateUpdate;
use alloy_primitives::B256;
use kona_protocol::{BlockInfo, L2BlockInfo};

const FINALIZED_NUMBER: u64 = 5;

fn block(number: u64, hash: u8) -> L2BlockInfo {
L2BlockInfo {
block_info: BlockInfo { hash: B256::repeat_byte(hash), number, ..Default::default() },
..Default::default()
}
}

fn sync_state_finalized_at(finalized_head: L2BlockInfo) -> EngineSyncState {
EngineSyncState::default().apply_update(EngineSyncStateUpdate {
finalized_head: Some(finalized_head),
..Default::default()
})
}

/// The finalized head at 5 once finality is established, and the default head before.
fn finalized_head(is_finality_established: bool) -> L2BlockInfo {
if is_finality_established { block(FINALIZED_NUMBER, 1) } else { L2BlockInfo::default() }
}

/// The violation expected for `target` checked against the finalized head at 5.
fn behind(target: L2BlockInfo) -> Option<FinalityViolation> {
Some(FinalityViolation::BehindFinalizedHead {
finalized: block(FINALIZED_NUMBER, 1).block_info.id(),
target: target.block_info.number,
})
}

/// The violation expected for `target` conflicting with the finalized head at 5.
fn conflicting(target: L2BlockInfo) -> Option<FinalityViolation> {
Some(FinalityViolation::ConflictsWithFinalizedHead {
finalized: block(FINALIZED_NUMBER, 1).block_info.id(),
target: target.block_info.id(),
})
}

/// A block below the established finalized head, or a different block at its height, breaks
/// finality. Before finality is established no block pins it, so a different block at the
/// default head's height, genesis, passes.
#[rstest::rstest]
#[case::above(true, block(FINALIZED_NUMBER + 1, 2), None)]
#[case::at(true, block(FINALIZED_NUMBER, 1), None)]
#[case::below(true, block(FINALIZED_NUMBER - 1, 2), behind(block(FINALIZED_NUMBER - 1, 2)))]
#[case::conflicting(true, block(FINALIZED_NUMBER, 2), conflicting(block(FINALIZED_NUMBER, 2)))]
#[case::not_established(false, block(0, 2), None)]
fn block_is_checked_against_established_finality(
#[case] is_finality_established: bool,
#[case] target: L2BlockInfo,
#[case] expected_violation: Option<FinalityViolation>,
) {
let sync_state = sync_state_finalized_at(finalized_head(is_finality_established));

let result = sync_state.ensure_respects_finality(target.block_info.id());

assert_eq!(result.err(), expected_violation);
}
}
3 changes: 3 additions & 0 deletions rust/kona/crates/node/engine/src/state/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,6 @@

mod core;
pub use core::{EngineState, EngineSyncState, EngineSyncStateUpdate};

mod finality;
pub use finality::FinalityViolation;
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
//! Contains error types for the [`crate::ConsolidateTask`].

use crate::{
BuildTaskError, EngineTaskError, SealTaskError, SynchronizeTaskError,
BuildTaskError, EngineTaskError, FinalityViolation, SealTaskError, SynchronizeTaskError,
task_queue::tasks::{BuildAndImportError, task::EngineTaskErrorSeverity},
};
use thiserror::Error;

/// An error that occurs when running the [`crate::ConsolidateTask`].
#[derive(Debug, Error)]
pub enum ConsolidateTaskError {
/// A delegated safe head would move the safe labels below finality.
#[error("Delegated safe head breaks finality: {0}")]
BreaksFinality(#[from] FinalityViolation),
/// Failed to fetch the execution layer's block at the height of a delegated safe head below the
/// safe head.
#[error("Failed to fetch the block at delegated safe head height {0}")]
FailedToFetchDelegatedSafeBlock(u64),
Comment thread
joshklop marked this conversation as resolved.
Resolved
/// The unsafe L2 block is missing.
#[error("Unsafe L2 block is missing {0}")]
MissingUnsafeL2Block(u64),
Expand Down Expand Up @@ -38,8 +45,11 @@ impl From<BuildAndImportError> for ConsolidateTaskError {
impl EngineTaskError for ConsolidateTaskError {
fn severity(&self) -> EngineTaskErrorSeverity {
match self {
Self::BreaksFinality(_) => EngineTaskErrorSeverity::Skip,
Self::MissingUnsafeL2Block(_) => EngineTaskErrorSeverity::Reset,
Self::FailedToFetchUnsafeL2Block => EngineTaskErrorSeverity::Temporary,
Self::FailedToFetchDelegatedSafeBlock(_) | Self::FailedToFetchUnsafeL2Block => {
Comment thread
joshklop marked this conversation as resolved.
Resolved
EngineTaskErrorSeverity::Temporary
}
Self::BuildTaskFailed(inner) => inner.severity(),
Self::SealTaskFailed(inner) => inner.severity(),
Self::ForkchoiceUpdateFailed(inner) => inner.severity(),
Expand Down
Loading
Loading