perf(rpc): search the block log for a record instead of scanning it

`Context::record_for_hash` asks the block tree for the hash, gets the height
back, and then scanned the block-record log linearly for the matching
`(hash, height)` pair. The height was already in hand and the log is ordered by
height, so the scan was avoidable work proportional to chain length - on the
path under `getblock`, `getblockheader`, `getblockstats`, `getrawtransaction`
with a blockhash, the REST block endpoint, and `gettxoutproof`s explicit-hash
path. `verifychain` calls it once per block it checks, so that RPC was quadratic.

This is a hotter path than the chain-info fold: `getblockchaininfo` is a status
call, `getblockheader` is what a tip-following client polls.

Measured over one fixture in one process, `before_scan` against `after_search`:

  10,000 records, hash at tip:     14.59 us -> 37.4 ns        390x
  100,000 records, hash at tip:   433.40 us -> 38.5 ns     11,265x
  500,000 records, hash at tip:     3.850 ms -> 44.0 ns    87,551x
  963,124 records, hash at tip:     6.263 ms -> 42.2 ns   148,548x
  963,124 records, hash in middle:  3.448 ms -> 46.9 ns    73,548x

The new arm is flat at 37-47 ns across 96x the records: a binary search is ~20
steps at a mainnet tip. Both lookup positions are reported because measuring one
would flatter the scan - the tip is its worst case, the middle costs it half.

`BlockLog::record_at_height_hash` and `record_at_height` are not new code.
`block_source.rs` already had both, private, over `&[BlockRecord]`; they now live
on `BlockLog` beside the data and the node calls them, so this deletes a
duplicate implementation rather than adding one.

`record_at_height` keeps the direct-index shortcut, accepted only when the record
and its predecessor agree, so a log with gaps or duplicate heights falls through
to the search rather than answering with the wrong record.

Step 2 of `record_for_hash` stays linear on purpose: when the tree has no node
for the hash there is no height, so there is nothing to search on.

Seven mutations, all killed. Two survived the first pass and both were the
fixture's fault: it started at height 0, where the predecessor check can never
matter, and nothing exercised `block_by_height` with no applied tip. See
docs/benchmarks/block-record-lookup.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rabbitson87

crates/node/src/block_source.rs

@@ -14,7 +14,7 @@ use bitcoin::hex::FromHex as _;
 use bitcoin_rs_chain::{BlockTree, NodeId, TipSnapshot};
 use bitcoin_rs_index::BlockSource;
 use bitcoin_rs_primitives::Hash256;
-use bitcoin_rs_rpc::{BlockBodySource, BlockLog, BlockRecord};
+use bitcoin_rs_rpc::{BlockBodySource, BlockLog};
 use parking_lot::RwLock;
 
 /// Reads decoded Bitcoin blocks from the shared in-memory log.
@@ -82,7 +82,7 @@ impl BlockSource for NodeBlockSource {
             tree.read().active_node_at_height(height)?.hash
         } else {
             let guard = self.blocks.read();
-            record_at_height(&guard, height)?.hash
+            guard.record_at_height(height)?.hash
         };
         self.resolve_block_by_hash(height, active_hash)
     }
@@ -98,7 +98,7 @@ impl BlockSource for NodeBlockSource {
             tree.read().active_node_at_height(height)?.hash
         } else {
             let guard = self.blocks.read();
-            record_at_height(&guard, height)?.hash
+            guard.record_at_height(height)?.hash
         };
         source.block_body_range(height, hash, offset, len)
     }
@@ -138,7 +138,7 @@ impl NodeBlockSource {
     fn cached_body_bytes(&self, height: u32, hash: Hash256) -> Option<Vec<u8>> {
         let block_hex = {
             let guard = self.blocks.read();
-            let record = record_at_height_hash(&guard, height, hash)?;
+            let record = guard.record_at_height_hash(height, hash)?;
             (!record.block_hex.is_empty()).then(|| record.block_hex.clone())
         }?;
         Vec::<u8>::from_hex(&block_hex).ok()
@@ -298,47 +298,6 @@ fn serialized_header(
     })
 }
 
