docs(receipt): littidx receipt store README#3695
Conversation
PR SummaryLow Risk Overview The doc explains the LittDB bodies + Pebble tag index layout, how Reviewed by Cursor Bugbot for commit c11538c. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).
|
![seidroid[bot]](https://avatars.githubusercontent.com/in/2745135?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation-only PR adding a README for the littidx receipt store. The prose is clear and well-organized, but it describes the legacy-receipt migration as "governance-triggered," which contradicts the implementation (an automatic per-block backfill). No code changes, no test impact.
Findings: 0 blocking | 3 non-blocking | 1 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- Cursor's second-opinion review file (cursor-review.md) was empty — that pass produced no output.
- The PR description repeats the same inaccurate "legacy backfill is chain-level / gov-triggered" framing as the README; consider correcting it too so the summary matches actual behavior.
- 1 suggestion(s)/nit(s) flagged inline on specific lines.
| builds `littidx` forward from its sync height. Nothing to export/import. | ||
| - **Legacy receipts** (written before `littidx`, held in the EVM module's | ||
| in-state KV store) are drained into `littidx` by a **chain-level, | ||
| governance-triggered background migration**, not an operator action. Point |
There was a problem hiding this comment.
[suggestion] This describes legacy-receipt draining as a governance-triggered migration, but the implementation runs it automatically with no governance involvement: x/evm/keeper/abci.go:87 calls MigrateLegacyReceiptsBatch on every block where BlockHeight() % LegacyReceiptMigrationInterval == 0 (interval 10, batch size 100, both fixed constants in x/evm/keeper/receipt.go:22,25). Calling it "governance-triggered" is operationally misleading — a reader may wait for a governance action that never occurs. Suggest describing it as an automatic per-block background backfill (every N blocks, small fixed batches). (Also flagged by Codex.)
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-only, adds a new README for the littidx receipt store backend.
Extended reasoning...
Overview
The PR adds a single new file, sei-db/ledger_db/receipt/README.md, documenting the littidx EVM receipt store backend (architecture, durability, retention, configuration knobs, limits, and rollout). No source, config, build, or test files are touched.
Security risks
None. Pure documentation; no executable code paths, dependencies, or configuration defaults are modified.
Level of scrutiny
Low. Documentation-only changes carry no runtime risk. Content is descriptive prose about the existing littidx backend and consistent with the surrounding module (sei-db/ledger_db/receipt, sei-db/db_engine/litt, [receipt-store] app.toml section). Any minor inaccuracies could be corrected in a follow-up doc PR without operational consequence.
Other factors
The bug hunting system found no issues, and the cursor bot flagged this as low risk. No prior claude[bot] reviews on this PR to reconcile against.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3695 +/- ##
==========================================
- Coverage 59.30% 58.35% -0.95%
==========================================
Files 2273 2186 -87
Lines 188305 178509 -9796
==========================================
- Hits 111675 104176 -7499
+ Misses 66579 65083 -1496
+ Partials 10051 9250 -801
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Single doc covering the littidx receipt backend: high-level architecture (litt bodies + pebble tag index), durability/retention model, limits & trade-offs (auxiliary durability, no legacy fallback for getLogs ranges, cold-range latency), the receipt-store config knobs, and the rollout story (no operator data migration — config + state sync, gov-triggered legacy backfill). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kbhat1
force-pushed
the
docs/littidx-readme
branch
from
9b0a1d8 to
c11538c
Compare
There was a problem hiding this comment.
Docs-only PR adding a well-written README for the littidx receipt backend. Verified claims (config defaults, 5ms flush interval, point-lookup legacy fallback) match the code. One clarity gap in the rollout section could mislead operators doing an in-place backend switch.
Findings: 0 blocking | 4 non-blocking | 2 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- Cursor produced no second-opinion output (
cursor-review.mdis empty).REVIEW_GUIDELINES.mdis also empty, so no repo-specific standards were applied. - The doc pairs a strong 'Rollout — no migration, state sync only' framing with a standalone 'set
rs-backendand restart' bullet. Consider making the state-sync-only path explicit in that bullet so operators don't read it as an endorsed in-place switch for retained pre-switch ranges (see inline comment). - 2 suggestion(s)/nit(s) flagged inline on specific lines.
| (state) sync — the same posture as the SeiDB state store. Nothing to export, | ||
| import, or backfill by hand, and no downtime beyond the restart. | ||
|
|
||
| - **Enable it:** set `rs-backend = "littidx"` and restart. |
There was a problem hiding this comment.
[suggestion] Verified against the code: littidx builds forward only, and the point-lookup fallback (legacyReceiptFromKVStore, litt_receipt_store.go:492) reads the in-state legacy KV store (ctx.KVStore(storeKey)) — not the pebbledb receipt side store. So an in-place pebbledb → littidx switch on a node still retaining blocks whose receipts live only in the pebbledb side store leaves those receipts in neither store: eth_getTransactionReceipt point lookups miss (not just getLogs ranges), until those blocks age out of the retention window. The heading says 'state sync only', but this bare 'set rs-backend and restart' bullet reads as an endorsed in-place switch. Suggest either scoping this bullet to a fresh/state-synced node, or noting that an in-place switch over a retained pebbledb range has the same (plus point-lookup) unavailability as the getLogs legacy caveat above. (Raised by Codex.)
| - **Auxiliary durability only.** A crash can drop up to ~one block of the most | ||
| recent receipt *bodies*; those reads return not-found rather than erroring. | ||
| Fine for RPC data, not a consensus-grade guarantee. | ||
| - **`getLogs` has no legacy fallback for ranges.** Point lookups |
There was a problem hiding this comment.
[nit] This caveat says point lookups 'fall back to the legacy in-state KV store ... for pre-littidx receipts', which is accurate for pre-side-store receipts but not for receipts written into the pebbledb side store. Those are not reachable by the fallback. Worth a word here to disambiguate 'legacy' (in-state KV) from the alternate pebbledb side-store backend.
| log-filter-parallelism = 16 | ||
| prune-interval-seconds = 600 |
There was a problem hiding this comment.
We don't wanna expose these configs to the users yet, my suggestions is to remove these and use whatever the recommended default we set for them
2 participants
One clean doc for the
littidxreceipt backend, co-located atsei-db/ledger_db/receipt/README.md.Covers:
eth_getLogs; parallel per-block fan-out.getLogsranges have no legacy fallback (archive-node/migration caveat); cold-range latency.[receipt-store]knobs (rs-backend,log-filter-parallelism, etc.) and that KeepRecent derives frommin-retain-blocks.