feat(rpc): add transaction hash caching to EthStateCache by figtracer · Pull Request #21180 · paradigmxyz/reth

figtracer · 2026-01-19T09:27:19Z

Summary

Adds O(1) transaction hash lookup caching to the RPC layer's EthStateCache. This speeds up eth_getTransactionByHash and eth_getTransactionReceipt for recently cached blocks by avoiding database lookups.

Changes

Introduces CachedTransaction<B, R> helper struct containing:
- block: Arc<RecoveredBlock<B>> - the cached block (shared with block cache)
- tx_index: usize - transaction index within the block
- receipts: Option<Arc<Vec<R>>> - optional receipts (shared with receipts cache)
Adds tx_hash_index: LruMap<TxHash, Rc(B256, usize)> to EthStateCacheService that indexes transaction hashes to their block hash and index
New get_transaction_by_hash() method returns the full CachedTransaction with block and optional receipts in a single lookup
Transactions are indexed when new canonical blocks arrive via CacheNewCanonicalChain and removed on reorgs via RemoveReorgedChain
Adds --rpc-cache.max-cached-tx-hashes CLI option (default: 30,000) to configure the transaction hash cache size

figtracer · 2026-01-19T10:12:56Z

doesn't show results in practice

mattsse

@figtracer I like this idea, but perhaps we can solve this on the rpc level, like monitor new blocks and track the index there, see ethrpccache

then we could ptimistaically use the cached block already

figtracer · 2026-01-19T10:53:50Z

@figtracer I like this idea, but perhaps we can solve this on the rpc level, like monitor new blocks and track the index there, see ethrpccache

then we could ptimistaically use the cached block already

thanks, will reopen and expand into this

Moving transaction hash caching to RPC layer instead, following maintainer suggestion to use EthStateCache pattern.

Add a transaction hash index to EthStateCache that maps TxHash to (BlockHash, TxIndex) for O(1) transaction lookups on recently cached blocks. Changes: - Add tx_hash_index HashMap to EthStateCacheService - Add block_tx_hashes HashMap to track txs per block for cleanup - Index transactions when blocks are cached via CacheNewCanonicalChain - Remove tx index entries when blocks are reorged via RemoveReorgedChain - Add get_transaction_by_hash() method to EthStateCache - Update LoadTransaction::transaction_by_hash() to check cache first

Replace HashMap with schnellru::LruMap for the transaction hash index. This eliminates the need for block_tx_hashes tracking since the LRU automatically evicts old entries when full. Benefits: - Saves ~32MB memory (no block_tx_hashes HashMap) - Self-managing via LRU eviction - Simpler code with same O(1) lookup performance - Graceful degradation on cache miss (falls back to DB)

crates/rpc/rpc-eth-types/src/cache/mod.rs

crates/rpc/rpc-eth-types/src/cache/config.rs

mattsse

this makes a lot of sense actually and will be more important once we no longer have the index in mdbx directly

left some suggestions

mattsse · 2026-01-22T11:57:18Z

crates/node/core/src/args/rpc_server.rs

                max_receipts: 2000,
                max_headers: 1000,
                max_concurrent_db_requests: 512,
+                max_cached_tx_hashes: 20_000,


I think we can bump this to 30k by default which should maybe be ~150MB or so

how do we get this number?

mattsse · 2026-01-22T11:59:43Z

crates/rpc/rpc-eth-types/src/cache/mod.rs

+/// Cached data for a transaction lookup.
+#[derive(Debug, Clone)]
+pub struct CachedTransaction<B: Block, R> {
+    /// The block containing this transaction.
+    pub block: Arc<RecoveredBlock<B>>,
+    /// Index of the transaction within the block.
+    pub tx_index: usize,
+    /// Receipts for the block, if available.
+    pub receipts: Option<Arc<Vec<R>>>,
+}


I'd be nice if this has a helper fn for creating the receipt directly

which could use:

reth/crates/rpc/rpc-eth-types/src/block.rs

Lines 75 to 86 in 4d0e06c

/// Converts a transaction and its receipt into the rpc receipt format using the given converter.

pub fn convert_transaction_receipt<N, C>(

block: &RecoveredBlock<BlockTy<N>>,

all_receipts: &[ReceiptTy<N>],

tx: IndexedTx<'_, BlockTy<N>>,

receipt: &ReceiptTy<N>,

converter: &C,

) -> Option<Result<<C::Network as RpcTypes>::Receipt, C::Error>>

where

N: NodePrimitives,

C: RpcConvert<Primitives = N>,

{

so we can move this type there as well I believe

mattsse · 2026-01-22T12:00:34Z

crates/rpc/rpc-eth-types/src/cache/mod.rs

+// `EthStateCacheService` task. It is created in `index_block_transactions`, accessed in the
+// `GetTransactionByHash` handler, and removed in `remove_block_transactions` - all within
+// the same task's poll loop.
+unsafe impl<Provider, Tasks, LimitBlocks, LimitReceipts, LimitHeaders> Send


instead of this, let's do a warpper helper around rc

…, fix reorg bug Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-019bfa8e-74c2-73fd-b8ed-c38cd6a79b97

mattsse

very nice

Amp-Thread-ID: https://ampcode.com/threads/T-019bfaa8-7d15-730d-a423-e49efe69369d Co-authored-by: Amp <amp@ampcode.com>

Co-authored-by: Matthias Seitz <matthias.seitz@outlook.de> Co-authored-by: Amp <amp@ampcode.com>

wip

1f6a5b1

github-project-automation bot moved this to Backlog in Reth Tracker Jan 19, 2026

github-project-automation bot added this to Reth Tracker Jan 19, 2026

figtracer added 5 commits January 19, 2026 09:28

rm bench

5961a09

cleanup

03e3228

rm comment

1254b14

rm test_utils

0b25582

wip

79678f7

figtracer closed this Jan 19, 2026

github-project-automation bot moved this from Backlog to Done in Reth Tracker Jan 19, 2026

mattsse reviewed Jan 19, 2026

View reviewed changes

figtracer reopened this Jan 19, 2026

github-project-automation bot moved this from Done to In Progress in Reth Tracker Jan 19, 2026

figtracer changed the title ~~perf(chain-state): add cache for tx hashes~~ perf(chain-state): add tx_hash_index to EthStateCacheService Jan 19, 2026

revert: remove tx cache from chain-state layer

45e39b5

Moving transaction hash caching to RPC layer instead, following maintainer suggestion to use EthStateCache pattern.

figtracer changed the title ~~perf(chain-state): add tx_hash_index to EthStateCacheService~~ perf(rpc): add tx_hash_index to EthStateCacheService Jan 19, 2026

figtracer added 2 commits January 19, 2026 14:58

figtracer force-pushed the cache-txs branch from 0c9eedc to 81e556e Compare January 19, 2026 15:09

mattsse requested changes Jan 19, 2026

View reviewed changes

crates/rpc/rpc-eth-types/src/cache/mod.rs Outdated Show resolved Hide resolved

crates/rpc/rpc-eth-types/src/cache/mod.rs Outdated Show resolved Hide resolved

figtracer force-pushed the cache-txs branch from e9f573b to c795cc7 Compare January 19, 2026 15:14

style: collapse nested if statements per clippy

dde524f

figtracer force-pushed the cache-txs branch from c795cc7 to dde524f Compare January 19, 2026 15:15

return block

2fcdc47

figtracer commented Jan 19, 2026

View reviewed changes

crates/rpc/rpc-eth-types/src/cache/config.rs Outdated Show resolved Hide resolved

wip

4704a67

figtracer changed the title ~~perf(rpc): add tx_hash_index to EthStateCacheService~~ feat(rpc): add transaction hash caching to EthStateCache Jan 19, 2026

wip

0dc125a

figtracer added 3 commits January 19, 2026 15:49

docs

b44440e

docs

f4dd3a0

replace arc with rc

79c1931

figtracer marked this pull request as ready for review January 19, 2026 16:34

figtracer requested review from Rjected and klkvr as code owners January 19, 2026 16:34

figtracer requested a review from mattsse January 19, 2026 16:34

mattsse requested changes Jan 22, 2026

View reviewed changes

figtracer added 5 commits January 22, 2026 16:16

suggestions

820163a

docs

662034e

fix

933e98e

nit

971fc0b

docs

10fd033

figtracer requested a review from gakonst as a code owner January 22, 2026 16:40

figtracer and others added 2 commits January 22, 2026 16:42

nit

bc077d9

refactor: remove SendRc, add CachedTransaction::recovered_transaction…

9863892

…, fix reorg bug Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-019bfa8e-74c2-73fd-b8ed-c38cd6a79b97

mattsse force-pushed the cache-txs branch from 12f9368 to 9863892 Compare January 26, 2026 13:59

mattsse approved these changes Jan 26, 2026

View reviewed changes

Merge branch 'main' into cache-txs

bc1cac6

mattsse enabled auto-merge January 26, 2026 14:04

mattsse added M-changelog This change should be included in the changelog A-rpc Related to the RPC implementation labels Jan 26, 2026

mattsse and others added 2 commits January 26, 2026 15:17

chore: fix clippy unused binding warnings

8309060

Amp-Thread-ID: https://ampcode.com/threads/T-019bfaa8-7d15-730d-a423-e49efe69369d Co-authored-by: Amp <amp@ampcode.com>

chore: clippy

b0db00a

mattsse added this pull request to the merge queue Jan 26, 2026

Merged via the queue into paradigmxyz:main with commit ab68557 Jan 26, 2026
45 checks passed

github-project-automation bot moved this from In Progress to Done in Reth Tracker Jan 26, 2026

figtracer deleted the cache-txs branch January 26, 2026 17:17

rakita pushed a commit that referenced this pull request Jan 26, 2026

feat(rpc): add transaction hash caching to EthStateCache (#21180)

29f51ab

Co-authored-by: Matthias Seitz <matthias.seitz@outlook.de> Co-authored-by: Amp <amp@ampcode.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(rpc): add transaction hash caching to EthStateCache#21180

feat(rpc): add transaction hash caching to EthStateCache#21180
mattsse merged 27 commits intoparadigmxyz:mainfrom
figtracer:cache-txs

figtracer commented Jan 19, 2026 •

edited

Loading

Uh oh!

figtracer commented Jan 19, 2026

Uh oh!

mattsse left a comment

Uh oh!

figtracer commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mattsse left a comment

Uh oh!

mattsse Jan 22, 2026

Uh oh!

figtracer Jan 22, 2026

Uh oh!

mattsse Jan 22, 2026

Uh oh!

mattsse Jan 22, 2026

Uh oh!

mattsse left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	/// Converts a transaction and its receipt into the rpc receipt format using the given converter.
	pub fn convert_transaction_receipt<N, C>(
	block: &RecoveredBlock<BlockTy<N>>,
	all_receipts: &[ReceiptTy<N>],
	tx: IndexedTx<'_, BlockTy<N>>,
	receipt: &ReceiptTy<N>,
	converter: &C,
	) -> Option<Result<<C::Network as RpcTypes>::Receipt, C::Error>>
	where
	N: NodePrimitives,
	C: RpcConvert<Primitives = N>,
	{

Conversation

figtracer commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

figtracer commented Jan 19, 2026

Uh oh!

mattsse left a comment

Choose a reason for hiding this comment

Uh oh!

figtracer commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mattsse left a comment

Choose a reason for hiding this comment

Uh oh!

mattsse Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

figtracer Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

mattsse Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

mattsse Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

mattsse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

figtracer commented Jan 19, 2026 •

edited

Loading