mining: createNewBlock() waits if tip is updating

Sjors · Sjors · commit e8b01c43bb05 · 2025-12-31T14:18:58.000+07:00
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
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
@@ -964,7 +964,13 @@ class MinerImpl : public Mining
     std::unique_ptr<BlockTemplate> createNewBlock(const BlockCreateOptions& options) override
     {
         // Ensure m_tip_block is set so consumers of BlockTemplate can rely on that.
-        if (!waitTipChanged(uint256::ZERO, MillisecondsDouble::max())) return {};
+        const std::optional<BlockRef> maybe_tip{waitTipChanged(uint256::ZERO, MillisecondsDouble::max())};
+        if (!maybe_tip) return {};
+
+        // Avoid generating a new template immediately after connecting a block while
+        // our best known header chain still has more work. This prevents a burst of
+        // block templates during the final catch-up moments after IBD.
+        if (!CooldownIfHeadersAhead(chainman(), notifications(), *maybe_tip)) return {};
 
         BlockAssembler::Options assemble_options{options};
         ApplyArgsManOptions(*Assert(m_node.args), assemble_options);
diff --git a/src/node/miner.cpp b/src/node/miner.cpp
@@ -412,6 +412,42 @@ std::optional<BlockRef> GetTip(ChainstateManager& chainman)
     return BlockRef{tip->GetBlockHash(), tip->nHeight};
 }
 
+bool CooldownIfHeadersAhead(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const BlockRef& last_tip)
+{
+    constexpr auto COOLDOWN{1s};
+    // Use a steady clock so cooldown is independent of mocktime.
+    auto cooldown_deadline{SteadyClock::now() + COOLDOWN};
+    uint256 last_tip_hash{last_tip.hash};
+    while (true) {
+        bool best_header_ahead{false};
+        {
+            LOCK(::cs_main);
+            best_header_ahead = chainman.BestHeaderAheadOfActiveTip();
+        }
+        if (!best_header_ahead) break;
+
+        WAIT_LOCK(kernel_notifications.m_tip_block_mutex, lock);
+        kernel_notifications.m_tip_block_cv.wait_until(lock, cooldown_deadline, [&]() EXCLUSIVE_LOCKS_REQUIRED(kernel_notifications.m_tip_block_mutex) {
+            const auto tip_block = kernel_notifications.TipBlock();
+            return tip_block && *tip_block != last_tip_hash;
+        });
+        if (chainman.m_interrupt) return false;
+
+        // If the tip changed during the wait, extend the deadline
+        const auto tip_block = kernel_notifications.TipBlock();
+        if (tip_block && *tip_block != last_tip_hash) {
+            last_tip_hash = *tip_block;
+            cooldown_deadline = SteadyClock::now() + COOLDOWN;
+            continue;
+        }
+
+        // No tip change and the cooldown window has expired.
+        if (SteadyClock::now() >= cooldown_deadline) break;
+    }
+
+    return true;
+}
+
 std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const uint256& current_tip, MillisecondsDouble& timeout)
 {
     Assume(timeout >= 0ms); // No internal callers should use a negative timeout
diff --git a/src/node/miner.h b/src/node/miner.h
@@ -157,6 +157,15 @@ std::optional<BlockRef> GetTip(ChainstateManager& chainman);
 /* Waits for the connected tip to change until timeout has elapsed. During node initialization, this will wait until the tip is connected (regardless of `timeout`).
  * Returns the current tip, or nullopt if the node is shutting down. */
 std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const uint256& current_tip, MillisecondsDouble& timeout);
+
+/**
+ * Pause block template creation when the best header chain is ahead of the tip.
+ *
+ * @param last_tip tip at the start of the cooldown window.
+ *
+ * @returns false if interrupted.
+ */
+bool CooldownIfHeadersAhead(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const BlockRef& last_tip);
 } // namespace node
 
 #endif // BITCOIN_NODE_MINER_H
diff --git a/src/validation.cpp b/src/validation.cpp
@@ -6320,6 +6320,16 @@ void ChainstateManager::RecalculateBestHeader()
     }
 }
 
