RFC: mining, ipc: allow resizing coinbase reservation on an existing BlockTemplate #36834

issue mutatrum opened this issue on November 11, 2026
  1. mutatrum commented at 12:49 PM on November 11, 2026: contributor

    Problem

    In the Mining IPC interface, block_reserved_weight (minimum 2,000 WU) and coinbase_output_max_additional_sigops must be chosen upfront in Mining.createNewBlock(options), and BlockTemplate.waitNext() reuses those captured options.

    In practice, mining clients often don't want a static upfront guess:

    1. Changing coinbase size (#33575): When downstream payout outputs grow or shrink (e.g., Stratum V2 CoinbaseOutputConstraints or dynamic pool payouts), the client has to interruptWait() and call createNewBlock(), locking the mempool and rebuilding the entire template just to free or reclaim a few hundred/thousand WU.
    2. Multiple downstream profiles (#33389 / #35675): A proxy serving both solo miners (~930 WU total header + coinbase) and multi-output pool channels (16,000+ WU) cannot share a single BlockTemplate stream.
    3. 2,000 WU static floor (#31384): MINIMUM_BLOCK_RESERVED_WEIGHT (2,000 WU) includes a ~1,000+ WU human-error cushion for -blockreservedweight CLI users, which isn't needed when an IPC client knows the exact byte weight of its serialized coinbase.

    Proposal

    Add a method on BlockTemplate (or support inside BlockTemplateManager) that derives a new immutable BlockTemplate for a given coinbase weight and sigop budget by dropping enough low-feerate transactions/chunks from the existing template in memory, without re-locking cs_main or the mempool:

    # src/ipc/capnp/mining.capnp (inside interface BlockTemplate)
    trim [@11](/bitcoin-bitcoin/contributor/11/) (context :Proxy.Context, options: BlockCreateOptions) -> (result: BlockTemplate);
    

    Concretely, this only needs to:

    1. Record cluster-chunk boundaries in CBlockTemplate during BlockAssembler::addChunks() so whole dependent chunks (or standalone transactions) are dropped cleanly without stranding low-fee CPFP parents.
    2. Copy the kept vtx slice into a new BlockTemplateImpl (leaving the original template and any active waitNext() / submitSolution() calls untouched).
    3. Subtract the dropped transaction fees from CoinbaseTx::block_reward_remaining and call the existing BlockWitnessMerkleRoot() and CoinbaseMerklePath() helpers (~0.2 ms, lock-free).

    Alternative proposal

    If the requirement that the raw template be submittable before trimming is dropped, you can go one step further: have createNewBlock / BlockTemplateManager snapshot slightly more than 4,000,000 WU of linearized chunks from the mempool (say 4,050,000 WU, maybe ~15–30 extra chunks in memory) and only materialize the CoinbaseTx + Merkle commitments when the client calls finalize(exact_coinbase_weight, exact_sigops), exchanging enough transactions inside the 4 MWU limit with excess chunks to find the best fit.

    This can work in conjuction with the above proposal for backwards compatibility (if needed for such a new interface), where createNewBlock can trim it to the requested size.

    Questions for Feedback

    1. Does this belong as a method on BlockTemplate, transparently inside BlockTemplateManager (#35675), or both?
    2. Does it make sense to drop the 2,000 WU MINIMUM_BLOCK_RESERVED_WEIGHT safety cushion for the IPC path to the actual header + base-coinbase structural weight (~776 WU), letting the client trim the exact additional weight its coinbase needs?
  2. ismaelsadeeq commented at 10:33 AM on November 12, 2026: member

    This is a duplicate of #35596. The main question is: do we want to be pedantic and allow the absolute minimum, which may let users shoot themselves in the foot or assume there is a minor accounting bug having the absolute minimum may causes us to create an invalid block? Historically, we've been conservative and left a few unused blocks in case of such incidents. See #36156 for related discussion.

  3. mutatrum commented at 1:49 PM on November 12, 2026: contributor

    Apologies, I missed that issue. It is in the same area, but one noticeable difference with the alternative approach is that the block is sealed (by lack of better name) when the exact sizes are known, so all accounting happens internally. This removes the need to pre-determine the reserved space, and takes the foot-gun out of the users hands. It does add some computation at the finalize call, but re-ordering the tail of the block and rehashing a small part of the merkle tree should be really fast.

    Shall I close this issue and add a comment there?


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-19 19:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me