rpc/jsonrpc: gate receipts and logs on the data they actually read

[lupin012]

Defects in the same family — how receipt- and log-serving endpoints decide availability.

Note: while this PR was under review, main removed Polygon support entirely (#23492..#23497). The Bor-specific fixes made in earlier review rounds are therefore no longer part of this PR — the history gate inside borReceiptForBlock and borStateSyncLogs, the txnLookupWithBorFallback resolution in eth_getTransactionReceipt, the Bor clamp on the receipts capability, and the four Bor gating tests were retired by the merge (34f460e) together with the code they gated. Non-Bor behaviour is untouched: those helpers were wrappers, and their callers now use the generic functions they wrapped (getReceipts, txnLookup).

1. The receipts gate consulted the wrong setting. It read kvcfg.PersistReceipts, a boolean saying the receipt cache exists on disk, and concluded receipts were available for every block. Retention is a separate setting: RCacheDomain is retired on its own --prune.receipts.distance window when one is set, and alongside state history otherwise, which is the default. It now consults prune.Mode.ReceiptsAmount(), distinguishing the same three shapes historyRetireCutoffs already distinguishes. Where the cache stops covering a block, availability falls back to state history, because a missing cache entry is not fatal: ReadReceiptCacheV2 reports it as absent and GetReceipt re-executes the block from ReceiptDomain plus state history, retired at the history cutoff rather than the RCacheDomain one. So a --prune.receipts.distance narrower than the history window costs the caller nothing.

2. Four endpoints were gated on receipts alone, though matching logs can need more. eth_getLogs and erigon_getLogs search LogAddrIdx and LogTopicIdx when the query filters by address or topic; those are standalone inverted indices retired at the history cutoff whatever the receipt retention is, so gated on receipts they answered with an empty log array instead of PrunedError. They now take the history gate on top, but only when the filter actually reaches the indices: usesLogIndex mirrors applyFiltersV3, which skips topic positions that are empty because those match any topic — so "topics": [null] searches nothing and stays on the receipts path, exactly like the unfiltered form. erigon_getLatestLogs re-executes through a TraceWorker and overlay_getLogs re-executes with overridden code, so both take the history gate unconditionally.

3. Ten endpoints serving the receipts of one block were gated on history alone, which both rejects blocks whose body and receipts are present and never checks the body at all. New checkBlockReceiptsAvailable composes the two boundaries: reading a stored receipt needs the block body anyway, since the receipt carries no TxHash and it is derived from the transaction. The two GraphQL block-detail entry points had no gate; theirs is placed before the body read, because after it a pruned body reads back as nil and the endpoint answers "not found" before any gate could fire. The GraphQL and Otterscan block-detail paths also select one overlay view per request and thread it through resolution, gate, block and receipt reads, so a background commit cannot gate one generation while another answers.

4. The log path needs the block body for the same reason. getLogsV3 reads the transaction through TxnByIdxInBlock for every txNum it does not find in the in-memory cache, because GetReceipt derives the receipt from it. With bodies pruned and receipts kept — minimal with --prune.receipts.distance=keep-all — the lookup came back empty and the loop skipped the block silently, answering with an empty array. New checkLogsAvailable composes the three boundaries and replaces the duplicated gate block in the two getLogs, so the rationale is stated once.

5. A block with no transactions could not have its receipts read at all. GetReceipts decided whether the cache had answered by testing len(receiptsFromDB) > 0, which cannot tell "the cache holds nothing for this block" from "this block has no transactions", so an empty block fell through to PrepareEnv and its state-history read. Where history is pruned, eth_getBlockReceipts, debug_getRawReceipts, ots_getBlockDetails and ots_getBlockTransactions answered with a leaked ReceiptsGen: PrepareEnv: ... old data not available instead of an empty list. The fix belongs in the generator rather than the gate: the gate decides availability from retention, and a block it lets through must not leak an execution error. Availability itself is a separate question, and the gate makes no exception for these blocks — a transaction-free block below the cutoff is refused like any other, and the caller gets PrunedError rather than an empty list that cannot be told apart from "no receipts". So this fix covers the blocks the gate serves: receipts retained, archive, or above the cutoff. The two boundaries are the whole gate, so oldestBlock in eth_capabilities is the exact boundary the endpoints honour rather than a floor with holes below it.

6. The blocks gate read the chain-history-expiry sentinel as "nothing is pruned". KeepPostMergeBlocksPruneMode is a policy, not a window: on a chain declaring a merge point, pre-merge transaction segments are never downloaded, so checkPruneBlocks now refuses below MergeHeight, and eth_capabilities resolves its blocks boundary through the same function, so the two cannot diverge. A legacy archive datadir persists the same blocks sentinel, so the datadir decides rather than the stored retention — and neither a pre-merge body nor the oldest available block can: expiry keeps pre-merge headers and bodies, and the transaction segment spanning the merge point reaches below it. The gate reads a pre-merge transaction, sampled by halving the range so the candidates stay clear of the transaction segment spanning the merge point; where the chain carries no pre-merge transaction at all, the cumulative txnum position of the last pre-merge body says so and nothing is left to be missing. The verdict is availability rather than policy, so it is cached for a short TTL in both directions instead of being settled once, and availability widening while segments arrive reopens the gate within that window. The remote rpcdaemon's block reader answers FrozenBlocks through a new ethbackend RPC instead of panicking, so the receipt gates, eth_capabilities and the receipt generator keep consulting the real value everywhere.

7. erigon_getLogsByHash consulted its receipt cache before any gate. A receipt set cached while its block was inside the retention window stayed servable after the boundary moved past it — holes below the advertised oldestBlock, the defect class this PR removes. The gate now runs before the cache, so a hit is gated like a miss, at the cost of one read-only tx on cache hits.

This covers the audit asked for in point 2 of #22260 for erigon_receipts.go and otterscan_block_details.go: migrated to the correct boundary rather than documented as genuinely needing history.

Coverage

prune_gating_test.go pins 34 endpoints across the nine prune mode shapes on an old and a recent block: 612 cells. check_prune_gates_test.go covers the gates directly — the boundary block itself, the boundary named in each error, the archive short circuit, each receipt retention shape including a window wider and a window narrower than history, each leg of both composed gates, and usesLogIndex over the criteria shapes. checkTxFee gains the unit test it never had, so every check* in the package now has one. It also pins the datadir shapes behind the blocks sentinel — aligned segments, bodies without transactions, a chain with no pre-merge user transaction, a sampled block without transactions, blocks arriving later, and a stored history retention that does not change the verdict. The remote block reader's frozen-block refresh is covered directly: a failed fetch is retried instead of being served as fresh, and a slow one delays only the goroutine that fetches.

Verified on a live node

Sepolia at tip with --prune.mode=minimal --prune.include-receipts — receipts on disk, block bodies pruned. Head 11500055, both boundaries at 11400054, old block probed 5750027. 35 checks, all passing.

Family	Endpoints	Old block	Why
headers	erigon_getHeaderByNumber, debug_getRawHeader	served	headers are never pruned
block data	eth_getBlockByNumber, eth_getBlockTransactionCountByNumber, eth_getUncleCountByBlockNumber, debug_getRawBlock	refused	bodies are pruned in minimal
receipts of one block	eth_getBlockReceipts, debug_getRawReceipts, erigon_getBlockReceiptsByBlockHash, erigon_getLogsByHash, ots_getBlockDetails, ots_getBlockTransactions	refused, naming blocks are available	the blocks leg this PR adds — receipts are present, the body is not
logs by filter	eth_getLogs, erigon_getLogs	refused, naming history is available	log indices follow history, not receipts
state / trace	eth_getBalance, trace_block, debug_traceBlockByNumber, ots_hasCode	refused	history is pruned

This table was measured before the log gate took the blocks leg described in point 4. On the current revision its two log rows refuse on the blocks boundary rather than the history one, because minimal prunes bodies and that leg is checked first; the rows above and below are unaffected. The blocks leg is covered end to end by the unit tests, not by a live probe.

Every recent-block probe is served. The two middle rows name different boundaries for the same block, which is what this configuration shows: before the change both said history is available.

Note that in minimal the receipt endpoints refuse either way, so only the named boundary changes. The behavioural flip — refused becoming served — happens where bodies are kept and receipts outlive history (blocks with --prune.receipts.distance=keep-all), which is the largest group of the 26 red cells above.

Second live node: blocks with receipts kept

Sepolia at tip with --prune.mode=blocks --prune.include-receipts --prune.receipts.distance=keep-all — every body and every receipt on disk, state history pruned below block 11238830. Old block probed: 5750484, some 5.5M blocks below the history boundary.

Family	Endpoints	Old block	Why
headers	erigon_getHeaderByNumber, debug_getRawHeader	served	never pruned
block data	eth_getBlockByNumber, eth_getBlockTransactionCountByNumber, eth_getUncleCountByBlockNumber, eth_getTransactionByHash	served	bodies are kept
receipts of one block	eth_getBlockReceipts, debug_getRawReceipts, eth_getTransactionReceipt, erigon_getBlockReceiptsByBlockHash, erigon_getLogsByHash, ots_getBlockDetails, ots_getBlockTransactions	served	body and receipts are both there — on main all seven refuse
logs, unfiltered	eth_getLogs, erigon_getLogs	served, 125 logs	read straight from receipts; no index is consulted
logs, filtered by address	eth_getLogs, erigon_getLogs	refused, naming history is available	the index search needs history — on main both return an empty array
state / trace	eth_getBalance, trace_block, debug_traceBlockByNumber, ots_hasCode	refused	history is pruned
block data, follow-up	debug_getRawBlock, debug_getRawTransaction	refused	still gated on history; see Follow-up

This is the configuration where the change is behavioural rather than a difference in wording. eth_getBlockReceipts returns 101 receipts for a block whose state history is long gone, ots_getBlockDetails computes its totalFees, and erigon_getLogsByHash returns all 101 log positions — none of which main will answer. In the other direction a filtered eth_getLogs now refuses instead of quietly returning [], while the unfiltered form still answers with its 125 logs.

36 of 38 checks pass; the two failures are debug_getRawBlock and debug_getRawTransaction, whose fix is in the follow-up PR.

Topic shapes on the same node

The empty-topic-position case, probed on block 5750932 of the same datadir with an rpcdaemon opened read-only:

filter	before	after
no topics	1117 logs	1117 logs
"topics": []	1117 logs	1117 logs
"topics": [null]	PrunedError	1117 logs
"topics": [[]]	PrunedError	1117 logs
"topics": [null, null]	PrunedError	1113 logs

The last row keeps 1113 rather than 1117 because that shape requires two topic positions to match, so it drops the four logs carrying a single topic; the filter is working, the gate is not involved. A query filtered by address still refuses naming history is available, and the single-block receipt endpoints stay served, so the blocks leg added in point 4 introduces no false refusal where bodies are kept.

Gate boundaries measured against the data

Each gate names a boundary; a second rpcdaemon built with checkPruneField short-circuited to nil says where the data actually starts. Both were opened read-only on the same Sepolia blocks datadir — head 11501094, declared boundary 11238950 — and the first block that answers correctly was found by bisection, with a block's own receipts as the ground truth for what its log endpoints must reproduce.

gate	endpoints	declared	first block that answers	verdict
checkPruneHistory	eth_getBalance, eth_getCode	11238950	11163680	conservative by 75270
checkPruneHistory	trace_block, debug_traceBlockByNumber	11238950	11163681	conservative by 75269
index leg of checkLogsAvailable	eth_getLogs, erigon_getLogs filtered	11238950	11163681	conservative by 75269
checkBlockReceiptsAvailable	eth_getBlockReceipts, debug_getRawReceipts, ots_getBlockDetails, ots_getBlockTransactions	never refuses	complete at every block with transactions from 800000 to the tip	exact
receipts leg of checkLogsAvailable	eth_getLogs, erigon_getLogs unfiltered	never refuses	correct at every block with logs	exact

The 75k-block gap is not a defect: file retirement is floored to the file step, so data survives below the declared boundary until the next prune pass removes it. The gate promises the boundary the configuration guarantees rather than the physical one that moves at every retire, which is the pre-existing behaviour of checkPruneField.

The index leg is where the change earns its place. Filtering the same block by an address taken from its own logs:

block	gate removed	gate in place
5750932	0 of 1 expected log	refused
11163680	0 of 1 expected log	refused
11163679	0 of 1 expected log	refused
11238949	35 logs, correct	refused
11238950	116 logs, correct	116 logs

Below the physical floor the filtered query answers silently zero, which is what the history leg turns into PrunedError. The physical floor of the log index, 11163681, coincides with that of state history, 11163680 — the premise this PR rests on, measured rather than assumed. The unfiltered form is correct at every block probed: 1117, 1016, 1360, 525, 443, 1237 and 216 logs, each matching its receipts, identical with and without the gate.

Point 5 was found the same way: blocks 1000, 1000000, 1510087 and 2000000 go from the PrepareEnv error to an empty list, while blocks carrying transactions are unchanged — 800000 keeps 1 receipt, 1511431 keeps 4, 5750932 keeps 99, 11501058 keeps 94.

The blocks leg is the one this datadir cannot exercise, since it keeps every body; it stays covered by the unit tests.

Follow-up

The endpoints that need the block body but not the receipts are left to a second PR: debug_getRawBlock, debug_getRawTransaction and erigon_getBlockByTimestamp still gate on history, so under --prune.mode=blocks they refuse bodies that were never pruned — the defect class #21965 reported. That PR also gates eth_feeHistory, which has none today, and completes the table with the header, trace and Otterscan search endpoints.

[Copilot]

Pull request overview

Updates receipt and log RPC pruning gates to reflect block-body, receipt-cache, log-index, and state-history availability.

Changes:

• Adds composed availability gates for receipts and logs.
• Migrates affected RPC endpoints to the new boundaries.
• Adds broad endpoint and boundary test coverage, including empty blocks.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
rpc/jsonrpc/receipts/receipts_generator.go	Handles transaction-free blocks without re-execution.
rpc/jsonrpc/prune_gating_test.go	Expands endpoint gating coverage.
rpc/jsonrpc/overlay_api.go	Changes overlay log gating.
rpc/jsonrpc/otterscan_block_details.go	Updates block-detail receipt gates.
rpc/jsonrpc/otterscan_api.go	Updates block-transaction receipt gating.
rpc/jsonrpc/graphql_api.go	Adds block-detail availability checks.
rpc/jsonrpc/eth_receipts.go	Adds log-index and block-receipt gates.
rpc/jsonrpc/eth_api.go	Implements receipt retention and composed gates.
rpc/jsonrpc/erigon_receipts.go	Migrates Erigon receipt and log endpoints.
rpc/jsonrpc/debug_api.go	Updates raw-receipt gating.
rpc/jsonrpc/check_prune_gates_test.go	Tests gate boundaries and retention shapes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[yperbasis]

Requesting changes for the following blockers.

Please address the four unresolved inline findings on this head:

1. erigon_getLatestLogs checks history but not block transaction availability, so a shorter blocks window can produce incomplete or empty results.
2. overlay_getLogs has the same missing blocks boundary and can turn a missing block into an empty result.
3. eth_getTransactionReceipt checks block zero before resolving a Bor state-sync transaction to its real block.
4. The receipt gate runs before the body is inspected, so the new empty-block fast path remains unreachable when receipt history is pruned.

I also found these issues:

5. eth_capabilities is now inconsistent with the new gates. When PersistReceipts is enabled with the default follow-history retention, it still reports receipts and logs from blocksOldest. A focused cross-check reported oldestBlock 0 while checkBlockReceiptsAvailable rejected blocks below 10. Finite receipt windows are also ignored, and filtered logs require the history boundary.
6. resolveLogsRange handles BlockHash by loading the full block before checkLogsAvailable runs. If transaction snapshots are pruned, eth_getLogs and overlay_getLogs return a block-read/not-found error instead of PrunedError. Resolve the block number from the retained header first.
7. RCache coverage is not sufficient for receipt paths that bypass RCache. Pre-Byzantium receipts with post-state calculation skip the persistent cache, and Bor synthetic receipts reconstruct historical state. The migrated endpoints can therefore pass the receipt gate and fail below pruned history.
8. checkPruneBlocks treats KeepPostMergeBlocksPruneMode as disabled. On merge chains, pre-merge transaction segments are intentionally absent, so these requests pass the gate. The capabilities implementation already derives this boundary from MergeHeight.

Validation on commit 866b2f9: go test ./rpc/jsonrpc/... -count=1 passed, and git diff --check was clean.

[lupin012]

@yperbasis

All eight are addressed:

The four inline findings are answered in their threads — the first two share a small checkBlockHistoryAvailable helper since both need the same pair of boundaries, the third follows your suggestion with txnLookupWithBorFallback and no new code, and the fourth is the only place I deviated from the shape proposed: the empty-block shortcut lives in the gate rather than in the ten callers.

5. It never consulted ReceiptsAmount() — hence the oldestBlock 0 against a gate refusing below 10. It now mirrors checkReceiptsAvailable: the history boundary when the cache is absent or follows it, 0 on an explicit keep-all, and a finite window only where it is wider than history, since below it the read falls back to re-execution. deleteStrategy reports the retention that decides rather than always the blocks one, and logs take the filtered form, adding the history boundary for LogAddrIdx and LogTopicIdx.
   TestCapabilitiesAgreeWithGates pins, for every prune shape, that the oldest block each field advertises is served by the matching gate and the block below it refused; TestCapabilitiesAdvertiseTheReceiptWindow covers a finite receipt window.

6. The BlockHash branch now resolves the number through _blockReader.HeaderNumber instead of loading the block, so a pruned body reaches the gate and gets PrunedError instead of "block not found". TestLogsByBlockHashNamesThePruneBoundary deletes the body with rawdb.DeleteBody first, since the harness stores the prune mode without pruning.

7. checkReceiptsAvailable now consults postStateCalculated, mirroring the generator's own (commitmentHistory || FrozenBlocks() == 0) && !IsByzantium(block): there the cache is skipped, so only history can answer. For Bor the history gate sits in borReceiptForBlock after the events check, so it applies only to the blocks that actually carry a synthetic receipt. Pinned by TestReceiptsGateFollowsHistoryWherePostStateIsComputed and TestBorStateSyncReceiptFollowsHistory

8. It now recognises the sentinel and takes MergeHeight as the cutoff, as capabilities and blocksRetentionCutoff already do. Datadirs carrying the same sentinel in History are excluded — legacy archive and prune.MockMode hold every body; pinned by TestBlocksGateServesLegacyArchive.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (4)

rpc/jsonrpc/eth_system.go:190

• Equal current cutoffs also lose the log-index retention policy here. With a young node whose history window exceeds the head and a keep-all receipt cache, both values are 0, this condition is false, and Logs.DeleteStrategy is omitted even though filtered logs will later be retired with history. Tie-breaking must retain the finite history policy.

	if stateOldest > logsOldest {
		logsOldest, logsAmount = stateOldest, pruneMode.History

rpc/jsonrpc/eth_system.go:180

• When the head is still below every configured window, both cutoffs are 0, so this >= can replace a finite receipts/history policy with an unlimited blocks policy. For example, with History=Distance(100), blocks kept forever, no receipt cache, and head 20, Receipts.DeleteStrategy becomes nil even though receipts will be pruned after block 100. Resolve equal cutoffs from the configured retention policies rather than treating blocks as stricter automatically.

This issue also appears on line 189 of the same file.

	if blocksOldest >= receiptsOldest {
		receiptsOldest, receiptsAmount = blocksOldest, pruneMode.Blocks

rpc/jsonrpc/eth_system.go:170

• Keep-all cache retention does not make every receipt available from genesis. The new checkReceiptsAvailable forces receipts requiring a computed post-state (for example pre-Byzantium blocks when FrozenBlocks()==0 or commitment history is enabled) through the history gate. This branch still advertises oldestBlock=0, so routing via eth_capabilities can select this node for blocks that its receipt endpoints reject. Derive this field from the same cache-bypass conditions and fork boundary as the gate.

		switch amount := pruneMode.ReceiptsAmount(); {
		case amount == prune.KeepAllReceiptsPruneMode:
			receiptsOldest, receiptsAmount = 0, amount
		case pruneMode.ReceiptsFollowHistory():

rpc/jsonrpc/eth_receipts.go:168

• A no-index log query can still require history on Bor. getLogsV3 handles the final transaction via borStateSyncLogs, whose GenerateBorLogs calls ComputeBlockContext; this is the same state-history dependency now gated in borReceiptForBlock. With receipts kept beyond history, this early return lets an old range containing state-sync events pass the gate and fail during generation. Add the history check in borStateSyncLogs after confirming events exist.

	if !usesLogIndex(crit) {
		return nil

[yperbasis]

Requesting changes for five findings on d43a562650.

1. blocksFollowChainHistoryExpiry cannot use History == KeepPostMergeBlocksPruneMode to identify a legacy archive. The supported --prune.mode=archive --prune.distance.blocks=keep-post-merge configuration produces the same persisted pair, while snapshot download treats it as chain-history expiry and omits pre-merge transaction segments. The RPC gate therefore passes requests for missing bodies and can return empty/not-found instead of PrunedError. The legacy mode needs to be normalized in storage or distinguished through another source of truth.

2. Unfiltered Bor log queries still need state history. checkLogsAvailable adds the history leg only when usesLogIndex is true, but getLogsV3 handles Bor's final synthetic transaction through GenerateBorLogs, which reconstructs end-of-block state. With receipts kept beyond history, an unfiltered query passes the gate and then fails when it reaches a block carrying state-sync events.

3. eth_capabilities does not include the pre-Byzantium history requirement enforced by postStateCalculated. With blocks and receipts kept, finite state history, and commitment history enabled, it advertises receipt availability from block zero while checkReceiptsAvailable rejects transaction-bearing pre-Byzantium blocks. A routing client can therefore select a node that refuses the advertised range.

4. The capabilities calculation selects a retention policy by comparing only current PruneTo results. When multiple configured windows have not started pruning, their oldest values are all zero, and the >= branch can replace a finite history or receipt window with keep-all (or with a wider block window). deleteStrategy is then omitted or reports the wrong retention even though the category will be pruned later. Resolve equal cutoffs using the underlying policies, not their current oldest block alone.

5. blockHasNoReceipts rejects every Bor block before checking whether state-sync events exist. A retained old block with no transactions and no state-sync events is answerable as an empty receipt list, but the gate returns PrunedError. This also blocks GraphQL and Otterscan paths that request only regular receipts. Inspect the events or separate the gate for callers that include synthetic Bor receipts.

Local validation: go test ./rpc/jsonrpc/... -count=1, the focused snapshot-retention tests, and git diff --check all passed.

[AskAlexSharov]

FrozenBlocks() hands out 0 on a failed or timed-out fetch, and 0 is a load-bearing sentinel.

fetchFrozenBlocks returns r.frozenBlocksValue on the error path, which is 0 until the first success. The one consumer this RPC exists for reads that value as a boolean: receipts.PostStateCalculated returns commitmentHistoryEnabled || blockReader.FrozenBlocks() == 0.

So one failed round trip (or one 5s deadline) on a remote rpcdaemon flips every pre-Byzantium block:

• Generator.GetReceipts sets calculatePostState = true, skips ReadReceiptsCacheV2 and re-executes with the per-tx post-state path;
• checkReceiptsAvailable takes the computed branch and falls to checkPruneHistory, so eth_getBlockReceipts answers PrunedError for a block whose receipts are on disk;
• eth_capabilities moves receipts.oldestBlock to the Byzantium height for the same reason.

The doc comment above states exactly this hazard ("Zero is not [conservative]") but the code still returns it. Either surface "never observed" to the caller distinctly, or return a value the predicate reads as "snapshots exist" until something has actually been observed.

[lupin012]

Fixed in #23812: FrozenBlocksObserved reports the count together with whether the backend ever answered, and the sentinel readers use it — receipts.PostStateCalculated and the eth_simulateV1 commitment path, which are the two a remote reader can reach. An unobserved zero therefore no longer stands for "no snapshots". Caching a failed attempt (your other note) is only safe with that distinction in place, so the two land together.

[AskAlexSharov]

A slow backend costs every caller a full 5s, with the request's read transaction open.

The refresh runs inline in the calling goroutine, and a failed fetch never sets frozenBlocksFetchedAt. Against a backend that is reachable but unresponsive there is therefore no observed fast path at all: line 168 can never fire, so each caller either runs its own 5s fetch or waits out one and then runs its own.

FrozenBlocks() is reached from checkReceiptsAvailable -> postStateCalculated -> receipts.PostStateCalculated, i.e. from an RPC handler that already holds a BeginTemporalRo transaction. One unresponsive backend then parks the whole handler pool for 5s a request and pins one MDBX read transaction per parked handler — the stall TestRemoteBlockReaderFrozenBlocksServesCacheWhileRefreshing protects against, but only once a value has been observed, which is exactly what never happens here.

Refreshing in a background goroutine (and serving the last value, or a distinct "unknown") would keep the handler off the wire entirely.

[lupin012]

Fixed in #23812: the refresh runs on a goroutine of its own and a caller that already has a value returns without waiting for it. A failed attempt is stamped like a successful one, so the fast path exists against a backend that is down: one attempt per TTL instead of one per caller. Pinned by TestRemoteBlockReaderFrozenBlocksSuppressesRepeatFetchesAfterFailure and ...ServesCacheWhileRefreshing, which now asserts the stale caller answers without waiting.

[AskAlexSharov]

The expiry boundary is MergeHeight regardless of what the datadir actually holds, so eth_capabilities can advertise blocks that are gone.

holdsPreMergeBlockData already reads MinimumBlockAvailable() (line 607) but the verdict is thrown away — only the boolean survives, and the boundary returned here is always chainConfig.MergeHeight.

EnsureNotChanged explicitly allows Distance <-> KeepPostMergeBlocksPruneMode in both directions, so a datadir that ran with --prune.distance.blocks=N and is later opened with the expiry sentinel has its oldest block above MergeHeight. In that shape:

• checkPruneBlocks returns nil for every block >= MergeHeight, including the pruned range [MergeHeight, oldest);
• Capabilities sets blocksOldest = *expiryFrom = MergeHeight, so blocks.oldestBlock / tx.oldestBlock advertise a floor with holes above it.

That is the same "holes below the advertised oldestBlock" class the PR sets out to remove. Since the probe has oldest in hand, max(*MergeHeight, oldest) would close it.

[AskAlexSharov]

oldest > 1 is read as proof of expiry without comparing it to mergeHeight.

A datadir whose oldest available block sits below the merge point (segments that start mid-chain, or a datadir previously distance-pruned to a point below MergeHeight on a chain with a low merge height like Chiado) is classified as chain-history expiry. checkPruneBlocks then refuses every block in [oldest, mergeHeight) with PrunedError although the bodies and transactions are on disk, and eth_getBlockByNumber / eth_getTransactionByHash / the new checkBlockReceiptsAvailable gates all inherit that refusal.

The comment says "anything higher starts mid-chain, however far below the merge point" — but starting mid-chain and not holding pre-merge data are different facts, and only the second one justifies the expiry verdict. Comparing oldest against mergeHeight (and only short-circuiting when oldest >= mergeHeight) would keep the cheap path without the false refusal.

[AskAlexSharov]

An undecided probe is not cached, so it re-runs on every gated RPC.

_preMergeData is only stored when decided. probePreMergeBlockData returns decided == false whenever the block data it needs is itself unreadable (hasEarlyTransaction with last == nil and no sampled body, or earlyTxnUnread from the search). On such a datadir every single call into checkPruneBlocks — which now sits on eth_getBlockByNumber, eth_getTransactionByHash, all the eth_getUncle*, and the new checkBlockReceiptsAvailable / checkLogsAvailable gates — reruns the whole probe: MinimumBlockAvailable + ~log2(mergeHeight) CanonicalBodyForStorage reads + up to earlyTxnSearchBudget (256) more in searchUserTxnBlock.

On a remote rpcdaemon each of those is a gRPC round trip, and joinPreMergeProbe serialises them, so concurrent requests queue behind one another instead of fanning out. A negative-cache entry with a short TTL for the undecided verdict would bound this; as written the "open question is not remembered" rule makes the worst datadir the most expensive one.

[AskAlexSharov]

Reuse: this is the second hand-rolled "TTL cache + single-flight" in the same PR.

RemoteBlockReader.FrozenBlocks (here, lines 162-229) and BaseAPI.holdsPreMergeBlockData / joinPreMergeProbe / runPreMergeProbe / finishPreMergeProbe (rpc/jsonrpc/eth_api.go 542-590) implement the same mechanism — cache a value for a TTL, dedupe concurrent refreshes, publish the result to waiters, do not cache a failure — with about 120 lines between them and different rules for what a waiter gets (FrozenBlocks gives waiters the stale value and a one-retry budget; the probe gives waiters the error and retries unbounded).

golang.org/x/sync/singleflight is already in the module graph and covers the dedupe half exactly; a small shared cachedValue[T] helper would cover the rest and leave one set of rules to reason about instead of two.

[lupin012]

Fixed in #23812: both sites now hold a common/concurrent.CachedValue[T] — one TTL, one dedup, one rule for what a failed pass leaves behind. Each keeps its own waiting policy, which is the part that legitimately differs.

singleflight was tried and dropped. DoChan cannot join the pass in flight without possibly starting one of its own, and it runs the producer on a goroutine the caller does not own; the pre-merge probe reads through the caller kv.Tx, so a caller released by ctx.Done() rolls that transaction back under a live reader. Produce runs the pass on the caller goroutine instead, and Go is the background form for FrozenBlocks, which borrows nothing. DoChan also turns a producer panic into go panic(e), which ends the process rather than the request.

[lupin012]

@AskAlexSharov
Thanks for the review. This PR has already been through eight review rounds. Rather than reopen it, I would like to land it as approved and take all thirteen comments into dedicated follow-up PRs. Before deciding that, I checked each one against origin/main: none of them is a regression this PR introduces.

I have saved all thirteen into the follow-up list