BlockTemplate Manager Tracking issue #33758

1. 
   ismaelsadeeq commented at 5:55 pm on October 31, 2025: member

   The main motivation and design rationale are discussed in #33389.

   What to review

   • #33421

   Plan

   • Introduce the Block Template Cache (Manager) #33421 Implement a cache layer. All newly created block templates should be stored along with their respective configuration options. Client requests for block templates will specify the maximum age of the template in seconds; that is, how fresh they want the template to be:

     • If a template with matching options exists in the cache and the interval has not elapsed, a cached template is returned.
     • If no template exists or the interval has elapsed, a new template is generated, stored in the cache, and returned.
     • After insertion, the oldest template is evicted if the cache exceeds its maximum size. The cache has a configurable maximum size (default: 10). It also subscribes to the validation interface’s BlockConnected notification and clears the cache when a new block is connected or disconnected, preventing stale templates from being served. If test_block_validity is set to true in the block creation options and the cached template found has not yet been validated, it is checked and then returned. This stage will also allow sharing of template metadata built from the mining interface for a fee estimation mechanism that requires building a block template to obtain package fee rates and use them for fee estimation, and vice versa. See the discussion in #33389.

   • Create a block template manager that will own the BlockTemplateCache. Block template requests from node components and other block template-related operations will be handled via this cache.

   • Prune WaitAndCreateNewBlock and move its implementation to the block template manager under GetNext. This method will use the block template cache for decisions to build a block template. This approach is cleaner and should allow reusing the logic in getblocktemplate, thereby removing the global state. https://github.com/bitcoin/bitcoin/blob/292ea0eb8982faef460c210bd4215d603f487463/src/rpc/mining.cpp#L776 https://github.com/bitcoin/bitcoin/blob/292ea0eb8982faef460c210bd4215d603f487463/src/rpc/mining.cpp#L859-L861 This will also allow pruning WaitTipChanged and exposing information to retrieve the metadata of the last built block template, enabling the removal of additional global state. https://github.com/bitcoin/bitcoin/blob/292ea0eb8982faef460c210bd4215d603f487463/src/node/miner.h#L186-L189

   • Implement trimming of transactions in larger block templates to enable reuse when configurations do not match (see the idea here: https://github.com/bitcoin/bitcoin/issues/33389#issuecomment-3295505510) This will allow reusing block templates from SENDTEMPLATE for mining and fee estimation, but not vice versa, because SENDTEMPLATE builds templates larger than 4 MB.

   • Introduce a push-based subscription mechanism that allows clients to subscribe to fee updates for a given block template and receive a new template when the fee threshold is reached or when the tip changes. This is what waitnext should use. See the related discussion here: https://delvingbitcoin.org/t/determining-blocktemplate-fee-increase-using-fee-rate-diagram/2052 This feature depends on cluster mempool.

Contributors
ismaelsadeeq