Skip to content

kona-node: record each safe head at one floor-corrected L1 block - #23652

Closed
teddyknox wants to merge 1 commit into
claude/happy-payne-c7b612from
claude/kona-safedb-floor
Closed

teddyknox wants to merge 1 commit into
claude/happy-payne-c7b612from
claude/kona-safedb-floor

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.

kona-node's safe head database and #23634's in-memory safe-head history now record each safe head at the same L1 block. That fixes database answers that were too low after a reset.

The bug. After a reset, derivation replays L1 from a channel timeout before the safe head's L1 origin. The replay can produce the next block while reading an L1 block below the one its parent was recorded at. Pre-Holocene, for example, that happens when the next block's batch was included before its parent's and buffered. A block cannot become safe before its parent. Yet the database recorded it at the lower block, out of the ascending order safe_head_updated requires. So safe_head_at_l1 for that lower block returned a safe head whose parent was not yet safe there (invariant I6 in docs/ai/safedb-review.md). This predates #23634, since every reset replays. #23634's history guarded against it with a floor.

The fix. Both records now take one L1 block: the derivation source, raised to the L1 block the parent was recorded at. SafeHeadHistory::record works it out and returns it, and the database writes what it returns. The history used to skip such a block; now it records it at the raised block too.

How exact the raised block is.

  • Before Holocene, the first pass buffers the early batch and derives the block right after its parent, at the parent's L1 block. So the raised block is exactly where the block became safe.
  • After Holocene, the first pass drops that batch as a future batch, and takes the block from a later batch. A node that reset then records the block lower than a node that never reset. It is still never lower than the parent, whereas the raw source can be. op-node records the raw source, so the two clients can now give different answers after a reset. I'd like the protocol owners to decide what the database should answer in this case.

Effect on operators. With the safe head database enabled, its entries stay in ascending L1 order across resets, and a block is never answered for an L1 height where its parent was not yet safe. kona's database is not served over RPC yet, so no query consumer sees the change today.

Not changed

  • A floor known only as a bound. This happens after a reset or EL sync to a head the history has not recorded. The history still skips safe heads below the bound, and the database still records the derivation source, as before. Raising them needs a block hash the node does not have.
  • The restart gap in kona-node: keep the safe head across L1 reorgs that leave its L1 data canonical #23634. A restarted node's history starts empty, so reorg protection resumes only once derivation passes the end of the resume head's sequencing window. I tried seeding the history from the database's tip after truncation, but dropped it. During the bounded phase above, the database can hold a too-low entry. A restart in that phase would turn it into a reorg-keep candidate, and the engine could keep a safe head whose parent's L1 data was reorged out. Closing the gap soundly needs the database to record only once the floor is known. That delays its first entries by up to a sequencing window after it starts empty, which is a semantics change for the database's owners.

Review. A review following safedb-reviewer (docs/ai/safedb-review.md) found the seeding issue above. That led to dropping the seeding and to the Holocene wording. It found no issue with I1 to I3, nor with I4 once the seeding was gone. The tests fail if the database writes the raw source again, or if the history goes back to skipping.

🤖 Generated with Claude Code

After a reset the pipeline replays from before the safe head's L1 origin
and can produce the next block from an L1 block below the one its parent
was recorded at. The in-memory SafeHeadHistory skipped such a block; the
safe head database recorded it there, out of ascending L1 order, so it
answered that block for L1 heights where its parent was not yet safe.

The history now raises such a block to its parent's L1 block and returns
that block, which the database records too, so the two records agree.

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

Copy link
Copy Markdown
Contributor Author

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

@teddyknox teddyknox closed this Oct 26, 2026
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