bch(m5): windowed headers-first block download — close the IBD block-body gap

header_sync drove the HEADER chain to the peer tip (ContinueSync re-issues
getheaders), but those headers blocks were never getdata d: only the BIP130
tip-announce path (<=3 headers) pulled bodies. Cold-start IBD therefore walked
2000-header batches forward forever and downloaded zero block bodies — yet the
embedded daemon ABLA size feed and full-block->mempool reconciliation need real
block data, so IBD could never complete.

block_download.hpp: pure, peer-free BlockDownloadWindow — enqueue learned header
hashes in chain order, keep at most MAX_BLOCKS_IN_FLIGHT (16, BCHN/Bitcoin
per-peer default) getdata(MSG_BLOCK) outstanding, top the window up oldest-first
as each block arrives. Dedupes against queued/in-flight/received so an
overlapping locator batch or re-announce never double-downloads. In-flight
timeout/eviction deferred (robustness once blocks flow).

Wired into NodeP2P: ContinueSync enqueues the batch + drains the window;
the block handler frees the slot on arrival and tops up. bch stays skip-green
(header-only, build-inert). Zero p2pool-merged-v36 surface — pure SPV/IBD
wire-sync; per-coin isolation (src/impl/bch/ only).

bch_block_download_test: window bound, top-up ordering, dedupe, unsolicited,
degenerate-window. ctest 10/10 -> 11/11.

Author: frstrtr

src/impl/bch/coin/block_download.hpp

