From 51dc31db12aa4f96a028664305cbbd3a7f1fc9b4 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Thu, 28 May 2026 19:51:42 +0200
Subject: [PATCH 1/6] test: refresh MiniWallet after node restart

---
 test/functional/interface_ipc_mining.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/test/functional/interface_ipc_mining.py b/test/functional/interface_ipc_mining.py
index 4cd9c17c99f6..5a60bcfee433 100755
--- a/test/functional/interface_ipc_mining.py
+++ b/test/functional/interface_ipc_mining.py
@@ -326,6 +326,7 @@ def run_ipc_option_override_test(self):
         # blockReservedWeight per template request and are unaffected; later in
         # the test the IPC template includes a mempool transaction.
         self.restart_node(0, extra_args=[f"-blockreservedweight={MAX_BLOCK_WEIGHT}"])
+        self.miniwallet.rescan_utxos()
 
         async def async_routine():
             ctx, mining = await make_mining_ctx(self)

From a619ececa4a1450612ba93813fb2795cb43fb245 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Tue, 25 Nov 2025 18:16:43 +0100
Subject: [PATCH 2/6] rpc: move static block_template to node context

The getblocktemplate RPC uses a static BlockTemplate, which goes out
of scope only after the node completed its shutdown sequence.

This becomes a problem when a later commit implements a destructor
that uses m_node.
---
 src/node/context.h | 3 +++
 src/rpc/mining.cpp | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/node/context.h b/src/node/context.h
