block DB interface

[wen-coding]

Summary

Interface only — no implementation, no consumer rewiring yet. To share with the colleague implementing the backend so the contract is pinned before any code changes hands.

The data.Store interface captures what data.State needs from a durable backing store to replace the current DataWAL (separate file WALs for blocks and FullCommitQCs). Adds a by-hash block index that the WAL didn't have — needed for the /block_by_hash RPC path.

Surface

type Store interface {
    // Writes — two-phase (write, then Flush)
    WriteBlock(ctx, n GlobalBlockNumber, *types.Block) error
    WriteQC(ctx, *types.FullCommitQC) error           // QC carries its GlobalRange
    PruneBefore(ctx, n GlobalBlockNumber) error
    Flush(ctx) error

    // Reads
    ReadAll(ctx) (*Loaded, error)                     // startup replay
    ReadBlockByNumber(ctx, n)    (utils.Option[*types.Block], error)
    ReadBlockByHash(ctx, hash)   (utils.Option[*types.Block], error)
    ReadQCByBlockNumber(ctx, n)  (utils.Option[*types.FullCommitQC], error)  // QC covering block n

    // Lifecycle
    Close(ctx) error
}

Contract highlights (full docs in the file)

• Concurrency: all methods safe for concurrent use.
• Durability is two-phase: WriteBlock / WriteQC return without guaranteeing the record is on disk; Flush blocks until everything previously written is durable. Reasoning: synchronous fsync-per-Write at chain throughput is real disk bandwidth — at dozens of blocks/sec it crowds out useful I/O. The expected pattern is "drain queue → write batch → Flush once," not "Flush after every Write." Implementations write eagerly even without Flush; Flush is "wait until durable," not "start writing."
• What Store does NOT persist: AppHashes (recovered from app.Info().LastBlockAppHash + re-execution; data.State.inner.appProposals is in-memory only), and per-tx execution results / logs / events (those live on the receipt store per the Giga Transaction Query proposal). GlobalBlock.FinalAppState is extracted from qc.Proposal().App() — derivable from the persisted QC, no separate AppHash record needed.
• GlobalRange convention: half-open interval [GlobalRange.First(), GlobalRange.Next()). The QC covers GlobalBlockNumbers First, First+1, …, Next-1, and Next is the First of the next contiguous QC.
• QC contiguity: caller (data.State.runPersist) guarantees each QC's First equals the previous one's Next; implementations may but need not enforce.
• Idempotency: duplicate writes (same n + same hash for blocks, same GlobalRange.First for QCs) are silent no-ops.
• n on WriteBlock: required because *types.Block does NOT carry its GlobalBlockNumber — block.Header().BlockNumber() is the per-lane number (different typedef). The lane→global mapping lives in the QC's GlobalRange.
• No separate hash arg on WriteBlock: derivable via block.Header().Hash(); implementation indexes it automatically.
• Reads return utils.Option: "not yet written" / "pruned" surface as utils.None. Reads are non-blocking; wait semantics live above the interface in data.State.

What's not in this PR

• No implementation. mem implementation, persistent implementation, all follow-ups.
• No consumer rewiring. data.State.NewState / runPersist / runPruning still talk to DataWAL; that swap happens once an implementation exists.

Test plan

• go build ./sei-tendermint/internal/autobahn/data/... — clean
• gofmt -s -l — clean
• go vet — clean
• No tests intentionally — interface only, nothing to exercise yet.

🤖 Generated with Claude Code

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	May 19, 2026, 6:30 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.29%. Comparing base (823a78d) to head (f295435).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3445   +/-   ##
=======================================
  Coverage   59.29%   59.29%           
=======================================
  Files        2125     2125           
  Lines      175629   175629           
=======================================
  Hits       104144   104144           
  Misses      62404    62404           
  Partials     9081     9081           

Flag	Coverage Δ
sei-chain-pr	75.54% <ø> (?)
sei-db	70.41% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pompon0]

LGTM, couple of remarks:

• we will not be able to afford ReadAll in prod (perhaps it will still be useful in tests). Instead we will need a method to fetch the available range of blocks/commitqc [first,next).
• imo (weak preference) the type-aware layer should also be responsible for maintaining consistency between qcs and blocks.
• I think we shouldn't focus on optimizing db layout rn. Afaik there is a huge chance that from the evm pov we will be aggregating multiple lane blocks into single execution block (sth like, 1 evm block per 1 commit qc) in which case the evm queries will need to respond with the whole evm block. Still, this large evm block (as of today a single commit qc can sequence even 400 lane blocks) is not a reasonable unit of network traffic (400 lane blocks x 2000 txs/block x 1kB/tx ~ 0.8GB), so block syncing will operate on lane blocks (currently equivalent to global blocks) anyway.