+bool ChainstateManager::BestHeaderAheadOfActiveTip() const
+{
+    AssertLockHeld(::cs_main);
+    const CBlockIndex* best_header{m_best_header};
+    const CBlockIndex* tip{ActiveChain().Tip()};
+    // Only consider headers that extend the active tip; ignore competing branches.
+    return best_header && tip && best_header->nChainWork > tip->nChainWork &&
+           best_header->GetAncestor(tip->nHeight) == tip;
+}
+
 bool ChainstateManager::ValidatedSnapshotCleanup(Chainstate& validated_cs, Chainstate& unvalidated_cs)
 {
     AssertLockHeld(::cs_main);
diff --git a/src/validation.h b/src/validation.h
@@ -1336,6 +1336,8 @@ class ChainstateManager
     //! header in our block-index not known to be invalid, recalculate it.
     void RecalculateBestHeader() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
 
+    bool BestHeaderAheadOfActiveTip() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
+
     CCheckQueue<CScriptCheck>& GetCheckQueue() { return m_script_check_queue; }
 
     ~ChainstateManager();
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
@@ -5,17 +5,28 @@
 """Test the IPC (multiprocess) interface."""
 import asyncio
 import inspect
+import time
 from contextlib import asynccontextmanager, AsyncExitStack
 from io import BytesIO
 from pathlib import Path
 import shutil
-from test_framework.messages import (CBlock, CTransaction, ser_uint256, COIN)
+from test_framework.messages import (
+    CBlock,
+    CBlockHeader,
+    CTransaction,
+    COIN,
+    from_hex,
+    msg_headers,
+    ser_uint256,
+)
 from test_framework.test_framework import BitcoinTestFramework
 from test_framework.util import (
     assert_equal,
+    assert_greater_than_or_equal,
     assert_not_equal
 )
 from test_framework.wallet import MiniWallet
+from test_framework.p2p import P2PInterface
 
 # Test may be skipped and not have capnp installed
 try:
@@ -174,19 +185,38 @@ async def async_routine():
             assert_equal(oldblockref.height, newblockref.height)
 
             async with AsyncExitStack() as stack:
-                self.log.debug("Create a template")
                 opts = self.capnp_modules['mining'].BlockCreateOptions()
                 opts.useMempool = True
                 opts.blockReservedWeight = 4000
                 opts.coinbaseOutputMaxAdditionalSigops = 0
+
+                self.log.debug("createNewBlock() should wait if tip is still updating")
+                self.disconnect_nodes(0, 1)
+                node1_block_hash = self.generate(self.nodes[1], 1, sync_fun=self.no_op)[0]
+                header = from_hex(CBlockHeader(), self.nodes[1].getblockheader(node1_block_hash, False))
+                header_only_peer = self.nodes[0].add_p2p_connection(P2PInterface())
+                header_only_peer.send_and_ping(msg_headers([header]))
+                start = time.time()
+                async with destroying((await mining.createNewBlock(opts)).result, ctx):
+                    pass
+                # Lower-bound only: a heavily loaded CI host might still exceed 0.9s
+                # even without the cooldown, so this can miss regressions but avoids
+                # spurious failures.
+                assert_greater_than_or_equal(time.time() - start, 0.9)
+                header_only_peer.peer_disconnect()
+                self.connect_nodes(0, 1)
+                self.sync_all()
+
+                self.log.debug("Create a template")
                 template = await create_block_template(mining, stack, ctx, opts)
 
                 self.log.debug("Test some inspectors of Template")
                 header = (await template.getBlockHeader(ctx)).result
                 assert_equal(len(header), block_header_size)
                 block = await self.parse_and_deserialize_block(template, ctx)
-                assert_equal(ser_uint256(block.hashPrevBlock), newblockref.hash)
-                assert len(block.vtx) >= 1
+                current_tip = self.nodes[0].getbestblockhash()
+                assert_equal(ser_uint256(block.hashPrevBlock), ser_uint256(int(current_tip, 16)))
+                assert_greater_than_or_equal(len(block.vtx), 1)
                 txfees = await template.getTxFees(ctx)
                 assert_equal(len(txfees.result), 0)
                 txsigops = await template.getTxSigops(ctx)

Original file line number	Diff line number	Diff line change
`@@ -6320,6 +6320,16 @@ void ChainstateManager::RecalculateBestHeader()`
`6320`	`6320`	`}`
`6321`	`6321`	`}`
`6322`	`6322`
	`6323`	`+bool ChainstateManager::BestHeaderAheadOfActiveTip() const`
	`6324`	`+{`
	`6325`	`+ AssertLockHeld(::cs_main);`
	`6326`	`+ const CBlockIndex* best_header{m_best_header};`
	`6327`	`+ const CBlockIndex* tip{ActiveChain().Tip()};`
	`6328`	`+ // Only consider headers that extend the active tip; ignore competing branches.`
	`6329`	`+ return best_header && tip && best_header->nChainWork > tip->nChainWork &&`
	`6330`	`+ best_header->GetAncestor(tip->nHeight) == tip;`
	`6331`	`+}`
	`6332`	`+`
`6323`	`6333`	`bool ChainstateManager::ValidatedSnapshotCleanup(Chainstate& validated_cs, Chainstate& unvalidated_cs)`
`6324`	`6334`	`{`
`6325`	`6335`	`AssertLockHeld(::cs_main);`