Skip to content

kona-node,safedb: add configuration, disabled-state errors, and documentation #23477

Closed

Description

@einar-oplabs

Part of #23473.

Scope

  • A kona-node CLI flag and env var for the safedb path, disabled when unset, mirroring op-node's --safedb.path. Wire it through op-devstack/sysgo/l2_cl.go (SafeDBPath) so acceptance tests can enable it for kona-node.
  • Choose the disabled-state and not-found error shape deliberately. Two consumers sniff it today: op-service/sources/rollupclient.go coerces any error containing "not found" into safedb.ErrNotFound, and the kona-sp1 fetcher has matched on -32601 and "safedb" in the past. Document the choice in the crate.
  • Docs: kona-node flag reference, rpc/rollup.mdx for both RPCs, and the crate README.

Done

  • Flag and env var exist and are documented.
  • devstack can start kona-node with a safedb path.
  • RPC error mapping is implemented and unit-tested: missing records return -32000 / not found and map to safedb.ErrNotFound; disabled databases return -32000 / safe head database not enabled and remain distinct (kona-node,op-acceptance-tests: serve the safe head history and compare it with op-node #23590).
  • Document the disabled/not-found error contract in the crate README.
  • Add the implemented SafeDB RPCs and their error contract to the public RPC reference; rpc/rollup.mdx currently omits optimism_safeHeadAtL1Block.

Status evidence: #23590 merged the flag, configuration reference, RPC error handling, and mixed-runtime wiring. #23704 merged SafeDB option forwarding through normal Kona startup, with five configuration unit cases and successful Kona/op-node withdrawal runs. Public RPC reference and crate README completion were not found on develop.

Status — 2026-10-29

The 24-hour soak verified the merged build with KONA_NODE_SAFEDB_PATH=/admin/safedb, fsGroup 10001, and the retained PVC: final evidence. #23479 is closed after validation. This does not complete the unchecked crate README/public RPC-reference documentation; #23473 continues to track those documentation requirements.

Documentation progress — 2026-10-30

#23787 is ready for review, with Josh and Akos requested. The original documentation completion criteria remain unchecked until merge; this closed implementation ticket does not close the parent integration issue.

Activity

  1. self-assigned this
    on Oct 16, 2026
  2. changed the title [-]kona-node: safedb config flag, disabled-state error shape and docs[/-] [+]kona-node,safedb: add configuration, disabled-state errors, and documentation[/+] on Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions