validation: prefetch blocks while connecting #36000

This is creating a new ThreadPool on each invocation of ActivateBestChain. This is what's causing the logs in #36000 (comment). The BlockFetcher or at least a shared pointer to a ThreadPool that can be passed to it should be owned by the Chainstate, so it can keep the fetcher threads alive throughout IBD.

This works fine for -reindex-chainstate, because it is one long ActivateBestChain call. But for IBD this gets called many times.

Yes, thanks @fanquake and @andrewtoth, I also just noticed that BlockFetcher was indeed recreated on every ActivateBestChain() call: I’ve pushed a fix that keeps it alive on Chainstate, and will remeasure IBD performance. Added you both as coauthors, thanks for the tests!

I’ve also reduced the default queue size from 4 to 2, since the results so far indicate that 4 isn’t worthwhile and single threaded for now for simplicity - proper HDD measurements may change this again later: <img width="235" height="201" alt="image" src="https://github.com/user-attachments/assets/3225e3ad-a924-46bb-89b4-6124cb4862b9" />

Also removed configurability to make the patch even simpler - we can add it back later if needed.

We can make this useful for reorgs here by checking if the pindexFork is not our current tip, then clearing the prefetch queue and start fetching from the fork index. We would then be fetching the sibling while we read the current tip synchronously in DisconnectTip.

Thanks, implemented. Before disconnecting the current tip, activation now clears followups for the previous candidate and fills the queue from the first sibling. This overlaps that read with DisconnectTip().

Should we just pass in height here, and internally start at height + 1? We are adding the + 1 to callsites, so this would probably be cleaner to handle it in here instead.

    void Prefetch(const CBlockIndex& index_most_work, int height) EXCLUSIVE_LOCKS_REQUIRED(::cs_main)

I think next_height is clearer here because the argument is the first height to enqueue: there's no "current" height here, it doesn't make sense to give an unrelated block height to the fetcher. But the names should be consolidated (pending vs queued vs followups vs provided vs saved), I kept renaming these and they don't match anymore.

I think this method might be more efficient as a sliding window rather than just adding all pending tasks only when the validation thread has emptied the queue. The current way has the worker thread go idle once it hits the max queue size and waits until validation catches up, whereas we can make sure the worker thread is always either working or bumping up against the max queue size.

        while (m_pending.size() < QUEUE_SIZE) {
            auto* next{index_most_work.GetAncestor(next_height + static_cast<int>(m_pending.size()))};
            if (!next || !Enqueue(*next)) break;
        }

Thanks, implemented. FillQueue() (renamed) now starts from the number of queued followups and fills every missing slot.

