Skip to content

kona-node,safedb,devex: serve a paginated safe-head history dump RPC #23584

Open

Description

@einar-oplabs

Part of ethereum-optimism/protocol-team#442 (long-term Kona improvements). Related to #23473; this RPC is not a completion requirement for the current SafeDB integration.

Why

The only way to inspect a safe head database today is to open its files, and both backends (pebble on op-node, rocksdb on kona-node) hold an exclusive lock, so the node has to be stopped or the volume snapshotted first. That is why safedb-scan (ethereum-optimism/protocol-team#407) and the restore runbook (ethereum-optimism/protocol-team#404) are stop-first procedures. An RPC that pages through the recorded history lets an operator extract or validate the record from a running node.

Scope

A paginated read over the recorded history, served from the node's own database handle:

  • debug_safeHeadHistory(fromL1: u64, limit: u32) -> { entries: [{ l1: BlockID, safeHead: BlockID }], nextL1: u64 | null }, entries in ascending L1 order starting at the first entry at or above fromL1. Paginated because a mainnet history grows by one entry per L1 block that advanced the safe head, so a single dump would be millions of rows.
  • A bounded limit, with the server clamping to a maximum such as 10,000.
  • The disabled-state error shape agreed in kona-node,safedb: add configuration, disabled-state errors, and documentation #23477 when no database is configured.
  • A SafeDb::entries_from(l1_block_num, limit) iteration method on the trait, implemented for the rocksdb backend and the disabled backend.
  • kona-node only. op-node is not changed; a live op-node still needs the stop-first procedure.

A plain debug_dumpSafeDb that streams the whole history is a client-side loop over this call, and belongs in a small CLI (for example in op-node's cmd or a kona-node subcommand) rather than in one RPC response.

Done

  • kona-node serves the paginated history and the page boundaries are exact (no duplicated or skipped entry across pages).
  • Unit tests cover an empty history, a page inside the history, the last page, fromL1 above the tip, and the disabled state.
  • A CLI or script walks the pages into the file format safedb-scan reads, so a live kona-node can be validated against a reference (which may be a stopped op-node snapshot) without stopping it.
  • Documented next to the other safedb RPCs.

Status — 2026-10-29

The current integration passed its 24-hour persistence soak and #23479 is closed. Final evidence. The scan used repeated existing optimism_safeHeadAtL1Block requests; it did not add or validate a paginated history-dump RPC. This issue remains open as deferred long-term work under ethereum-optimism/protocol-team#442; none of its implementation checkboxes are completed by the soak.

Activity

  1. self-assigned this
    on Oct 22, 2026
  2. changed the title [-]kona-node: serve a paginated safe head history dump RPC[/-] [+]kona-safedb: serve a paginated safe head history dump RPC[/+] on Oct 26, 2026
  3. changed the title [-]kona-safedb: serve a paginated safe head history dump RPC[/-] [+]kona-node,safedb: serve a paginated safe-head history dump RPC[/+] on Oct 26, 2026
  4. changed the title [-]kona-node,safedb: serve a paginated safe-head history dump RPC[/-] [+]kona-node,safedb,devex: serve a paginated safe-head history dump RPC[/+] on Oct 26, 2026
  5. removed their assignment
    on Nov 13, 2026
  6. einar-oplabs commented on Nov 13, 2026

    @einar-oplabs
    ContributorAuthor

    Unassigning.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions