Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
383feb9
kona-node: keep the safe head across L1 reorgs that leave its L1 data…
teddyknox Oct 24, 2026
5ab40d4
kona-node: resume derivation itself after a reset that keeps its safe…
teddyknox Oct 24, 2026
eeef88a
kona-node: rewind only the unsafe chain when a reorg replaces its L1 …
teddyknox Oct 25, 2026
12911b0
kona-node: record each safe head at one floor-corrected L1 block
teddyknox Oct 26, 2026
60e4baa
kona-node: share the unsafe-chain walk and check L1 origins by number
teddyknox Oct 26, 2026
6b10628
Merge develop into claude/happy-payne-c7b612
teddyknox Oct 27, 2026
832d804
Merge develop into claude/happy-payne-c7b612
teddyknox Oct 27, 2026
ef7b869
kona-node: retrigger CI after a conductor leadership-transfer flake
teddyknox Oct 27, 2026
50e6a90
Merge develop into claude/happy-payne-c7b612
teddyknox Oct 27, 2026
398c0d8
Merge develop into claude/happy-payne-c7b612
teddyknox Oct 28, 2026
a57f5fd
kona-engine: never raise the safe head on a cold-start reset
teddyknox Oct 28, 2026
4ec8681
Merge develop into claude/happy-payne-c7b612
teddyknox Oct 29, 2026
8b8a49d
kona-engine: leave the safe head search uncapped just after EL sync
teddyknox Oct 29, 2026
981d129
Merge branch 'develop' of github.com:ethereum-optimism/optimism into …
teddyknox Nov 4, 2026
e6d31eb
Merge branch 'develop' of github.com:ethereum-optimism/optimism into …
teddyknox Nov 13, 2026
68263f7
Merge branch 'develop' of github.com:ethereum-optimism/optimism into …
teddyknox Nov 17, 2026
dac04e9
Merge branch 'develop' of github.com:ethereum-optimism/optimism into …
teddyknox Nov 17, 2026
465e9da
Merge branch 'develop' of github.com:ethereum-optimism/optimism into …
teddyknox Nov 17, 2026
a8c0a51
Merge branch 'develop' into claude/happy-payne-c7b612
teddyknox Nov 17, 2026
b48da2f
Merge branch 'develop' into claude/happy-payne-c7b612
teddyknox Nov 19, 2026
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
7 changes: 5 additions & 2 deletions rust/kona/crates/node/engine/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ pub use client::{EngineClient, EngineClientError, EngineQueryClient};
mod request;
pub use request::{
BuildRequest, CanonicalizeRequest, EngineActorRequest, EngineRequestError, EngineRequestResult,
ResetRequest, SealRequest,
ResetKind, ResetRequest, SealRequest,
};

mod versions;
Expand All @@ -74,7 +74,10 @@ mod metrics;
pub use metrics::Metrics;

mod sync;
pub use sync::{L2ForkchoiceState, SyncStartError, find_starting_forkchoice};
pub use sync::{
DerivedSafeHead, L2ForkchoiceState, SyncStartError, find_reorg_forkchoice,
find_starting_forkchoice,
};

#[cfg(any(test, feature = "test-utils"))]
/// Utilities that are useful when creating unit tests using structs within this library.
Expand Down
10 changes: 10 additions & 0 deletions rust/kona/crates/node/engine/src/metrics/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,10 @@ impl Metrics {
/// Identifier for the counter that tracks the number of times the engine has been reset.
pub const ENGINE_RESET_COUNT: &str = "kona_node_engine_reset_count";

/// Identifier for the counter that tracks the number of L1 reorgs the engine answered by
/// keeping a safe head derived from canonical L1 data, instead of a full reset.
pub const ENGINE_REORG_RESET_COUNT: &str = "kona_node_engine_reorg_reset_count";

/// Initializes metrics for the engine.
///
/// This does two things:
Expand All @@ -85,6 +89,11 @@ impl Metrics {
metrics::Unit::Count,
"Engine reset count"
);
metrics::describe_counter!(
Self::ENGINE_REORG_RESET_COUNT,
metrics::Unit::Count,
"L1 reorgs answered without a full engine reset"
);
}

/// Initializes metrics to `0` so they can be queried immediately by consumers of prometheus
Expand All @@ -107,5 +116,6 @@ impl Metrics {

// Engine reset count
metrics::counter!(Self::ENGINE_RESET_COUNT).absolute(0);
metrics::counter!(Self::ENGINE_REORG_RESET_COUNT).absolute(0);
}
}
17 changes: 16 additions & 1 deletion rust/kona/crates/node/engine/src/request.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
//! Requests sent to the node engine actor and their replies.

