perf(debug-trace-server): thread resolved (number, hash) through the fetch pipeline

[flyq]

Summary

Every resolved lookup was paying a redundant serial upstream header round trip. Tag resolution now binds number → hash in its one header fetch and skips resolve_canonical_hash; the by-number prelude, the tag path, and the transaction lookup hand the resolved (number, hash) pair to a new get_block_data_with_known_number entry (data_provider.rs:612), whose fetch future skips the pipeline's number-discovery header fetch. One upstream RTT saved on every tag request and every cold resolved miss; raw by-hash requests are unchanged.

Root cause

Two shapes of the same waste. Tag requests: Latest burned eth_blockNumber and Finalized/Safe fetched a full header but kept only the number — then resolve_canonical_hash re-fetched the same header by number (shallow heights are never memoized, so this second trip was paid on every tag request, before the cache check). Cold misses: do_fetch_block_data Step 1 re-discovered the block number via eth_getHeaderByHash even when the caller had just resolved number and hash one step earlier.

Fix

• resolve_block_number returns (u64, Option<B256>) (data_provider.rs:744): numeric/Earliest → (n, None); Latest/Finalized/Safe → one hash-verified header fetch (Latest switches off eth_blockNumber), returning the atomically-bound hash. Same trust bar as the numeric upstream path; the binding comes from one response, so reorg safety only improves. observe_tip feeding is unchanged.
• lookup_block_by_number uses the tag-supplied hash when present, else resolve_canonical_hash as before, and fetches via get_block_data_with_known_number.
• do_fetch_block_data takes known_number: Option<u64>; Step 1 runs only when it is None (raw by-hash requests). The number is routing input only (witness-source selection, deadline tightening) — every fetch stays keyed by hash, so a wrong number could at worst misroute, never mis-serve.
• get_block_data_for_tx passes tx.block_number (mined tx objects carry it next to the hash; None falls back to discovery) — covers the tx-driven majority of historical traffic.

Testing

• tag_resolution_binds_hash_in_its_single_round_trip (data_provider.rs:1935): per tag exactly one eth_getHeaderByNumber, zero eth_blockNumber, hash returned, tip hint fed; numeric tags stay local.
• known_number_skips_header_discovery (data_provider.rs:1974): with a known number the fetch pipeline makes zero header calls; the raw by-hash entry still makes exactly one — pinned via per-method counters on the extended start_mock_rpc mock (now serves tag params and eth_getHeaderByHash, counting block_number/header_by_number/header_by_hash).
• Full workspace: fmt/clippy/cargo-sort clean, all test targets green (108 bin unit tests).

Notes

• The tx-path branch (tx.block_number Some vs None) has no dedicated unit test — both arms funnel into the same tested inner path; constructing a full OP tx JSON mock wasn't worth the churn.
• Upstream compatibility: Finalized/Safe already used tag-param eth_getHeaderByNumber in production; Latest now uses the same call shape.

🤖 Generated with Claude Code

[mega-maxwell]

Claude review status

Living comment — rewritten in place. The review workflow keeps this single comment up to date instead of posting a new one each round, so it always describes the latest reviewed commit and the earlier text is intentionally gone. No reply is needed here; reply to a finding in its own review thread, and answer an open question in a reply on this PR. The next review round reconciles your answer.

🛠️ Review did not finish

Attempted head 78490c59 · updated 2026-08-01T15:15:18+00:00

This round did not publish: MODEL_ACTION_FAILED in phase review_retry. Anything listed below is from the last round that did. Re-run the workflow or push a new commit to try again.