net: introduce block tracker to retry to download blocks after failure #35113

pull optout21 wants to merge 6 commits into bitcoin:master from optout21:block-dl changing 8 files +330 −10

optout21 commented at 9:01 AM on April 19, 2026: contributor

Revival of closed/stale #27837 . The change is taken (as of b18c72cfcd6f27070928bc0ba16db6897960f211) and rebased to current master. Original description follows.

Coming from #27652, part of #29183.

The general idea is to keep track of the user requested blocks so, in case of a bad behaving peer or a network disconnection, they can be fetched from another one automatically without any further user interaction.

This was requested by users because the getblockfrompeer RPC command lacks the functionality to notify them about block request failures or peer disconnections (which is expected due to the asynchronous nature of the block requests).

Currently, this new functionality is limited to blocks requested by the user via the 'getblockfrompeer' RPC command.

In the future, this class could expand its scope and be utilized in the regular chain synchronization process. Or, even could be employed in special procedures like a prune node rescan that uses BIP158 block filters, or even into BIP157 itself.
DrahtBot added the label P2P on Apr 19, 2026
DrahtBot commented at 9:01 AM on April 19, 2026: contributor


The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Reviews

See the guideline for information on the review process. A summary of reviews will appear here.



Conflicts

Reviewers, this pull request conflicts with the following ones:
- #28690 (build: Introduce internal kernel library by sedited)
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

net: FetchBlock, disallow requesting blocks from network limited peers

This is in preparation for block tracker.

Co-authored-by: optout <13562139+optout21@users.noreply.github.com>

ddacb2a667

net: FetchBlock, disallow requesting block to the same peer multiple times
Co-authored-by: optout <13562139+optout21@users.noreply.github.com>
1a2b81b1d1

net: introduce BlockRequestTracker

Co-authored-by: optout <13562139+optout21@users.noreply.github.com>

80c742584e

rpc: getblockfrompeer, connect block tracking mechanism and add coverage

If the initial block fetching process fails, the p2p layer will be in
charge of fetching the block from 'any' connected peer.
Re-trying to download the block from different peers until it is
received.

Co-authored-by: optout <13562139+optout21@users.noreply.github.com>

3867d35acb

rpc: getblockfrompeer, introduce fetch from "any" peer functionality

If no 'peer_id' is provided, 'getblockfrompeer' will delegate
the peer selection to the internal block downloading logic.

Co-authored-by: optout <13562139+optout21@users.noreply.github.com>

fccf94bd62

rpc: getblockfrompeer, add one-shot block requests capability

Allowing what we had before, a single block request with no automatic
retry nor tracking mechanism.

Co-authored-by: optout <13562139+optout21@users.noreply.github.com>

2034c609f3

optout21 force-pushed on Apr 21, 2026

in src/rpc/blockchain.cpp:540 in 2034c609f3

 533 | @@ -534,7 +534,10 @@ static RPCMethod getblockfrompeer()
 534 |          "Returns an empty JSON object if the request was successfully scheduled.",
 535 |          {
 536 |              {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The block hash to try to fetch"},
 537 | -            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::NO, "The peer to fetch it from (see getpeerinfo for peer IDs)"},
 538 | +            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "The peer to fetch it from (see getpeerinfo for peer IDs). "
 539 | +                        "If omitted, the node will fetch the block from any available peer."},
 540 | +            {"retry", RPCArg::Type::BOOL, RPCArg::Optional::OMITTED, "Whether to automatically retry to download the block from different peers if the initial request fails or not. "
 541 | +                        "If omitted, the node will continuously attempt to download the block from various peers until it succeeds."},

luke-jr commented at 4:29 PM on April 25, 2026:

Sounds like that's a default of true (not RPCArg::Optional::OMITTED with a description noting it)?

in src/rpc/blockchain.cpp:538 in 2034c609f3

 533 | @@ -534,7 +534,10 @@ static RPCMethod getblockfrompeer()
 534 |          "Returns an empty JSON object if the request was successfully scheduled.",
 535 |          {
 536 |              {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The block hash to try to fetch"},
 537 | -            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::NO, "The peer to fetch it from (see getpeerinfo for peer IDs)"},
 538 | +            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "The peer to fetch it from (see getpeerinfo for peer IDs). "
 539 | +                        "If omitted, the node will fetch the block from any available peer."},

luke-jr commented at 4:31 PM on April 25, 2026:

                        "If omitted, the node will fetch the block from any available peer. (requires retry=true)"},

...or fix it to work without retry

in src/rpc/blockchain.cpp:539 in 2034c609f3

 533 | @@ -534,7 +534,10 @@ static RPCMethod getblockfrompeer()
 534 |          "Returns an empty JSON object if the request was successfully scheduled.",
 535 |          {
 536 |              {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The block hash to try to fetch"},
 537 | -            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::NO, "The peer to fetch it from (see getpeerinfo for peer IDs)"},
 538 | +            {"peer_id", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "The peer to fetch it from (see getpeerinfo for peer IDs). "
 539 | +                        "If omitted, the node will fetch the block from any available peer."},
 540 | +            {"retry", RPCArg::Type::BOOL, RPCArg::Optional::OMITTED, "Whether to automatically retry to download the block from different peers if the initial request fails or not. "

luke-jr commented at 4:31 PM on April 25, 2026:

Booleans should ideally not be positional parameters, named only (eg, with an options Object)

luke-jr changes_requested
optout21 commented at 10:07 AM on April 28, 2026: contributor

The last commit re-introduces behavior "what we had before". I will see how changes could be reordered to avoid removing some behavior and then re-introducing again.
optout21 commented at 1:32 PM on April 30, 2026: contributor

@luke-jr , thanks for the comments on the RPC parameters, I will consider them with upcoming changes.

Contributors

Labels

Linked (view graph)

#27652 Allow getblockfrompeer to use any peer #27837 net: introduce block tracker to retry to download blocks after failure #29183 Prune Node Rescan Project Tracking

net: introduce block tracker to retry to download blocks after failure #35113

Reviews

Conflicts