feat: add ledger cache layer for receipt store by jewei1997 · Pull Request #2788 · sei-protocol/sei-chain

jewei1997 · 2026-02-02T15:02:16Z

Summary

This PR introduces an in-memory cache layer on top of the pebbledb receipt store backend, improving GetReceipt performance for recently accessed receipts.

Add cachedReceiptStore wrapper that caches receipts in rotating chunks
Simplify FilterLogs API: change from per-block signature to range-based (fromBlock, toBlock, crit)
Pebble backend's FilterLogs returns ErrRangeQueryNotSupported, signaling callers to fetch receipts individually
Update evmrpc/filter.go with fallback logic for backends that don't support range queries
Simplify ReceiptStoreConfig by removing unused pebble options

The cache rotates every 500 blocks (configurable) and keeps 3 chunks, providing a sliding window of recent receipts for fast lookups.

Test plan

Receipt store unit tests pass
Cached receipt store tests verify cache hits
FilterLogs returns ErrRangeQueryNotSupported for pebble backend

github-actions · 2026-02-02T15:03:17Z

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

Build	Format	Lint	Breaking	Updated (UTC)
`✅ passed`	`✅ passed`	`✅ passed`	`✅ passed`	Feb 11, 2026, 5:16 PM

codecov · 2026-02-02T15:06:26Z

Codecov Report

❌ Patch coverage is 77.47036% with 57 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.09%. Comparing base (e31ab0c) to head (fbf9b69).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
evmrpc/filter.go	56.00%	25 Missing and 8 partials ⚠️
sei-db/ledger_db/receipt/receipt_cache.go	83.92%	6 Missing and 3 partials ⚠️
sei-db/ledger_db/receipt/cached_receipt_store.go	89.04%	4 Missing and 4 partials ⚠️
sei-db/ledger_db/receipt/receipt_store.go	86.84%	3 Missing and 2 partials ⚠️
evmrpc/tx.go	77.77%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2788      +/-   ##
==========================================
- Coverage   57.12%   57.09%   -0.03%     
==========================================
  Files        2088     2090       +2     
  Lines      171079   171169      +90     
==========================================
+ Hits        97726    97734       +8     
- Misses      64680    64735      +55     
- Partials     8673     8700      +27

Flag	Coverage Δ
sei-chain	`52.55% <77.47%> (-0.03%)`	⬇️
sei-cosmos	`48.12% <ø> (-0.01%)`	⬇️
sei-db	`68.72% <ø> (ø)`

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

Files with missing lines	Coverage Δ
sei-db/db_engine/pebbledb/mvcc/db.go	`64.14% <100.00%> (+0.06%)`	⬆️
evmrpc/tx.go	`84.53% <77.77%> (-0.33%)`	⬇️
sei-db/ledger_db/receipt/receipt_store.go	`69.59% <86.84%> (-14.64%)`	⬇️
sei-db/ledger_db/receipt/cached_receipt_store.go	`89.04% <89.04%> (ø)`
sei-db/ledger_db/receipt/receipt_cache.go	`83.92% <83.92%> (ø)`
evmrpc/filter.go	`68.63% <56.00%> (-1.57%)`	⬇️

... and 28 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.

yzang2019 · 2026-02-02T23:20:51Z

sei-db/ledger_db/receipt/cached_receipt_store.go