index b8b3274f090c..6bd8e8a454cd 100644
--- a/src/node/context.h
+++ b/src/node/context.h
@@ -29,6 +29,7 @@ class NetGroupManager;
 class PeerManager;
 class TorController;
 namespace interfaces {
+class BlockTemplate;
 class Chain;
 class ChainClient;
 class Mining;
@@ -69,6 +70,8 @@ struct NodeContext {
     std::unique_ptr<AddrMan> addrman;
     std::unique_ptr<CConnman> connman;
     std::unique_ptr<CTxMemPool> mempool;
+    //! Cache latest getblocktemplate result for BIP 22 long polling
+    std::unique_ptr<interfaces::BlockTemplate> gbt_result;
     std::unique_ptr<const NetGroupManager> netgroupman;
     std::unique_ptr<CBlockPolicyEstimator> fee_estimator;
     std::unique_ptr<PeerManager> peerman;
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 1d72c699c593..7eafd0529c91 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -889,7 +889,7 @@ static RPCMethod getblocktemplate()
     // Update block
     static CBlockIndex* pindexPrev;
     static int64_t time_start;
-    static std::unique_ptr<BlockTemplate> block_template;
+    std::unique_ptr<BlockTemplate>& block_template{node.gbt_result};
     if (!pindexPrev || pindexPrev->GetBlockHash() != tip ||
         (mempool.GetTransactionsUpdated() != nTransactionsUpdatedLast && GetTime() - time_start > 5))
     {

From fd003b91bec3ec3b748b6177c58447e3f5afde00 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 21 Nov 2025 16:12:27 +0100
Subject: [PATCH 3/6] mining: track non-mempool memory usage

IPC clients can hold on to block templates indefinately, which has the
same impact as when the node holds a shared pointer to the
CBlockTemplate. Because each template in turn tracks CTransactionRefs,
transactions that are removed from the mempool will not have
their memory cleared.

This commit adds bookkeeping to the block template constructor and
destructor that will let us track the resulting memory footprint.

Co-authored-by: Vasil Dimov <vd@FreeBSD.org>
---
 src/node/context.h      | 10 +++++++++-
 src/node/interfaces.cpp | 21 ++++++++++++++++++++-
 src/node/mining_types.h |  7 +++++++
 src/util/hasher.h       | 16 ++++++++++++++++
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/node/context.h b/src/node/context.h
index 6bd8e8a454cd..297aad1035be 100644
--- a/src/node/context.h
+++ b/src/node/context.h
@@ -11,6 +11,7 @@
 #include <cstdlib>
 #include <functional>
 #include <memory>
+#include <sync.h>
 #include <thread>
 #include <vector>
 
@@ -70,7 +71,14 @@ struct NodeContext {
     std::unique_ptr<AddrMan> addrman;
     std::unique_ptr<CConnman> connman;
     std::unique_ptr<CTxMemPool> mempool;
-    //! Cache latest getblocktemplate result for BIP 22 long polling
+    mutable Mutex template_state_mutex;
+    //! Track how many templates (which we hold on to on behalf of connected IPC
+    //! clients) are referencing each transaction.
+    mutable TxTemplateMap template_tx_refs GUARDED_BY(template_state_mutex);
+    //! Cache latest getblocktemplate result for BIP 22 long polling. Must be
+    //! cleared before template_tx_refs because the destructor decrements the
+    //! count in template_tx_refs of each transaction in the template and aborts
+    //! if an entry is missing.
     std::unique_ptr<interfaces::BlockTemplate> gbt_result;
     std::unique_ptr<const NetGroupManager> netgroupman;
     std::unique_ptr<CBlockPolicyEstimator> fee_estimator;
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 2f68f414f0da..10509825d62b 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -78,8 +78,10 @@
 #include <map>
 #include <memory>
 #include <optional>
+#include <ranges>
 #include <string>
 #include <tuple>
+#include <unordered_map>
 #include <utility>
 #include <vector>
 
@@ -884,7 +886,24 @@ class BlockTemplateImpl : public BlockTemplate
                                                           m_block_template(std::move(block_template)),
                                                           m_node(node)
     {
-        assert(m_block_template);
+        // Don't track the dummy coinbase, because it can be modified in-place
+        // by submitSolution()
+        LOCK(m_node.template_state_mutex);
+        for (const CTransactionRef& tx : Assert(m_block_template)->block.vtx | std::views::drop(1)) {
+            m_node.template_tx_refs[tx]++;
+        }
+    }
+
+    ~BlockTemplateImpl()
+    {
+        LOCK(m_node.template_state_mutex);
+        for (const CTransactionRef& tx : m_block_template->block.vtx | std::views::drop(1)) {
+            auto ref_count{m_node.template_tx_refs.find(tx)};
+            if (!Assume(ref_count != m_node.template_tx_refs.end())) break;
+            if (--ref_count->second == 0) {
+                m_node.template_tx_refs.erase(ref_count);
+            }
+        }
     }
 
     CBlockHeader getBlockHeader() override
diff --git a/src/node/mining_types.h b/src/node/mining_types.h
index 9c4fbcbbafeb..c898ddf21335 100644
--- a/src/node/mining_types.h
+++ b/src/node/mining_types.h
@@ -17,11 +17,13 @@
 #include <primitives/transaction.h>
 #include <script/script.h>
 #include <uint256.h>
+#include <util/hasher.h>
 #include <util/time.h>
 
 #include <cstddef>
 #include <cstdint>
 #include <optional>
+#include <unordered_map>
 #include <vector>
 
 namespace node {
@@ -173,6 +175,11 @@ struct CoinbaseTx {
     uint32_t lock_time;
 };
 
+/**
+ * Map how many templates refer to each transaction reference.
+ */
+using TxTemplateMap = std::unordered_map<CTransactionRef, size_t, CTransactionRefSaltedHash, CTransactionRefComp>;
+
 } // namespace node
 
 #endif // BITCOIN_NODE_MINING_TYPES_H
diff --git a/src/util/hasher.h b/src/util/hasher.h
index 7e74c6767693..2e35cac08a88 100644
--- a/src/util/hasher.h
+++ b/src/util/hasher.h
@@ -116,4 +116,20 @@ class SaltedSipHasher
     size_t operator()(const std::span<const unsigned char>& script) const;
 };
 
+struct CTransactionRefSaltedHash {
+    SaltedWtxidHasher m_hasher;
+
+    size_t operator()(const CTransactionRef& tx) const
+    {
+        return m_hasher(tx->GetWitnessHash());
+    }
+};
+
+struct CTransactionRefComp {
+    bool operator()(const CTransactionRef& a, const CTransactionRef& b) const
+    {
+        return a->GetWitnessHash() == b->GetWitnessHash();
+    }
+};
+
 #endif // BITCOIN_UTIL_HASHER_H

From 1cdc31b8ee4c3ae083536350389b30149757a7c7 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Tue, 25 Nov 2025 16:26:16 +0100
Subject: [PATCH 4/6] mining: add GetTemplateMemoryUsage()

Calculate the non-mempool memory footprint for template transaction
references.

Add bench logging to collect data on whether caching or simplified
heuristics are needed, such as not checking for mempool presence.
---
 src/node/miner.cpp | 23 ++++++++++++++++++++++-
 src/node/miner.h   | 10 ++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/src/node/miner.cpp b/src/node/miner.cpp
index ccd9cc7c57ac..465c9f625838 100644
--- a/src/node/miner.cpp
+++ b/src/node/miner.cpp
@@ -14,7 +14,9 @@
 #include <consensus/params.h>
 #include <consensus/tx_verify.h>
 #include <consensus/validation.h>
+#include <core_memusage.h>
 #include <interfaces/types.h>
+#include <logging/timer.h>
 #include <node/blockstorage.h>
 #include <node/kernel_notifications.h>
 #include <node/mining_args.h>
@@ -44,7 +46,6 @@
 #include <algorithm>
 #include <compare>
 #include <condition_variable>
-#include <cstddef>
 #include <functional>
 #include <numeric>
 #include <span>
@@ -587,4 +588,24 @@ std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifi
     return GetTip(chainman);
 }
 
+size_t GetTemplateMemoryUsage(const CTxMemPool& mempool, const TxTemplateMap& tx_refs)
+{
+    size_t usage_bytes{0};
+    {
+        LOG_TIME_MILLIS_WITH_CATEGORY("Calculate template transaction reference memory footprint", BCLog::BENCH);
+        for (const auto& [tx_ref, _] : tx_refs) {
+            if (!Assume(tx_ref)) continue;
+            // mempool.exists() locks mempool.cs each time, which slows down
+            // our calculation. This is preferable to potentially blocking
+            // the node from processing new transactions while this
+            // (non-urgent) calculation is in progress.
+            //
+            // As a side-effect the result is not an accurate snapshot, because
+            // the mempool may change during the loop.
+            if (mempool.exists(tx_ref->GetWitnessHash())) continue;
+            usage_bytes += RecursiveDynamicUsage(*tx_ref);
+        }
+    }
+    return usage_bytes;
+}
 } // namespace node
diff --git a/src/node/miner.h b/src/node/miner.h
index af3273073295..216bf5124863 100644
--- a/src/node/miner.h
+++ b/src/node/miner.h
@@ -15,6 +15,7 @@
 #include <util/feefrac.h>
 #include <util/time.h>
 
+#include <cstddef>
 #include <cstdint>
 #include <memory>
 #include <optional>
@@ -177,6 +178,15 @@ std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifi
  * @returns false if interrupted.
  */
 bool CooldownIfHeadersAhead(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const BlockRef& last_tip, bool& interrupt_mining);
+
+/**
+ * Estimate non-mempool memory footprint of transaction data referenced by block
+ * templates.
+ *
+ * Result is not guaranteed to be an accurate snapshot, because it does not
+ * lock mempool.cs while iterating over transaction references.
+ */
+size_t GetTemplateMemoryUsage(const CTxMemPool& mempool, const TxTemplateMap& tx_refs);
 } // namespace node
 
 #endif // BITCOIN_NODE_MINER_H

From 807d1a660d29eba196e4bf5cf8769a20aa14cd9f Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 19 Dec 2025 18:17:48 -0600
Subject: [PATCH 5/6] ipc: add getMemoryLoad()

Allow IPC clients to inspect the amount of memory consumed by
non-mempool transactions in blocks.

Returns a MemoryLoad struct which can later be expanded to e.g.
include a limit.

Expand the interface_ipc.py test to demonstrate the behavior and
to illustrate how clients can call destroy() to reduce memory
pressure.
---
 src/interfaces/mining.h                 | 12 ++++++++++++
 src/ipc/capnp/mining.capnp              |  5 +++++
 src/node/interfaces.cpp                 |  8 ++++++++
 test/functional/interface_ipc_mining.py | 25 +++++++++++++++++++++++++
 4 files changed, 50 insertions(+)

diff --git a/src/interfaces/mining.h b/src/interfaces/mining.h
index ff4f87109f92..f20a8ba34fe6 100644
--- a/src/interfaces/mining.h
+++ b/src/interfaces/mining.h
@@ -96,6 +96,12 @@ class BlockTemplate
     virtual void interruptWait() = 0;
 };
 
+//! Tracks memory usage for template-bound transactions.
+struct MemoryLoad
+{
+    uint64_t usage{0};
+};
+
 //! Interface giving clients (RPC, Stratum v2 Template Provider in the future)
 //! ability to create block templates.
 class Mining
