[bkeroack]

Problem

IBD download window. IbdScheduler::block_received (node/src/net/ibd.rs) recorded any delivered block whose hash matched a height as downloaded, including heights the connector had already passed. The Duplicate arm of handle_block_ibd calls it for every re-sent block. downloaded drains only as the cursor advances (connect_cursor_advanced), so those entries stayed in the -maxahead window, and the near-cursor priority zone in assign_blocks_up_to was gated by the same window. With the window full and the next height not in flight (released from a peer that did not deliver it, or after a restart with a smaller -maxahead), no peer was ever given that height and the download stopped. Core measures its window from the last common block, so the blocks just above the tip are always inside it (net_processing.cpp:1436-1441).

Any delivered block also reset the sender's stall clock and failure count, so a peer still owing heights looked active. Core clears m_stalling_since only when a requested block arrives (RemoveBlockRequest, net_processing.cpp:1199-1230).

A released height that waited in the pending pool while its block arrived late and was connected from disk could also be handed out again after the cursor passed it.

Local store errors charged to the sender. handle_block_ibd added 10 to the sender's ban score for every store_block error except an unknown parent, and store_bg_block added 5. A block-file write or fsync failure (ChainError::FlatFile) or a database write failure (ChainError::Storage) is this node's problem, so after the disk fills each peer reached the ban threshold after ten blocks. Core treats a failed write as fatal (FatalError in AcceptBlock) and does not call Misbehaving.

Tip-following sweep. With no scheduler (the gap to the best header is 24 blocks or less), the run loop called request_missing_blocks for every serving peer on each tip advance and every 5 s. Each peer got the same list of up to 128 missing blocks, so each block was downloaded once per peer. Core keeps one request per block (mapBlocksInFlight).

Which peers are asked. Forward IBD (assign_peer_work) and the AssumeUTXO background download assigned blocks to any connected peer, including ones that advertise neither NODE_NETWORK nor NODE_NETWORK_LIMITED. Core's CanServeBlocks (net_processing.cpp:1152-1155) excludes them. Core also asks a limited peer only for blocks within 286 of its tip (:1533), never during IBD (:6164), and never for historical blocks (:6176). The background download had no cap on what a peer had outstanding (16 new heights per peer every 2 s pass), restarted its round-robin at the same peer each pass, could give a timed-out height straight back to the same peer, and ignored notfound.

Fix

• block_received counts only a height that is in flight, and records it as downloaded only when it is above the connect cursor. The peer's activity clock, failure count and blocks_received move only when the block was in flight to that peer. Delivery by a different peer still frees the holder's slot, as before.
• The priority zone (cursor+1..cursor+256) is exempt from max_ahead, so the window can be exceeded by at most 256 blocks. The pending pool drops heights at or below the cursor.
• store_error_is_the_blocks: only Validation and CheckpointMismatch are scored, on both paths. Other errors are logged at warn and the sender is not charged.
• sweep_missing_blocks replaces the per-peer loop in the run-loop sweep. Each missing block goes to one peer, at most 16 per peer per pass. A block asked of anyone (as a full block) less than 30 s ago is skipped, and an older one goes to a peer not asked before when there is one. request_missing_blocks and its other callers are unchanged, as are compact-block requests.
• PeerInfo::advertises_blocks (Core's CanServeBlocks) and PeerInfo::is_limited (Core's IsLimitedPeer). Forward IBD and the sweep require advertises_blocks. A limited peer gets IBD work only when every height it could be given is within 286 of its tip. The background download uses NODE_NETWORK peers only.
• BgDownloader::assign caps outstanding heights at 16 per peer (Core's MAX_BLOCKS_IN_TRANSIT_PER_PEER), moves the round-robin start on each pass, and gives a released height (timed out, or answered with notfound) to a different peer unless that peer is the only one. The notfound handler releases background heights asked of that peer.
• Operator Manual (ibd.md): the window always fetches the 256 blocks above the tip, and which peers are asked for blocks.

Tests

New files: node/src/net/ibd_ibdwindow_tests.rs, bg_catchup_ibdwindow_tests.rs, manager_ibdwindow_tests.rs.

To check each test, I reverted ibd.rs to the parent and disabled each guard in bg_catchup.rs and manager.rs. All 14 tests in the first commit then failed on their own assertions:

• a_re_sent_connected_block_does_not_count_as_downloaded: fails without the fix: yes ("connected heights entered the window", left 3). It also checks that a requested block still counts.
• an_unrequested_block_above_the_cursor_does_not_count: yes.
• a_full_window_still_hands_out_the_next_height: yes ("height 1 not handed out with the window full: []").
• a_released_next_height_goes_to_another_peer_with_the_window_full: yes ("height 1 not given to peer 2: []").
• a_pooled_height_below_the_cursor_is_not_handed_out: yes ("connected heights handed out: [2, 3, 4, …]").
• only_a_requested_block_resets_the_stall_clock: yes ("an unrequested block reset the failure count"). It also checks that the peer's own block does reset it.
• a_local_write_failure_does_not_charge_the_sender: yes ("forward IBD: the sender was charged for our disk", left 10). It makes the block files read-only, and checks that a block with a bad merkle root is still charged 10 (forward) or 5 (background).
• ibd_work_goes_only_to_peers_that_can_serve_it: yes ("no block service: asked for […]"). It also checks that NODE_NETWORK and a recent limited peer get work. The 286-block limited case was not perturbed on its own.
• the_sweep_asks_one_peer_per_block: yes ("asked for 2 times"). It also checks that an aged request goes to a different peer.
• the_sweep_asks_a_peer_that_has_the_block: yes, with the height filter removed ("a peer without the blocks was asked"). It also checks that a limited peer is asked only for blocks it keeps, and that a notfound frees the block for the next pass.
• notfound_releases_a_background_height: yes.
• bg_catchup: a_peer_at_the_cap_gets_nothing_more_on_the_next_pass, a_released_height_goes_to_a_different_peer, the_round_robin_start_moves_each_pass, notfound_releases_only_the_askers_height: yes, each.

Local gate: clippy (all features, and node with no default features), cargo test -p node --lib, and cargo test -p satd --test regtest -- ibd sync.

Notes

• Stacked on p2p: bound learned addresses and outbound dials; manual peers outside the automatic cap #952 (merge that first).
• The sweep's 30 s re-request delay is shorter than Core's block download timeout. The sweep used to re-send every 5 s, and a request that went unanswered for much longer would leave a block near the tip waiting.
• Not changed: the single-peer cooldown bypass in IbdScheduler (a lone slow peer is re-asked for the heights it still owes every 15 s), and the re-created scheduler not reusing the startup scan of blocks already on disk.

Release notes

IBD no longer stalls when the -maxahead window is full while the next block is not being downloaded. Blocks re-sent for heights that are already connected no longer count against the window. A peer that is still owed blocks is only treated as active when it delivers blocks it was asked for. A local disk or database write failure while storing a downloaded block no longer raises the sending peer's ban score. When following the tip, satd asks one peer for each missing block instead of all of them. Block downloads, including the AssumeUTXO background download, now go only to peers that advertise block service, as in Bitcoin Core.

🤖 Generated with Claude Code