node: add BlockTemplateCache #33421

1. 
   ismaelsadeeq commented at 6:47 pm on September 17, 2025: member

   This PR implements the first step of #33389.

   Main motivation and design rationale are discussed in #33389.

   It introduces a BlockTemplateCache exposed via the node interfaces.

   Block template requests from other node components should go through the cache. Each request specifies the maximum age of the template in seconds. If a cached template exists with matching configuration and is still fresh, it is returned; otherwise, a new template with the requested configuration is generated and added to the cache.

   The BlockTemplateCache subscribes to the validation interface BlockConnected notification and clears the cache when a new block is connected, preventing stale templates from being served.

   The cache has a configurable maximum size (default 10).

   ---

   If test_block_validity is true in the request block creation options and the found cached template has not been validated yet, it is checked and returned. This is the reason GetBlockTemplate also locks cs_main; otherwise, the method can run with only locking m_mutex .

   MakeBlockTemplateCache returns a shared pointer so it can be registered with the validation interface using RegisterSharedValidationInterface hence not requiring explicit unregistration.

2. DrahtBot renamed this:
   node: add `BlockTemplateCache`
   node: add `BlockTemplateCache`
   on Sep 17, 2025
3. 
   DrahtBot commented at 6:47 pm on September 17, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33421.

   Reviews

   See the guideline for information on the review process. A summary of reviews will appear here.

   Conflicts

   Reviewers, this pull request conflicts with the following ones:

   • #31664 (Fees: add Fee rate Forecaster Manager by ismaelsadeeq)
   • #31382 (kernel: Flush in ChainstateManager destructor by TheCharlatan)
   • #30157 (Fee Estimation via Fee rate Forecasters by ismaelsadeeq)
   • #28676 (Cluster mempool implementation by sdaftuar)

   If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

4. ismaelsadeeq force-pushed on Sep 17, 2025
5. ismaelsadeeq force-pushed on Sep 17, 2025
6. ismaelsadeeq force-pushed on Sep 23, 2025
7. 
   ismaelsadeeq commented at 4:45 pm on September 23, 2025: member

   Forced pushed from dca8200c71bb568ffe4821c68209e07a305db80d to 16d55585aa2d26e9177734927b8446faa72570e7 5db80d..16d5558

   Main Changes are

   1. Moved the BlockTemplateCache to src/node/miner.cpp to fix the circular dependency issue
   2. The response now return the block template creation time
   3. We search for match from right to left to return the fresh hit first
   4. Added a fuzz test that test various cache condition and add more coverage to the BlockAssembler Code.
8. 
   ismaelsadeeq commented at 5:01 pm on September 23, 2025: member

   It seems the new fuzz test in 16d5558 caught a minor UndefinedBehaviorSanitizer: unsigned-integer-overflow issue on master.

   0/home/admin/actions-runner/_work/_temp/src/node/miner.cpp:414:47: runtime error: unsigned integer overflow: 2000 - 4000 cannot be represented in type 'size_t' (aka 'unsigned long')
   1    [#0](/bitcoin-bitcoin/0/) 0x5b2b2753aee0 in node::BlockAssembler::addPackageTxs(int&, int&) /home/admin/actions-runner/_work/_temp/build/src/./node/miner.cpp:414:47
   2
   3
   4SUMMARY: UndefinedBehaviorSanitizer: unsigned-integer-overflow /home/admin/actions-runner/_work/_temp/src/node/miner.cpp:414:47 
   5MS: 5 PersAutoDict-PersAutoDict-EraseBytes-CopyPart-InsertRepeatedBytes- DE: "\000\000\000\000"-"\001\000\000\000\000\000\000\000"-; base unit: 05fe405753166f125559e7c9ac558654f107c7e9
   60x1,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x27,0x27,0x27,0x27,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,
   7\001\000\000\000\000\000\000\000''''\000\000\000\000\000\000\000\000\000\000\000\000\000
   8artifact_prefix='./'; Test unit written to ./crash-52e81f820b02d40ce3132a4d8e27726deb8eb132
   9Base64: AQAAAAAAAAAnJycnAAAAAAAAAAAAAAAAAA==
   

   https://github.com/bitcoin/bitcoin/actions/runs/17949962995/job/51047356983?pr=33421

   This is possible on master when node is started with -blockmaxweight=2000 , -blockreservedweight=2000 or just blockmaxweight=2000 and mining interface createNewBlock pass blockReservedWeight as 2000.

   This undefined behaviour is possible after #32355 because it introduced a fixed BLOCK_FULL_ENOUGH_WEIGHT_DELTA with value 4000. Before #32355 the delta was tied to the options.blockreservedweight so will just be 2000 - 2000 which will result in a valid size_t value.

   I’ll push a commit with a fix soon.

9. ismaelsadeeq force-pushed on Sep 24, 2025
10. glozow added the label Bug on Sep 24, 2025
11. glozow added the label Needs backport (29.x) on Sep 24, 2025
12. glozow added the label Needs backport (30.x) on Sep 24, 2025
13. glozow removed the label Bug on Sep 24, 2025
14. glozow removed the label Needs backport (29.x) on Sep 24, 2025
15. glozow removed the label Needs backport (30.x) on Sep 24, 2025
16. 
    glozow commented at 5:55 pm on September 24, 2025: member

    It seems the new fuzz test in 16d5558 caught a minor UndefinedBehaviorSanitizer: unsigned-integer-overflow issue on master.

    Nice! Sorry for the labeling noise, I meant to label #33475

17. fanquake referenced this in commit 05d984b1a4 on Sep 25, 2025
18. DrahtBot added the label Needs rebase on Sep 25, 2025
19. node/miner: allow generation of oversized templates

    Constructing a BlockAssembler with ALLOW_OVERSIZED_BLOCKS allows oversized blocks.

    a28c653eb2
20. node: add block template cache to miner 0154401f10
21. test: add blocktemplatecache fuzz test ed482dedb5
22. ismaelsadeeq force-pushed on Sep 25, 2025
23. DrahtBot removed the label Needs rebase on Sep 25, 2025

Contributors
ismaelsadeeq DrahtBot glozow