+}
+
+type cacheWarmupProvider interface {
+	warmupReceipts() []ReceiptRecord


Does warm up means we will load some receipts into cache during initialization?

yes it is used for parquet to replay from WAL

yzang2019 · 2026-02-02T23:58:57Z

sei-db/ledger_db/receipt/cached_receipt_store.go

+		s.cacheNextRotate = blockNumber + s.cacheRotateInterval
+		return
+	}
+	for blockNumber >= s.cacheNextRotate {


Why not use blockNumber % interval == 0?

we could miss the rotation if the blockNumber % interval == 0 block does not have EVM receipts for some reason.

sei-db/ledger_db/receipt/cached_receipt_store.go

yzang2019 · 2026-02-03T00:24:59Z

sei-db/ledger_db/receipt/receipt_cache.go

+		receipt, found := blockReceipts[txHash]
+		if found {
+			// Callers (e.g. RPC response formatting) may normalize TransactionIndex in-place.
+			// Clone to avoid mutating the cached receipt and corrupting future lookups.


For perf reason, do we want to default to zero copy? As long as we make sure the codebase doesn't modify the receipt after calling get, we should be able to enable zeroCopy

I think there are other places we do modify the receipt actually for example:

there are multiple mutations in evmrpc/tx.go: Lines 154-165 (for failed txs that used 0 gas): receipt.From = from.Hex() receipt.To = etx.To().Hex() receipt.ContractAddress = "" receipt.TxType = uint32(etx.Type()) receipt.Status = uint32(ethtypes.ReceiptStatusFailed) receipt.GasUsed = 0 Line 456 (tx index normalization): receipt.TransactionIndex = uint32(evmTxIndex)

Hmm that's bad, is this the only place we modify receipts? Can we actually fix those places where we modify receipts directly and make that a cloned copy before we modify?

fixed. moved the clone receipt functionality out of ledger_db and to the modification locations

yzang2019

Overall LGTM

sei-db/ledger_db/receipt/receipt_log_filters.go

evmrpc/filter.go

sei-db/ledger_db/receipt/receipt_log_filters.go

evmrpc/filter_test.go

evmrpc/filter.go

sei-db/ledger_db/receipt/receipt_cache.go

sei-db/ledger_db/receipt/cached_receipt_store.go

## Summary This PR adds a parquet-based receipt storage backend with DuckDB for efficient range queries on logs, enabling fast `eth_getLogs` queries across block ranges. - Add parquet backend option (`Backend: "parquet"` in config) - Parquet files rotate every 500 blocks - DuckDB queries across closed parquet files for efficient log filtering - WAL for crash recovery of in-progress parquet files - Pruning of old parquet files based on `KeepRecent` config - Build tag support: use `-tags duckdb` to enable parquet backend The parquet backend supports the new `FilterLogs` range query API introduced in #2788, enabling efficient cross-block log queries without falling back to per-receipt fetching. ## Dependencies - Depends on #2788 (ledger cache layer) ## Test plan - Receipt store unit tests pass (without duckdb tag) - Parquet store tests pass with `-tags duckdb` - Integration testing with full node using parquet backend

## Summary This PR introduces an in-memory cache layer on top of the pebbledb receipt store backend, improving `GetReceipt` performance for recently accessed receipts. - Add `cachedReceiptStore` wrapper that caches receipts in rotating chunks - Simplify `FilterLogs` API: change from per-block signature to range-based `(fromBlock, toBlock, crit)` - Pebble backend's `FilterLogs` returns `ErrRangeQueryNotSupported`, signaling callers to fetch receipts individually - Update `evmrpc/filter.go` with fallback logic for backends that don't support range queries - Simplify `ReceiptStoreConfig` by removing unused pebble options The cache rotates every 500 blocks (configurable) and keeps 3 chunks, providing a sliding window of recent receipts for fast lookups. ## Test plan - [x] Receipt store unit tests pass - [x] Cached receipt store tests verify cache hits - [x] FilterLogs returns `ErrRangeQueryNotSupported` for pebble backend

## Summary This PR adds a parquet-based receipt storage backend with DuckDB for efficient range queries on logs, enabling fast `eth_getLogs` queries across block ranges. - Add parquet backend option (`Backend: "parquet"` in config) - Parquet files rotate every 500 blocks - DuckDB queries across closed parquet files for efficient log filtering - WAL for crash recovery of in-progress parquet files - Pruning of old parquet files based on `KeepRecent` config - Build tag support: use `-tags duckdb` to enable parquet backend The parquet backend supports the new `FilterLogs` range query API introduced in #2788, enabling efficient cross-block log queries without falling back to per-receipt fetching. ## Dependencies - Depends on #2788 (ledger cache layer) ## Test plan - Receipt store unit tests pass (without duckdb tag) - Parquet store tests pass with `-tags duckdb` - Integration testing with full node using parquet backend

This PR introduces an in-memory cache layer on top of the pebbledb receipt store backend, improving `GetReceipt` performance for recently accessed receipts. - Add `cachedReceiptStore` wrapper that caches receipts in rotating chunks - Simplify `FilterLogs` API: change from per-block signature to range-based `(fromBlock, toBlock, crit)` - Pebble backend's `FilterLogs` returns `ErrRangeQueryNotSupported`, signaling callers to fetch receipts individually - Update `evmrpc/filter.go` with fallback logic for backends that don't support range queries - Simplify `ReceiptStoreConfig` by removing unused pebble options The cache rotates every 500 blocks (configurable) and keeps 3 chunks, providing a sliding window of recent receipts for fast lookups. - [x] Receipt store unit tests pass - [x] Cached receipt store tests verify cache hits - [x] FilterLogs returns `ErrRangeQueryNotSupported` for pebble backend

This PR adds a parquet-based receipt storage backend with DuckDB for efficient range queries on logs, enabling fast `eth_getLogs` queries across block ranges. - Add parquet backend option (`Backend: "parquet"` in config) - Parquet files rotate every 500 blocks - DuckDB queries across closed parquet files for efficient log filtering - WAL for crash recovery of in-progress parquet files - Pruning of old parquet files based on `KeepRecent` config - Build tag support: use `-tags duckdb` to enable parquet backend The parquet backend supports the new `FilterLogs` range query API introduced in #2788, enabling efficient cross-block log queries without falling back to per-receipt fetching. - Depends on #2788 (ledger cache layer) - Receipt store unit tests pass (without duckdb tag) - Parquet store tests pass with `-tags duckdb` - Integration testing with full node using parquet backend

feat: add ledger cache layer for receipt store

de009ae

jewei1997 mentioned this pull request Feb 2, 2026

feat: add parquet receipt store with DuckDB range queries #2789

Open

3 tasks

jewei1997 added the non-app-hash-breaking label Feb 2, 2026

fix: update fakeReceiptStore.FilterLogs to new signature

982cf16

yzang2019 reviewed Feb 2, 2026

View reviewed changes

yzang2019 reviewed Feb 3, 2026

View reviewed changes

yzang2019 approved these changes Feb 3, 2026

View reviewed changes

jewei1997 added 4 commits February 3, 2026 09:58

rename flushBatch to fillCache

3da7c1c

Merge branch 'main' into ledger-cache-layer

3f64159

Merge branch 'main' into ledger-cache-layer

eb54490

fix test

6aa9c6b

blindchaser reviewed Feb 9, 2026

View reviewed changes

sei-db/ledger_db/receipt/receipt_log_filters.go Outdated Show resolved Hide resolved

blindchaser reviewed Feb 9, 2026

View reviewed changes

evmrpc/filter.go Show resolved Hide resolved

blindchaser reviewed Feb 9, 2026

View reviewed changes

sei-db/ledger_db/receipt/receipt_log_filters.go Outdated Show resolved Hide resolved

blindchaser reviewed Feb 9, 2026

View reviewed changes

evmrpc/filter_test.go Outdated Show resolved Hide resolved

jewei1997 added 7 commits February 10, 2026 07:26

remove dead code

6a8e24a

Merge branch 'main' into ledger-cache-layer

6bb32d7

add back bloom filtering

3a53aab

Merge branch 'main' into ledger-cache-layer

62670ce

merge with main

b40e7b3

fix TestCollectLogsEvmTransactionIndex

4284c76

clone receipt at modification location

9622931

blindchaser reviewed Feb 10, 2026

View reviewed changes

evmrpc/filter.go Show resolved Hide resolved

blindchaser reviewed Feb 10, 2026

View reviewed changes

sei-db/ledger_db/receipt/receipt_cache.go Outdated Show resolved Hide resolved

blindchaser reviewed Feb 10, 2026

View reviewed changes

sei-db/ledger_db/receipt/cached_receipt_store.go Show resolved Hide resolved

remove dead code

6728d5a

blindchaser approved these changes Feb 10, 2026

View reviewed changes

jewei1997 added 2 commits February 10, 2026 14:06

remove dead code

1ae0028

Merge branch 'main' into ledger-cache-layer

fbf9b69

Kbhat1 approved these changes Feb 11, 2026

View reviewed changes

jewei1997 enabled auto-merge (squash) February 11, 2026 17:19

jewei1997 merged commit 7db2f0a into main Feb 11, 2026
40 checks passed

jewei1997 deleted the ledger-cache-layer branch February 11, 2026 17:31

jewei1997 mentioned this pull request Feb 11, 2026

feat: add parquet receipt store with DuckDB range queries #2861

Merged

Conversation

jewei1997 commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yzang2019 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jewei1997 commented Feb 2, 2026 •

edited

Loading

github-actions bot commented Feb 2, 2026 •

edited

Loading

codecov bot commented Feb 2, 2026 •

edited

Loading