#33922 mining: add getMemoryLoad() and track template non-mempool memory footprint

• Track memory held by transactions retained only because open block templates reference them
• Expose template memory load over IPC so external mining clients like Stratum v2 providers can manage it

This pull request tracks the memory footprint of transactions that are retained in memory solely because open block templates reference them after they have been removed from the mempool. It adds transaction reference accounting to BlockTemplateManager and introduces a getMemoryLoad() method to the IPC Mining interface so external clients like sv2-tp can monitor this footprint. A fuzz test for template memory usage and functional test coverage in interface_ipc_mining.py are also included.

Problem: When external mining clients retain block templates over IPC, transactions evicted or replaced in the node's mempool cannot be freed until all template references are dropped. Without memory tracking or inspection methods, node operators and IPC clients have no visibility into how much memory stale templates are holding.

P3 · new feature

• P3 because tracking non-mempool template memory provides a useful operational tool for external miners
• Unevicted memory footprint is typically modest under standard conditions rather than a critical risk

P3 because tracking memory footprint of stale block templates helps IPC mining clients manage their memory consumption during mempool churn. Mainnet testing indicates the unevicted memory footprint is typically modest under standard conditions, making this a worthwhile operational tool rather than a critical stability fix.

Membership: Modifies BlockTemplateManager and template transaction reference accounting to track non-mempool memory footprints.

Factors: security/stability 1, bug 0, performance 1, user value 1, leverage 1

P3 · new feature

• P3 because it adds a new monitoring capability to the multiprocess mining interface
• Enables Stratum v2 template providers to inspect server-side memory held by active templates

P3 because it supplies a concrete new capability to the multiprocess mining interface requested for Stratum v2 template providers (sv2-tp). It allows external clients to monitor server-side memory load caused by held template objects.

Membership: Adds the getMemoryLoad() RPC to the interfaces::Mining interface and updates Cap'n Proto mining definitions.

Factors: security/stability 1, bug 0, performance 0, user value 1, leverage 1

• Review #35675 first

The PR builds directly on open PR 35675 (block template manager); reviewing the base PR first will prevent redundant review of shared commits.

Author status: Active; regularly rebasing on top of PR 35675, with recent updates in September 2026.

Resolved concerns:

• ismaelsadeeq argued that relying on IPC clients rather than node-enforced FIFO template eviction could risk OOM; Sjors explained getMemoryLoad() gives clients an opportunity to manage memory gracefully and does not preclude future node-side limits.
• ryanofsky identified that template_tx_refs could be accessed concurrently and needed a mutex; Sjors added template_state_mutex.
• maflcko NACKed an IWYU workaround in transaction primitives; Sjors split out the CTransactionRef hasher changes into PR 35101 and dropped them from this branch.

• Consensus in favor of exposing template memory load over IPC
• Support for the design and utility of template memory tracking (ryanofsky, vasild, enirox001)
• Nonblocking objection: prefer node-side FIFO limits over delegating memory management to clients (ismaelsadeeq)
• Resolved objection: data race addressed by adding a mutex (ryanofsky)
• Resolved objection: brittle header workaround removed into another PR (maflcko)

Positive; consensus on the tracking approach, with thread safety, hashing, and IWYU concerns addressed in updates.

Reviewers support exposing template memory load over IPC. Objections regarding thread safety and IWYU header workarounds were addressed by pushing fixes or moving controversial commits into standalone PRs.

• 2025-12-03: ryanofsky Concept ACKed the getMemoryLoad function and tracking design.
• 2026-04-27: vasild provided an updated PGP-signed ACK following hasher refinements.

Objections:

Support:

• ryanofsky: The getMemoryLoad() function is useful and underlying tracking provides what is needed to limit memory used by block templates
• vasild: Reviewed and approved the accounting and hashing logic across multiple updates
• enirox001: Reviewed all commits and verified functional tests

Participants: ismaelsadeeq (objection), brunoerg (neutral), ryanofsky (support), vasild (support), enirox001 (support), hebasto (question), maflcko (objection)

State derived from the lists: substantive support, no open objection (ryanofsky, vasild, enirox001) (model's own read: Positive)

Review verdicts (DrahtBot): 0 (+2)

• Stale ACK: enirox001, vasild
• Concept ACK: ismaelsadeeq, ryanofsky

Depends on: #35675

Based on (shares commits with): #35675

504 lines under test/bench/ci.

• src/node/block_template_manager.cpp +355/-0
• src/test/fuzz/block_template_manager.cpp +347/-0
• src/node/miner.cpp +0/-243
• src/node/block_template_manager.h +139/-0
• src/rpc/mining.cpp +36/-38
• src/node/miner.h +0/-58
• src/node/interfaces.cpp +29/-26
• src/rpc/blockchain.cpp +15/-16
• src/test/miner_tests.cpp +20/-6
• test/functional/interface_ipc_mining.py +25/-0
• src/test/util/setup_common.cpp +15/-8
• src/test/validation_block_tests.cpp +10/-9
• src/test/util/mining.cpp +9/-8
• src/init.cpp +8/-8
• src/util/hasher.h +16/-0
• src/interfaces/mining.h +15/-0
• src/node/context.h +3/-11
• src/test/peerman_tests.cpp +5/-4
• src/private_broadcast.h +1/-7
• src/rpc/server_util.cpp +4/-4
• src/test/fuzz/private_broadcast.cpp +1/-7
• src/test/fuzz/rpc.cpp +4/-4
• src/rpc/server_util.h +2/-4
• src/ipc/capnp/mining.capnp +5/-0
• src/test/util/setup_common.h +4/-0
• src/test/fuzz/connect_block.cpp +3/-0
• src/test/fuzz/utxo_snapshot.cpp +3/-0
• src/test/util/validation.cpp +3/-0
• src/test/validation_chainstatemanager_tests.cpp +3/-0
• src/wallet/test/fuzz/fees.cpp +3/-0
• ci/test/03_test_script.sh +1/-1
• src/node/context.cpp +1/-1
• src/CMakeLists.txt +1/-0
• src/test/fuzz/CMakeLists.txt +1/-0

This PR tracks the memory footprint of transactions that are retained in memory solely because open block templates reference them after removal from the mempool. It exposes a getMemoryLoad IPC method to allow mining clients such as Stratum v2 template providers to monitor memory pressure and drop stale templates accordingly. The change provides useful operational safety for process-separated mining setups without altering block construction. Code review has been positive with ACKs from multiple contributors, but the PR is stacked on open PR 35675.