Skip to content

kona-engine,kona-node-service: import delegated local-safe and cross-safe heads separately - #24005

Open
einar-oplabs wants to merge 1 commit into
developfrom
einar/23911-delegated-cross-safe
Open

einar-oplabs wants to merge 1 commit into
developfrom
einar/23911-delegated-cross-safe

Conversation

@einar-oplabs

@einar-oplabs einar-oplabs commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Why

Under interop op-node imports a delegate's local-safe and cross-safe heads separately; kona-node copies the delegated safe head into both, so its forkchoice safe hash can run ahead of cross-chain verification.

What

  • Kona-node follows local-safe for the EL lookup, EL sync and reorgs, and moves the safe label to cross-safe only when it advances; only the unsafe head and established finality count as chain proof.
  • A head that does not extend the unsafe chain reorgs directly, moving safe to cross-safe clamped to finalized, unless the EL holds the current safe label; while the EL has not applied the last forkchoice, safe only moves forward.
  • Before interop both heads are one block, so non-interop chains see no change; the kona-node docs and --l2-follow-source help describe the labels.

Breakdown

Added Removed Net
Implementation 590 264 326
Tests 914 258 656
Docs 21 1 20

Closes

Part of ethereum-optimism/protocol-team#545. Stack, in merge order: #23900 → #23899 → #23908 → #23947 → #24004 → #24005 → #24007 → #24065.

  1. Closes: kona-node: document or resolve the interop local-safe and cross-safe delegated parity gap #23911

AI Reviews

  • 2026-11-10T14:13:49Z f8b9000 Fable 5.1 xhigh
  • 2026-11-11T13:19:53Z 9ba3492 Fable 5.1 xhigh
  • 2026-11-11T14:27:58Z be16fdc Fable 5.1 xhigh
  • 2026-11-11T16:34:22Z 3c2d3be Fable 5.1 xhigh

BREAKING CHANGE: ConsolidateInput::BlockInfo is replaced by Delegated(Box<DelegatedSafeHeads>), built with DelegatedSafeHeads::try_new, which returns InconsistentSafeHeadsError; the From<L2BlockInfo> conversions are removed.

🤖 Generated with Claude Code

@einar-oplabs einar-oplabs self-assigned this Nov 9, 2026
@einar-oplabs
einar-oplabs force-pushed the einar/23911-delegated-cross-safe branch from 60e90ee to a3be2c0 Compare November 9, 2026 18:36
@einar-oplabs
einar-oplabs force-pushed the einar/23911-delegated-cross-safe branch from a3be2c0 to f8b9000 Compare November 10, 2026 14:04
@einar-oplabs
einar-oplabs force-pushed the einar/23911-delegated-cross-safe branch from 3c2d3be to e2a4306 Compare November 11, 2026 17:17
@einar-oplabs
einar-oplabs marked this pull request as ready for review November 11, 2026 17:17
@einar-oplabs
einar-oplabs requested review from a team as code owners November 11, 2026 17:17

@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?

@joshklop joshklop left a comment

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: Review of 9ad3406b91. The core goal holds. On every delegated path, the forkchoice safe hash is the delegate's cross-safe head, the finalized head, or unchanged. It is never local-safe unless the two are the same block, and finalized ≤ safe after every transition. But the new advance-only rule breaks the repair #24004 promises, on non-interop chains too (first comment). There's also no property test asserting cross-safe ≤ local-safe ≤ unsafe and finalized ≤ safe after each transition, which is how that slipped through. My earlier comment about a separate task for delegated derivation still stands, since ConsolidateTask now switches on its input type in five places.

let safe = state.sync_state.safe_head();
let cross_safe = heads.safe_head();
// Below the safe label the cross-safe head can neither advance nor replace it.
if cross_safe.block_info.number < safe.block_info.number {

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: Bug: labels with unsafe below safe are no longer repaired. When unsafe < safe, execute skips the lagging branch. Every remaining path ends here or in unverified_advancing_safe_head, both of which return None when cross-safe < safe. Those paths are extend_onto_delegated_safe_heads for a head at or one above the unsafe head, consolidate for one below it, and the EL-sync path. reconcile_to_delegated_safe_heads then keeps the old safe label.

Example (non-interop): unsafe = 10 after a p2p reorg via insert/task.rs, and local-safe = safe = 15. The delegate reports 11 for both, a child of 10. Result: unsafe = local-safe = 11, safe still 15. apply_update has no clamp, so the FCU carries safe above head, the EL rejects it, and the engine resets. #24004 set all three labels to the delegated head here. The only repair test covers the unproven-extension case, which still reorgs.

let is_child_of_unsafe_head = local_safe.number == unsafe_head.number + 1 &&
local_safe.parent_hash == unsafe_head.hash;
let is_unproven_extension = !is_at_unsafe_height && !is_child_of_unsafe_head;
let would_lower_safe_label =

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: This assumes cross-safe below the safe label means the delegate is lagging. For one delegate, cross-safe going backwards mostly means a delegate reorg or an interop invalidation. Example: the delegate reorgs at 14 while kona's safe label is 15 on the old fork, and reports local = 23, cross = 12. The EL still holds old 15, so safe stays 15 while head moves to the new 23. Once the EL syncs, the FCU is invalid and kona resets. It matches op-node's soft-update path, so it's not a parity gap, but the case where the EL still holds the label through a real reorg is untested.

);

self.apply_delegated_safe_head(
let safe_head = Self::unverified_advancing_safe_head(state, heads);

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] Non-interop change: before this PR, this path set safe to the delegated head. Now a same-height delegated block with a different hash moves local-safe to the new block while safe stays on the old hash. That's narrow, but it contradicts "non-interop chains see no change".

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.

@joshklop
joshklop removed this pull request from stack #24203 November 19, 2026 02:00
@joshklop
joshklop added this pull request to stack #24271 November 19, 2026 02:00
Base automatically changed from einar/23910-delegated-stale-safe to develop November 19, 2026 09:26
@mintlify

mintlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
Optimism-Docs 🟢 Ready View Preview Nov 19, 2026, 11:30 PM

…safe heads separately

Under interop op-node imports a delegate's local-safe and cross-safe
heads separately; kona-node copies the delegated safe head into both, so
its forkchoice safe hash can run ahead of cross-chain verification.

Kona-node now follows local-safe for the EL lookup, EL sync and reorgs,
and moves the safe label to cross-safe only when it advances. Only the
unsafe head and established finality count as proof of the chain; other
heights are checked against an EL that applied the last forkchoice, and
only at or below the unsafe head. A head that does not extend the unsafe
chain reorgs directly, moving safe to cross-safe, clamped to finalized,
unless the EL holds the current safe label, which a catch-up then keeps;
only a conflict with finalized skips the update. While the EL has not
applied the last forkchoice, safe only moves forward and nothing reorgs.
Inconsistent heads are rejected, and the local-safe L1 origin must be
canonical. Before interop both heads are one block, so non-interop
chains see no change. A rejected update resets the engine; recovery is
#24065.

Closes #23911.

BREAKING CHANGE: `ConsolidateInput::BlockInfo` is replaced by
`Delegated(Box<DelegatedSafeHeads>)`, built with
`DelegatedSafeHeads::try_new`, which returns
`InconsistentSafeHeadsError`; the `From<L2BlockInfo>` conversions are
removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging - docs/public-docs — 536e4f67 Deployed Nov 19, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kona-node: document or resolve the interop local-safe and cross-safe delegated parity gap

2 participants