-fn record_at_height(records: &[BlockRecord], height: u32) -> Option<&BlockRecord> {
-    if let Ok(index) = usize::try_from(height)
-        && let Some(record) = records.get(index)
-        && record.height == height
-        && index
-            .checked_sub(1)
-            .and_then(|previous| records.get(previous))
-            .is_none_or(|previous| previous.height < height)
-    {
-        return Some(record);
-    }
-
-    let mut index = records
-        .binary_search_by_key(&height, |record| record.height)
-        .ok()?;
-    while index > 0 && records[index.saturating_sub(1)].height == height {
-        index = index.saturating_sub(1);
-    }
-    records.get(index)
-}
-
-fn record_at_height_hash(
-    records: &[BlockRecord],
-    height: u32,
-    hash: Hash256,
-) -> Option<&BlockRecord> {
-    let mut index = records
-        .binary_search_by_key(&height, |record| record.height)
-        .ok()?;
-    while index > 0 && records[index.saturating_sub(1)].height == height {
-        index = index.saturating_sub(1);
-    }
-    while index < records.len() && records[index].height == height {
-        if records[index].hash == hash {
-            return Some(&records[index]);
-        }
-        index += 1;
-    }
-    None
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -347,6 +306,7 @@ mod tests {
     use bitcoin::consensus::encode::serialize;
     use bitcoin_rs_chain::NodeStatus;
     use bitcoin_rs_primitives::Hash256;
+    use bitcoin_rs_rpc::BlockRecord;
     use std::error::Error;
 
     type TestResult = Result<(), Box<dyn Error>>;

crates/rpc/Cargo.toml

@@ -52,3 +52,7 @@ criterion.workspace = true
 [[bench]]
 name = "chaininfo"
 harness = false
+
+[[bench]]
+name = "blocklookup"
+harness = false

crates/rpc/benches/blocklookup.rs

@@ -0,0 +1,112 @@
+//! Block-record lookup cost under `getblock` and `getblockheader`.
+//!
+//! `Context::record_for_hash` resolves a hash to a block record. Step 1 asks the
+//! block tree, which answers with the height — and then scans the block-record
+//! log linearly for the matching `(hash, height)` pair, even though the log is
+//! ordered by height and the height is in hand.
+//!
+//! That log grows one entry per block forever, so `getblock`,
+//! `getblockheader`, `getblockstats`, `getrawtransaction` with a blockhash, the
+//! REST block endpoint and `gettxoutproof`'s explicit-hash path each pay a walk
+//! proportional to chain length. `verifychain` pays one per block it checks.
+//!
+//! Both arms of the refactor set run here over one fixture in one process, so
+//! the ratio cannot be confounded by the rebuild and baseline drift recorded in
+//! `docs/solutions/best-practices/criterion-bench-trust-rebuild-drift-baselines-allocator.md`.
+//! `before_scan` is the linear find that was there; `after_search` is the
+//! height-keyed binary search plus duplicate-height walk that replaced it.
+//!
+//! Two lookup positions are measured. A hash at the *end* of the log is the
+//! best case for a forward scan and the one a tip-following client asks for; a
+//! hash in the *middle* is what a wallet rescanning history asks for. Measuring
+//! only the tip would report the linear scan at its most flattering.
+// PERF: Criterion emits public harness items whose docs are irrelevant here.
+#![allow(missing_docs)]
+// A fixture that fails to build has no meaningful degraded mode.
+#![allow(clippy::expect_used)]
+
+use std::hint::black_box;
+use std::sync::Arc;
+
+use bitcoin_rs_primitives::Hash256;
+use bitcoin_rs_rpc::{BlockLog, BlockRecord, Context};
+use criterion::{Criterion, criterion_group, criterion_main};
+
+/// Log lengths to measure. The last is a mainnet tip at the time of writing.
+const LOG_LENGTHS: [u32; 4] = [10_000, 100_000, 500_000, 963_124];
+
+fn hash_for(height: u32) -> Hash256 {
+    let mut hash = [0_u8; 32];
+    hash[..4].copy_from_slice(&height.to_le_bytes());
+    Hash256::from_le_bytes(&hash)
+}
+
+fn log_with_records(count: u32) -> Arc<Context> {
+    let ctx = Arc::new(Context::new());
+    {
+        let mut blocks = ctx.blocks.write();
+        blocks.reserve(count as usize);
+        for height in 0..count {
+            let mut record = BlockRecord::synthetic(height, hash_for(height));
+            record.body_size = 1_000_000 + (height as usize % 400_000);
+            record.tx_count = 1 + (height as usize % 3_000);
+            record.time = 1_231_006_505 + height * 600;
+            blocks.push(record);
+        }
+    }
+    ctx
+}
+
+/// The scan that was in `record_for_hash`, kept here as the `before` arm and as
+/// the oracle the search is checked against.
+///
+/// Written out rather than called through the crate: it is three lines, and an
+/// oracle that shares code with the implementation cannot disagree with it.
+fn scan_for(log: &BlockLog, height: u32, hash: Hash256) -> Option<&BlockRecord> {
+    log.iter()
+        .find(|candidate| candidate.hash == hash && candidate.height == height)
+}
+
+fn bench_lookup(c: &mut Criterion) {
+    let mut group = c.benchmark_group("block_record_lookup");
+    group.sample_size(20);
+
+    for count in LOG_LENGTHS {
+        let ctx = log_with_records(count);
+        let log = ctx.blocks.read();
+
+        for (label, height) in [("tip", count.saturating_sub(1)), ("middle", count / 2)] {
+            let hash = hash_for(height);
+
+            // Prove both arms find the same record before timing either. An arm
+            // that found nothing would be timed as a spectacular, empty win.
+            assert_eq!(
+                scan_for(&log, height, hash).map(|record| record.height),
+                log.record_at_height_hash(height, hash)
+                    .map(|record| record.height),
+                "the arms disagree at {label}; the benchmark would be meaningless"
+            );
+
+            group.bench_function(format!("before_scan/{label}/{count}"), |b| {
+                b.iter(|| black_box(scan_for(&log, height, hash).map(|record| record.time)));
+            });
+            group.bench_function(format!("after_search/{label}/{count}"), |b| {
+                b.iter(|| {
+                    black_box(
+                        log.record_at_height_hash(height, hash)
+                            .map(|record| record.time),
+                    )
+                });
+            });
+        }
+    }
+
+    group.finish();
+}
+
+criterion_group! {
+    name = benches;
+    config = Criterion::default();
+    targets = bench_lookup
+}
+criterion_main!(benches);