Skip to content
Open
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
20 changes: 20 additions & 0 deletions docs/public-docs/node-operators/kona-node/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,26 @@ The RPC server starts once. If it stops unexpectedly, the node shuts down with a
`kona-node` does not run a supervisor RPC server, so there is no `--supervisor.*`
flag group. `--interop.dependency-set` is the node's only interop flag.

## Derivation Delegation Arguments

| Flag | Env | Description | Default |
|------|-----|-------------|---------|
| `--l2-follow-source <URL>` (alias `--l2.follow.source`) | `KONA_NODE_L2_FOLLOW_SOURCE` | RPC URL of an OP Stack consensus client exposing `optimism_syncStatus`. When set, `kona-node` derives nothing itself and follows that client's safe and finalized heads instead. Cannot be combined with `--safedb.path`. | - |

Like op-node's follow-source mode, `kona-node` imports the source's local-safe and cross-safe
heads separately. The local-safe head is the block the execution client must have, or sync to,
and becomes the local-safe label; the cross-safe head becomes the safe label that forkchoice
updates carry, and finalization never goes above it. The safe label moves back to a lower
cross-safe head only when the source's chain has diverged from the node's, or when the unsafe head
moves to a source block whose ancestry the node cannot check and the execution client does not hold
the current safe label, and never below the finalized head. While the execution client has not
applied kona-node's last forkchoice update, for example while it is still syncing, its canonical
blocks do not count as evidence: a delegated block it lacks, or one that differs from its block,
moves the safe label only forward.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude, for @joshklop: [nit] extend_onto_delegated_safe_heads contradicts this. With el_applied_last_forkchoice == false, is_safe_label_on_el_chain is always false. So an unproven extension, more than one block above the unsafe head, takes the reorg path and lowers safe to cross-safe. The commit message makes the same claim. That path also logs warn!("Reorging onto the delegate's chain") on every normal catch-up poll more than one block ahead.

Before interop both heads are the same block.
Under interop, `kona-node` verifies no cross-chain dependencies itself, so its safe label is only
as safe as the source's cross-safe head: the source must verify them.

## RPC Trust Flag

