p2p: Track recent stale tips (BIP 332) #36919

pull pseudoramdom wants to merge 9 commits into bitcoin:master from pseudoramdom:bip332-staletips-pt1-tracking changing 26 files +1470 −23
  1. pseudoramdom commented at 9:48 PM on November 19, 2026: contributor

    Part of #36833

    This PR adds local tracking of recent stale tips for BIP 332. The feature is behind a new -staletips=<mode> option (default none). There is no P2P change yet: with -staletips=headers the node only tracks tips.

    Key changes

    • A new AcceptedStaleTip validation notification feeds the staletips tracker.
    • The tracker is built from the block index at startup, keeping the tips with the most work.
      • At most 10 tips are tracked. When the tracker is full, a new tip evicts the one with the least work, but only if the new tip has more work.
    • getchaintips RPC updates
      • Add new options max_depth and staletips_only
      • Report fork_point for each non-active tip.

    Test networks get the stricter policies the BIP recommends:

    • signet: only tips whose block has been validated, and one header variant per block.
    • testnet3/4: only tips with a difficulty of at least about 1,000,000.

    <details> <summary>Sample output (regtest, after a reorg replaced the tip at height 111)</summary>

    $ bitcoin-cli getchaintips
    [
      {
        "height": 112,
        "hash": "544a1c7f23c96990e2db9f4415f498d1ee61effac8e7416ec53fb91f538b2d2c",
        "branchlen": 0,
        "status": "active"
      },
      {
        "height": 111,
        "hash": "3a0797803400d80abdbf34f73df33f760c1e24696531746f975e3041055b6967",
        "branchlen": 1,
        "fork_point": "43765e057b6cde12df1701595d90ae51cf80490fef1343edd2d3fbe2edf3958e",
        "status": "valid-fork"
      }
    ]
    
    $ bitcoin-cli -named getchaintips staletips_only=true
    [
      {
        "height": 111,
        "hash": "3a0797803400d80abdbf34f73df33f760c1e24696531746f975e3041055b6967",
        "branchlen": 1,
        "fork_point": "43765e057b6cde12df1701595d90ae51cf80490fef1343edd2d3fbe2edf3958e",
        "status": "valid-fork"
      }
    ]
    

    </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 9:48 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:

    • #36598 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36598.svg"></sub> ([Demo] validation: remove AssumeUTXO by l0rinc)
    • #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)
    • #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:

    • test/functional/p2p_staletip.py: assert len(tracked) > 0 → Prefer assert_greater_than(len(tracked), 0).

    <sup>2026-11-20 02:07:59</sup>

  6. pseudoramdom force-pushed on Nov 19, 2026
  7. pseudoramdom marked this as ready for review on Nov 19, 2026
  8. DrahtBot added the label CI failed on Nov 19, 2026
  9. pseudoramdom force-pushed on Nov 19, 2026
  10. 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
  11. 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
  12. in src/test/util/blocktree.h:28 in dcbf15421a
      23 | +struct BlockTreeAddOptions {
      24 | +    //! Mark the block as stored and validated up to BLOCK_VALID_TRANSACTIONS.
      25 | +    bool have_data{false};
      26 | +    uint32_t bits{0x1d00ffff};
      27 | +    //! Merkle root of the header, or a value unique to the block if unset.
      28 | +    std::optional<uint256> merkle_root;
    


    w0xlt commented at 12:56 AM on November 20, 2026:

    This should fix the related CI errors. The "macOS native, fuzz" is a CI environment problem.

    diff --git a/src/test/util/blocktree.h b/src/test/util/blocktree.h
    index f750e95669..0231db753e 100644
    --- a/src/test/util/blocktree.h
    +++ b/src/test/util/blocktree.h
    @@ -25,7 +25,7 @@ struct BlockTreeAddOptions {
         bool have_data{false};
         uint32_t bits{0x1d00ffff};
         //! Merkle root of the header, or a value unique to the block if unset.
    -    std::optional<uint256> merkle_root;
    +    std::optional<uint256> merkle_root{};
     };
     
     /** Build a header on `prev` whose hash is unique for each `nonce`. */
    

    pseudoramdom commented at 2:09 AM on November 20, 2026:

    Thanks! Fixed

  13. pseudoramdom force-pushed on Nov 20, 2026
  14. 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
  15. 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
  16. 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
  17. 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
  18. doc: add release note for stale-tip tracking 84f9805954
  19. pseudoramdom force-pushed on Nov 20, 2026
  20. DrahtBot removed the label CI failed 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