ethereum-optimism / ethereum-optimism/optimism

Safedb Proofs Reqirements

Open
#20,593 1 comment 0 reactions 0 assignees View on GitHub
M-needs-triage
Dominant language
Go
Stars
6.5k
Forks
4k
Avg merge
2d 15h
Merged PRs (30d)
145

Description

There has been ongoing discussion about the use cases and guarantees of the safedb, and whether its behavior should be modified. To ensure we have an informed discussion, I'd like to align on the proof requirements for the safedb as they relate to this issue.

### What safedb actually is today

Safedb is sparse and second-class:

- It only records `L1 block -> L2 safe head` when the L2 safe head advances. It does not record every L1 block that was considered, and it does not record every intermediate L2 block in a batch.
- Snap/EL sync can create ranges that were never locally derived.
- If safedb is preserved across a skipped-derivation range without gap metadata, callers cannot tell valid provenance from stale data.

That last point has bitten proofs a couple times in the past. Everything else here flows from it.

### How it's used for Proofs

A root can be canonical and eventually safe and still be invalid for a specific game, if it was not derivable at that game's L1 scope. That distinction is what makes safedb load-bearing here. The answer it gives directly drives proof correctness, but the database itself was never designed to be load-bearing
Today's consumers:

- `op-challenger` calls `optimism_safeHeadAtL1Block` to cap honest output roots to blocks supported by L1 data at the game L1 head.
- `op-dispute-mon` calls both `optimism_outputAtBlock` and `optimism_safeHeadAtL1Block`. It can run without safedb, but in that mode it treats unavailable safe-head data optimistically and can mispredict outcomes.
- Interop / supernode also relies on the safedb for `superroot_atTimestamp`, which is consumed by op-challenger for super game interaction.

### What proofs needs

Correctness before availability. Roughly in priority order:

1. `safeHeadAtL1Block` should only answer from known-good, contiguous derivation history.
2. If coverage is missing, unknown, reset, or crosses an EL/snap-sync gap, the API should return a hard "unavailable / not found" error instead of returning stale data. Silent stale answers are the failure mode we cannot tolerate.
3. The node needs enough valid history to cover all live dispute games. About 21 days should suffice.
4. Coverage/health metadata should be exposed so operators and consumers can see:
- earliest L1 block covered,
- latest L1 block considered,
- whether any gaps exist,
- whether the node is safe for proof/challenger traffic.
5. `op-challenger` should treat missing or invalid safedb coverage as a hard dependency failure for games whose L1 scope falls inside the gap. Not a soft warning.
6. `op-dispute-mon` can keep degrading gracefully, but it should surface safedb unavailability and corruption clearly, because both affect forecast accuracy and incident detection.

### EL sync / backfill

Preserving safedb through an EL sync is unsafe for proof nodes unless the database can explicitly represent and reject gap ranges. I can think of three options that don't break correctness:

- Clear/invalidate safedb on EL sync that skips derivation - _we do this today_.
- Preserve safedb only with explicit gap tracking, so the API can refuse queries inside a gap.
- Targeted EL sync to a historical target, then derive forward normally so safedb is populated from that target onward.

@sebastianst suggested a reasonable compromise:

1. EL sync only up to a target far enough in the past, e.g. 21 days.
2. Switch to normal derivation from that target to tip.
3. Mark the node healthy for proof traffic only once safedb covers the required dispute horizon.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the named entry points `optimism_safeHeadAtL1Block`, `optimism_outputAtBlock`, and `superroot_atTimestamp`, along with their `op-challenger` and `op-dispute-mon` consumers. Done means the proof requirements are agreed for contiguous coverage, gaps, history, health metadata, and EL-sync behavior; this issue does not name implementation files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, databases, distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.