@@ -180,6 +186,12 @@ class Mining
      */
     virtual bool submitBlock(const CBlock& block, std::string& reason, std::string& debug) = 0;
 
+    /**
+     * Returns the current memory load for template transactions outside the
+     * mempool.
+     */
+    virtual MemoryLoad getMemoryLoad() = 0;
+
     //! Get internal node context. Useful for RPC and testing,
     //! but not accessible across processes.
     virtual const node::NodeContext* context() { return nullptr; }
diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index a6dd8d71f315..4435acabbb6c 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -26,6 +26,7 @@ interface Mining $Proxy.wrap("interfaces::Mining") {
     checkBlock @5 (context :Proxy.Context, block: Data, options: BlockCheckOptions) -> (reason: Text, debug: Text, result: Bool);
     interrupt @6 () -> ();
     submitBlock @7 (context :Proxy.Context, block: Data) -> (reason: Text, debug: Text, result: Bool);
+    getMemoryLoad @8 (context :Proxy.Context) -> (result: MemoryLoad);
 }
 
 interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
@@ -47,6 +48,10 @@ struct BlockCreateOptions $Proxy.wrap("node::BlockCreateOptions") {
     coinbaseOutputMaxAdditionalSigops @2 :UInt64 = .defaultCoinbaseOutputMaxAdditionalSigops $Proxy.name("coinbase_output_max_additional_sigops");
 }
 
+struct MemoryLoad $Proxy.wrap("interfaces::MemoryLoad") {
+    usage @0 :UInt64;
+}
+
 struct BlockWaitOptions $Proxy.wrap("node::BlockWaitOptions") {
     timeout @0 : Float64 = .maxDouble $Proxy.name("timeout");
     feeThreshold @1 : Int64 = .maxMoney $Proxy.name("fee_threshold");
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 10509825d62b..1056a90f2bf1 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -92,6 +92,7 @@ using interfaces::Chain;
 using interfaces::FoundBlock;
 using interfaces::Handler;
 using interfaces::MakeSignalHandler;
+using interfaces::MemoryLoad;
 using interfaces::Mining;
 using interfaces::Node;
 using interfaces::Rpc;
@@ -1053,6 +1054,13 @@ class MinerImpl : public Mining
         return accepted && new_block && reason.empty();
     }
 
+    MemoryLoad getMemoryLoad() override
+    {
+        LOCK(m_node.template_state_mutex);
+        CTxMemPool& mempool{*Assert(m_node.mempool)};
+        return {.usage = GetTemplateMemoryUsage(mempool, m_node.template_tx_refs)};
+    }
+
     const NodeContext* context() override { return &m_node; }
     ChainstateManager& chainman() { return *Assert(m_node.chainman); }
     KernelNotifications& notifications() { return *Assert(m_node.notifications); }
diff --git a/test/functional/interface_ipc_mining.py b/test/functional/interface_ipc_mining.py
index 5a60bcfee433..1c0edf8edc2f 100755
--- a/test/functional/interface_ipc_mining.py
+++ b/test/functional/interface_ipc_mining.py
@@ -31,6 +31,7 @@
 from test_framework.test_framework import BitcoinTestFramework
 from test_framework.util import (
     assert_equal,
+    assert_greater_than,
     assert_greater_than_or_equal,
     assert_not_equal,
 )
@@ -303,6 +304,11 @@ async def create_block():
                 block4 = await mining_get_block(template6, ctx)
                 assert_equal(len(block4.vtx), 3)
 
