From 3d45318ea148b4776349120e0f0fefede650d66d Mon Sep 17 00:00:00 2001 From: Josh Klopfenstein Date: Tue, 3 Nov 2026 09:36:23 -0800 Subject: [PATCH 1/2] kona-engine,kona-node!: place safe and finalized behind the tip after EL sync op-node handles the end of EL sync as its own step: its engine controller places safe and finalized --syncmode.offset-el-safe behind the synced tip (default 12h), because the tip arrived over P2P and may not be batched to L1 yet. kona-node instead ran an ordinary engine reset, so its safe and finalized heads after EL sync came from the sync-start search: finalized stayed at genesis and safe was found by walking back from the tip. The engine now completes EL sync with find_el_sync_forkchoice, a port of the offset path of op-node's headsAfterELSync. Like op-node, it applies only when the execution layer had no finality beyond genesis; otherwise this is a restart and the regular search runs. It keeps the execution layer's safe label when that is closer to the tip. A sequencer starts with a reset before EL sync finishes, so it keeps taking the regular path. The new --syncmode.offset-el-safe flag (KONA_NODE_SYNCMODE_OFFSET_EL_SAFE) sets the offset. Resuming from the safe head database tip, op-node's other EL-sync path, is left to ethereum-optimism/optimism#23658. BREAKING CHANGE: After EL sync, kona-node now sets safe and finalized 12h of L2 blocks behind the synced tip, where finalized used to stay at genesis. Set --syncmode.offset-el-safe to change the offset. Engine has a new el_sync_safe_offset setting, defaulting to DEFAULT_EL_SYNC_SAFE_OFFSET, and exhaustive SyncStartError matches must handle ElSyncOffsetBlockUnavailable, returned when the execution layer has pruned the block at the offset. Co-Authored-By: Claude Opus 5.5 --- rust/Cargo.lock | 1 + rust/kona/bin/node/Cargo.toml | 1 + .../bin/node/src/commands/node/command.rs | 15 + rust/kona/bin/node/src/commands/node/tests.rs | 35 +++ rust/kona/crates/node/engine/src/lib.rs | 5 +- .../crates/node/engine/src/sync/el_sync.rs | 264 ++++++++++++++++++ .../kona/crates/node/engine/src/sync/error.rs | 11 + rust/kona/crates/node/engine/src/sync/mod.rs | 3 + .../crates/node/engine/src/task_queue/core.rs | 40 ++- .../crates/node/engine/src/test_utils/misc.rs | 46 ++- .../crates/node/engine/src/test_utils/mod.rs | 2 +- .../node/service/src/actors/engine/actor.rs | 11 +- .../node/service/src/actors/engine/tests.rs | 85 +++++- .../node/service/src/service/builder.rs | 12 +- .../node/service/src/service/node/rollup.rs | 5 +- 15 files changed, 522 insertions(+), 14 deletions(-) create mode 100644 rust/kona/crates/node/engine/src/sync/el_sync.rs diff --git a/rust/Cargo.lock b/rust/Cargo.lock index 0c7ad65bc6f..a58d6079c9a 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -7615,6 +7615,7 @@ dependencies = [ "dirs 6.0.0", "discv5 0.12.0", "enr 0.14.0", + "humantime", "kona-cli", "kona-derive", "kona-disc", diff --git a/rust/kona/bin/node/Cargo.toml b/rust/kona/bin/node/Cargo.toml index fc30ed4c5b8..cc672c7d252 100644 --- a/rust/kona/bin/node/Cargo.toml +++ b/rust/kona/bin/node/Cargo.toml @@ -52,6 +52,7 @@ op-alloy-network.workspace = true # general url.workspace = true dirs.workspace = true +humantime.workspace = true strum.workspace = true discv5.workspace = true enr.workspace = true diff --git a/rust/kona/bin/node/src/commands/node/command.rs b/rust/kona/bin/node/src/commands/node/command.rs index b96712488c6..2124d736b2a 100644 --- a/rust/kona/bin/node/src/commands/node/command.rs +++ b/rust/kona/bin/node/src/commands/node/command.rs @@ -13,6 +13,7 @@ use anyhow::{Context as _, Result, bail}; use backon::{ExponentialBuilder, Retryable}; use clap::Parser; use kona_cli::{LogConfig, MetricsArgs}; +use kona_engine::DEFAULT_EL_SYNC_SAFE_OFFSET; use kona_genesis::{L1ChainConfig, RollupConfig}; use kona_interop::DependencySet; use kona_node_service::{EngineConfig, L1ConfigBuilder, NodeMode, RollupNodeBuilder}; @@ -29,6 +30,7 @@ use std::{ num::NonZeroUsize, path::PathBuf, sync::Arc, + time::Duration, }; use strum::IntoEnumIterator; use tracing::{debug, error, info}; @@ -145,6 +147,17 @@ pub struct NodeCommand { /// Reorgs are supported, but may be slow to recover from. #[arg(long = "verifier.l1-confs", env = "KONA_NODE_VERIFIER_L1_CONFS", default_value_t = 0)] pub verifier_l1_confs: u64, + /// After execution-layer sync, set the safe and finalized heads this far behind the synced tip + /// (converted to L2 blocks with ceiling division). Mirrors op-node's + /// `--syncmode.offset-el-safe`. kona-node has no consensus-layer sync mode, so this applies on + /// any start where the execution layer has no finalized block beyond genesis. + #[arg( + long = "syncmode.offset-el-safe", + env = "KONA_NODE_SYNCMODE_OFFSET_EL_SAFE", + default_value = "12h", + value_parser = humantime::parse_duration, + )] + pub el_sync_safe_offset: Duration, /// P2P CLI arguments. #[command(flatten)] pub p2p_flags: P2PArgs, @@ -167,6 +180,7 @@ impl Default for NodeCommand { interop_dependency_set: None, safedb_path: None, verifier_l1_confs: 0, + el_sync_safe_offset: DEFAULT_EL_SYNC_SAFE_OFFSET, node_mode: NodeMode::Validator, p2p_flags: P2PArgs::default(), rpc_flags: RpcArgs::default(), @@ -363,6 +377,7 @@ impl NodeCommand { .with_dependency_set(dependency_set) .with_safe_db(safe_db) .with_verifier_l1_confs(self.verifier_l1_confs) + .with_el_sync_safe_offset(self.el_sync_safe_offset) .build() .start() .await diff --git a/rust/kona/bin/node/src/commands/node/tests.rs b/rust/kona/bin/node/src/commands/node/tests.rs index 1de9a36c109..3224a210bc4 100644 --- a/rust/kona/bin/node/src/commands/node/tests.rs +++ b/rust/kona/bin/node/src/commands/node/tests.rs @@ -62,6 +62,41 @@ fn verifier_confirmation_depth_has_the_expected_environment_variable() { assert_eq!(arg.get_env().unwrap(), "KONA_NODE_VERIFIER_L1_CONFS"); } +/// Like op-node, the EL-sync safe offset defaults to 12h and takes durations such as `30m`, +/// including the milliseconds devstack passes and Go's `12h0m0s` form. +#[rstest::rstest] +#[case::default(None, 12 * 60 * 60)] +#[case::minutes(Some("30m"), 30 * 60)] +#[case::disabled(Some("0s"), 0)] +#[case::milliseconds(Some("90000ms"), 90)] +#[case::zero_milliseconds(Some("0ms"), 0)] +#[case::go_duration(Some("12h0m0s"), 12 * 60 * 60)] +fn el_sync_safe_offset_parses_durations(#[case] flag: Option<&str>, #[case] seconds: u64) { + let flag = flag.map(|value| ["--syncmode.offset-el-safe", value]); + let args = NodeCommand::parse_from( + std::iter::once("node") + .chain(default_flags().iter().copied()) + .chain(flag.into_iter().flatten()), + ); + assert_eq!(args.el_sync_safe_offset, std::time::Duration::from_secs(seconds)); +} + +#[test] +fn el_sync_safe_offset_default_matches_the_engine() { + assert_eq!( + NodeCommand::default().el_sync_safe_offset, + kona_engine::DEFAULT_EL_SYNC_SAFE_OFFSET + ); +} + +#[test] +fn el_sync_safe_offset_has_the_expected_environment_variable() { + use clap::CommandFactory; + let command = NodeCommand::command(); + let arg = command.get_arguments().find(|arg| arg.get_id() == "el_sync_safe_offset").unwrap(); + assert_eq!(arg.get_env().unwrap(), "KONA_NODE_SYNCMODE_OFFSET_EL_SAFE"); +} + #[test] fn test_node_cli_missing_l1_eth_rpc() { let err = NodeCommand::try_parse_from(["node"]).unwrap_err(); diff --git a/rust/kona/crates/node/engine/src/lib.rs b/rust/kona/crates/node/engine/src/lib.rs index eb26238be30..ec2af253d65 100644 --- a/rust/kona/crates/node/engine/src/lib.rs +++ b/rust/kona/crates/node/engine/src/lib.rs @@ -74,7 +74,10 @@ mod metrics; pub use metrics::Metrics; mod sync; -pub use sync::{L2ForkchoiceState, SyncStartError, find_starting_forkchoice}; +pub use sync::{ + DEFAULT_EL_SYNC_SAFE_OFFSET, L2ForkchoiceState, SyncStartError, find_el_sync_forkchoice, + find_starting_forkchoice, +}; #[cfg(any(test, feature = "test-utils"))] /// Utilities that are useful when creating unit tests using structs within this library. diff --git a/rust/kona/crates/node/engine/src/sync/el_sync.rs b/rust/kona/crates/node/engine/src/sync/el_sync.rs new file mode 100644 index 00000000000..94344e851c2 --- /dev/null +++ b/rust/kona/crates/node/engine/src/sync/el_sync.rs @@ -0,0 +1,264 @@ +//! The forkchoice state to adopt when execution-layer sync completes. + +use alloy_eips::BlockId; +use kona_genesis::RollupConfig; +use kona_protocol::L2BlockInfo; +use std::time::Duration; +use tracing::info; + +use crate::{EngineClient, L2ForkchoiceState, SyncStartError, find_starting_forkchoice}; + +/// Matches op-node's default `--syncmode.offset-el-safe`: how far behind an EL-synced tip the +/// safe and finalized heads are placed. The tip arrived over P2P and may not be batched to L1 +/// yet, so it must not be labelled safe or finalized. +pub const DEFAULT_EL_SYNC_SAFE_OFFSET: Duration = Duration::from_secs(12 * 60 * 60); + +/// Returns the forkchoice state to adopt once execution-layer sync has completed. +/// +/// Like op-node, EL sync applies only when the execution layer had no finalized block beyond +/// genesis. Then the unsafe head stays at the synced tip, and safe and finalized are placed +/// `el_sync_safe_offset` behind it, as op-node's `headsAfterELSync` does when it has no usable +/// safe head database. The execution layer's own safe label is kept when it is closer to the tip. +/// Otherwise the execution layer already had finality, so this is a restart and the heads come +/// from [`find_starting_forkchoice`]. +pub async fn find_el_sync_forkchoice( + cfg: &RollupConfig, + engine_client: &EngineClient, + el_sync_safe_offset: Duration, +) -> Result { + let current = L2ForkchoiceState::current(cfg, engine_client).await?; + if current.finalized.block_info.hash != cfg.genesis.l2.hash { + return find_starting_forkchoice(cfg, engine_client).await; + } + + let tip = current.un_safe; + let target = offset_block_number( + el_sync_safe_offset, + cfg.block_time, + tip.block_info.number, + cfg.genesis.l2.number, + ); + let offset_head = if target < tip.block_info.number { + let block = engine_client.get_l2_block(BlockId::number(target)).full().await?.ok_or( + SyncStartError::ElSyncOffsetBlockUnavailable { + number: target, + offset: el_sync_safe_offset, + }, + )?; + L2BlockInfo::from_block_and_genesis(&block.into_consensus(), &cfg.genesis)? + } else { + tip + }; + let safe = if current.safe.block_info.number > offset_head.block_info.number && + current.safe.block_info.number <= tip.block_info.number + { + current.safe + } else { + offset_head + }; + let forkchoice = L2ForkchoiceState { un_safe: tip, safe, finalized: offset_head }; + info!(target: "sync_start", ?el_sync_safe_offset, %forkchoice, "Adopting EL-synced forkchoice"); + Ok(forkchoice) +} + +/// Port of op-node's `OffsetBlockNum`: the block number `ceil(offset / block_time)` blocks behind +/// `head`, never below `genesis`. Like op-node, sub-second parts of `offset` are ignored. +pub(crate) fn offset_block_number( + offset: Duration, + block_time: u64, + head: u64, + genesis: u64, +) -> u64 { + if block_time == 0 || head <= genesis { + return head; + } + head - offset.as_secs().div_ceil(block_time).min(head - genesis) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_utils::{RpcMock, test_engine_client, test_l1_hash, test_l2_block_with_origin}; + use alloy_primitives::B256; + use serde_json::json; + use std::sync::Arc; + + type L1Block = alloy_rpc_types_eth::Block; + type L2Block = alloy_rpc_types_eth::Block; + + /// Two-second blocks, so a 10s offset is 5 blocks. + const BLOCK_TIME: u64 = 2; + const OFFSET: Duration = Duration::from_secs(10); + + fn info(block: &L2Block, cfg: &RollupConfig) -> L2BlockInfo { + L2BlockInfo::from_block_and_genesis(&block.clone().into_consensus(), &cfg.genesis).unwrap() + } + + fn expect_heads(mock: &RpcMock, finalized: &L2Block, safe: &L2Block, head: &L2Block) { + for (tag, block) in [("finalized", finalized), ("safe", safe), ("latest", head)] { + mock.expect_params("eth_getBlockByNumber", json!([tag, true]), block); + } + } + + fn config(genesis: &L2Block) -> RollupConfig { + let mut cfg = RollupConfig { block_time: BLOCK_TIME, ..Default::default() }; + cfg.genesis.l2.hash = genesis.header.hash; + cfg + } + + // With finalized at genesis, the execution layer was EL-synced: safe and finalized go the + // offset behind the tip, clamped at genesis, unless its safe label is closer to the tip. + #[rstest::rstest] + #[case::offset_behind_tip(100, 0, 95, 95)] + #[case::clamped_at_genesis(3, 0, 0, 0)] + #[case::safe_label_closer_to_tip(100, 98, 98, 95)] + #[case::safe_label_further_back(100, 50, 95, 95)] + #[tokio::test] + async fn el_synced_heads_are_placed_the_offset_behind_the_tip( + #[case] tip: u64, + #[case] safe_label: u64, + #[case] expected_safe: u64, + #[case] expected_finalized: u64, + ) { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let cfg = config(&genesis); + let block = |number: u64| { + if number == 0 { + genesis.clone() + } else { + test_l2_block_with_origin(number, number, 0, B256::ZERO) + } + }; + let (client, l1, l2) = test_engine_client(Arc::new(cfg.clone())); + expect_heads(&l2, &genesis, &block(safe_label), &block(tip)); + if expected_finalized < tip { + l2.expect_params( + "eth_getBlockByNumber", + json!([format!("{expected_finalized:#x}"), true]), + block(expected_finalized), + ); + } + + let result = find_el_sync_forkchoice(&cfg, &client, OFFSET).await.unwrap(); + + assert_eq!(result.un_safe, info(&block(tip), &cfg)); + assert_eq!(result.safe, info(&block(expected_safe), &cfg)); + assert_eq!(result.finalized, info(&block(expected_finalized), &cfg)); + l1.assert_finished(); + l2.assert_finished(); + } + + // With a zero offset, safe and finalized are the tip and nothing else is fetched. + #[tokio::test] + async fn zero_offset_uses_the_tip() { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let cfg = config(&genesis); + let tip = test_l2_block_with_origin(100, 100, 0, B256::ZERO); + let (client, l1, l2) = test_engine_client(Arc::new(cfg.clone())); + expect_heads(&l2, &genesis, &genesis, &tip); + + let result = find_el_sync_forkchoice(&cfg, &client, Duration::ZERO).await.unwrap(); + + let tip = info(&tip, &cfg); + assert_eq!(result, L2ForkchoiceState { un_safe: tip, safe: tip, finalized: tip }); + l1.assert_finished(); + l2.assert_finished(); + } + + // A safe label above the tip is stale, so safe goes to the offset head instead. + #[tokio::test] + async fn safe_label_above_the_tip_is_ignored() { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let cfg = config(&genesis); + let tip = test_l2_block_with_origin(100, 100, 0, B256::ZERO); + let offset_head = test_l2_block_with_origin(95, 95, 0, B256::ZERO); + let (client, l1, l2) = test_engine_client(Arc::new(cfg.clone())); + expect_heads(&l2, &genesis, &test_l2_block_with_origin(120, 120, 0, B256::ZERO), &tip); + l2.expect_params("eth_getBlockByNumber", json!(["0x5f", true]), &offset_head); + + let result = find_el_sync_forkchoice(&cfg, &client, OFFSET).await.unwrap(); + + let offset_head = info(&offset_head, &cfg); + assert_eq!( + result, + L2ForkchoiceState { + un_safe: info(&tip, &cfg), + safe: offset_head, + finalized: offset_head + } + ); + l1.assert_finished(); + l2.assert_finished(); + } + + // An execution layer that pruned the block at the offset height cannot complete EL sync. The + // error names the setting to change, and retrying would not help. + #[tokio::test] + async fn pruned_offset_block_is_reported() { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let cfg = config(&genesis); + let tip = test_l2_block_with_origin(100, 100, 0, B256::ZERO); + let (client, l1, l2) = test_engine_client(Arc::new(cfg.clone())); + expect_heads(&l2, &genesis, &genesis, &tip); + l2.expect_params("eth_getBlockByNumber", json!(["0x5f", true]), Option::::None); + + let err = find_el_sync_forkchoice(&cfg, &client, OFFSET).await.unwrap_err(); + + assert!( + matches!(err, SyncStartError::ElSyncOffsetBlockUnavailable { number: 95, offset } + if offset == OFFSET), + "{err:?}" + ); + assert!(err.to_string().contains("--syncmode.offset-el-safe")); + assert!(!crate::EngineResetError::SyncStart(err).is_temporary()); + l1.assert_finished(); + l2.assert_finished(); + } + + // An execution layer that already has a finalized block beyond genesis was not EL-synced, so + // the heads come from the regular sync-start search instead of the offset. + #[tokio::test] + async fn established_finality_uses_the_sync_start_search() { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let cfg = config(&genesis); + let head = test_l2_block_with_origin(100, 99, 0, B256::ZERO); + let (client, l1, l2) = test_engine_client(Arc::new(cfg.clone())); + for _ in 0..2 { + expect_heads(&l2, &head, &head, &head); + } + let mut origin = L1Block::default(); + origin.header.hash = test_l1_hash(99); + origin.header.inner.number = 99; + // The sync-start search reads the L1 head, then checks the origin is canonical. + for number in ["latest", "0x63"] { + l1.expect_params("eth_getBlockByNumber", json!([number, false]), &origin); + } + + let result = find_el_sync_forkchoice(&cfg, &client, OFFSET).await.unwrap(); + + let head = info(&head, &cfg); + assert_eq!(result, L2ForkchoiceState { un_safe: head, safe: head, finalized: head }); + l1.assert_finished(); + l2.assert_finished(); + } + + // Mirrors op-node's OffsetBlockNum: ceiling division by the block time, clamped at genesis. + #[rstest::rstest] + #[case::zero_offset(0, 2, 100, 0, 100)] + #[case::rounds_up(3_000, 2, 100, 0, 98)] + #[case::whole_blocks(4_000, 2, 100, 0, 98)] + #[case::ignores_sub_second(1_500, 2, 100, 0, 99)] + #[case::clamped_at_genesis(1_000_000, 2, 105, 100, 100)] + #[case::head_at_genesis(10_000, 2, 100, 100, 100)] + #[case::zero_block_time(10_000, 0, 100, 0, 100)] + fn offset_block_number_matches_op_node( + #[case] offset_millis: u64, + #[case] block_time: u64, + #[case] head: u64, + #[case] genesis: u64, + #[case] expected: u64, + ) { + let offset = Duration::from_millis(offset_millis); + assert_eq!(offset_block_number(offset, block_time, head, genesis), expected); + } +} diff --git a/rust/kona/crates/node/engine/src/sync/error.rs b/rust/kona/crates/node/engine/src/sync/error.rs index 1bb9197629c..ac9b9085196 100644 --- a/rust/kona/crates/node/engine/src/sync/error.rs +++ b/rust/kona/crates/node/engine/src/sync/error.rs @@ -24,6 +24,17 @@ pub enum SyncStartError { /// A block could not be found. #[error("Block not found: {0}")] BlockNotFound(BlockId), + /// The execution layer has no block at the height where EL sync places safe and finalized. + #[error( + "Execution layer has no block {number}, {offset:?} behind the EL-synced tip; it may have \ + been pruned. Lower --syncmode.offset-el-safe or keep more block history" + )] + ElSyncOffsetBlockUnavailable { + /// The L2 block number at the EL-sync safe offset. + number: u64, + /// The configured EL-sync safe offset. + offset: std::time::Duration, + }, /// Invalid L1 genesis hash. #[error("Invalid L1 genesis hash. Expected {0}, Got {1}")] InvalidL1GenesisHash(B256, B256), diff --git a/rust/kona/crates/node/engine/src/sync/mod.rs b/rust/kona/crates/node/engine/src/sync/mod.rs index 8631123d50e..d2682df6edb 100644 --- a/rust/kona/crates/node/engine/src/sync/mod.rs +++ b/rust/kona/crates/node/engine/src/sync/mod.rs @@ -9,6 +9,9 @@ pub use forkchoice::L2ForkchoiceState; mod error; pub use error::SyncStartError; +mod el_sync; +pub use el_sync::{DEFAULT_EL_SYNC_SAFE_OFFSET, find_el_sync_forkchoice}; + use tracing::info; use crate::EngineClient; diff --git a/rust/kona/crates/node/engine/src/task_queue/core.rs b/rust/kona/crates/node/engine/src/task_queue/core.rs index 65ef7bdc252..2808f0a2323 100644 --- a/rust/kona/crates/node/engine/src/task_queue/core.rs +++ b/rust/kona/crates/node/engine/src/task_queue/core.rs @@ -2,14 +2,14 @@ use super::ExecutableEngineTask; use crate::{ - EngineClient, EngineState, EngineSyncStateUpdate, EngineTask, EngineTaskError, - EngineTaskErrorSeverity, Metrics, SyncStartError, SynchronizeTaskError, - find_starting_forkchoice, + DEFAULT_EL_SYNC_SAFE_OFFSET, EngineClient, EngineState, EngineSyncStateUpdate, EngineTask, + EngineTaskError, EngineTaskErrorSeverity, L2ForkchoiceState, Metrics, SyncStartError, + SynchronizeTaskError, find_el_sync_forkchoice, find_starting_forkchoice, task_queue::{EngineTaskErrors, synchronize_unconditionally}, }; use kona_genesis::RollupConfig; use kona_protocol::L2BlockInfo; -use std::{cmp::Ordering, collections::BinaryHeap, sync::Arc}; +use std::{cmp::Ordering, collections::BinaryHeap, sync::Arc, time::Duration}; use thiserror::Error; use tokio::sync::watch::Sender; @@ -63,6 +63,8 @@ pub struct Engine { /// Preserve the task being retried ahead of newly enqueued work: it may have already /// performed part of an Engine API operation. active: Option, + /// How far behind the synced tip [`Engine::reset_after_el_sync`] places safe and finalized. + el_sync_safe_offset: Duration, } impl Engine { @@ -74,9 +76,17 @@ impl Engine { tasks: BinaryHeap::default(), active: None, next_sequence: 0, + el_sync_safe_offset: DEFAULT_EL_SYNC_SAFE_OFFSET, } } + /// Sets how far behind the synced tip [`Engine::reset_after_el_sync`] places safe and + /// finalized. Defaults to [`DEFAULT_EL_SYNC_SAFE_OFFSET`]. + pub const fn with_el_sync_safe_offset(mut self, el_sync_safe_offset: Duration) -> Self { + self.el_sync_safe_offset = el_sync_safe_offset; + self + } + /// Returns a reference to the inner [`EngineState`]. pub const fn state(&self) -> &EngineState { &self.state @@ -114,12 +124,32 @@ impl Engine { config: Arc, ) -> Result { let start = find_starting_forkchoice(&config, client.as_ref()).await?; + self.adopt_forkchoice(&client, start).await + } + /// Resets the engine once execution-layer sync has completed, with the forkchoice state from + /// [`find_el_sync_forkchoice`]. Synchronizes the execution layer and publishes the recovered + /// state before returning. + pub async fn reset_after_el_sync( + &mut self, + client: Arc, + config: Arc, + ) -> Result { + let start = + find_el_sync_forkchoice(&config, client.as_ref(), self.el_sync_safe_offset).await?; + self.adopt_forkchoice(&client, start).await + } + + async fn adopt_forkchoice( + &mut self, + client: &EngineClient, + start: L2ForkchoiceState, + ) -> Result { // One attempt. The actor retains the reset request and retries transient failures. The // execution layer may have lost or changed its forkchoice, so the reset sends one even when // the recovered labels equal the current ones. synchronize_unconditionally( - client.as_ref(), + client, &mut self.state, EngineSyncStateUpdate { unsafe_head: Some(start.un_safe), diff --git a/rust/kona/crates/node/engine/src/test_utils/misc.rs b/rust/kona/crates/node/engine/src/test_utils/misc.rs index fd77bf7ccf4..218055652bc 100644 --- a/rust/kona/crates/node/engine/src/test_utils/misc.rs +++ b/rust/kona/crates/node/engine/src/test_utils/misc.rs @@ -1,6 +1,6 @@ use alloy_eips::BlockNumHash; -use alloy_primitives::B256; -use kona_protocol::{BlockInfo, L2BlockInfo}; +use alloy_primitives::{B256, Sealed, U256}; +use kona_protocol::{BlockInfo, L1BlockInfoBedrock, L2BlockInfo}; /// Helper to create a test `L2BlockInfo` at a specific block number pub fn test_block_info(number: u64) -> L2BlockInfo { @@ -15,3 +15,45 @@ pub fn test_block_info(number: u64) -> L2BlockInfo { seq_num: 0, } } + +/// The hash that tests give the L1 block at `number`, distinct for every height. +pub fn test_l1_hash(number: u64) -> B256 { + B256::from(U256::from(number)) +} + +/// Builds a full L2 block with a real L1-info deposit, whose L1 origin hash is +/// [`test_l1_hash`]`(origin)` and whose timestamp is `number * 2`. +pub fn test_l2_block_with_origin( + number: u64, + origin: u64, + sequence: u64, + parent: B256, +) -> alloy_rpc_types_eth::Block { + let data = L1BlockInfoBedrock::new( + origin, + 0, + 0, + test_l1_hash(origin), + sequence, + Default::default(), + Default::default(), + Default::default(), + ) + .encode_calldata(); + let transaction = + op_alloy_consensus::OpTxEnvelope::Deposit(Sealed::new(op_alloy_consensus::TxDeposit { + input: data, + ..Default::default() + })); + let transaction = op_alloy_rpc_types::Transaction::from_transaction( + alloy_consensus::transaction::Recovered::new_unchecked(transaction, Default::default()), + Default::default(), + ); + let mut block: alloy_rpc_types_eth::Block = Default::default(); + block.header.inner.number = number; + block.header.inner.parent_hash = parent; + block.header.inner.timestamp = number * 2; + block.header.hash = block.header.inner.hash_slow(); + block.transactions = alloy_rpc_types_eth::BlockTransactions::Full(vec![transaction]); + block +} diff --git a/rust/kona/crates/node/engine/src/test_utils/mod.rs b/rust/kona/crates/node/engine/src/test_utils/mod.rs index dd8c55020bd..1feed127fa1 100644 --- a/rust/kona/crates/node/engine/src/test_utils/mod.rs +++ b/rust/kona/crates/node/engine/src/test_utils/mod.rs @@ -14,4 +14,4 @@ mod engine_state; pub use engine_state::TestEngineStateBuilder; mod misc; -pub use misc::test_block_info; +pub use misc::{test_block_info, test_l1_hash, test_l2_block_with_origin}; diff --git a/rust/kona/crates/node/service/src/actors/engine/actor.rs b/rust/kona/crates/node/service/src/actors/engine/actor.rs index b45bfa62238..080fcab3598 100644 --- a/rust/kona/crates/node/service/src/actors/engine/actor.rs +++ b/rust/kona/crates/node/service/src/actors/engine/actor.rs @@ -142,8 +142,15 @@ where /// Resets the inner [`Engine`] and propagates the reset to the derivation actor. async fn reset(&mut self) -> Result<(), EngineError> { - // Reset the engine. - let l2_safe_head = self.engine.reset(self.client.clone(), self.rollup.clone()).await?; + // Reset the engine. The first reset after EL sync finishes completes EL sync like + // op-node's engine controller: if the execution layer has no finality yet, safe and + // finalized go the EL-sync offset behind the synced tip. A sequencer's initial reset runs + // before EL sync finishes, so it takes the regular path. + let l2_safe_head = if !self.el_sync_complete && self.engine.state().el_sync_finished { + self.engine.reset_after_el_sync(self.client.clone(), self.rollup.clone()).await? + } else { + self.engine.reset(self.client.clone(), self.rollup.clone()).await? + }; // The sequencer must observe the same reset head as RPC readers before its reset // acknowledgement can release a queued start command. self.publish_unsafe_head(); diff --git a/rust/kona/crates/node/service/src/actors/engine/tests.rs b/rust/kona/crates/node/service/src/actors/engine/tests.rs index 0d0169c241f..68a33db2828 100644 --- a/rust/kona/crates/node/service/src/actors/engine/tests.rs +++ b/rust/kona/crates/node/service/src/actors/engine/tests.rs @@ -4,7 +4,7 @@ use alloy_primitives::B256; use alloy_rpc_types_engine::{ForkchoiceUpdated, PayloadStatus, PayloadStatusEnum}; use kona_engine::{ Engine, EngineActorRequest, EngineState, EngineSyncStateUpdate, FinalizeBlockId, NoopBlockSink, - test_utils::{TestAttributesBuilder, test_engine_client}, + test_utils::{TestAttributesBuilder, test_engine_client, test_l2_block_with_origin}, }; use kona_genesis::RollupConfig; use kona_protocol::{BlockInfo, L2BlockInfo}; @@ -256,6 +256,89 @@ async fn admin_reset_recovers_and_completes_original_request( l2.assert_finished(); } +/// EL-sync completion places safe and finalized the EL-sync offset behind the synced tip, as +/// op-node's engine controller does, whatever the chain's age. The tip arrived over P2P and may +/// not be on L1 yet. Derivation then resumes from that head, without reading the synced chain's +/// ancestry. +#[tokio::test(start_paused = true)] +async fn el_sync_completion_places_safe_and_finalized_the_offset_behind_the_tip() { + let genesis = test_l2_block_with_origin(0, 0, 0, B256::ZERO); + let mut config = RollupConfig { block_time: 2, ..Default::default() }; + config.genesis.l2.hash = genesis.header.hash; + let tip = test_l2_block_with_origin(100, 50, 0, B256::ZERO); + // A 10s offset is five two-second blocks. + let offset_head = test_l2_block_with_origin(95, 47, 0, B256::ZERO); + let [tip_info, offset_info] = [&tip, &offset_head].map(|block| { + L2BlockInfo::from_block_and_genesis(&block.clone().into_consensus(), &config.genesis) + .unwrap() + }); + let config = Arc::new(config); + let (client, l1, l2) = test_engine_client(config.clone()); + let state = EngineState { + sync_state: EngineState::default().sync_state.apply_update(EngineSyncStateUpdate { + unsafe_head: Some(tip_info), + ..Default::default() + }), + el_sync_finished: true, + ..Default::default() + }; + let (state_tx, state_rx) = tokio::sync::watch::channel(state); + let (requests, request_rx) = mpsc::channel(1); + let (derivation_tx, mut derivation_rx) = mpsc::channel(2); + let mut actor = EngineActor::new( + Arc::new(client), + config, + QueuedEngineDerivationClient { derivation_actor_request_tx: derivation_tx }, + Engine::new(state, state_tx).with_el_sync_safe_offset(Duration::from_secs(10)), + None, + request_rx, + Arc::new(NoopBlockSink), + ); + // The completed EL sync with an unset finalized head schedules its own reset. + actor.step().await.unwrap(); + for (tag, block) in [("finalized", &genesis), ("safe", &genesis), ("latest", &tip)] { + l2.expect_params("eth_getBlockByNumber", serde_json::json!([tag, true]), block); + } + l2.expect_params("eth_getBlockByNumber", serde_json::json!(["0x5f", true]), &offset_head); + l2.expect_params( + "engine_forkchoiceUpdatedV3", + serde_json::json!([ + alloy_rpc_types_engine::ForkchoiceState { + head_block_hash: tip_info.hash(), + safe_block_hash: offset_info.hash(), + finalized_block_hash: offset_info.hash(), + }, + null + ]), + ForkchoiceUpdated::new(PayloadStatus::from_status(PayloadStatusEnum::Valid)), + ); + // Closing input lets the step return after recovery and its notifications have completed. + drop(requests); + assert!(matches!(actor.step().await, Err(crate::EngineError::ChannelClosed))); + let published = *state_rx.borrow(); + assert_eq!(published.sync_state.unsafe_head(), tip_info); + assert_eq!(published.sync_state.local_safe_head(), offset_info); + assert_eq!(published.sync_state.safe_head(), offset_info); + assert_eq!(published.sync_state.finalized_head(), offset_info); + let DerivationActorRequest::ProcessEngineSignalRequest(signal) = + derivation_rx.recv().await.unwrap() + else { + panic!("expected the reset head"); + }; + assert!( + matches!(*signal, kona_derive::Signal::Reset(reset) if reset.l2_safe_head == offset_info) + ); + let DerivationActorRequest::ProcessEngineSyncCompletionRequest(head) = + derivation_rx.recv().await.unwrap() + else { + panic!("expected EL-sync completion after reset"); + }; + assert_eq!(*head, offset_info); + assert!(derivation_rx.try_recv().is_err()); + l1.assert_finished(); + l2.assert_finished(); +} + fn l2_block(number: u64) -> L2BlockInfo { L2BlockInfo { block_info: BlockInfo { diff --git a/rust/kona/crates/node/service/src/service/builder.rs b/rust/kona/crates/node/service/src/service/builder.rs index 92a019d2ea7..b52f04fa3f7 100644 --- a/rust/kona/crates/node/service/src/service/builder.rs +++ b/rust/kona/crates/node/service/src/service/builder.rs @@ -1,9 +1,10 @@ //! Contains the builder for the [`RollupNode`]. use crate::{EngineConfig, NetworkConfig, RollupNode, SequencerConfig, service::node::L1Config}; -use std::sync::Arc; +use std::{sync::Arc, time::Duration}; use url::Url; +use kona_engine::DEFAULT_EL_SYNC_SAFE_OFFSET; use kona_genesis::{L1ChainConfig, RollupConfig}; use kona_interop::DependencySet; use kona_providers_alloy::{AlloyChainProvider, OnlineBeaconClient}; @@ -54,6 +55,8 @@ pub struct RollupNodeBuilder { pub safe_db: Option>, /// Number of L1 confirmations required before deriving L2 blocks. pub verifier_l1_confs: u64, + /// How far behind the synced tip safe and finalized are placed when EL sync completes. + pub el_sync_safe_offset: Duration, } impl RollupNodeBuilder { @@ -78,6 +81,7 @@ impl RollupNodeBuilder { dependency_set: None, safe_db: None, verifier_l1_confs: 0, + el_sync_safe_offset: DEFAULT_EL_SYNC_SAFE_OFFSET, } } @@ -100,6 +104,11 @@ impl RollupNodeBuilder { Self { verifier_l1_confs, ..self } } + /// Sets how far behind the synced tip safe and finalized are placed when EL sync completes. + pub fn with_el_sync_safe_offset(self, el_sync_safe_offset: Duration) -> Self { + Self { el_sync_safe_offset, ..self } + } + /// Sets the [`EngineConfig`] on the [`RollupNodeBuilder`]. pub fn with_engine_config(self, engine_config: EngineConfig) -> Self { Self { engine_config, ..self } @@ -158,6 +167,7 @@ impl RollupNodeBuilder { dependency_set: self.dependency_set, safe_db: self.safe_db, verifier_l1_confs: self.verifier_l1_confs, + el_sync_safe_offset: self.el_sync_safe_offset, } } } diff --git a/rust/kona/crates/node/service/src/service/node/rollup.rs b/rust/kona/crates/node/service/src/service/node/rollup.rs index 10e926c33ed..012f046c698 100644 --- a/rust/kona/crates/node/service/src/service/node/rollup.rs +++ b/rust/kona/crates/node/service/src/service/node/rollup.rs @@ -115,6 +115,8 @@ pub struct RollupNode { pub(crate) safe_db: Option>, /// L1 confirmation depth for online derivation, independent of sequencing. pub(crate) verifier_l1_confs: u64, + /// How far behind the synced tip safe and finalized are placed when EL sync completes. + pub(crate) el_sync_safe_offset: Duration, } /// A RollupNode-level derivation actor wrapper. @@ -242,7 +244,8 @@ impl RollupNode { // Share engine state with RPC without routing reads through the actor. let engine_state = EngineState::default(); let (engine_state_tx, engine_state_rx) = watch::channel(engine_state); - let engine = Engine::new(engine_state, engine_state_tx); + let engine = Engine::new(engine_state, engine_state_tx) + .with_el_sync_safe_offset(self.el_sync_safe_offset); let engine_client = Arc::new( self.engine_config.clone().build_engine_client(self.l1_config.provider.clone()), From 154c5104b5f2d6f95b7c6c3dfa81fcd717cbd636 Mon Sep 17 00:00:00 2001 From: Josh Klopfenstein Date: Tue, 3 Nov 2026 09:36:24 -0800 Subject: [PATCH 2/2] op-devstack: pass the EL-sync safe offset to kona-node kona-node now supports op-node's --syncmode.offset-el-safe, so devstack passes OffsetELSafe to it instead of rejecting the option. Like op-node, the offset applies only to a node configured for EL sync. kona-node has no CL-sync mode, so any other node keeps its 12h default, which places safe and finalized at genesis on a young devnet instead of marking unsafe blocks final. A negative offset is rejected, as op-node does. Co-Authored-By: Claude Opus 5.5 --- op-devstack/sysgo/l2_cl_kona_config.go | 14 +++++++++ op-devstack/sysgo/l2_cl_kona_config_test.go | 34 +++++++++++++++++++-- op-devstack/sysgo/singlechain_build_test.go | 3 +- 3 files changed, 47 insertions(+), 4 deletions(-) diff --git a/op-devstack/sysgo/l2_cl_kona_config.go b/op-devstack/sysgo/l2_cl_kona_config.go index ecf1f1a54a1..2be8496507b 100644 --- a/op-devstack/sysgo/l2_cl_kona_config.go +++ b/op-devstack/sysgo/l2_cl_kona_config.go @@ -48,6 +48,7 @@ func resolveKonaL2CLConfig(t devtest.T, key string, chainID eth.ChainID, isSeque unsupported.VerifierSyncMode = baseCfg.VerifierSyncMode unsupported.SafeDBPath = "" unsupported.VerifierL1Confs = 0 + unsupported.OffsetELSafe = 0 unsupported.NoDiscovery = baseCfg.NoDiscovery unsupported.FollowSource = "" if isSequencer { @@ -57,6 +58,7 @@ func resolveKonaL2CLConfig(t devtest.T, key string, chainID eth.ChainID, isSeque unsupported.ConductorRPCTimeout = 0 t.Require().Equal(baseCfg, unsupported, "unsupported L2CL option for kona-node") + t.Require().GreaterOrEqual(cfg.OffsetELSafe, time.Duration(0), "EL-sync safe offset must not be negative") if cfg.ConductorRPC != "" { t.Require().Positive(cfg.ConductorRPCTimeout, "conductor RPC timeout must be positive") t.Require().Zero(cfg.ConductorRPCTimeout%time.Second, "Kona conductor RPC timeout must use whole seconds") @@ -69,6 +71,18 @@ func konaL2CLEnv(cfg *L2CLConfig, sequencerStopped bool) []string { fmt.Sprintf("KONA_NODE_P2P_NO_DISCOVERY=%t", cfg.NoDiscovery), fmt.Sprintf("KONA_NODE_VERIFIER_L1_CONFS=%d", cfg.VerifierL1Confs), } + // kona-node has no CL-sync mode: it completes EL sync whenever its execution layer has no + // finality yet. Like op-node, apply the offset only to a node configured for EL sync. Any + // other node keeps kona-node's 12h default, which on a young devnet places safe and + // finalized at genesis instead of marking unsafe blocks final. + syncMode := cfg.VerifierSyncMode + if cfg.IsSequencer { + syncMode = cfg.SequencerSyncMode + } + if syncMode == nodeSync.ELSync { + extraEnv = append(extraEnv, + fmt.Sprintf("KONA_NODE_SYNCMODE_OFFSET_EL_SAFE=%dms", cfg.OffsetELSafe.Milliseconds())) + } if cfg.SafeDBPath != "" { extraEnv = append(extraEnv, "KONA_NODE_SAFEDB_PATH="+cfg.SafeDBPath) } diff --git a/op-devstack/sysgo/l2_cl_kona_config_test.go b/op-devstack/sysgo/l2_cl_kona_config_test.go index d70dc2b7690..696f22cb8a0 100644 --- a/op-devstack/sysgo/l2_cl_kona_config_test.go +++ b/op-devstack/sysgo/l2_cl_kona_config_test.go @@ -94,7 +94,12 @@ func TestKonaL2CLEnvAcceptsSyncModeCompatibilityInputs(t *testing.T) { })} // Neither compatibility mode emits a flag pretending to select a // native mode: Kona always drives EL sync through Engine API responses. - require.Equal(t, []string{"KONA_NODE_P2P_NO_DISCOVERY=true", "KONA_NODE_VERIFIER_L1_CONFS=0"}, + // EL sync only adds its safe offset, as it does for op-node. + want := []string{"KONA_NODE_P2P_NO_DISCOVERY=true", "KONA_NODE_VERIFIER_L1_CONFS=0"} + if mode == nodeSync.ELSync { + want = append(want, "KONA_NODE_SYNCMODE_OFFSET_EL_SAFE=0ms") + } + require.Equal(t, want, konaL2CLEnv(resolveKonaL2CLConfig(devtest.SerialT(t), "node", eth.ChainIDFromUInt64(901), isSequencer, "", opts), false)) }) } @@ -136,7 +141,7 @@ func TestKonaL2CLConfigRejectsUnsupportedOptions(t *testing.T) { apply func(*L2CLConfig) message string }{ - {"safe offset", true, func(cfg *L2CLConfig) { cfg.OffsetELSafe = time.Second }, "unsupported L2CL option"}, + {"negative safe offset", true, func(cfg *L2CLConfig) { cfg.OffsetELSafe = -time.Second }, "must not be negative"}, {"role override", true, func(cfg *L2CLConfig) { cfg.IsSequencer = false }, "unsupported L2CL option"}, {"sequencer sync", true, func(cfg *L2CLConfig) { cfg.SequencerSyncMode = nodeSync.Mode(99) }, "unknown effective sync mode"}, {"verifier sync", false, func(cfg *L2CLConfig) { cfg.VerifierSyncMode = nodeSync.Mode(99) }, "unknown effective sync mode"}, @@ -216,3 +221,28 @@ func TestKonaL2CLEnvVerifierL1Confs(t *testing.T) { } } } + +func TestKonaL2CLEnvOffsetELSafe(t *testing.T) { + t.Setenv("KONA_NODE_P2P_NO_DISCOVERY", "true") + for _, isSequencer := range []bool{false, true} { + for _, mode := range nodeSync.Modes { + for offset, want := range map[time.Duration]string{0: "0ms", 90 * time.Second: "90000ms", 1500 * time.Millisecond: "1500ms"} { + t.Run(fmt.Sprintf("sequencer=%t/mode=%s/offset=%s", isSequencer, mode, offset), func(t *testing.T) { + opts := []L2CLOption{L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { + cfg.SequencerSyncMode, cfg.VerifierSyncMode = mode, mode + cfg.OffsetELSafe = offset + })} + env := konaL2CLEnv(resolveKonaL2CLConfig(devtest.SerialT(t), "node", eth.ChainIDFromUInt64(901), isSequencer, "", opts), false) + if mode == nodeSync.ELSync { + require.Contains(t, env, "KONA_NODE_SYNCMODE_OFFSET_EL_SAFE="+want) + } else { + // Like op-node, the offset applies only to EL sync. + for _, entry := range env { + require.NotContains(t, entry, "KONA_NODE_SYNCMODE_OFFSET_EL_SAFE") + } + } + }) + } + } + } +} diff --git a/op-devstack/sysgo/singlechain_build_test.go b/op-devstack/sysgo/singlechain_build_test.go index e69392ec74d..e064d6a4b1f 100644 --- a/op-devstack/sysgo/singlechain_build_test.go +++ b/op-devstack/sysgo/singlechain_build_test.go @@ -3,7 +3,6 @@ package sysgo import ( "fmt" "testing" - "time" "github.com/stretchr/testify/require" @@ -20,7 +19,7 @@ func TestKonaOptionsRejectedBeforeStartup(t *testing.T) { dt := &rejectedKonaOptionTest{T: devtest.SerialT(t)} network := &L2Network{chainID: eth.ChainIDFromUInt64(901)} opts := []L2CLOption{L2CLOptionFn(func(_ devtest.T, _ ComponentTarget, cfg *L2CLConfig) { - cfg.OffsetELSafe = time.Second + cfg.IsSequencer = false })} // Nil startup dependencies ensure validation runs before starting any process or RPC. require.PanicsWithValue(t, "Kona option rejected", func() {