p2p: Relay stale tip announcements (BIP 332) #36920

pull pseudoramdom wants to merge 21 commits into bitcoin:master from pseudoramdom:bip332-staletips-pt2-headersrelay changing 42 files +3419 −37
  1. pseudoramdom commented at 10:04 PM on November 19, 2026: contributor

    Part of #36833. Based on #36919; review from p2p: add staletip message type and payload.

    This adds the BIP 332 staletip message, negotiated through the BIP 434 BIP332 feature. With -staletips=headers, the node announces the stale tips it tracks and tracks the ones its peers announce. Only headers are relayed.

    Key changes

    • New staletip message type and payload.

    • Add a StaleTipRelayManager, which holds the relay policy.

    • With -staletips=headers, the node advertises BIP332 (with prefers_blocks=false) and relays only with peers that advertise it too.

    • Stale tips learned from peers are tracked, and listed by getchaintips with staletips_only:

      <details> <summary>Sample output</summary>

      A node that learned of a stale tip only from a peer's staletip message:

      $ bitcoin-cli -named getchaintips staletips_only=true
      [
        {
          "height": 111,
          "hash": "6377f9037ff98cb738f676bee62d1931adf41c2cdb00e0148b8d5fbf6161807d",
          "branchlen": 1,
          "fork_point": "24bed510a58473fb7ac8cd0f48bb25d75cf9848f00a62be08721b64cea6acd20",
          "status": "headers-only"
        }
      ]
      

      </details>

    • getnetworkinfo gets a localfeatures field, listing the BIP 434 features the node advertises.

      <details> <summary>Sample output</summary>

      $ bitcoin-cli getnetworkinfo
      {
        ...
        "localfeatures": {
          "BIP332": {
            "prefers_blocks": false
          }
        },
        ...
      }
      

      </details>

    • getpeerinfo gets a features field, listing the BIP 434 features each peer advertises.

      <details> <summary>Sample output</summary>

      $ bitcoin-cli getpeerinfo
      [
        {
          "id": 1,
          ...
          "features": {
            "BIP332": {
              "prefers_blocks": false
            }
          },
          ...
        }
      ]
      

      </details>

  2. validation: add AcceptedStaleTip notification
    Notify validation interface listeners when a header or block is
    accepted that is not on the active chain and has no more work than
    the active tip. BIP 332 stale-tip tracking, added in later commits,
    uses this.
    
    Headers from one ProcessNewBlockHeaders() call are coalesced into one
    notification for the last new header. A block is notified again when
    its data is stored.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    dd6225d6da
  3. staletips: add bounded stale-tip tracker
    Add StaleTipTracker, which keeps up to MAX_ADVERTISED_STALETIPS
    recent stale tips that are eligible for relay under BIP 332. When
    full, it evicts the tip with the least work.
    
    Add BlockTree to test/util/blocktree.h so later tests can share it.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    1674bdad6f
  4. DrahtBot added the label P2P on Nov 19, 2026
  5. DrahtBot commented at 10:04 PM on November 19, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    External sites

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

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

    <!--174a7506f384e20aa4161008e828411d-->

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #36819 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36819.svg"></sub> ([RFC] enable clang-tidy optin.performance.Padding by fanquake)
    • #36808 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36808.svg"></sub> (iwyu: Fix warnings in src/test/fuzz and treat them as errors by hebasto)
    • #36598 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36598.svg"></sub> ([Demo] validation: remove AssumeUTXO by l0rinc)
    • #36268 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36268.svg"></sub> (refactor: prune unused semi-colons by fanquake)
    • #35713 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35713.svg"></sub> (Remove boost as a unit test runner by rustaceanrob)
    • #35570 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35570.svg"></sub> (refactor: Change some validation.cpp methods to return BlockValidationState by optout21)
    • #35522 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35522.svg"></sub> (refactor: Extract per-message helpers from SendMessages() (move-only) by pablomartin4btc)
    • #35502 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35502.svg"></sub> (refactor: extract per-message helpers from ProcessMessage (move-only) by w0xlt)
    • #35474 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35474.svg"></sub> (node: move index ownership to NodeContext by w0xlt)
    • #31260 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/31260.svg"></sub> (scripted-diff: Type-safe settings retrieval by ryanofsky)

    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.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

    LLM Linter (✨ experimental)

    Possible places where comparison-specific test macros should replace generic comparisons:

    • src/test/staletipmessage_tests.cpp: BOOST_CHECK_THROW(DecodeExact(trailing), std::ios_base::failure) → Prefer BOOST_CHECK_EXCEPTION with the expected failure message.
    • src/test/staletipmessage_tests.cpp: BOOST_CHECK_THROW(DecodeExact(invalid_bool), std::ios_base::failure) → Prefer BOOST_CHECK_EXCEPTION with the expected failure message.
    • src/test/staletipmessage_tests.cpp: BOOST_CHECK_THROW(DecodeExact(truncated), std::ios_base::failure) → Prefer BOOST_CHECK_EXCEPTION with the expected failure message.
    • src/test/staletipmessage_tests.cpp: BOOST_CHECK_THROW(DecodeExact(noncanonical), std::ios_base::failure) → Prefer BOOST_CHECK_EXCEPTION with the expected failure message.
    • src/test/staletipmessage_tests.cpp: BOOST_CHECK_THROW(DecodeExact(empty_headers), std::ios_base::failure) → Prefer BOOST_CHECK_EXCEPTION with the expected failure message.
    • test/functional/p2p_staletip.py: assert len(tracked) > 0 → Prefer assert_greater_than(len(tracked), 0).

    <sup>2026-11-20 03:00:29</sup>

  6. pseudoramdom force-pushed on Nov 19, 2026
  7. DrahtBot added the label CI failed on Nov 19, 2026
  8. DrahtBot commented at 10:09 PM on November 19, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task i686: https://github.com/bitcoin/bitcoin/actions/runs/44625059152/job/135916554369</sub> <sub>LLM reason (✨ experimental): The build failed because staletiprelayman.cpp omits the StaleTipMessage::headers initializer, and warnings are treated as errors.</sub>

    <details><summary>Hints</summary>

    Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

    • Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

    • A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

    • An intermittent issue.

    Leave a comment here, if you need help tracking down a confusing failure.

    </details>

  9. staletips: apply test-network tracking policies
    Test networks are less protected by proof of work, so BIP 332
    recommends stricter stale-tip policies there. On signet, only track
    tips whose block has been validated, and one header variant per
    block. On testnet3 and testnet4, only track tips with a difficulty
    of at least about 1,000,000.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    11e6784cc7
  10. staletips: seed tracker from the block index
    The tracker is not persisted, so add SeedFromBlockIndex() to rebuild
    it at startup from the eligible stale tips in the block index.
    Candidates go through AddStaleTip(), so the same policies apply as
    at runtime.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    66bb87e393
  11. init: add -staletips option
    Add -staletips=<mode> to opt in to BIP 332 stale-tip relay. For now
    'headers' only enables stale-tip tracking, which the next commits
    add; later PRs add relay behind the same mode.
    
    Make the PeerManager ApplyArgsManOptions() return util::Result, like
    the other ApplyArgsManOptions() helpers, so an invalid mode is
    reported at startup.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    1155e78047
  12. net_processing: track local stale tips
    When -staletips is enabled, track the stale tips this node learns
    about.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    7ef1950d1a
  13. rpc: add max_depth and fork_point to getchaintips
    Add an optional max_depth argument that limits getchaintips to tips at
    most that many blocks below the active tip, and report fork_point for
    each tip that is not on the active chain.
    
    This lets callers find recent forks without listing every old stale
    branch on mainnet or walking back each branch to its fork point.
    6035be9103
  14. rpc: report tracked stale tips in getchaintips
    Add a staletips_only argument to getchaintips that lists only the
    recent stale tips the node tracks with -staletips, taken from the
    stale-tip tracker.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    695a29a9b8
  15. doc: add release note for stale-tip tracking 84f9805954
  16. p2p: add staletip message type and payload
    Define the BIP 332 staletip message. Move MAX_STALETIP_HEADERS from
    the tracker to the message header, as the limit comes from the
    message format.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    7635c6a7bb
  17. refactor: move stale-tip tracker into StaleTipRelayManager
    Add StaleTipRelayManager to hold the stale-tip relay state and policy,
    starting with the tracker that PeerManager has owned so far. It
    requires cs_main instead of a lock of its own, as it holds CBlockIndex
    pointers.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    eb25d86e55
  18. staletips: build staletip messages for tracked forks
    Add MakeStaleTipMessage() to build the staletip message announcing a
    tracked fork. Make HasAncestor() public so it can check the fork.
    9e0ecc7af2
  19. net_processing: negotiate staletip relay via BIP 434
    Advertise the BIP 434 stale-tip relay feature when -staletips is
    enabled, and record the feature data of peers that advertise it.
    Malformed feature data is ignored. On signet, set prefers_blocks, as
    stale tips there can only be validated with their blocks.
    
    Add NetFeatures to hold the recognized BIP 434 features, so that their
    data is parsed and serialized in one place.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    d6c21b36f6
  20. rpc: report BIP 434 features in getnetworkinfo and getpeerinfo
    Add "localfeatures" to getnetworkinfo and "features" to getpeerinfo,
    listing the BIP 434 features the node and each peer advertise, with
    their decoded data.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    3406845c89
  21. refactor: add window param to GetAntiDoSWorkThreshold
    Name the 144-block anti-DoS buffer ANTI_DOS_WORK_WINDOW and let
    callers pass a different window. A later commit checks inbound
    staletip messages against a wider window.
    3bcf7f9fde
  22. net_processing: validate and track inbound staletip messages
    Accept staletip messages from peers that negotiated the feature, and
    add their headers and track the tip if they pass validation and
    policy checks.
    
    Use STALETIP_RECENT_WINDOW for the work threshold rather than the
    default 144 blocks, so stale tips that peers may advertise are not
    discarded.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    b6208615a9
  23. net_processing: fetch higher-work blocks announced via staletip
    If a staletip branch has more work than our active tip, for example
    because we are behind, handle it as for a headers message: update the
    peer's header state and request the blocks through the direct-fetch
    path. Only do so when the peer set have_block, as otherwise it has not
    said it can serve the blocks.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    303bc6d825
  24. net_processing: announce active tips for stale-tip relay
    Queue an inv for our new active tip to peers that negotiated staletip,
    even when the normal announcement is skipped because the peer already
    has the header. A peer only sends us a staletip message whose fork
    point it knows we have, which it infers from the blocks we announce,
    so BIP 332 asks nodes to always announce their active tip.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    9c884487dd
  25. net_processing: relay stale-tip announcements
    Announce each eligible stale tip once to negotiated peers that have its
    fork point but not the tip. On signet, wait until we can serve the
    block, which peers need to validate the tip.
    
    Remember per peer the tips it announced to us, so we don't echo them
    back. Remember the tips we announced to a peer for as long as they stay
    tracked, so a reorg doesn't make us announce them again.
    
    Co-authored-by: woltx <94266259+w0xlt@users.noreply.github.com>
    Co-authored-by: Anthony Towns <aj@erisian.com.au>
    43e90c3f6a
  26. net_processing: don't punish peers for invalid stale-branch blocks
    BIP 332 lets a peer serve blocks on a stale branch it never connected,
    so their scripts may be unchecked. Remember which tips a peer announced
    with have_block set, and, as for BIP 152 compact blocks, don't punish
    it for a block on such a branch that only fails once connected, or that
    already turned out invalid, through an ancestor, when it arrives.
    
    Still punish it for a block failing the checks done before storing it,
    as the peer must have passed them to store the block.
    493457cc93
  27. doc: add BIP 332 to bips.md and release note d68292556f
  28. pseudoramdom force-pushed on Nov 20, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-20 15:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me