+                self.log.debug("Memory load should be zero because there was no mempool churn")
+                with self.nodes[0].assert_debug_log(["Calculate template transaction reference memory footprint"]):
+                    memory_load = await mining.getMemoryLoad(ctx)
+                assert_equal(memory_load.result.usage, 0)
+
                 self.log.debug("Wait for another, but time out, since the fee threshold is set now")
                 template7 = await mining_wait_next_template(template6, stack, ctx, waitoptions)
                 assert template7 is None
@@ -316,6 +322,13 @@ async def wait_for_block():
                     assert template7 is None
                 await wait_and_do(wait_for_block(), template6.interruptWait())
 
+                self.log.debug("Template objects go out of scope")
+                # Since multiple templates have common transaction references,
+                # a regression in BlockTemplateImpl / ~BlockTemplateImpl reference
+                # counting should result in a crash here.
+
+            self.log.debug("Template objects are out of scope")
+
         asyncio.run(capnp.run(async_routine()))
 
     def run_ipc_option_override_test(self):
@@ -590,6 +603,18 @@ async def async_routine():
                 self.log.debug("submitBlock should reject the duplicate complete block")
                 await self.assert_submit_block(mining2, ctx2, block, result=False, reason="duplicate")
 
+                self.log.debug("Reported memory load should be > 0")
+                # Clients are expected to drop references to stale block templates
+                # briefly after the tip updates. In practice we mainly care about
+                # the memory footprint caused by mempool churn, but this scenario
+                # is easier to test.
+                assert_greater_than((await mining.getMemoryLoad(ctx)).result.usage, 0)
+
+                # Manually release the template:
+                await template.destroy(ctx)
+                self.log.debug("Reported memory load should be 0")
+                assert_equal((await mining.getMemoryLoad(ctx)).result.usage, 0)
+
             self.log.debug("Block should propagate")
             # Check that the IPC node actually updates its own chain
             assert_equal(self.nodes[0].getchaintips()[0]["height"], current_block_height + 1)

From c82ccf896759b0d89a953dfb0c66fda176f22afc Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 19 Dec 2025 18:23:59 -0600
Subject: [PATCH 6/6] test: cover feeThreshold = MAX_MONEY

---
 test/functional/interface_ipc_mining.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/test/functional/interface_ipc_mining.py b/test/functional/interface_ipc_mining.py
index 1c0edf8edc2f..7d0cec3c2380 100755
--- a/test/functional/interface_ipc_mining.py
+++ b/test/functional/interface_ipc_mining.py
@@ -24,6 +24,7 @@
     DEFAULT_BLOCK_RESERVED_WEIGHT,
     MAX_BLOCK_SIGOPS_COST,
     MAX_BLOCK_WEIGHT,
+    MAX_MONEY,
     from_hex,
     msg_headers,
     ser_uint256,
@@ -265,12 +266,15 @@ async def create_block():
                 txsigops = await template.getTxSigops(ctx)
                 assert_equal(len(txsigops.result), 0)
 
-                self.log.debug("Wait for a new template")
+                self.log.debug("Wait for a new template, get one after the tip updates")
                 waitoptions = self.capnp_modules['mining'].BlockWaitOptions()
                 waitoptions.timeout = timeout
-                waitoptions.feeThreshold = 1
+                # Ignore fee increases, wait only for the tip update
+                waitoptions.feeThreshold = MAX_MONEY
+                self.miniwallet.send_self_transfer(fee_rate=10, from_node=self.nodes[0])
                 template2 = await wait_and_do(
                     mining_wait_next_template(template, stack, ctx, waitoptions),
+                    # This mines the transaction, so it won't be in the next template
                     lambda: self.generate(self.nodes[0], 1))
                 assert template2 is not None
                 block2 = await mining_get_block(template2, ctx)
@@ -281,6 +285,7 @@ async def create_block():
                 assert template3 is None
 
                 self.log.debug("Wait for another, get one after increase in fees in the mempool")
+                waitoptions.feeThreshold = 1
                 template4 = await wait_and_do(
                     mining_wait_next_template(template2, stack, ctx, waitoptions),
                     lambda: self.miniwallet.send_self_transfer(fee_rate=10, from_node=self.nodes[0]))