I originally waited for the queue to empty so adjacent reads would be submitted together (from the same file probably), which I thought might improve file-cache locality, but your measurements indicate that's not the case, so I'll remeasure. Instead of the while loop above (which might be infinite if m_pending doesn't get updated in the loop) I used a bounded loop.

What if we moved this out into a header in src/node/blockfetcher.h, and allowed passing the thread name in the constructor? Then with a simple commit on top (and shortening index thread names)

<details><summary>Index patch</summary>

diff --git a/src/index/base.cpp b/src/index/base.cpp
index 5820448bb7..4225796fc0 100644
--- a/src/index/base.cpp
+++ b/src/index/base.cpp
@@ -11,6 +11,7 @@
 #include <interfaces/types.h>
 #include <kernel/types.h>
 #include <node/abort.h>
+#include <node/blockfetcher.h>
 #include <node/blockstorage.h>
 #include <node/context.h>
 #include <node/database_args.h>
@@ -209,6 +210,7 @@ void BaseIndex::Sync()
 {
     const CBlockIndex* pindex = m_best_block_index.load();
     if (!m_synced) {
+        node::BlockFetcher fetcher{m_chainstate->m_blockman, m_thread_name};
         auto last_log_time{NodeClock::now()};
         auto last_locator_write_time{last_log_time};
         while (true) {
@@ -249,8 +251,14 @@ void BaseIndex::Sync()
             }
             pindex = pindex_next;
 
-
-            if (!ProcessBlock(pindex)) return; // error logged internally
+            std::shared_ptr<const CBlock> loaded;
+            WITH_LOCK(::cs_main, {
+                loaded = fetcher.Load(pindex->GetBlockHash());
+                if (const auto* tip{m_chainstate->m_chain.Tip()}) {
+                    fetcher.FillQueue(*tip, pindex->nHeight + 1);
+                }
+            });
+            if (!ProcessBlock(pindex, loaded.get())) return; // error logged internally
 
             auto current_time{NodeClock::now()};
             if (current_time - last_log_time >= SYNC_LOG_INTERVAL) {

</details>

we could have parallelism for all indexes. With this patch I measured speedups of 30% for txindex, 50% for blockfilterindex, and 6% for coinstatsindex. We could improve the latter two even more with an optional prefetch of the undo data as a follow-up.

cc @furszy what do you think of this approach to parallelizing the indexing code? It would stack easily with #34489 for txospenderindex and txindex; it should be as simple as increasing the threadcount and queue depth of the blockfetcher (since each append would no longer be writing so the bottleneck would just be reading/deserializing blocks).

Thanks, I like this approach. I moved BlockFetcher into src/node/blockfetcher.{h,cpp} in this push and added you as a co-author - although I initially forgot to add it to the Kernel build, and ReadBlock introduced a circular dependency. Since the extraction is useful independently of the index follow-up and makes the diff simpler, I also wired it into BaseIndex::Sync() locally to make sure the interface works. Your results make index prefetching worth doing, but I left the index wiring and configurable thread name out so we can finish the validation path in this PR first.

One detail for the follow-up is thread naming: ThreadPool adds a .xx suffix, so the current blkfltbscidx, coinstatsidx, and txospenderidx names would exceed the limit accepted by ThreadRename() before it adds b-. Since we just shortened these names in this release, maybe we should leave room for the worker suffix now, even if index prefetching remains a follow-up, to avoid renaming the threads again later (assuming each index will get their own ThreadPool, which would kind of defeat the purpose of handling shared resources).

And about the index parallelization work: this change is independent of batching index writes or parallelizing MuHash, so @furszy's ideas can still make sense on top. Before batching or adding more index concurrency, I think we should fix the concrete Stop()/Init() reader issue and account for pre-genesis sync and flush callbacks, stale-tip rewind after a disconnect, and blockfilter/coinstats crash-reorg recovery (I found several of these issues by repeatedly crashing during sync, and while some paths are theoretical and can wait, we should account for these states first).

There is also a separate follow-up for context-free validation: the prefetched block is owned by the worker until its future is consumed, so CheckBlock() can safely populate its memoization flags there, and I left a TODO at that point.

So I agree index block prefetching should be a follow-up, but before batching or parallelizing the indexes, I'd like to harden them to be more crash-safe.

I don't think there's a circular dependency. We don't need the ReadBlockFn (so we also don't need BlockFetcher to be wrapped in a std::unique_ptr):

<details><summary>Patch</summary>

diff --git a/src/node/blockfetcher.cpp b/src/node/blockfetcher.cpp
index cc8c65e182..0528622606 100644
--- a/src/node/blockfetcher.cpp
+++ b/src/node/blockfetcher.cpp
@@ -5,12 +5,11 @@
 #include <node/blockfetcher.h>
 
 #include <chain.h>
-#include <flatfile.h>
 #include <kernel/cs_main.h>
+#include <node/blockstorage.h>
 #include <primitives/block.h>
 #include <sync.h>
 #include <uint256.h>
-#include <util/expected.h>
 #include <util/threadpool.h>
 
 #include <cstddef>
@@ -31,9 +30,9 @@ std::shared_ptr<const CBlock> BlockFetcher::PopFollowup()
 bool BlockFetcher::Enqueue(const CBlockIndex& index)
 {
     if (m_pool.WorkersCount() == 0) m_pool.Start(WORKER_COUNT);
-    auto followup{m_pool.Submit([&read_block = m_read_block, hash = index.GetBlockHash(), pos = index.GetBlockPos()]() -> std::shared_ptr<const CBlock> {
+    auto followup{m_pool.Submit([&blockman = m_blockman, hash = index.GetBlockHash(), pos = index.GetBlockPos()]() -> std::shared_ptr<const CBlock> {
         auto block{std::make_shared<CBlock>()};
-        if (!read_block(*block, pos, hash)) return nullptr;
+        if (!blockman.ReadBlock(*block, pos, hash)) return nullptr;
         // TODO The block is owned by the worker until its future is consumed, so CheckBlock() may safely set its memoization flags.
         return block;
     })};
diff --git a/src/node/blockfetcher.h b/src/node/blockfetcher.h
index 88290a39af..40e489f328 100644
--- a/src/node/blockfetcher.h
+++ b/src/node/blockfetcher.h
@@ -5,33 +5,30 @@
 #ifndef BITCOIN_NODE_BLOCKFETCHER_H
 #define BITCOIN_NODE_BLOCKFETCHER_H
 
+#include <attributes.h>
 #include <kernel/cs_main.h>
 #include <sync.h>
 #include <util/threadpool.h>
 
 #include <cstdint>
 #include <deque>
-#include <functional>
 #include <future>
 #include <memory>
-#include <string>
-#include <utility>
 
 class CBlock;
 class CBlockIndex;
-struct FlatFilePos;
 class uint256;
 
 namespace node {
+class BlockManager;
+
 /** Supplies blocks to validation. Destruction waits for any queued reads. */
 class BlockFetcher
 {
-    using ReadBlockFn = std::function<bool(CBlock&, const FlatFilePos&, const uint256&)>;
-
     static constexpr uint32_t WORKER_COUNT{1};
     static constexpr uint32_t QUEUE_SIZE{2};
 
-    const ReadBlockFn m_read_block;
+    const BlockManager& m_blockman;
     ThreadPool m_pool{"blockread"};
     std::deque<std::future<std::shared_ptr<const CBlock>>> m_followups GUARDED_BY(::cs_main);
 
@@ -40,7 +37,7 @@ class BlockFetcher
     bool Enqueue(const CBlockIndex& index) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
 
 public:
-    explicit BlockFetcher(ReadBlockFn read_block) : m_read_block{std::move(read_block)} {}
+    explicit BlockFetcher(const BlockManager& blockman LIFETIMEBOUND) : m_blockman{blockman} {}
 
     void Clear() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
     std::shared_ptr<const CBlock> Load(const uint256& hash) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
diff --git a/src/validation.cpp b/src/validation.cpp
index abb2a612be..be006fdd0d 100644
--- a/src/validation.cpp
+++ b/src/validation.cpp
@@ -29,7 +29,6 @@
 #include <kernel/types.h>
 #include <kernel/warning.h>
 #include <logging/timer.h>
-#include <node/blockfetcher.h>
 #include <node/blockstorage.h>
 #include <node/utxo_snapshot.h>
 #include <policy/ephemeral_policy.h>
@@ -1876,17 +1875,13 @@ Chainstate::Chainstate(
     BlockManager& blockman,
     ChainstateManager& chainman,
     std::optional<uint256> from_snapshot_blockhash)
-    : m_block_fetcher{std::make_unique<node::BlockFetcher>([blockman = &blockman](CBlock& block, const FlatFilePos& pos, const uint256& hash) {
-          return blockman->ReadBlock(block, pos, hash);
-      })},
+    : m_block_fetcher{blockman},
       m_mempool(mempool),
       m_blockman(blockman),
       m_chainman(chainman),
       m_assumeutxo(from_snapshot_blockhash ? Assumeutxo::UNVALIDATED : Assumeutxo::VALIDATED),
       m_from_snapshot_blockhash(from_snapshot_blockhash) {}
 
-Chainstate::~Chainstate() = default;
-
 fs::path Chainstate::StoragePath() const
 {
     fs::path path{m_chainman.m_options.datadir / "chainstate"};
@@ -3222,8 +3217,8 @@ bool Chainstate::ActivateBestChainStep(BlockValidationState& state, CBlockIndex&
     const CBlockIndex* pindexFork = m_chain.FindFork(index_most_work);
     const CBlockIndex* read_ahead_tip{provided_block ? index_most_work.pprev : &index_most_work}; // Avoid rereading the provided block
     if (pindexFork && pindexFork != pindexOldTip) {
-        m_block_fetcher->Clear();
-        if (read_ahead_tip) m_block_fetcher->FillQueue(*read_ahead_tip, pindexFork->nHeight + 1);
+        m_block_fetcher.Clear();
+        if (read_ahead_tip) m_block_fetcher.FillQueue(*read_ahead_tip, pindexFork->nHeight + 1);
     }
 
     // Disconnect active blocks which are no longer in the best chain.
@@ -3263,8 +3258,8 @@ bool Chainstate::ActivateBestChainStep(BlockValidationState& state, CBlockIndex&
 
         // Connect new blocks.
         for (CBlockIndex* pindexConnect : vpindexToConnect | std::views::reverse) {
-            auto block_to_connect{provided_block && pindexConnect == &index_most_work ? provided_block : m_block_fetcher->Load(pindexConnect->GetBlockHash())};
-            if (read_ahead_tip) m_block_fetcher->FillQueue(*read_ahead_tip, pindexConnect->nHeight + 1);
+            auto block_to_connect{provided_block && pindexConnect == &index_most_work ? provided_block : m_block_fetcher.Load(pindexConnect->GetBlockHash())};
+            if (read_ahead_tip) m_block_fetcher.FillQueue(*read_ahead_tip, pindexConnect->nHeight + 1);
             if (!ConnectTip(state, pindexConnect, std::move(block_to_connect), connected_blocks, disconnectpool)) {
                 if (state.IsInvalid()) {
                     // The block violates a consensus rule.
diff --git a/src/validation.h b/src/validation.h
index 2c67d1aa32..2793ccb92b 100644
--- a/src/validation.h
+++ b/src/validation.h
@@ -18,6 +18,7 @@
 #include <kernel/chainparams.h>
 #include <kernel/chainstatemanager_opts.h>
 #include <kernel/cs_main.h> // IWYU pragma: export
+#include <node/blockfetcher.h>
 #include <node/blockstorage.h>
 #include <policy/feerate.h>
 #include <policy/packages.h>
@@ -63,7 +64,6 @@ namespace kernel {
 struct ChainstateRole;
 } // namespace kernel
 namespace node {
-class BlockFetcher;
 class SnapshotMetadata;
 } // namespace node
 namespace Consensus {
@@ -562,7 +562,7 @@ protected:
     Mutex m_chainstate_mutex;
 
     //! Reads blocks ahead during chain activation.
-    std::unique_ptr<node::BlockFetcher> m_block_fetcher;
+    node::BlockFetcher m_block_fetcher;
 
     //! Optional mempool that is kept in sync with the chain.
     //! Only the active chainstate has a mempool.
@@ -594,7 +594,6 @@ public:
         node::BlockManager& blockman,
         ChainstateManager& chainman,
         std::optional<uint256> from_snapshot_blockhash = std::nullopt);
-    ~Chainstate();
 
     //! Return path to chainstate leveldb directory.
     fs::path StoragePath() const;

</details>

The full patch still introduces the exact cycle: node/blockfetcher -> node/blockstorage -> validation -> node/blockfetcher, can you please check it with lint-circular-dependencies.py?

Ahh I did not use the linter, I just compiled. Indeed, my patch fails lint. Thanks!

Does this warrant a release note? It is covered already by "performance improvements" in every release note.

I expect this to land in a future release, so for now I'd keep it

nit: we can remove the dates altogether. same for header file.

// Copyright (c) The Bitcoin Core developers

Not sure we should have this TODO here. I don't know if there is consensus for this yet. Changing the validation ordering is a different beast than just parallelizing reading a block from disk and deserializing.

Could we pass these as default parameters to the constructor, and call ThreadPool::Start on construction? That way we can inject different values. Why do we wait to start the threadpool later? IMO it's cleaner/more RAII to start in constructor.

We should call Clear here, since on a miss we have gotten out of sync of the fetching.

Since we have multiple worker threads now, maybe we can take advantage of the multi-Submit overload whenever we have an empty m_followups? That would awaken all threads at once. This would happen on every ActivateBestChainStep call, so could show some improvement?

Also, if we have multiple threads and queue depth, we might want to allow disabling this mechanism for low memory systems. Maybe worth it to just be an on/off toggle (that defaults to on)? Or maybe a configuration of threads only and the queue depth is 2*threads? Just trying to think of ways to make it simple instead of adding all kinds of configuration options.

@l0rinc just wondering if you had any thoughts on these suggestions?

I started investigating your suggestions, then got pulled into a few issues for this release and forgot to follow up here. I prototyped batching when the queue is empty, but the extra task-building code was hard to justify without a measured speedup - I can measure them later. But I did add -blockreadahead=<n> with a default of 2 readers and a queue capacity of 2*n blocks. Setting it to 0 disables read-ahead. Thanks for the reminder.

I played with it a bit more and massaged it until I found a setup I liked. I forgot that we already have a batch overload that avoids locking and notifying for each entry - missing reads now use it, including refills of a partly drained queue. Let me know what you think, I’ll come back with the benchmarks tomorrow.

Now that the code for multi-submit isn't more complicated than single-submit (which was the case in my original attempt), the 1% speedup is probably worth it (I should update the assumevalid in my benchmarks).

<details><summary>master vs single-submit vs multi-submit</summary>

for DBCACHE in 2000; do
  COMMITS="ed7dd7cf4e1561a97edf72eba29a67b14e28c717 7c4efd1174070eba967fb0803c2080500b77ee10 c5aafe25576d341451d679816ae0d1f8c8405c7e"
  STOP=968869; CC=gcc; CXX=g++
  BASE_DIR="/mnt/my_storage"; DATA_DIR="$BASE_DIR/BitcoinData"; LOG_DIR="$BASE_DIR/logs"
  (echo ""; for c in $COMMITS; do git fetch -q origin "$c" 2>/dev/null || true; git log -1 --pretty='%h %s' "$c" || exit 1; done) &&
  (echo "" && echo "$(date -I) | reindex-chainstate | ${STOP} blocks | dbcache ${DBCACHE} | $(hostname) | $(uname -m) | $(lscpu | grep 'Model name' | head -1 | cut -d: -f2 | xargs) | $(nproc) threads | $(free -h | awk '/^Mem:/{print $2}') RAM | $(lsblk -no ROTA $(df --output=source $BASE_DIR | tail -1) | grep -q 1 && echo HDD || echo SSD)"; echo "") &&
  hyperfine   --sort command   --runs 1   --export-json "$BASE_DIR/rdx-$(sed -E 's/([a-f0-9]{8})[a-f0-9]* ?/\1-/g;s/-$//'<<<"$COMMITS")-$STOP-$DBCACHE-$CC.json"   --parameter-list COMMIT ${COMMITS// /,}   --prepare "killall -9 bitcoind 2>/dev/null; rm -f ./build/bin/bitcoind; git clean -fxd; git reset --hard {COMMIT} && \
CC=$CC CXX=$CXX cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && ninja -C build bitcoind -j1 && \
./build/bin/bitcoind -datadir=$DATA_DIR -stopatheight=$STOP -printtoconsole=0; sleep 20 && rm -f $DATA_DIR/debug.log && rm -rfd $DATA_DIR/chainstate $DATA_DIR/indexes"     --conclude "killall bitcoind || true; sleep 100; sync; echo 3 | sudo tee /proc/sys/vm/drop_caches; \
grep -q 'height=0' $DATA_DIR/debug.log && \
grep -q 'height=$STOP' $DATA_DIR/debug.log && \
grep 'Bitcoin Core version' $DATA_DIR/debug.log | grep -q \"\$(git rev-parse --short=12 {COMMIT})\" && \
cp $DATA_DIR/debug.log $LOG_DIR/debug-{COMMIT}-\$(date +%s).log"   "COMPILER=$CC ./build/bin/bitcoind -datadir=$DATA_DIR -stopatheight=$STOP -dbcache=$DBCACHE -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0"; done

ed7dd7cf4e Merge bitcoin/bitcoin#34371: wallet: allow importprunedfunds for spending transactions
7c4efd1174 doc: add block read-ahead release note
c5aafe2557 doc: add block read-ahead release note

2026-09-29 | reindex-chainstate | 968869 blocks | dbcache 2000 | ssd-ryzen | x86_64 | AMD Ryzen 7 3700X 8-Core Processor | 16 threads | 62Gi RAM | SSD

Benchmark 1: COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = ed7dd7cf4e1561a97edf72eba29a67b14e28c717)
  Time (abs ≡):        12430.900 s               [User: 36689.125 s, System: 2521.533 s]

Benchmark 2: COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 7c4efd1174070eba967fb0803c2080500b77ee10)
  Time (abs ≡):        9641.134 s               [User: 37300.454 s, System: 2003.075 s]

Benchmark 3: COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = c5aafe25576d341451d679816ae0d1f8c8405c7e)
  Time (abs ≡):        9562.801 s               [User: 37275.991 s, System: 2185.462 s]

Relative speed comparison
        1.30          COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = ed7dd7cf4e1561a97edf72eba29a67b14e28c717)
        1.01          COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 7c4efd1174070eba967fb0803c2080500b77ee10)
        1.00          COMPILER=gcc ./build/bin/bitcoind -datadir=/mnt/my_storage/BitcoinData -stopatheight=968869 -dbcache=2000 -reindex-chainstate -assumevalid=00000000000000000000ccebd6d74d9194d8dcdc1d177c478e094bfad51ba5ac -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = c5aafe25576d341451d679816ae0d1f8c8405c7e)

</details>

The release notes are stale. There are now multiple threads.

This comment is not very helpful IMO. Why would anyone care about destruction waiting on queued reads? Something like this would be better.

/**
 * Reads and deserializes blocks in parallel starting from a requested block index.
 * Useful for improving performance when scanning blocks.
 **/

This comment is a bit cryptic.

    // If we have a provided block, we don't need to read it so we can stop reading ahead at the previous block.
    const CBlockIndex* read_ahead_tip{provided_block ? index_most_work.pprev : &index_most_work};

When a block was rejected, blocks read ahead for its branch could remain in memory indefinitely.

diff --git a/src/validation.cpp b/src/validation.cpp
index 86a2c8a2a4..0a14db9e9b 100644
--- a/src/validation.cpp
+++ b/src/validation.cpp
@@ -3256,7 +3256,8 @@ bool Chainstate::ActivateBestChainStep(BlockValidationState& state, CBlockIndex&
             if (read_ahead_tip) m_block_fetcher->FillQueue(*read_ahead_tip, pindexConnect->nHeight + 1);
             if (!ConnectTip(state, pindexConnect, std::move(block_to_connect), connected_blocks, disconnectpool)) {
                 if (state.IsInvalid()) {
-                    // The block violates a consensus rule.
+                    // The block violates a consensus rule. Discard any prefetched descendants.
+                    m_block_fetcher->Clear();
                     if (state.GetResult() != BlockValidationResult::BLOCK_MUTATED) {
                         InvalidChainFound(vpindexToConnect.front());
                     }

We should bound this to a max value, no?

I know we usually do that. I didn’t see the need here, but I don’t mind. Pushed a cap of 16 readers per chainstate.

Well without this guard the application could spawn millions of threads if misconfigured?

Sure, but we don't usually guard against user error like -dbcache=-1 or similar - and I did apply it, I was just hesitant because of the reasons above.

Should we also add this to the reduce memory usage docs?

It was already there, but I updated it in the latest push to cover the cap and queue capacity.

I don't see the purpose of this line. Seems like it will always be a no-op. I think it should be removed.

I'm not sure whether it wasn't needed before, but FillQueue now handles cleanup when the read-ahead range ends, so it isn't needed anymore.

Instead of passing a time_point, could we pass const CBlockIndex* read_ahead_tip? Then we could do

if (!block_to_connect) {
    block_to_connect = m_block_fetcher->Load(pindexNew->GetBlockHash());
}
if (read_ahead_tip) {
    m_block_fetcher->FillQueue(*read_ahead_tip, pindexNew->nHeight + 1);
}

inside ConnectTip instead, and not have to adjust any of the timing variables?

Thanks, this minimizes the diff, I like the outcome. Loading and refilling now happen inside ConnectTip, keeping the existing timing variables. FillQueue handles the guard internally, so its callers don't need one.

nit: Assert() aborts here instead of throwing, so if the retry path regresses, test_bitcoin dies with no Boost report and the remaining blockmanager_tests cases don't run. This file already uses BOOST_REQUIRE(block) for this at lines 169 and 197:

suggestion:

     const auto loaded{fetcher.Load(hash)};
     BOOST_REQUIRE(loaded);
     BOOST_CHECK_EQUAL(loaded->GetHash(), hash);

I consider the loaded block a precondition for the hash comparison, so I used Assert() deliberately to keep it a simple one-liner.

nit: this can now be util::NotNullUniquePtr<node::BlockFetcher>.

Indeed, rebased & switched.

I also find this comment cryptic. I'm not sure it's useful.

            } catch (std::exception&) {}

I over-compressed the comment, and I meant to explain why it's okay to swallow the exception. I kept the rationale but clarified it: ConnectTip() retries failed async read-ahead synchronously.

    """Returns the number of blocks ConnectTip() did not have to read from disk since log_start."""

    """Returns the startup lines logged by the block read-ahead workers, one per worker thread."""

I'm not sure what this comment is here for? I think it should be removed.

Removed

Why do we repeat this line here? Seems like a redundant assertion that can be removed?

This checks restoration after invalidate/reconsider, which the earlier assertion doesn't cover. We could also assert height 0 immediately after invalidation to make that transition explicit.

Not sure why we assert this here either? This isn't what's under test here. I think we can remove this line and blockcount = node.getblockcount() above.

Thanks, removed the height assertion and its saved value

Maybe something like this is more clear:

    //! Clear queued reads. Queued block reads will no longer be returned via Load, but will still complete asynchronously.

Thanks, clarified that clearing results doesn't cancel submitted reads and documented Load() and FillQueue().

I ran a reindex-chainstate with the latest code here, and it was 14 minutes slower at 2h 02m. Maybe it is worth reverting to single task submission, which would make this a bit simpler?

My comparison favored the bulk version slightly. I'll run a few more tests a bit later and see if we need to revert this.

Maybe it is worth reverting to single task submission

I tested again against submitting each block read separately to compare single-task scheduling with bulk submission and it still shows a 1% speedup for me while the code isn't any more complicated so I think we should keep it now.

<details><summary>temp: use single-task block read-ahead submission</summary>

diff --git a/src/node/blockfetcher.cpp b/src/node/blockfetcher.cpp
index 5e7465cbce..518086d4e0 100644
--- a/src/node/blockfetcher.cpp
+++ b/src/node/blockfetcher.cpp
@@ -17,10 +17,8 @@
 #include <algorithm>
 #include <cstddef>
 #include <exception>
-#include <iterator>
 #include <memory>
 #include <utility>
-#include <vector>
 
 namespace node {
 BlockFetcher::BlockFetcher(ReadBlockFn read_block, int32_t thread_count)
@@ -54,17 +52,15 @@ void BlockFetcher::FillQueue(const CBlockIndex* last_index, int next_height)
         Clear();
         return;
     }
-    std::vector<ReadTask> tasks;
     for (size_t i{m_followups.size()}; i < m_thread_count * BLOCKS_PER_READ_AHEAD_THREAD; ++i) {
         const auto* next{last_index->GetAncestor(next_height + i)};
         if (!next || !(next->nStatus & BLOCK_HAVE_DATA)) break;
-        tasks.emplace_back([this, hash = next->GetBlockHash(), pos = next->GetBlockPos()] {
+        if (auto followup{m_pool.Submit([this, hash = next->GetBlockHash(), pos = next->GetBlockPos()]() -> std::shared_ptr<const CBlock> {
             try {
                 if (auto block{std::make_shared<CBlock>()}; m_read_block(*block, pos, hash)) return block;
             } catch (std::exception&) {} // ConnectTip() retries failed read-ahead synchronously
-            return std::shared_ptr<CBlock>{};
-        });
+            return nullptr;
+        })}) m_followups.emplace_back(std::move(*followup));
     }
-    if (auto followups{m_pool.Submit(std::move(tasks))}) std::ranges::move(*followups, std::back_inserter(m_followups));
 }
 } // namespace node
diff --git a/src/node/blockfetcher.h b/src/node/blockfetcher.h
index e158132322..7d53b25317 100644
--- a/src/node/blockfetcher.h
+++ b/src/node/blockfetcher.h
@@ -26,7 +26,6 @@ namespace node {
 class BlockFetcher
 {
     using ReadBlockFn = std::function<bool(CBlock&, const FlatFilePos&, const uint256&)>;
-    using ReadTask = std::function<std::shared_ptr<const CBlock>()>;
 
     const ReadBlockFn m_read_block;
     const int32_t m_thread_count;

</details>

<details><summary>2026-10-14 | reindex-chainstate | 968869 blocks | dbcache 3000 | ssd-ryzen | x86_64 | AMD Ryzen 7 3700X 8-Core Processor | 16 threads | 62Gi RAM | SSD</summary>

for DBCACHE in 3000; do \
  COMMITS="81006fa18ce7177ba36046ae35ee3198b48b5501 dcf775943e168813d898cbdb2092c654dfbf383b"; \
  STOP=968869; export CC=gcc CXX=g++; \
  BASE_DIR="/mnt/my_storage"; DATA_DIR="$BASE_DIR/BitcoinData"; LOG_DIR="$BASE_DIR/logs"; \
  mkdir -p "$DATA_DIR" "$LOG_DIR" && \
  python3 -c 'import fcntl, sys; f = open(sys.argv[1], "a"); fcntl.lockf(f, fcntl.LOCK_EX | fcntl.LOCK_NB)' "$DATA_DIR/.lock" && \
  (echo ""; for c in $COMMITS; do git fetch -q origin "$c" 2>/dev/null || true; git log -1 --pretty='%h %s' "$c" || exit 1; done) && \
  (echo "" && echo "$(date -I) | reindex-chainstate | ${STOP} blocks | dbcache ${DBCACHE} | $(hostname) | $(uname -m) | $(lscpu | grep 'Model name' | head -1 | cut -d: -f2 | xargs) | $(nproc) threads | $(free -h | awk '/^Mem:/{print $2}') RAM | $(lsblk -snro NAME,TYPE,ROTA,TRAN "$(findmnt -nvo SOURCE -T "$BASE_DIR")" 2>/dev/null | awk '\
    $2 == "disk" { k=$1 ~ /^mmcblk/ ? "SD/MMC" : $1 ~ /^(vd|xvd|nbd)/ ? "unknown (virtual)" : $3 == 1 ? "HDD" : $4 == "usb" ? "unknown (USB flash/SSD/SD)" : $3 == 0 ? "SSD (reported nonrotational)" : "unknown"; seen[k]=1 } \
    END { for (k in seen) { n++; result=k } print (n > 1 ? "mixed media" : n == 1 ? result : "unknown") }')"; echo "") && \
  hyperfine --shell 'bash -euo pipefail' \
  --sort command \
  --runs 1 \
  --export-json "$BASE_DIR/rdx-$(printf '%.8s-' $COMMITS)$STOP-$DBCACHE-$CC.json" \
  --parameter-list COMMIT "${COMMITS// /,}" \
  --setup "git clean -fxd; git reset --hard {COMMIT} && \
    cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && ninja -C build bitcoind -j1" \
  --prepare "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -printtoconsole=0 && sleep 20 && rm -f \"$DATA_DIR\"/debug.log && sync && echo 3 | sudo tee /proc/sys/vm/drop_caches >/dev/null" \
    --conclude "cp \"$DATA_DIR\"/debug.log \"$LOG_DIR/debug-{COMMIT}-\$(date +%s).log\"; sleep 5; \
      grep -Eq 'height=0([^0-9]|$)' \"$DATA_DIR\"/debug.log && \
      grep -Eq 'height=$STOP([^0-9]|$)' \"$DATA_DIR\"/debug.log && \
      grep -Fq \"version \$(./build/bin/bitcoind -version | sed -En '1s/.* version ([^ ]+).*/\1/p') \" \"$DATA_DIR\"/debug.log" \
  "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -dbcache=$DBCACHE -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0"; \
done

81006fa18c doc: add block read-ahead release note
dcf775943e temp: use single-task block read-ahead submission

2026-10-14 | reindex-chainstate | 968869 blocks | dbcache 3000 | ssd-ryzen | x86_64 | AMD Ryzen 7 3700X 8-Core Processor | 16 threads | 62Gi RAM | SSD

Benchmark 1: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)
  Time (abs ≡):        8209.909 s               [User: 20215.701 s, System: 1796.500 s]
 
Benchmark 2: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = dcf775943e168813d898cbdb2092c654dfbf383b)
  Time (abs ≡):        8253.195 s               [User: 20154.134 s, System: 1596.314 s]
 
Relative speed comparison
        1.00          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)
        1.01          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = dcf775943e168813d898cbdb2092c654dfbf383b)

</details>

Edit: I also checked general speedup, it's still blazing fast for reindexes, 50-60% faster:

<details><summary>2026-10-13 | reindex-chainstate | 968869 blocks | dbcache 1000/3000 | i9-ssd | x86_64 | Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz | 16 threads | 62Gi RAM | SSD </summary>

for DBCACHE in 1000 3000; do \                                                                                                                                                                                                                                                                      
  COMMITS="99252a0a4a89c39820663d66c4765d7b53bcc821 81006fa18ce7177ba36046ae35ee3198b48b5501"; \                                                                                                                                                                                                                                          
  STOP=968869; export CC=gcc CXX=g++; \                                                                                                                                                                                                                                                                                                   
  BASE_DIR="/mnt/my_storage"; DATA_DIR="$BASE_DIR/BitcoinData"; LOG_DIR="$BASE_DIR/logs"; \                                                                                                                                                                                                                                               
  mkdir -p "$DATA_DIR" "$LOG_DIR" && \                                                                                                                                                                                                                                                                                                    
  python3 -c 'import fcntl, sys; f = open(sys.argv[1], "a"); fcntl.lockf(f, fcntl.LOCK_EX | fcntl.LOCK_NB)' "$DATA_DIR/.lock" && \                                                                                                                                                                                                        
  (echo ""; for c in $COMMITS; do git fetch -q origin "$c" 2>/dev/null || true; git log -1 --pretty='%h %s' "$c" || exit 1; done) && \                                                                                                                                                                                                    
  (echo "" && echo "$(date -I) | reindex-chainstate | ${STOP} blocks | dbcache ${DBCACHE} | $(hostname) | $(uname -m) | $(lscpu | grep 'Model name' | head -1 | cut -d: -f2 | xargs) | $(nproc) threads | $(free -h | awk '/^Mem:/{print $2}') RAM | $(lsblk -snro NAME,TYPE,ROTA,TRAN "$(findmnt -nvo SOURCE -T "$BASE_DIR")" 2>/dev/null | awk '\                                                                         
    $2 == "disk" { k=$1 ~ /^mmcblk/ ? "SD/MMC" : $1 ~ /^(vd|xvd|nbd)/ ? "unknown (virtual)" : $3 == 1 ? "HDD" : $4 == "usb" ? "unknown (USB flash/SSD/SD)" : $3 == 0 ? "SSD (reported nonrotational)" : "unknown"; seen[k]=1 } \                                                                                                          
    END { for (k in seen) { n++; result=k } print (n > 1 ? "mixed media" : n == 1 ? result : "unknown") }')"; echo "") && \                                          
  hyperfine --shell 'bash -euo pipefail' \                                        
  --sort command \                                                                
  --runs 1 \                                                                      
  --export-json "$BASE_DIR/rdx-$(printf '%.8s-' $COMMITS)$STOP-$DBCACHE-$CC.json" \                                                                                  
  --parameter-list COMMIT "${COMMITS// /,}" \                                     
  --setup "git clean -fxd; git reset --hard {COMMIT} && \                         
    cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && ninja -C build bitcoind -j1" \                                                                             
  --prepare "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -printtoconsole=0 && sleep 20 && rm -f \"$DATA_DIR\"/debug.log && sync && echo 3 | sudo tee /proc/sys/vm/drop_caches >/dev/null" \                                                                                                                           
    --conclude "cp \"$DATA_DIR\"/debug.log \"$LOG_DIR/debug-{COMMIT}-\$(date +%s).log\"; sleep 5; \                                                                  
      grep -Eq 'height=0([^0-9]|$)' \"$DATA_DIR\"/debug.log && \                                                                                                     
      grep -Eq 'height=$STOP([^0-9]|$)' \"$DATA_DIR\"/debug.log && \                                                                                                 
      grep -Fq \"version \$(./build/bin/bitcoind -version | sed -En '1s/.* version ([^ ]+).*/\1/p') \" \"$DATA_DIR\"/debug.log" \                                                                                                                                                                                                         
  "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -dbcache=$DBCACHE -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0"; \                                                                   
done                                                                              

99252a0a4a test: characterize block connection cache use                          
81006fa18c doc: add block read-ahead release note                                 

2026-10-13 | reindex-chainstate | 968869 blocks | dbcache 1000 | i9-ssd | x86_64 | Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz | 16 threads | 62Gi RAM | SSD (reported nonrotational)                                                                                                                                                        

Benchmark 1: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                              
  Time (abs ≡):        14120.107 s               [User: 29406.097 s, System: 1603.310 s]                                                                             
                                                                                  
Benchmark 2: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)                                                                              
  Time (abs ≡):        8860.643 s               [User: 31706.561 s, System: 1674.162 s]                                                                              
                                                                                  
Relative speed comparison                                                         
        1.59          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                     
        1.00          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)                                                                     

99252a0a4a test: characterize block connection cache use                          
81006fa18c doc: add block read-ahead release note                                 

2026-10-13 | reindex-chainstate | 968869 blocks | dbcache 3000 | i9-ssd | x86_64 | Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz | 16 threads | 62Gi RAM | SSD (reported nonrotational)                                                                                                                                                        

Benchmark 1: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                              
  Time (abs ≡):        14186.928 s               [User: 23973.212 s, System: 1048.147 s]
  
Benchmark 2: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)                                                                              
  Time (abs ≡):        8741.336 s               [User: 25051.586 s, System: 1068.567 s]
  
Relative speed comparison
        1.62          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                     
        1.00          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 81006fa18ce7177ba36046ae35ee3198b48b5501)

</details>

<details><summary>2026-10-13 | reindex-chainstate | 968869 blocks | dbcache 1000/3000 | i7-hdd | x86_64 | Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz | 8 threads | 62Gi RAM | HDD</summary>

for DBCACHE in 1000 3000; do \                                                                                                                                                                                                                                     
  COMMITS="99252a0a4a89c39820663d66c4765d7b53bcc821 81006fa18ce7177ba36046ae35ee3198b48b5501"; \                                                                                                                                                                                                         
  STOP=968869; export CC=gcc CXX=g++; \                                                                                                                                                                                                                                                                  
  BASE_DIR="/mnt/my_storage"; DATA_DIR="$BASE_DIR/BitcoinData"; LOG_DIR="$BASE_DIR/logs"; \                                                                                                                                                                                                              
  mkdir -p "$DATA_DIR" "$LOG_DIR" && \                                                                                                                                                                                                                                                                   
  python3 -c 'import fcntl, sys; f = open(sys.argv[1], "a"); fcntl.lockf(f, fcntl.LOCK_EX | fcntl.LOCK_NB)' "$DATA_DIR/.lock" && \                                                                                                                                                                       
  (echo ""; for c in $COMMITS; do git fetch -q origin "$c" 2>/dev/null || true; git log -1 --pretty='%h %s' "$c" || exit 1; done) && \                                                                                                                                                                   
  (echo "" && echo "$(date -I) | reindex-chainstate | ${STOP} blocks | dbcache ${DBCACHE} | $(hostname) | $(uname -m) | $(lscpu | grep 'Model name' | head -1 | cut -d: -f2 | xargs) | $(nproc) threads | $(free -h | awk '/^Mem:/{print $2}') RAM | $(lsblk -snro NAME,TYPE,ROTA,TRAN "$(findmnt -nvo SO
URCE -T "$BASE_DIR")" 2>/dev/null | awk '\                                                                                                                                                                                                                                                               
    $2 == "disk" { k=$1 ~ /^mmcblk/ ? "SD/MMC" : $1 ~ /^(vd|xvd|nbd)/ ? "unknown (virtual)" : $3 == 1 ? "HDD" : $4 == "usb" ? "unknown (USB flash/SSD/SD)" : $3 == 0 ? "SSD (reported nonrotational)" : "unknown"; seen[k]=1 } \                                                                         
    END { for (k in seen) { n++; result=k } print (n > 1 ? "mixed media" : n == 1 ? result : "unknown") }')"; echo "") && \                                                                                                                                                                              
  hyperfine --shell 'bash -euo pipefail' \                                                                                                                                                                                                                                                               
  --sort command \                                                                                                                                                                                                                                                                                       
  --runs 1 \                                                                                                                                                                                                                                                                                             
  --export-json "$BASE_DIR/rdx-$(printf '%.8s-' $COMMITS)$STOP-$DBCACHE-$CC.json" \                                                                                                                                                                                                                      
  --parameter-list COMMIT "${COMMITS// /,}" \                                                                                                                                                                                       
  --setup "git clean -fxd; git reset --hard {COMMIT} && \                                                                                                                                                                           
    cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && ninja -C build bitcoind -j1" \                                                                                                                                            
  --prepare "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -printtoconsole=0 && sleep 20 && rm -f \"$DATA_DIR\"/debug.log && sync && echo 3 | sudo tee /proc/sys/vm/drop_caches >/dev/null" \                     
    --conclude "cp \"$DATA_DIR\"/debug.log \"$LOG_DIR/debug-{COMMIT}-\$(date +%s).log\"; sleep 5; \                                                                                                                                                     
      grep -Eq 'height=0([^0-9]|$)' \"$DATA_DIR\"/debug.log && \                                                                                                                                                                    
      grep -Eq 'height=$STOP([^0-9]|$)' \"$DATA_DIR\"/debug.log && \                                                                                                                                                                
      grep -Fq \"version \$(./build/bin/bitcoind -version | sed -En '1s/.* version ([^ ]+).*/\1/p') \" \"$DATA_DIR\"/debug.log" \                                                                                                   
  "./build/bin/bitcoind -datadir=\"$DATA_DIR\" -stopatheight=$STOP -dbcache=$DBCACHE -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0"; \
done                                                                                                                                                                                                                                
                                                                                                                                                                                                                                    
99252a0a test: characterize block connection cache use                                                                                                                                                                                                  
81006fa1 doc: add block read-ahead release note                                                                                                                                                                                     
                                                                                                                                                                                                                                    
2026-10-13 | reindex-chainstate | 968869 blocks | dbcache 1000 | i7-hdd | x86_64 | Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz | 8 threads | 62Gi RAM | HDD                                                                             
                                                                                                                  
Benchmark 1: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 9925
2a0a4a89c39820663d66c4765d7b53bcc821)                                                                                                                                                                                                                                                    
  Time (abs ≡):        28121.273 s               [User: 32327.904 s, System: 1700.115 s]                                                                                                                                            
                                                                                                                  
Benchmark 2: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 8100
6fa18ce7177ba36046ae35ee3198b48b5501)                                                                                                                                                                                                                   
  Time (abs ≡):        19444.230 s               [User: 35364.384 s, System: 1814.729 s]                                                            
                                                                                                                                                                                                                                                        
Relative speed comparison                                                                                                                                                                                                           
        1.45          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMM
IT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                                                                                                                                      
        1.00          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=1000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMM
IT = 81006fa18ce7177ba36046ae35ee3198b48b5501)                                                                    
                                                                                                                  
99252a0a test: characterize block connection cache use                                                                      
81006fa1 doc: add block read-ahead release note                                                                                                                                                                                     
                                                                                                                            
2026-10-14 | reindex-chainstate | 968869 blocks | dbcache 3000 | i7-hdd | x86_64 | Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz | 8 threads | 62Gi RAM | HDD                                                                             
                                                                                                                  
Benchmark 1: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 9925
2a0a4a89c39820663d66c4765d7b53bcc821)                                                                             
  Time (abs ≡):        27015.804 s               [User: 26895.784 s, System: 1210.885 s]                                                                                                                                            
                                                                                                                  
Benchmark 2: ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMMIT = 8100
6fa18ce7177ba36046ae35ee3198b48b5501)                    
  Time (abs ≡):        16243.500 s               [User: 27838.870 s, System: 1222.553 s]                                                            
                                                                                                                                                                                                                                    
Relative speed comparison                                                                                                                                                                                                           
        1.66          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMM
IT = 99252a0a4a89c39820663d66c4765d7b53bcc821)                                                                                                                                                                                      
        1.00          ./build/bin/bitcoind -datadir="/mnt/my_storage/BitcoinData" -stopatheight=968869 -dbcache=3000 -reindex-chainstate -assumevalid=00000000000000000000748969ec33043c0e52a763c6dd5193861f559f2c72e3 -blocksonly -disablewallet -connect=0 -listen=0 -dnsseed=0 -printtoconsole=0 (COMM
IT = 81006fa18ce7177ba36046ae35ee3198b48b5501)

</details>

I ran this again twice, and it seems the slowdown was an anomaly. I got 1h 42m and 1h 44m, both faster than pushing single tasks.

nit: when tasks is empty, could we return early here?

I don't think we need to mention connection or falling back to synchronous reading here. These things seem unrelated to this class on its own.

    //! Returns the block with the specified hash if it had been previously queued, otherwise nullptr.

Same here, the block connection is an external use case for this class.

    //! Queue upcoming blocks to be read and deserialized asynchronously.