@@ -0,0 +1,132 @@
+#pragma once
+// ---------------------------------------------------------------------------
+// bch::coin::block_download -- M5 full-block body. Windowed headers-first block
+// download, factored out of NodeP2P as a PURE, peer-free state machine so the
+// in-flight window policy is unit-testable without a live socket.
+//
+// THE GAP THIS CLOSES: header_sync.hpp drives the *header* chain forward --
+// ContinueSync re-issues getheaders so cold-start IBD walks the whole header
+// chain to the peer tip. But those headers' BLOCKS were never getdata'd: only
+// the tiny BIP130 tip-announce path (RequestBlocks, <= 3 headers) pulled full
+// blocks. So IBD synced 2000-header batches forward indefinitely and never
+// downloaded a single block body -- and the embedded daemon's ABLA size feed
+// (abla_block_feed.hpp) and the full-block -> mempool reconciliation
+// (block_connector.hpp) need REAL block data, not just headers. Cold-start IBD
+// could never actually complete.
+//
+// POLICY (mirrors Bitcoin/BCHN headers-first block download, net_processing):
+//   * headers learned during IBD are enqueued in chain order;
+//   * at most MAX_BLOCKS_IN_FLIGHT getdata(MSG_BLOCK) are outstanding at once
+//     (a bounded window -- never blast the whole 2000-header batch as getdata
+//     and stall on a slow peer / unbounded memory);
+//   * each arriving block frees one window slot, and the window tops up from
+//     the front of the queue (oldest-first), so blocks stream in at the peer's
+//     pace until the queue drains.
+//
+// DEDUPE: a hash already queued, in flight, or already received is never
+// re-requested, so an overlapping getheaders locator batch or a re-announce
+// cannot double-download.
+//
+// NOT IN THIS SLICE (deferred per integrator 2026-06-18): in-flight timeout /
+// eviction (a block requested but never delivered by a stalling peer). That is
+// robustness hardening worth doing only once blocks are actually flowing; this
+// slice builds the happy-path window first.
+//
+// p2pool-merged-v36 SURFACE: NONE -- pure SPV/IBD wire-sync plumbing; no PoW
+// hash, share format, coinbase commitment, AuxPoW, or PPLNS math. PER-COIN
+// ISOLATION: src/impl/bch/coin/ only; header-only, build-INERT (bch stays
+// skip-green).
+// ---------------------------------------------------------------------------
+
+#include <cstddef>
+#include <deque>
+#include <unordered_set>
+#include <vector>
+
+#include <core/uint256.hpp>
+
+namespace bch::coin::block_download {
+
+/// Default cap on outstanding getdata(MSG_BLOCK) requests. 16 matches the
+/// Bitcoin/BCHN per-peer MAX_BLOCKS_IN_FLIGHT default -- enough to keep a fast
+/// peer's pipe full without unbounded memory on a slow one.
+inline constexpr std::size_t DEFAULT_MAX_BLOCKS_IN_FLIGHT = 16;
+
+/// Bounded headers-first block-download window. Peer-free + deterministic:
+/// callers feed it learned header hashes (enqueue), drain the requests it wants
+/// issued now (next_requests), and report arrivals (on_block_received) which
+/// free window slots for the next drain.
+class BlockDownloadWindow {
+    /// Low-64 of a cryptographic hash is already uniform -- no further mixing.
+    struct HashHasher {
+        std::size_t operator()(const uint256& h) const { return h.GetLow64(); }
+    };
+
+public:
+    explicit BlockDownloadWindow(std::size_t max_in_flight = DEFAULT_MAX_BLOCKS_IN_FLIGHT)
+        : m_max_in_flight(max_in_flight ? max_in_flight : 1) {}
+
+    /// Enqueue block hashes learned from a headers batch, in chain order.
+    /// Skips any hash already queued, in flight, or already received so a
+    /// re-announce / overlapping locator batch never double-requests. Returns
+    /// the count newly enqueued.
+    std::size_t enqueue(const std::vector<uint256>& hashes)
+    {
+        std::size_t added = 0;
+        for (const auto& h : hashes) {
+            if (m_known.count(h)) continue;
+            m_known.insert(h);
+            m_queue.push_back(h);
+            ++added;
+        }
+        return added;
+    }
+
+    /// Pop hashes to request now, up to the free window slots
+    /// (max_in_flight - in_flight). Marks them in flight. Oldest-first
+    /// (chain order) so block bodies are pulled in the order they were learned.
+    std::vector<uint256> next_requests()
+    {
+        std::vector<uint256> out;
+        while (m_in_flight.size() < m_max_in_flight && !m_queue.empty()) {
+            uint256 h = m_queue.front();
+            m_queue.pop_front();
+            m_in_flight.insert(h);
+            out.push_back(h);
+        }
+        return out;
+    }
+
+    /// Report an arrived block. Removes it from the in-flight set (freeing a
+    /// window slot) and remembers it so a later re-announce is not re-queued.
+    /// Returns true iff it was one we actually had in flight (vs. an
+    /// unsolicited / already-handled block).
+    bool on_block_received(const uint256& h)
+    {
+        auto it = m_in_flight.find(h);
+        if (it == m_in_flight.end()) {
+            // Unsolicited or already handled: still remember it so a later
+            // headers batch never queues it, but report not-in-flight.
+            m_known.insert(h);
+            return false;
+        }
+        m_in_flight.erase(it);
+        return true;
+    }
+
+    std::size_t in_flight()     const { return m_in_flight.size(); }
+    std::size_t queued()        const { return m_queue.size(); }
+    std::size_t max_in_flight() const { return m_max_in_flight; }
+    /// True when there is window room AND something queued to fill it.
+    bool has_capacity() const { return m_in_flight.size() < m_max_in_flight && !m_queue.empty(); }
+    /// True when nothing is queued and nothing is outstanding (IBD drained).
+    bool idle() const { return m_queue.empty() && m_in_flight.empty(); }
+
+private:
+    std::size_t m_max_in_flight;
+    std::deque<uint256> m_queue;                            // pending, chain order
+    std::unordered_set<uint256, HashHasher> m_in_flight;    // outstanding getdata
+    std::unordered_set<uint256, HashHasher> m_known;        // queued ∪ inflight ∪ received
+};
+
+} // namespace bch::coin::block_download

src/impl/bch/coin/p2p_node.hpp

@@ -50,6 +50,7 @@
 #include "mempool.hpp"
 #include "merkle.hpp"
 #include "header_sync.hpp"
+#include "block_download.hpp"
 
 #include <memory>
 
@@ -129,6 +130,10 @@ class NodeP2P : public core::ICommunicator, public core::INetwork, public core::
     uint256   m_sent_cmpct_hash;
     // External mempool for compact block tx matching
     Mempool* m_mempool{nullptr};
+    // Headers-first windowed block download (cold-start IBD). Bounds outstanding
+    // getdata(MSG_BLOCK) so the synced header stream is pulled as block bodies at
+    // the peer's pace instead of stalling after header sync. See block_download.hpp.
+    block_download::BlockDownloadWindow m_block_dl;
 
     // Callbacks for broadcaster integration
     using AddrCallback = std::function<void(const std::vector<NetService>&)>;
@@ -348,6 +353,24 @@ class NodeP2P : public core::ICommunicator, public core::INetwork, public core::
         }
     }
 
