From 8e4294a7abd0ac30699be269c9dd3070cf4f21d8 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Tue, 25 Nov 2025 18:16:43 +0100
Subject: [PATCH 1/5] 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 848c872fd4a9..b4da0cdea39d 100644
--- a/src/node/context.h
+++ b/src/node/context.h
@@ -27,6 +27,7 @@ class NetGroupManager;
 class PeerManager;
 class TorController;
 namespace interfaces {
+class BlockTemplate;
 class Chain;
 class ChainClient;
 class Mining;
@@ -67,6 +68,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 dcf5ee26457a..0aa4ce9e30fd 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -859,7 +859,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 56609d959839c6f150f438f48c3db4bae3713492 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 21 Nov 2025 16:12:27 +0100
Subject: [PATCH 2/5] 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      | 12 +++++++++++-
 src/node/interfaces.cpp | 20 +++++++++++++++++++-
 src/node/types.h        |  7 +++++++
 src/util/hasher.h       | 16 ++++++++++++++++
 4 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/src/node/context.h b/src/node/context.h
index b4da0cdea39d..c70d5ef645a2 100644
--- a/src/node/context.h
+++ b/src/node/context.h
@@ -5,10 +5,13 @@
 #ifndef BITCOIN_NODE_CONTEXT_H
 #define BITCOIN_NODE_CONTEXT_H
 
+#include <node/types.h>
+
 #include <atomic>
 #include <cstdlib>
 #include <functional>
 #include <memory>
+#include <sync.h>
 #include <thread>
 #include <vector>
 
@@ -68,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
+    Mutex template_state_mutex;
+    //! Track how many templates (which we hold on to on behalf of connected IPC
+    //! clients) are referencing each transaction.
+    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 16db8692a154..ba5e8dead47d 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -70,6 +70,7 @@
 #include <any>
 #include <memory>
 #include <optional>
+#include <ranges>
 #include <stdexcept>
 #include <utility>
 
@@ -873,7 +874,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/types.h b/src/node/types.h
index 01e74528e06f..056218919d95 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -21,6 +21,8 @@
 #include <primitives/transaction.h>
 #include <script/script.h>
 #include <uint256.h>
+#include <unordered_map>
+#include <util/hasher.h>
 #include <util/time.h>
 #include <vector>
 
@@ -172,6 +174,11 @@ enum class TxBroadcast : uint8_t {
     NO_MEMPOOL_PRIVATE_BROADCAST,
 };
 
+/**
+ * Map how many templates refer to each transaction reference.
+ */
+using TxTemplateMap = std::unordered_map<CTransactionRef, size_t, CTransactionRefSaltedHash, CTransactionRefComp>;
+
 } // namespace node
 
 #endif // BITCOIN_NODE_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 f9db4928d9db11004285ced0f551432855a1a7df Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Tue, 25 Nov 2025 16:26:16 +0100
Subject: [PATCH 3/5] 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   |  9 +++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/node/miner.cpp b/src/node/miner.cpp
index 7ea8d10b7306..18fc29e270d7 100644
--- a/src/node/miner.cpp
+++ b/src/node/miner.cpp
@@ -16,12 +16,15 @@
 #include <consensus/validation.h>
 #include <deploymentstatus.h>
 #include <logging.h>
+#include <logging/timer.h>
+#include <memusage.h>
 #include <node/context.h>
 #include <node/kernel_notifications.h>
 #include <policy/feerate.h>
 #include <policy/policy.h>
 #include <pow.h>
 #include <primitives/transaction.h>
+#include <util/check.h>
 #include <util/moneystr.h>
 #include <util/signalinterrupt.h>
 #include <util/time.h>
@@ -524,4 +527,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 5c8668771f59..8554db2c8e5d 100644
--- a/src/node/miner.h
+++ b/src/node/miner.h
@@ -184,6 +184,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 a9171534b9506fd369c7c14b15417e5269dba6fc Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 19 Dec 2025 18:17:48 -0600
Subject: [PATCH 4/5] 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 f4c42e204a7c..2376bd5e0cfd 100644
--- a/src/interfaces/mining.h
+++ b/src/interfaces/mining.h
@@ -91,6 +91,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
@@ -154,6 +160,12 @@ class Mining
      */
     virtual bool checkBlock(const CBlock& block, const node::BlockCheckOptions& options, 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 node::NodeContext* context() { return nullptr; }
diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index 64cad4d49f28..f3560da18ec9 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -25,6 +25,7 @@ interface Mining $Proxy.wrap("interfaces::Mining") {
     createNewBlock @4 (context :Proxy.Context, options: BlockCreateOptions, cooldown: Bool = true) -> (result: BlockTemplate);
     checkBlock @5 (context :Proxy.Context, block: Data, options: BlockCheckOptions) -> (reason: Text, debug: Text, result: Bool);
     interrupt @6 () -> ();
+    getMemoryLoad @7 (context :Proxy.Context) -> (result: MemoryLoad);
 }
 
 interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
@@ -46,6 +47,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 ba5e8dead47d..3a82e4e57333 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -81,6 +81,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;
@@ -1028,6 +1029,13 @@ class MinerImpl : public Mining
         return state.IsValid();
     }
 
+    MemoryLoad getMemoryLoad() override
+    {
+        LOCK(m_node.template_state_mutex);
+        CTxMemPool& mempool{*Assert(m_node.mempool)};
+        return {.usage = GetTemplateMemoryUsage(mempool, m_node.template_tx_refs)};
+    }
+
     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 31ccec63fa86..4c03c0586ed6 100755
--- a/test/functional/interface_ipc_mining.py
+++ b/test/functional/interface_ipc_mining.py
@@ -28,6 +28,7 @@
 from test_framework.util import (
     assert_equal,
     assert_greater_than_or_equal,
+    assert_greater_than,
     assert_not_equal
 )
 from test_framework.wallet import MiniWallet
@@ -278,6 +279,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
@@ -291,6 +297,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):
@@ -390,6 +403,18 @@ async def async_routine():
                 submitted = (await template.submitSolution(ctx, block.nVersion, block.nTime, block.nNonce, coinbase.serialize())).result
                 assert_equal(submitted, True)
 
+                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 d37e0fc16c235ff511bd9485ef505f0c5615d9e4 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 19 Dec 2025 18:23:59 -0600
Subject: [PATCH 5/5] 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 4c03c0586ed6..6eaaa8b359fe 100755
--- a/test/functional/interface_ipc_mining.py
+++ b/test/functional/interface_ipc_mining.py
@@ -10,6 +10,7 @@
 from test_framework.blocktools import NULL_OUTPOINT
 from test_framework.messages import (
     MAX_BLOCK_WEIGHT,
+    MAX_MONEY,
     CBlockHeader,
     CTransaction,
     CTxIn,
@@ -240,12 +241,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)
@@ -256,6 +260,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]))