mining: add cooldown to createNewBlock() immediately after IBD

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

DrahtBot renamed this:
~~mining: add cooldown to createNewBlock() immediately after IBD~~
mining: add cooldown to createNewBlock() immediately after IBD
on Dec 31, 2025

DrahtBot added the label Mining on Dec 31, 2025

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
Approach ACK	w0xlt
Stale 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:

#34284 (ipc, test: Add tests for unclean disconnect and thread busy behavior by ryanofsky)
#33966 (refactor: disentangle miner startup defaults from runtime options by Sjors)
#33965 (mining: fix -blockreservedweight shadows IPC option by Sjors)
#33922 (mining: add getMemoryLoad() and track template non-mempool memory footprint by Sjors)
#32420 (miner: drop dummy extraNonce in coinbase scriptSig for templates requested via IPC by Sjors)
#29700 (kernel, refactor: return error status on all fatal errors 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.

Sjors force-pushed on Dec 31, 2025

DrahtBot added the label CI failed on Dec 31, 2025

Sjors force-pushed on Dec 31, 2025

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.

DrahtBot removed the label CI failed on Dec 31, 2025

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

DrahtBot added the label Needs rebase on Jan 13, 2026

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

c02c2832f7

Sjors force-pushed on Jan 22, 2026

Sjors commented at 9:02 am on January 22, 2026: member

Rebased.

DrahtBot removed the label Needs rebase on Jan 22, 2026

in src/node/miner.cpp:464 in c02c2832f7

459+        }
460+        if (!best_header_ahead) break;
461+
462+        WAIT_LOCK(kernel_notifications.m_tip_block_mutex, lock);
463+        kernel_notifications.m_tip_block_cv.wait_until(lock, cooldown_deadline, [&]() EXCLUSIVE_LOCKS_REQUIRED(kernel_notifications.m_tip_block_mutex) {
464+            const auto tip_block = kernel_notifications.TipBlock();

w0xlt commented at 6:43 am on January 27, 2026:

Runtime assertion for consistency with WaitAndCreateNewBlock pattern.

0            AssertLockHeld(kernel_notifications.m_tip_block_mutex);
1            const auto tip_block = kernel_notifications.TipBlock();

in src/node/miner.cpp:465 in c02c2832f7

460+        if (!best_header_ahead) break;
461+
462+        WAIT_LOCK(kernel_notifications.m_tip_block_mutex, lock);
463+        kernel_notifications.m_tip_block_cv.wait_until(lock, cooldown_deadline, [&]() EXCLUSIVE_LOCKS_REQUIRED(kernel_notifications.m_tip_block_mutex) {
464+            const auto tip_block = kernel_notifications.TipBlock();
465+            return tip_block && *tip_block != last_tip_hash;

w0xlt commented at 6:44 am on January 27, 2026:

This makes the wait wakes immediately on shutdown signal.

0            return (tip_block && *tip_block != last_tip_hash) || chainman.m_interrupt;

w0xlt commented at 6:44 am on January 27, 2026: contributor

Approach ACK

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

Code Coverage & Benchmarks

Reviews

Conflicts