Skip to content

kona-engine,kona-node!: place safe and finalized behind the tip after EL sync - #23883

Open
joshklop wants to merge 2 commits into
joshklop/kona-delegate-current-l1-soft-failfrom
joshklop/kona-el-sync-completion
Open

joshklop wants to merge 2 commits into
joshklop/kona-delegate-current-l1-soft-failfrom
joshklop/kona-el-sync-completion

Conversation

@joshklop

@joshklop joshklop commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #23990 (base joshklop/kona-delegate-current-l1-soft-fail), so the diff shows only the EL-sync change. Stack, in merge order: #23990 → #23883 → #23859.

After execution-layer sync, kona-node set its safe and finalized heads by running an ordinary engine reset, so they came from the sync-start search: finalized stayed at genesis and safe was found by walking back from the tip. op-node handles the end of EL sync as its own step and 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 now does the same.

The EL-sync completion step ports the offset path of op-node's headsAfterELSync. Like op-node, it applies only when the execution layer has no finality beyond genesis; an execution layer that already has finality is a restart, and the regular search runs. It keeps the execution layer's own safe label when that is closer to the tip. The new --syncmode.offset-el-safe flag (KONA_NODE_SYNCMODE_OFFSET_EL_SAFE) sets the offset. If the execution layer has pruned the block at the offset, the node stops with an error that names the flag.

devstack now passes OffsetELSafe to kona-node instead of rejecting it, but only for a node configured for EL sync, as op-node applies it. kona-node has no CL-sync mode, so a node configured for CL sync keeps the 12h default. On a young devnet that places safe and finalized at genesis; passing devstack's zero offset instead would mark unsafe blocks final.

Two gaps remain:

Closes https://github.com/ethereum-optimism/protocol-team/issues/590

#23828 is not closed yet. TestELSyncSafeRetractedByOffset is skipped on op-reth on develop, and #23827 makes it wipe the verifier's EL so that it really EL-syncs. With #23827 applied locally, kona-node set safe to 13 with unsafe at 18, which is the 10s offset at 2s blocks, the same as op-node. The test still failed on kona-node: it waits for local-safe to advance by one after the verifier restarts, and kona-node had already finished EL sync before that wait began, with the batcher stopped. The test needs to stop depending on that timing before #23827 can run it on kona-node.

Reviewed with the rust-code-reviewer and go-code-reviewer agents. Two suggestions were declined:

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 (with_el_sync_safe_offset), defaulting to DEFAULT_EL_SYNC_SAFE_OFFSET. Exhaustive SyncStartError matches must handle ElSyncOffsetBlockUnavailable.

🤖 Generated with Claude Code

teddyknox
teddyknox previously approved these changes Nov 13, 2026

@teddyknox teddyknox 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.

I found no blocking bug in this PR. This PR does stop a freshly EL-synced verifier from walking back to genesis. But one case remains: a node whose first reset runs before EL sync finishes, which is any sequencer, including a fresh standby. That node still ends EL sync with the safe and finalized heads at genesis and the unsafe head at the tip. The follow-up's previous-safe rule would make its next reset walk every L2 block back to genesis. So the follow-up still needs op-node's RecoverMinSeqWindows exception, or this gap closed first.

The EL-sync completion is consumed by any VALID forkchoice update, not only the one that ends EL sync (actors/engine/actor.rs:132, synchronize/helper.rs:74-76). el_sync_finished is set by the first forkchoice update the EL answers VALID. A sequencer's initial reset sends one against the EL's current labels, and an empty EL answers VALID at genesis. So attempt_reset marks EL sync complete before any EL sync has happened, and reset_after_el_sync never runs. The EL then syncs to the tip through unsafe payloads, with safe and finalized still at genesis. Derivation starts from genesis, as it does on develop. That is the sequencer gap the description names. But the claim that EL-sync completion "can't walk back to genesis" holds only for verifiers. Once the planned previous-safe rule lands, the next reset on such a node runs find_starting_forkchoice with the safe head at genesis, and the cap walks the whole chain back one RPC per block. op-node keeps RecoverMinSeqWindows in FindL2Heads for exactly this state. A verifier that gets a reset during EL sync, for example after an invalid forkchoice state from an insert, takes the same path.

Smaller points:

  • Conflict with develop (task_queue/core.rs:149). #23900 changed Engine::reset to call synchronize_unconditionally, so that a restarted EL that lost its forkchoice still gets one. When you resolve the conflict, adopt_forkchoice should keep the unconditional call, so that the EL-sync path also resends.
  • A pruned offset block stops the node (sync/el_sync.rs:43). op-node returns a temporary error for a missing offset block and retries. Here ElSyncOffsetBlockUnavailable is permanent. Stopping with a message that names the flag seems better than retrying forever, but it is a divergence from op-node worth a line in the description.
  • Nit: --syncmode.offset-el-safe is parsed with humantime (commands/node/command.rs:138). That accepts 12h and 90s, but not Go's 1.5h. So an operator copying an op-node value can hit a parse error.
  • Nit: the flag doc says the offset applies "on any start where the execution layer has no finalized block beyond genesis". Given the sequencer gap, it applies only when EL sync finishes before the first reset.

I checked out the head (f834481) and ran all 388 tests in kona-engine and kona-node-service; they pass. I compared find_el_sync_forkchoice and offset_block_number with op-node's headsAfterELSync and OffsetBlockNum, and they match. That covers the ceiling division, the clamp at genesis, keeping a closer safe label, and taking the restart path when the EL already has finality.

@joshklop
joshklop force-pushed the joshklop/kona-el-sync-completion branch from f834481 to e802613 Compare November 19, 2026 23:31
@joshklop joshklop self-assigned this Nov 21, 2026
joshklop and others added 2 commits November 21, 2026 15:09
… 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 #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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
@joshklop
joshklop force-pushed the joshklop/kona-el-sync-completion branch from e802613 to 154c510 Compare November 21, 2026 23:13
@joshklop
joshklop requested a review from a team as a code owner November 21, 2026 23:13
@joshklop
joshklop changed the base branch from develop to joshklop/kona-delegate-current-l1-soft-fail November 21, 2026 23:13

This branch has not been deployed

No deployments
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.

2 participants