+    /// Drain the IBD block-download window: issue getdata(MSG_BLOCK) for every
+    /// hash the window releases (bounded by MAX_BLOCKS_IN_FLIGHT). Called after
+    /// enqueuing a synced headers batch and again on each block arrival to top
+    /// the window back up. No-op when the window is full or the queue is empty.
+    void drain_block_window()
+    {
+        if (!m_peer) return;
+        for (const auto& bhash : m_block_dl.next_requests()) {
+            auto getdata_msg = message_getdata::make_raw(
+                {inventory_type(inventory_type::block, bhash)});
+            m_peer->write(getdata_msg);
+            LOG_DEBUG_COIND << "[" << m_chain_label << "] IBD getdata block "
+                            << bhash.GetHex().substr(0, 16) << "... (in flight "
+                            << m_block_dl.in_flight() << ", queued "
+                            << m_block_dl.queued() << ")";
+        }
+    }
+
     /// Whether this peer supports compact blocks (BIP 152).
     bool supports_compact_blocks() const { return m_peer_supports_cmpct; }
     /// Peer's service flags from version message (for NODE_BLOOM check etc.)
@@ -678,6 +701,11 @@ class NodeP2P : public core::ICommunicator, public core::INetwork, public core::
                  << blockhash.GetHex().substr(0, 16) << "..."
                  << " txs=" << block.m_txs.size();
         emit_full_block(block, blockhash);
+
+        // IBD window: this block freed a slot (if it was one we requested) --
+        // top the window back up so the next queued block bodies stream in.
+        m_block_dl.on_block_received(blockhash);
+        drain_block_window();
     }
 
     ADD_P2P_HANDLER(headers)
@@ -717,6 +745,20 @@ class NodeP2P : public core::ICommunicator, public core::INetwork, public core::
                     LOG_INFO << "[" << m_chain_label << "] IBD: got "
                              << vheaders.size() << " headers, continuing from "
                              << last_hash.GetHex().substr(0, 16) << "...";
+
+                    // Headers-first BLOCK download: queue this batch's blocks and
+                    // pull them through the bounded in-flight window. Without this
+                    // IBD walked the header chain to the tip but never downloaded
+                    // a single block body (ABLA size feed / block-connector need
+                    // real block data). block_download.hpp dedupes + bounds.
+                    std::vector<uint256> batch_hashes;
+                    batch_hashes.reserve(vheaders.size());
+                    for (auto& hdr : vheaders) {
+                        auto p = pack(hdr);
+                        batch_hashes.push_back(Hash(p.get_span()));
+                    }
+                    m_block_dl.enqueue(batch_hashes);
+                    drain_block_window();
                 }
                 break;
             case Followup::RequestBlocks:

src/impl/bch/test/CMakeLists.txt

@@ -14,6 +14,7 @@ if(BUILD_TESTING)
         abla_block_feed_test
         abla_block_feed_gap_test
         header_sync_test          # M5: headers-first IBD continuation policy (pure)
+        block_download_test       # M5: windowed headers-first block download (pure)
     )
     foreach(t IN LISTS BCH_ABLA_TESTS)
         add_executable(bch_${t} ${t}.cpp)