use crate::{
BuildTaskError, CanonicalizeTaskError, ConsolidateInput, FinalizeBlockId, SealTaskError,
BuildTaskError, CanonicalizeTaskError, ConsolidateInput, DerivedSafeHead, FinalizeBlockId,
SealTaskError,
};
use alloy_rpc_types_engine::PayloadId;
use kona_protocol::OpAttributesWithParent;
Expand Down Expand Up @@ -76,6 +77,20 @@ pub struct BuildRequest {
pub struct ResetRequest {
/// The channel on which the reset result will be sent.
pub result_tx: mpsc::Sender<EngineRequestResult<()>>,
/// The reset to perform.
pub kind: ResetKind,
}

/// The reset a [`ResetRequest`] asks the engine for.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResetKind {
/// Find a sync starting point with [`crate::find_starting_forkchoice`].
Full,
/// Answer an L1 reorg detected by derivation. Holds the safe heads derivation recently
/// produced, newest first, each with an L1 block that all of the L1 data it depends on is at
/// or below. The engine keeps the newest one the reorg left canonical; see
/// [`crate::Engine::reset_after_l1_reorg`].
AfterL1Reorg(Vec<DerivedSafeHead>),
}

/// A request to fetch a sealed payload without changing forkchoice.
Expand Down
16 changes: 16 additions & 0 deletions rust/kona/crates/node/engine/src/sync/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,22 @@ pub enum SyncStartError {
/// Finalized block mismatch
#[error("Finalized block mismatch. Expected {0}, Got {1}")]
MismatchedFinalizedBlock(B256, B256),
/// The unsafe chain does not lead back to a block it must descend from.
#[error("Unsafe chain does not lead back to {expected}; found {found}")]
UnsafeChainMismatch {
/// The block the unsafe chain must descend from.
expected: B256,
/// The block the unsafe chain has at that height.
found: B256,
},
/// The unsafe head is below a block it must descend from.
#[error("Unsafe head {unsafe_head} is below block {floor}, which it must descend from")]
UnsafeHeadBelowFloor {
/// The unsafe head's number.
unsafe_head: u64,
/// The number of the block it must descend from.
floor: u64,
},
/// The L1 RPC reported a head at or above a height, then served no block there.
#[error("L1 block {number} is missing below the L1 head {l1_head}")]
L1BlockMissing {
Expand Down
81 changes: 76 additions & 5 deletions rust/kona/crates/node/engine/src/sync/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@ pub use forkchoice::L2ForkchoiceState;
mod error;
pub use error::SyncStartError;

mod reorg;
pub use reorg::{DerivedSafeHead, find_reorg_forkchoice};

mod unsafe_head;

use tracing::info;

use crate::EngineClient;
Expand All @@ -19,12 +24,18 @@ use crate::EngineClient;
/// kona does not derive.
const MAX_REORG_SEQ_WINDOWS: u64 = 5;

/// How many sequencing windows the unsafe head's L1 origin must be past L1 genesis, with the safe
/// and finalized heads still at genesis, for the safe head search to treat the node as just
/// EL-synced. Matches op-node's `RecoverMinSeqWindows`.
const RECOVER_MIN_SEQ_WINDOWS: u64 = 14;

/// Searches for the latest [`L2ForkchoiceState`] that we can use to start the sync process with.
///
/// - The *unsafe L2 block*: This is the highest L2 block whose L1 origin is a *plausible*
/// extension of the canonical L1 chain (as known to the rollup node).
/// - The *safe L2 block*: This is the highest L2 block whose epoch's sequencing window is
/// complete within the canonical L1 chain (as known to the rollup node).
/// - The *safe L2 block*: This is the highest L2 block, at or below the previous safe one, whose
/// epoch's sequencing window is complete within the canonical L1 chain (as known to the rollup
/// node).
/// - The *finalized L2 block*: This is the L2 block which is known to be fully derived from
/// finalized L1 block data.
///
Expand Down Expand Up @@ -143,7 +154,20 @@ pub async fn find_starting_forkchoice(
);

// Search for the highest `safe` block that's L1 origin is at least older than the sequencing
// window, relative to the highest canonical L1 origin found above.
// window, relative to the highest canonical L1 origin found above, and that is no higher than
// the previous safe head: blocks above it were never derived, and may never be. Like op-node's
// `FindL2Heads`. After EL sync, though, the safe and finalized heads can still be at genesis
// with the unsafe head far ahead; there the cap would walk the whole chain back to genesis,
// so, like op-node's `RecoverMinSeqWindows` check, the search is left uncapped.
let el_synced_without_safe_head = current_fc.finalized.block_info.hash == cfg.genesis.l2.hash &&
current_fc.safe.block_info.hash == cfg.genesis.l2.hash &&
canonical_origin_head.l1_origin.number >
cfg.genesis
.l1
.number
.saturating_add(RECOVER_MIN_SEQ_WINDOWS * cfg.seq_window_size);
let previous_safe =
if el_synced_without_safe_head { u64::MAX } else { current_fc.safe.block_info.number };
let mut safe_cursor = canonical_origin_head;
loop {
info!(
Expand All @@ -157,9 +181,10 @@ pub async fn find_starting_forkchoice(
let is_behind_sequence_window =
canonical_origin_head.l1_origin.number.saturating_sub(cfg.seq_window_size) >
safe_cursor.l1_origin.number;
let is_derived = safe_cursor.block_info.number <= previous_safe;
let is_finalized = safe_cursor.block_info.hash == current_fc.finalized.block_info.hash;
let is_genesis = safe_cursor.block_info.hash == cfg.genesis.l2.hash;
if is_behind_sequence_window || is_finalized || is_genesis {
if (is_behind_sequence_window && is_derived) || is_finalized || is_genesis {
info!(
target: "sync_start",
l2_safe = %safe_cursor.block_info.number,
Expand Down Expand Up @@ -301,7 +326,9 @@ mod test {
l1_head: u64,
) {
l2.expect_params("eth_getBlockByNumber", json!(["finalized", true]), finalized);
l2.expect_params("eth_getBlockByNumber", json!(["safe", true]), finalized);
// The previous safe head is the unsafe head, so it never caps the safe head search here;
// `safe_cap_tests` covers the cap.
l2.expect_params("eth_getBlockByNumber", json!(["safe", true]), unsafe_head);
l2.expect_params("eth_getBlockByNumber", json!(["latest", true]), unsafe_head);
l1.expect_params("eth_getBlockByNumber", json!(["latest", false]), l1_block(l1_head, 0));
}
Expand Down Expand Up @@ -532,3 +559,47 @@ mod test {
l2.assert_finished();
}
}

#[cfg(test)]
mod safe_cap_tests {
use super::*;
use crate::test_utils::{TestChain, expect_l1_block, expect_l1_head, test_engine_client};
use rstest::rstest;
use std::sync::Arc;

/// The safe head never moves up. With a sequencing window of 2, block 22 (L1 origin 102) is
/// the first block below the unsafe head (L1 origin 105) more than a window behind it, but
/// derivation has only reached block 20, so the search keeps going down to block 20. Just
/// after EL sync, with the safe and finalized heads at genesis (here block 18) and the unsafe
/// head's L1 origin more than 14 windows past L1 genesis, it stops at block 22 instead of
/// walking the chain back to genesis.
#[rstest]
#[case::derivation_reached_block_20(false, 20)]
#[case::just_el_synced(true, 22)]
#[tokio::test]
async fn the_safe_head_stays_at_or_below_the_previous_one(
#[case] el_synced: bool,
#[case] expected_safe: u64,
) {
let chain = TestChain::new();
let mut config = RollupConfig { seq_window_size: 2, ..Default::default() };
if el_synced {
config.genesis.l2 = chain.info(18).block_info.id();
}
let config = Arc::new(config);
let (client, l1, l2) = test_engine_client(config.clone());
chain.expect_heads(&l2, 18, if el_synced { 18 } else { 20 }, 26);
expect_l1_head(&l1, 106);
expect_l1_block(&l1, 105, 106);
for number in (expected_safe..26).rev() {
chain.expect_by_hash(&l2, number);
}

let forkchoice = find_starting_forkchoice(&config, &client).await.unwrap();

assert_eq!(forkchoice.un_safe, chain.info(26));
assert_eq!(forkchoice.safe, chain.info(expected_safe));
l1.assert_finished();
l2.assert_finished();
}
}
108 changes: 108 additions & 0 deletions rust/kona/crates/node/engine/src/sync/reorg.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
//! Choosing the forkchoice to keep across an L1 reorg.
//!
//! [`find_starting_forkchoice`] cannot know which L1 block made the engine's safe head safe, so it
//! walks the safe head back a full sequencing window, stopping early only at the finalized head.
//! That is the right answer on a cold start, but after an L1 reorg detected mid-derivation it
//! makes the cost of a reset independent of the reorg's depth: a one-block replacement of the L1
//! tip rewinds the safe head as far as a cold start does, and while L1 finality is stalled that is
//! the whole sequencing window.
//!
//! Derivation does know where each safe head came from. A [`DerivedSafeHead`] records that all of
//! the L1 data `safe_head` depends on is at or below `derived_from`. Derivation is a function of
//! the L1 chain it has read, so while `derived_from` is canonical the reorg changed none of that
//! input and `safe_head` is still the safe head that L1 chain derives. Keeping it is then exactly
//! as sound as any reset: the pipeline restarts from a known-correct safe head, a channel timeout
//! behind its L1 origin, as it does after [`find_starting_forkchoice`].
//!
//! The unsafe chain is checked on its own terms. An unsafe block whose L1 origin the reorg
//! replaced commits to a non-canonical L1 block and can never become safe, so the unsafe head
//! moves back to the highest block whose L1 origin is still canonical. That walk visits only the
//! blocks built on replaced L1 blocks, and never passes the kept safe head, whose L1 data is
//! canonical.
//!
//! [`find_starting_forkchoice`]: crate::find_starting_forkchoice

use super::unsafe_head::{find_canonical_unsafe_head, is_canonical_l1};
use crate::{EngineClient, EngineState, EngineSyncState, L2ForkchoiceState, SyncStartError};
use alloy_eips::{BlockId, BlockNumHash};
use kona_protocol::L2BlockInfo;
use tracing::info;

/// A safe head, and an L1 block that all of the L1 data the safe head depends on is at or below.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DerivedSafeHead {
/// The safe head.
pub safe_head: L2BlockInfo,
/// An L1 block at or above every L1 block `safe_head` depends on, including through its
/// ancestors.
pub derived_from: BlockNumHash,
}

/// Picks the forkchoice to keep after an L1 reorg, or `None` when only a full reset is sound.
///
/// `candidates` must be ordered newest first. The safe head is the first candidate whose
/// `derived_from` is still canonical, kept only if it is still on the engine's chain, at or below
/// the local safe head and at or above the finalized head. The unsafe head is the highest block
/// between it and the current unsafe head whose L1 origin is still canonical. The finalized head
/// is unchanged.
pub async fn find_reorg_forkchoice(
engine_client: &EngineClient,
state: &EngineState,
candidates: &[DerivedSafeHead],
) -> Result<Option<L2ForkchoiceState>, SyncStartError> {
let sync_state = state.sync_state;
let Some(safe) = find_reorg_safe_head(engine_client, &sync_state, candidates).await? else {
return Ok(None);
};
let un_safe =
match find_canonical_unsafe_head(engine_client, sync_state.unsafe_head(), safe).await {
Ok(un_safe) => un_safe,
// An unsafe chain that misses a block or does not lead to the kept safe head is left to
// the full reset.
Err(
SyncStartError::BlockNotFound(_) |
SyncStartError::UnsafeChainMismatch { .. } |
SyncStartError::UnsafeHeadBelowFloor { .. },
) => {
return Ok(None);
}
Err(err) => return Err(err),
};

info!(
target: "sync_start",
safe_head = %safe.block_info.number,
unsafe_head = %un_safe.block_info.number,
"Keeping heads derived from canonical L1 data across the L1 reorg"
);
Ok(Some(L2ForkchoiceState { un_safe, safe, finalized: sync_state.finalized_head() }))
}

/// The first of `candidates` whose L1 data is canonical, if the engine can keep it as its safe
/// head.
async fn find_reorg_safe_head(
engine_client: &EngineClient,
sync_state: &EngineSyncState,
candidates: &[DerivedSafeHead],
) -> Result<Option<L2BlockInfo>, SyncStartError> {
for candidate in candidates {
if !is_canonical_l1(engine_client, candidate.derived_from).await? {
continue;
}

let safe_head = candidate.safe_head;
let number = safe_head.block_info.number;
if number > sync_state.local_safe_head().block_info.number ||
number < sync_state.finalized_head().block_info.number
{
return Ok(None);
}
let on_chain = engine_client
.get_l2_block(BlockId::number(number))
.await?
.is_some_and(|block| block.header.hash == safe_head.block_info.hash);
return Ok(on_chain.then_some(safe_head));
}

Ok(None)
}
Loading
Loading