flatkv iteration

[cody-littley]

Describe your changes and provide context

Adds the ability to iterate data in flatKV

Testing performed to validate your change

unit tests

[cursor]

PR Summary

Medium Risk
Touches state-store iteration, key translation, and new concurrency rules around pending writes and long-lived Pebble iterators; incorrect merge/skip logic could omit or mis-order keys, and coarse commit locking may affect read latency under load.

Overview
Adds FlatKV range iteration so callers can scan a module (or the full EVM store) in logical key order, with optional ascending/descending direction and [start, end) bounds that Domain() reports correctly.

Iterator stack: New map and domain iterators; mapping is renamed to transforming (with explicit valid so nil keys are allowed). NewMergingIterator now takes an ascending flag and supports descending merges. Pebble gains IterOptions.Reverse (First/Next vs Last/Prev).

FlatKV CommitStore: Implements Iterator(store, start, end, ascending) and moves RawGlobalIterator into store_iteration.go. EVM iteration merges multiple lanes (storage, code, nonce, codehash, legacy catch-all), each combining pending map writes with Pebble (pending wins), transforming physical keys/values to memIAVL-style logical keys and filtering tombstones. Non-EVM modules use the legacy DB lane only.

Concurrency: Adds sync.RWMutex around pending-write reads, iterator construction, ApplyChangeSets, and Commit so iterators are snapshots at build time and can be used concurrently with later commits (documented on the API). dbcache.Unwrap and pebbledb.TableIters support leak detection in tests.

Extensive unit/differential tests cover ranges, overlap, tombstones, domain bounds, and concurrent snapshot behavior.

^{Reviewed by Cursor Bugbot for commit 4f08135. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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 29, 2026, 7:09 PM

[codecov]

Codecov Report

❌ Patch coverage is 61.99575% with 179 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.47%. Comparing base (8567422) to head (4f08135).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
sei-db/state_db/sc/flatkv/store_iteration.go	57.74%	83 Missing and 48 partials ⚠️
sei-db/common/iterators/merging_iterator.go	22.58%	23 Missing and 1 partial ⚠️
sei-db/common/iterators/map_iterator.go	91.89%	3 Missing and 3 partials ⚠️
sei-db/db_engine/dbcache/unwrap.go	0.00%	6 Missing ⚠️
sei-db/db_engine/pebbledb/iterator.go	33.33%	2 Missing and 4 partials ⚠️
sei-db/db_engine/pebbledb/table_iters.go	0.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3523      +/-   ##
==========================================
- Coverage   59.03%   58.47%   -0.56%     
==========================================
  Files        2199     2153      -46     
  Lines      182207   177253    -4954     
==========================================
- Hits       107569   103657    -3912     
+ Misses      64975    64260     -715     
+ Partials     9663     9336     -327     

Flag	Coverage Δ
sei-chain-pr	91.60% <68.62%> (?)
sei-db	70.41% <ø> (ø)
sei-db-state-db	?
sei-db-state-db-pr	72.72% <58.80%> (?)

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

Files with missing lines	Coverage Δ
sei-db/common/iterators/domain_iterator.go	100.00% <100.00%> (ø)
sei-db/common/iterators/transforming_iterator.go	78.57% <100.00%> (ø)
sei-db/db_engine/types/types.go	100.00% <ø> (ø)
sei-db/state_db/sc/flatkv/snapshot.go	69.00% <ø> (ø)
sei-db/state_db/sc/flatkv/store.go	76.94% <ø> (ø)
sei-db/state_db/sc/flatkv/store_apply.go	91.74% <100.00%> (+0.08%)	⬆️
sei-db/state_db/sc/flatkv/store_read.go	59.01% <100.00%> (+4.53%)	⬆️
sei-db/state_db/sc/flatkv/store_write.go	78.22% <100.00%> (+0.17%)	⬆️
sei-db/common/iterators/map_iterator.go	91.89% <91.89%> (ø)
sei-db/db_engine/dbcache/unwrap.go	0.00% <0.00%> (ø)
... and 4 more

... and 56 files with indirect coverage changes

🚀 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.

[blindchaser]

buildLegacyDBLane, buildCodeLane, buildStorageLane, buildAccountNonceLane, and buildAccountCodehashLane are ~90% identical (serializer → NewMapIterator → pebble NewIter → NewMergingIterator(ascending, pebble, pending) → NewTransformingIterator).

how about abstract code to something like:

func buildLane[T vtype.VType](
    pending map[string]T, db seidbtypes.KeyValueDB,
    lower, upper []byte, ascending bool,
    serialize func(T) ([]byte, error),
    transform iterators.IteratorTransform,
) (dbm.Iterator, error)