perf(rpc): resolve block records by binary search, not by walking the chain

[rabbitson87]

Found while auditing #85 and #86, and larger than either of them.

The problem

Context::record_for_hash walked every record in the block log to find one. The log holds one entry per applied block and nothing removes it, so at a mainnet tip that is ~963k comparisons per call — and getblock, getblockheader and the index read path's block_at_height all land there.

It is the same shape as the gettxoutproof scan that #85 removes, on a hotter path.

The fix

Step 1 already knows the height, because the block tree gave it. That makes the lookup a binary search over a height-ordered log.

The log is append-only in height order — add_block pushes, and the only removal is the tail pop a disconnect performs on the applied tip. The codebase already relied on this: crates/node/src/block_source.rs had record_at_height and record_at_height_hash doing exactly this search, with tests.

Rather than copy them, they move to crates/rpc beside BlockRecord and node imports them — one implementation for both, and 40 lines of duplicate deleted. Context::block_by_height and Context::block_hash_at_height were scanning the same way and now use them too.

Step 2 stays linear on purpose. Without the tree there is no height to search on, and a hash-keyed index would have to be maintained for every block to serve a path only legacy state reaches. The comment says so.

Tests

Three cover what the rpc side never had:

• a hash is matched within a duplicate-height run, rather than the run's first record being assumed — a reorg leaves the losing block in the log beside the winner
• a hash absent from that run does not resolve to a sibling
• a log that does not start at height zero still resolves

The duplicate-height test is shaped deliberately: heights [1, 1, 2] put the dense fast path's index straight onto the second duplicate, where the height check alone would accept it and only the preceding-record guard rejects it.

An earlier version of that test used heights starting at zero. It passed — and the mutation audit showed it passed with the guard removed, because an index past the end of a 3-record log never enters the fast path at all. The test was not testing what its name claimed. This is the shape that does.

Mutation audit

Mutation	rpc	node
baseline	177 passed	442 passed
ignore the hash, return the first record at the height	2 failed — the new test and the pre-existing block_by_height_prefers_tree_identity_over_stale_cache	1 failed
dense fast path without its preceding-record guard	1 failed	1 failed
restored	177 passed	442 passed

An earlier run of this audit is not reported here because it was invalid, not because it passed: a second audit was editing the same file concurrently, and its baseline disagreed with its own restored run. Re-run serially.

Not in this PR

BlockRecord still carries an 80-byte header the block tree also holds, and the tree itself never drops a node. Both are per-block memory costs; separate work.

🤖 Generated with Claude Code

---

Update: the measurement this PR was missing

This PR argued for a change without a number. It has one now — and the audit was
re-run at seven mutations instead of two.

crates/rpc/benches/blocklookup.rs, both arms over one fixture in one process:

Records	Hash at	before_scan	after_search	ratio
10,000	tip	12.17 µs	39.6 ns	307x
100,000	tip	415.9 µs	50.2 ns	8,285x
500,000	tip	3.737 ms	46.1 ns	81,092x
963,124	tip	7.707 ms	48.3 ns	159,569x
963,124	middle	3.328 ms	48.6 ns	68,528x

Flat at 37–50 ns across 96x the records: ~20 binary-search steps at a mainnet
tip. Two lookup positions are measured because reporting one would flatter
the scan — the tip is its worst case, the middle costs it half.

The linear scan is written out in the benchmark and in the new tests rather than
called through the crate: it is two lines, and an oracle that shares code with
the implementation cannot disagree with it.

Three more tests

Two sweep the search against that scan over every height in and around the
fixture and every hash in it — including hashes at the wrong height, which
must find nothing. A search is wrong at its boundaries, and a test that picks one
pair picks whether it visits them.

The third closes a real gap: block_by_height with no applied tip was
uncovered. Replacing that fallback's whole body with "the last record in the
log" turned nothing red. block_by_height_without_an_applied_tip_reads_the_log
is the only test that kills that mutation.

The shared fixture starts at height 1 rather than 0, and that is load-bearing:
the preceding-record guard only matters when index h holds a record at height
h that is not the first at that height, and a log starting at zero can never
be in that state.

Re-audited

Mutation	Result
the search stops at the first record of the height run	3 tests failed
record_at_height_hash skips the rewind to the run head	3 tests failed
record_at_height skips the rewind to the run head	3 tests failed
record_at_height trusts the direct index unconditionally	4 tests failed
record_at_height drops only the preceding-record guard	3 tests failed
record_for_hash ignores the hash and takes the run head	1 test failed
block_by_height without a tip answers the last record	1 test failed

Baseline and restored: 181 passed, 0 failed.

Provenance

This change was written a second time on perf/chaininfo-fold (#89) before this
PR was noticed. That copy is reverted there; the measurement, the tests and the
audit from it are ported here. #89 keeps only the chain-info fold.

Full write-up: docs/benchmarks/block-record-lookup.md.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 02a71dd6-c2c0-40be-982e-d9da9708861c

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}