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; 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. 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.

2. willcl-ark added the label Mining on Nov 18, 2025
3. willcl-ark added the label Tracking Issue on Nov 18, 2025

Contributors
ismaelsadeeq

Labels
Mining Tracking Issue