Skip to content

kona-node: share the unsafe-chain walk and check L1 origins by number - #23653

Closed
teddyknox wants to merge 1 commit into
claude/happy-payne-c7b612from
claude/kona-unsafe-walk
Closed

teddyknox wants to merge 1 commit into
claude/happy-payne-c7b612from
claude/kona-unsafe-walk

Conversation

@teddyknox

Copy link
Copy Markdown
Contributor

Stacked on #23634; review that first. This PR targets its branch, and GitHub retargets it to develop when #23634 merges. It is independent of #23652.

kona-node's cold-start reset no longer keeps an unsafe head built on a reorged-out L1 block. find_starting_forkchoice kept the unsafe head whenever get_l1_block(origin.hash) returned a block. That proves only that the block exists. L1 nodes keep serving a block by hash after a reorg replaces it at the same height. So an unsafe head built on a replaced L1 block survived a cold start, even though it could never become safe. It stayed until derivation replaced it, and on a sequencer it was built on further.

The cold start and #23634's L1-reorg reset now share one walk, find_canonical_unsafe_head. It checks each L1 origin by number, so an origin counts as canonical only if the L1 node has that block at that height. It checks a replaced origin once, and fetches only the blocks built on replaced origins. It also never walks past a floor:

The chain just above the floor must link to it by parent hash. If it doesn't, the walk fails with the new SyncStartError::UnsafeChainMismatch. An unsafe head below the floor fails with the new UnsafeHeadBelowFloor, which names both heights. On a cold start both are fatal, like the existing BlockNotFound. On the reorg path all three fall back to the full reset, as before.

Behaviour change on cold start

Before After op-node FindL2Heads
Origin replaced at the same height kept walked back walked back
Origin the L1 node has not seen yet walked back walked back kept as plausible
Lowest unsafe head none, could pass finalized the finalized head the finalized head; a different block there is ReorgFinalizedErr

The middle row is unchanged in kona, and still differs from op-node. Walking back costs only unsafe blocks, which are fetched again. Keeping them would mean a sequencer could build on an L1 block its L1 node has not seen. Whether to match op-node is a separate decision.

Effect on operators

  • Restart after an L1 reorg: the unsafe head moves back to its last block with a canonical L1 origin, instead of staying on the replaced chain.
  • Unsafe chain that doesn't descend from the finalized head: this is an inconsistent execution client. The reset now fails with UnsafeChainMismatch, as op-node's does with ReorgFinalizedErr. Before, kona sent a forkchoice update the execution client rejected, and retried it forever.
  • Unsafe head below the finalized head: the reset already failed later, in the forkchoice update (FinalizedAheadOfUnsafe). It now fails before any L1 lookup, with UnsafeHeadBelowFloor.

Tests. The cold-start tests cover:

  • the unsafe head's L1 origin canonical, replaced at the same height, and not seen yet;
  • a walk that stops at the finalized head, and one whose chain does not lead there (asserted fatal);
  • an unsafe head equal to finalized, a different block at finalized's height, and one below it.

Under the old by-hash rule, the replaced-at-the-same-height case fails. The real-chain fixture moves to kona_engine::test_utils as TestChain. That lets the engine-actor recovery test give the cold start an unsafe head above finalized, so its L1-outage case still reaches L1. With the new floor, an unsafe head equal to finalized makes no L1 call.

Review. rust-code-reviewer ran on the change. It found the finalized floor matches op-node and breaks no cold start that worked before. Its findings are applied: a dedicated error for an unsafe head below finalized, tests for the failure modes, a TestChain fixture, named error fields, and a wider sequencing window in the recovery test, so it no longer depends on kona promoting unsafe blocks to safe. Dismissed: the genesis-fallback floor is not tested separately, because that code is unchanged and only picks the floor. The unused MismatchedFinalizedBlock variant stays, since removing it changes the crate's public API.

🤖 Generated with Claude Code

The cold-start reset kept an unsafe head whenever its L1 origin could be
fetched by hash. An L1 node serves a block by hash after a reorg replaces
it at the same height, so an unsafe head built on a replaced L1 block
survived a cold start. find_starting_forkchoice and the L1-reorg reset
now share one walk: it checks each origin by number, checks a replaced
origin once, and never walks past a floor, the finalized head on a cold
start and the kept safe head on an L1 reorg.

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

Copy link
Copy Markdown
Contributor Author

Folded into #23634 as commit f51ee1e, so it can be reviewed and merged with the change it builds on. Closing this one.

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.

1 participant