# Caching - Verification Matrix

| ID | Status | Summary | Verification Approach |
|----|--------|---------|----------------------|
| CAC-001 | done | Sharded block cache with 16 default shards, LRU per shard, shard by hash[0] % num_shards, parking_lot::RwLock per shard | `tests/cac_001_tests.rs` — default shard count 16, configurable, per-shard capacity distribution, shard selection by first byte, LRU eviction, cache hit avoids RocksDB (cf_blocks_physical_get_count=0), miss then hit, remove entry. 7 tests. |
| CAC-002 | done | Sharded header cache, same strategy as block cache, default capacity 2000, separate instance | `tests/cac_002_tests.rs` — default capacity 2000, configurable, stores L2BlockHeader, independent from block cache, hit avoids RocksDB, miss then hit, LRU eviction. 7 tests. |
| CAC-003 | done | BlockRecord cache: in-memory only, derived from header on miss, updated on put_block/update_status/set_canonical | `tests/cac_003_tests.rs` — put_block inserts, cache hit avoids RocksDB, miss derives from header, not persisted (empty after reopen), update_status reflects, set_canonical reflects, from_header field accuracy. 7 tests. |
| CAC-004 | done | Canonical height index BTreeMap<u64, Bytes32> for O(log n) lookups; populated from mmap; evicted on rollback | `tests/cac_004_tests.rs` — default capacity 10K, populated by extend_chain and set_canonical, bounded eviction of lowest height, disabled when capacity=0. 5 tests. |
| CAC-005 | done | Hash-to-height reverse cache Bytes32 -> u64; used by find_common_ancestor and set_canonical to avoid header deserialization | `tests/cac_005_tests.rs` — default capacity 10K, populated on put_block and set_canonical, works for non-canonical blocks, configurable capacity. 5 tests. |
| CAC-006 | done | Cache warming on open: preload N blocks/headers from canonical tip backwards when warm_cache_on_open is true | `tests/cac_006_tests.rs` — warming enabled populates all caches (block/header/record), disabled leaves caches empty, empty store noop, depth-limited, fewer-than-depth loads all, header/record cache verified independently. Replaced old `warm_recent_blocks` with `warm_caches` that populates ALL caches. 7 tests. |