<Unreleased component="kona-node" />
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ pub struct ConsolidateTask {
pub client: Arc<EngineClient>,
/// The RollupConfig.
pub cfg: Arc<RollupConfig>,
/// The input for consolidation (either attributes or block info).
/// The input for consolidation (either derived attributes or delegated safe heads).
pub input: ConsolidateInput,
/// Where to hand the decoded block once the engine has canonicalized it.
pub block_sink: Arc<dyn ImportedBlockSink>,
Expand Down
3 changes: 3 additions & 0 deletions rust/kona/bin/node/src/flags/engine/providers.rs
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,9 @@ impl Default for L2ClientArgs {
#[derive(Clone, Debug, Default, clap::Args)]
pub struct DerivationDelegateArgs {
/// The source must be an OP Stack L2 CL RPC exposing `optimism_syncStatus`.
///
/// Its local-safe and cross-safe heads become this node's local-safe and safe labels. Under
/// interop this node verifies no cross-chain dependencies itself, so the source must.
#[arg(long, visible_alias = "l2.follow.source", env = "KONA_NODE_L2_FOLLOW_SOURCE")]
pub l2_follow_source: Option<Url>,
}
Expand Down
9 changes: 5 additions & 4 deletions rust/kona/crates/node/engine/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,11 @@ extern crate tracing;
mod task_queue;
pub use task_queue::{
BuildTask, BuildTaskError, CanonicalizeTask, CanonicalizeTaskError, ConsolidateInput,
ConsolidateTask, ConsolidateTaskError, Engine, EngineBuildError, EngineResetError, EngineTask,
EngineTaskError, EngineTaskErrorSeverity, EngineTaskErrors, ExecutableEngineTask,
FinalizeBlockId, FinalizeTask, FinalizeTaskError, InsertTask, InsertTaskError, SealTask,
SealTaskError, SynchronizeTaskError,
ConsolidateTask, ConsolidateTaskError, DelegatedSafeHeads, Engine, EngineBuildError,
EngineResetError, EngineTask, EngineTaskError, EngineTaskErrorSeverity, EngineTaskErrors,
ExecutableEngineTask, FinalizeBlockId, FinalizeTask, FinalizeTaskError,
InconsistentSafeHeadsError, InsertTask, InsertTaskError, SealTask, SealTaskError,
SynchronizeTaskError,
};

mod attributes;
Expand Down

@joshklop joshklop Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am becoming increasingly convinced that we just need to separate the engine tasks used for normal derivation and delegated derivation. We might need to create new tasks.

For better or worse, it seems that it is not easy to put delegated and "normal" derivation behind the same interface. Either we should design that interface, or create completely separate code paths for each.

Thoughts?

Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
//! The safe heads a derivation delegate reports.

use alloy_eips::BlockNumHash;
use kona_protocol::L2BlockInfo;
use thiserror::Error;

/// The safe heads a derivation delegate reports, imported as separate labels.
///
/// Before interop both are the same block. Under interop the cross-safe head can lag the
/// local-safe head while the delegate verifies cross-chain dependencies, and only the cross-safe
/// head may reach the execution layer as its safe block.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DelegatedSafeHeads {
local_safe_head: L2BlockInfo,
safe_head: L2BlockInfo,
}

/// Safe heads that no consistent delegate reports.
#[derive(Debug, Clone, Copy, Error, PartialEq, Eq)]
pub enum InconsistentSafeHeadsError {
/// The cross-safe head is ahead of the local-safe head.
#[error("Safe head {safe} is ahead of local safe head {local_safe}")]
SafeAheadOfLocalSafe {
/// The number of the delegate's local-safe head.
local_safe: u64,
/// The number of the delegate's cross-safe head.
safe: u64,
},
/// The cross-safe head is a different block at the local-safe head's height.
#[error("Safe head {safe:?} conflicts with local safe head {local_safe:?}")]
SafeConflictsWithLocalSafe {
/// The delegate's local-safe head.
local_safe: BlockNumHash,
/// The delegate's cross-safe head.
safe: BlockNumHash,
},
}

impl DelegatedSafeHeads {
/// Pairs the delegate's local-safe head, derived from L1 with cross-chain dependencies not
/// verified yet, with its cross-safe head, which must be at or below it on the same chain: not
/// ahead of it, and not a different block at its height.
pub fn try_new(
local_safe_head: L2BlockInfo,
safe_head: L2BlockInfo,
) -> Result<Self, InconsistentSafeHeadsError> {
let local_safe = local_safe_head.block_info.id();
let safe = safe_head.block_info.id();
if safe.number > local_safe.number {
return Err(InconsistentSafeHeadsError::SafeAheadOfLocalSafe {
local_safe: local_safe.number,
safe: safe.number,
});
}
if safe.number == local_safe.number && safe.hash != local_safe.hash {
return Err(InconsistentSafeHeadsError::SafeConflictsWithLocalSafe {
local_safe,
safe,
});
}
Ok(Self { local_safe_head, safe_head })
}

/// The delegate's local-safe head.
pub const fn local_safe_head(&self) -> L2BlockInfo {
self.local_safe_head
}

/// The delegate's cross-safe head.
pub const fn safe_head(&self) -> L2BlockInfo {
self.safe_head
}

/// The cross-safe head when it is above `current_safe_head`, and `None` otherwise: a
/// cross-safe head at or below the safe label leaves it where it is.
pub(crate) const fn advancing_safe_head(
&self,
current_safe_head: &L2BlockInfo,
) -> Option<L2BlockInfo> {
if self.safe_head.block_info.number > current_safe_head.block_info.number {
Some(self.safe_head)
} else {
None
}
}
}

#[cfg(test)]
mod tests {
use super::*;
use crate::test_utils::test_block_info;
use alloy_primitives::B256;
use kona_protocol::BlockInfo;
use rstest::rstest;

const LOCAL_SAFE_HEAD: L2BlockInfo = L2BlockInfo {
block_info: BlockInfo {
hash: B256::repeat_byte(0x10),
number: 10,
parent_hash: B256::ZERO,
timestamp: 0,
},
l1_origin: BlockNumHash { hash: B256::ZERO, number: 0 },
seq_num: 0,
};

/// A different block at the height of `block`.
fn conflicting_block(block: L2BlockInfo) -> L2BlockInfo {
L2BlockInfo {
block_info: BlockInfo { hash: !block.block_info.hash, ..block.block_info },
..block
}
}

#[rstest]
#[case::cross_safe_lags(test_block_info(8), true)]
#[case::same_block(LOCAL_SAFE_HEAD, true)]
#[case::conflicting_at_same_height(conflicting_block(LOCAL_SAFE_HEAD), false)]
#[case::cross_safe_ahead(test_block_info(11), false)]
fn try_new_rejects_cross_safe_off_the_local_safe_chain(
#[case] safe_head: L2BlockInfo,
#[case] accepted: bool,
) {
let heads = DelegatedSafeHeads::try_new(LOCAL_SAFE_HEAD, safe_head);

assert_eq!(heads.is_ok(), accepted, "got {heads:?}");
}

/// Only a cross-safe head strictly above the safe label advances it.
#[rstest]
#[case::above(8, true)]
#[case::same_height(7, false)]
#[case::below(6, false)]
fn advancing_safe_head_requires_a_higher_block(#[case] safe: u64, #[case] advances: bool) {
let heads =
DelegatedSafeHeads::try_new(test_block_info(10), test_block_info(safe)).unwrap();

assert_eq!(heads.advancing_safe_head(&test_block_info(7)).is_some(), advances);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,7 @@ 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.
/// Failed to fetch the execution layer's block at the height of a delegated safe head.
#[error("Failed to fetch the block at delegated safe head height {0}")]
FailedToFetchDelegatedSafeBlock(u64),
/// The unsafe L2 block is missing.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
//! Consolidation Task

mod delegated_safe_heads;
pub use delegated_safe_heads::{DelegatedSafeHeads, InconsistentSafeHeadsError};

mod error;
pub use error::ConsolidateTaskError;

Expand Down
Loading
Loading