Include receipt store earliest height in watermark bounds to prevent silent undercount on pruned blocks

[amir-deris]

Problem

There was a fix implemented in PR 3125 in order to make eth_getBlockTransactionCountByNumber == len(eth_getBlockByNumber.transactions) by using same filtering mechanism for evm transactions to consider availability of receipts. That fix raised the following concern:

This change makes GetBlockTransactionCountByNumber and GetBlockTransactionCountByHash results dependent on the receipt store due to the receipt query leading to inconsistencies in historical results.
Those functions do ensure that the block is available based on watermarks. However, the receipt store does not contribute to the earliest height in the watermark manager, only the latest. So even if EnsureBlockHeightAvailable returns that the block is available that does not guarantee all receipts for that height are available. This will occur in the cases when ReceiptStore's KeepRecent is less than the StateStore's KeepRecent and MinRetainBlocks. In such cases the returned transaction count may diverge from the true count due to pruned receipts.

Analysis

eth_getBlockTransactionCountByNumber and eth_getBlockTransactionCountByHash silently return an incorrect (lower) transaction count for historical blocks when the receipt store has been pruned further back than the block or state stores.

The watermark check in EnsureBlockHeightAvailable uses blockEarliest (derived from Tendermint) to gate requests, but the receipt store's earliest version never contributed to that bound. So a block could pass the availability check while its receipts were already pruned — causing countBlockTxsLikeEncodeTmBlock to silently skip EVM transactions whose receipts are missing rather than returning an error.

This scenario occurs when ReceiptStoreConfig.KeepRecent is smaller than StateStoreConfig.KeepRecent / MinRetainBlocks.

Fix

• Added EarliestVersion() int64 to the ReceiptStore interface and implemented it across all backends (receiptStore/pebble, parquetReceiptStore, cachedReceiptStore) and the underlying parquet.Store.
• Added WatermarkManager.EnsureReceiptHeightAvailable — a targeted check that returns an explicit "receipts have been pruned" error when the requested height is below the receipt store's earliest retained version. Returns nil when no receipt store is configured or no pruning has occurred.
• Called EnsureReceiptHeightAvailable in both GetBlockTransactionCountByNumber and GetBlockTransactionCountByHash after block resolution, so callers receive a clear error instead of a silently wrong count.

Result

• Within receipt retention window: correct count (consistent with eth_getBlockByNumber)
• Outside receipt retention window: explicit pruned error (instead of silent undercount)

Fixes: PLT-256

[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	Apr 10, 2026, 7:45 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.96%. Comparing base (1f4724d) to head (8628a38).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3216      +/-   ##
==========================================
- Coverage   59.00%   58.96%   -0.04%     
==========================================
  Files        2065     2062       -3     
  Lines      169422   168986     -436     
==========================================
- Hits        99959    99644     -315     
+ Misses      60700    60627      -73     
+ Partials     8763     8715      -48     

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

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

Files with missing lines	Coverage Δ
evmrpc/block.go	82.37% <100.00%> (+0.21%)	⬆️
evmrpc/watermark_manager.go	75.67% <100.00%> (+1.20%)	⬆️
sei-db/ledger_db/parquet/store.go	69.67% <100.00%> (+1.35%)	⬆️
sei-db/ledger_db/receipt/cached_receipt_store.go	86.14% <100.00%> (+0.16%)	⬆️
sei-db/ledger_db/receipt/parquet_store.go	69.51% <100.00%> (+2.85%)	⬆️
sei-db/ledger_db/receipt/receipt_store.go	75.00% <100.00%> (+0.25%)	⬆️

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

[bdchatham]

Trying to wrap my head around this. Is there something special about this? Is it not generalized in the if-statement below it?

[amir-deris]

Thanks for feedback. That is a good point as the if statement below will not cause error since height is non-negative. I will remove it.

[masih]

• We also need to update GetBlockByNumber/Hash otherwise the behaviour between GetBlockTransactionCountByNumber/Hash and GetBlockByNumber/Hash would be inconsistent.

• Left a comment on earliest version in parquet store; looks like it is broken?

Thanks for picking this work up @amir-deris 🍻

[masih]

Looks like earliestVersion is never changed in parquet implementation even after pruning?

CC @jewei1997 for context.

[amir-deris]

@masih That is a nice observation. The earliest version in parquet store remains zero even after pruning, unlike other store implementations like pebbledb/mvcc/db.go. Should I fix that for Parquet store in another PR?