evmrpc: return null on above-watermark for spec-compliant endpoints

[wen-coding]

Summary

Several Ethereum JSON-RPC endpoints that take a block identifier currently surface the watermark race ("requested height N is not yet available; safe latest is N-1") as an error, where the Ethereum JSON-RPC spec says they should return JSON null (block doesn't exist yet from the caller's perspective). Wallets, indexers, and similar tools see this as a transient failure exactly when a tx has just been mined and the safe-latest watermark hasn't caught up.

#3119 fixed eth_getBlockByNumber and #3501 fixed eth_getTransactionReceipt with the same if errors.Is(err, ErrBlockHeightNotYetAvailable) { return nil, nil } pattern. This PR generalizes the pattern into two helpers and applies it to the remaining user‑facing endpoints.

Endpoints converted

RPC method	File:line
eth_getBlockReceipts	block.go
eth_getBlockTransactionCountByNumber	block.go
eth_getBlockTransactionCountByHash	block.go
eth_getBlockByHash + sei_getBlockByHashExcludeTraceFail (shared getBlockByHash)	block.go
eth_getTransactionByBlockNumberAndIndex	tx.go
eth_getTransactionByBlockHashAndIndex	tx.go
eth_getTransactionByHash	tx.go

Historic context (why propagation was the previous default)

The watermark integration (#2465) deliberately propagated the error so clients would know "data not yet ready — retry later" rather than getting a misleading null. That was the original conservative default across all evmrpc endpoints that touched a height.

Since then, subsequent PRs have progressively chosen JSON null per Ethereum spec on a per‑endpoint basis:

PR	Endpoint	Rationale
#3067 (Moji)	eth_getBlockByHash (unknown hash)	PLT‑162: "return result null for non‑existent hashes"
#3119 (Moji)	eth_getBlockByNumber (above watermark)	"Align with expectations" (Ethereum spec)
#3320 (Wen)	eth_getTransactionByBlock*AndIndex (out‑of‑range index)	"Per Ethereum JSON‑RPC spec, these methods must return null"
#3501	eth_getTransactionReceipt (above watermark)	spec
#3530 (this)	the remaining 7 user‑facing endpoints	continues the same pattern

So the propagation on these 7 endpoints wasn't a deliberate "this endpoint should error" choice — it's historical inertia from #2465 that subsequent PRs have been chipping away one endpoint at a time. #3530 finishes the same job; nothing about the original watermark intent is being reversed where it still serves users (see out of scope below).

Out of scope

State queries (eth_getBalance/Code/StorageAt/Proof), simulation paths, filter internals, and info.go/association.go helpers keep using blockByNumberRespectingWatermarks directly. These are where the original #2465 design still applies:

• The spec is fuzzier (some clients expect error for invalid blocks).
• The "data not ready" semantic is more meaningful — a wallet showing balance: 0 for a not‑yet‑ready block would mislead users.
• Internal call sites validate heights and rely on the error path.

Tests covering those error paths (TestStateAPIGetProofUnavailableHeight, the filter‑cache test) are intentionally unchanged.

Pruned-block path also unchanged. Explicit numeric requests for heights below the earliest watermark (height < earliest) still return "requested height N has been pruned". The helpers only convert ErrBlockHeightNotYetAvailable (and ErrBlockNotFoundByHash for the by-hash variant). Pre-PR behavior is preserved here — pruned is a different (permanent, not transient) failure class from the watermark race this PR addresses, and changing it would touch a different set of test assertions (watermark_manager_test.go:106,135). Hash-based requests for pruned blocks already return null in production because Tendermint returns Block: nil for unknown hashes, which blockByHashWithRetry wraps as ErrBlockNotFoundByHash.

Helpers

// blockByNumberOrNullForJSONRPC: wraps blockByNumberRespectingWatermarks
// and converts ErrBlockHeightNotYetAvailable to (nil, nil) so callers can
// return JSON null per the Ethereum spec.

// blockByHashOrNullForJSONRPC: same, by-hash variant. Also catches
// ErrBlockNotFoundByHash — both are "block doesn't exist" per spec.

Internal call sites that want the error keep using the originals.

Operational impact (broader than tests)

This is a production-correctness fix. Currently a wallet polling for a freshly-mined tx, or an indexer doing eth_getBlockReceipts near the chain head, can intermittently get a "block height not yet available" error response instead of null — they then surface that as a transient failure to users. With this change, those endpoints behave per Ethereum JSON-RPC spec.

Test plan

• go test ./evmrpc/ -count=1 passes (21s, includes the updated above-watermark tests).
• golangci-lint run ./evmrpc/: 0 issues.
• gofmt -s -l clean.
• CI integration matrix passes.

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Changes production JSON-RPC behavior for many high-traffic endpoints near chain head; spec-aligned but clients that retried on the old error must handle null instead.

Overview
This PR generalizes the pattern from earlier fixes (eth_getBlockByNumber, eth_getTransactionReceipt) so user-facing block/tx RPC methods return JSON null instead of a watermark error when a block is above safe-latest or unknown—matching Ethereum JSON-RPC semantics for “block doesn’t exist (yet).”

It adds blockByNumberOrNullForJSONRPC and blockByHashOrNullForJSONRPC in watermark_manager.go, mapping ErrBlockHeightNotYetAvailable (and ErrBlockNotFoundByHash for by-hash) to (nil, nil) while leaving real errors (e.g. pruned height, transport failures) unchanged. Block handlers (getBlockByHash, getBlockByNumber, transaction counts, GetBlockReceipts) and transaction handlers (getTransactionByHash, by-block index lookups, receipt fetch) now use these helpers and treat a nil block as null. GetBlockReceipts is refactored to resolve hash vs number separately so latest/safe/finalized/pending still resolve via safe-latest instead of being misread as missing.

State/simulation paths still use blockByNumberRespectingWatermarks and can return “not yet available” errors. Tests and the mock Tendermint client are updated to expect null for unknown/future blocks and to cover tag resolution and helper edge cases.

^{Reviewed by Cursor Bugbot for commit 5d0bccb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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	Jun 2, 2026, 3:28 AM

[codecov]

Codecov Report

❌ Patch coverage is 82.60870% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.28%. Comparing base (f8f1af1) to head (5d0bccb).

Files with missing lines	Patch %	Lines
evmrpc/block.go	75.00%	3 Missing and 3 partials ⚠️
evmrpc/tx.go	83.33%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3530      +/-   ##
==========================================
- Coverage   59.12%   58.28%   -0.84%     
==========================================
  Files        2213     2140      -73     
  Lines      182774   174431    -8343     
==========================================
- Hits       108072   101675    -6397     
+ Misses      64985    63717    -1268     
+ Partials     9717     9039     -678     

Flag	Coverage Δ
sei-chain-pr	67.98% <82.60%> (?)
sei-db	70.62% <ø> (+0.21%)	⬆️
sei-db-state-db	?

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

Files with missing lines	Coverage Δ
evmrpc/watermark_manager.go	77.48% <100.00%> (+3.01%)	⬆️
evmrpc/tx.go	84.45% <83.33%> (-0.34%)	⬇️
evmrpc/block.go	83.43% <75.00%> (-0.11%)	⬇️

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 06389ea. Configure here.}