src/impl/bch/test/block_download_test.cpp

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// bch::coin::block_download::BlockDownloadWindow -- M5 full-block body.
+// Pins the windowed headers-first block-download policy that NodeP2P drives
+// during cold-start IBD: enqueue learned header hashes, keep at most
+// MAX_BLOCKS_IN_FLIGHT getdata(MSG_BLOCK) outstanding, and top the window up
+// as blocks arrive. Header-only over coin/block_download.hpp + <core/uint256>;
+// no peer, socket, or coin lib.
+//
+// The behavior under test (the gap this slice closed): before this, IBD walked
+// the header chain to the peer tip but never getdata'd a single block body, so
+// the ABLA size feed / block-connector had no real block data and cold-start
+// IBD could not complete. The window turns the synced header stream into a
+// bounded, self-topping-up block download.
+//
+// p2pool-merged-v36 surface: NONE. per-coin isolation: src/impl/bch/ only.
+// ---------------------------------------------------------------------------
+
+#include <cassert>
+#include <iostream>
+#include <vector>
+
+#include <core/uint256.hpp>
+
+#include "../coin/block_download.hpp"
+
+using bch::coin::block_download::BlockDownloadWindow;
+using bch::coin::block_download::DEFAULT_MAX_BLOCKS_IN_FLIGHT;
+
+// Deterministic distinct hashes (no Math.random) -- hash i = uint256(i+1).
+static uint256 H(uint64_t i) { return uint256(base_uint<256>(i + 1)); }
+
+static std::vector<uint256> hashes(uint64_t lo, uint64_t hi) {
+    std::vector<uint256> v;
+    for (uint64_t i = lo; i < hi; ++i) v.push_back(H(i));
+    return v;
+}
+
+int main()
+{
+    // ---- Window bounds outstanding getdata at max_in_flight ----------------
+    {
+        BlockDownloadWindow w(4);
+        assert(w.idle());
+        // Enqueue a maximal-ish IBD batch of 10 headers.
+        assert(w.enqueue(hashes(0, 10)) == 10);
+        assert(w.queued() == 10);
+        assert(w.has_capacity());
+
+        // First drain requests exactly the window size (4), oldest-first.
+        auto req = w.next_requests();
+        assert(req.size() == 4);
+        assert(req[0] == H(0) && req[3] == H(3));   // chain order preserved
+        assert(w.in_flight() == 4);
+        assert(w.queued() == 6);
+
+        // Window is full -> a second drain with no arrivals yields nothing.
+        assert(w.next_requests().empty());
+        assert(w.in_flight() == 4);
+    }
+
+    // ---- Arrivals free slots; window tops up oldest-first ------------------
+    {
+        BlockDownloadWindow w(4);
+        w.enqueue(hashes(0, 10));
+        w.next_requests();                          // H0..H3 in flight
+
+        // H0 arrives (was in flight) -> frees one slot.
+        assert(w.on_block_received(H(0)) == true);
+        assert(w.in_flight() == 3);
+        auto req = w.next_requests();               // top up by 1
+        assert(req.size() == 1 && req[0] == H(4));
+        assert(w.in_flight() == 4 && w.queued() == 5);
+
+        // Drain the rest as blocks arrive, in order.
+        for (uint64_t i = 1; i < 10; ++i) {
+            assert(w.on_block_received(H(i)) == true);
+            w.next_requests();
+        }
+        assert(w.idle());
+        assert(w.queued() == 0 && w.in_flight() == 0);
+    }
+
+    // ---- Dedupe: re-announce / overlapping locator batch never re-requests --
+    {
+        BlockDownloadWindow w(8);
+        assert(w.enqueue(hashes(0, 5)) == 5);
+        // Overlapping batch (3..8): only 5,6,7 are new.
+        assert(w.enqueue(hashes(3, 8)) == 3);
+        assert(w.queued() == 8);
+
+        auto req = w.next_requests();               // window 8 >= 8 queued
+        assert(req.size() == 8);
+        // No hash requested twice.
+        std::vector<uint256> seen;
+        for (auto& h : req) {
+            for (auto& s : seen) assert(!(s == h));
+            seen.push_back(h);
+        }
+
+        // A block we already pulled, re-announced, is not re-queued.
+        assert(w.on_block_received(H(2)) == true);
+        assert(w.enqueue({H(2)}) == 0);
+        assert(w.queued() == 0);
+    }
+
+    // ---- Unsolicited block: not in flight, reported false, still remembered --
+    {
+        BlockDownloadWindow w(4);
+        assert(w.on_block_received(H(99)) == false); // never requested
+        // ...and remembering it means a later headers batch won't queue it.
+        assert(w.enqueue({H(99)}) == 0);
+    }
+
+    // ---- Degenerate window (0 -> clamped to 1) still makes progress --------
+    {
+        BlockDownloadWindow w(0);
+        assert(w.max_in_flight() == 1);
+        w.enqueue(hashes(0, 3));
+        auto req = w.next_requests();
+        assert(req.size() == 1 && req[0] == H(0));
+        assert(w.next_requests().empty());          // window full at 1
+        assert(w.on_block_received(H(0)) == true);
+        req = w.next_requests();
+        assert(req.size() == 1 && req[0] == H(1));
+    }
+
+    // ---- Default window size is the BCHN/Bitcoin per-peer default ----------
+    {
+        BlockDownloadWindow w;
+        assert(w.max_in_flight() == DEFAULT_MAX_BLOCKS_IN_FLIGHT);
+        assert(DEFAULT_MAX_BLOCKS_IN_FLIGHT == 16);
+    }
+
+    std::cout << "bch block_download window: ALL PASS\n";
+    return 0;
+}