mining: add cooldown to createNewBlock() immediately after IBD #34184

1. 
   Sjors commented at 5:17 am on December 31, 2025: member

   At startup isInitialBlockDownload() stops returning true once there’s less than a day of blocks left to sync. Connected mining clients will receive a flood of new templates as these last blocks are connected.

   Fix this by briefly pausing block template creation while the best header chain is ahead of the tip. If no tip update happens for one second, we stop waiting.

   It’s not safe to keep waiting, because a malicious miner could announce a header and delay revealing the block, causing all other miners using this software to stall.

   The cooldown only applies to createNewBlock(), which is typically called once per connected client; waitNext() remains unchanged.

   Fixes #33994

2. DrahtBot renamed this:
   mining: add cooldown to createNewBlock() immediately after IBD
   mining: add cooldown to createNewBlock() immediately after IBD
   on Dec 31, 2025
3. DrahtBot added the label Mining on Dec 31, 2025
4. 
   DrahtBot commented at 5:23 am on December 31, 2025: contributor

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

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/34184.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	bensig

   If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

   Conflicts

   Reviewers, this pull request conflicts with the following ones:

   • #33965 (mining: fix -blockreservedweight shadows IPC option by Sjors)
   • #33922 (mining: add getMemoryLoad() and track template non-mempool memory footprint by Sjors)
   • #33819 (mining: getCoinbase() returns struct instead of raw tx by Sjors)
   • #33795 (test: Ignore error message give from python because of PYTHON_GIL by kevkevinpal)
   • #32420 (miner: drop dummy extraNonce in coinbase scriptSig for templates requested via IPC by Sjors)

   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.

5. Sjors force-pushed on Dec 31, 2025
6. DrahtBot added the label CI failed on Dec 31, 2025
7. Sjors force-pushed on Dec 31, 2025
8. mining: createNewBlock() waits if tip is updating

   At startup isInitialBlockDownload() stops returning true once there’s
   less than a day of blocks left to sync. Connected mining clients will
   receive a flood of new templates as these last blocks are connected.
   
   Fix this by briefly pausing block template creation while the best
   header chain is ahead of the tip. If no tip update happens for one
   second, we stop waiting.
   
   It’s not safe to keep waiting, because a malicious miner could announce
   a header and delay revealing the block, causing all other miners using
   this software to stall.
   
   The cooldown only applies to createNewBlock(), which is typically called
   once per connected client. Subsequent templates are provided by
   waitNext().
   
   Fixes #33994

   e8b01c43bb
9. Sjors force-pushed on Dec 31, 2025
10. 
    Sjors commented at 7:28 am on December 31, 2025: member

    Switched to avoid mock time for the cooldown mechanism (it’s possible, but would require additional refactoring).

    Added a constraint to ignore alternative header branches. This probably doesn’t matter in real life, but it does in tests. E.g. the assume_utxo test “Check importing a snapshot where current chain-tip is not an ancestor of the snapshot block but has less work” creates an alternative chain of blocks despite having better headers (but not their blocks). In real life this implies a giant block witholding attack.

11. DrahtBot removed the label CI failed on Dec 31, 2025
12. 
    bensig commented at 0:46 am on January 3, 2026: contributor

    ACK e8b01c43bb05f1a52adf1279280a744111b8dc45

    Tested on macOS - interface_ipc.py passes.

    Code review:

    • Using SteadyClock for the cooldown (independent of mocktime) is the right call
    • BestHeaderAheadOfActiveTip() correctly uses ancestor check to ignore competing branches
    • 1s timeout prevents DoS from header-only attacks while still allowing catch-up during final IBD

    Nice fix for #33994

Contributors
Sjors DrahtBot bensig

Labels
Mining