#32468 rpc: generateblock to allow multiple outputs

ReviewabilityReviewsAgreementSize
#32468 polespinasa rpc: generateblock to allow multiple outputsReady0Strong131 + 134 tests
  • Allow developers to test blocks with multiple coinbase recipients and custom payout splits
  • Enable mining mempool transactions automatically in regtest without crafting raw blocks
  • Ready for review following an author rebase
  • No review verdicts recorded
  • Strong support for simulating protocols with multiple coinbase recipients (supertestnet)
  • Addressed objections against creating a separate RPC and modifying core miner logic (andrewtoth, maflcko)
  • Addressed objections on backwards compatibility and custom reward amounts (achow101, stickies-v)
  • 131 lines added or modified outside tests
  • 134 lines added or modified in tests
  • 55 lines removed in total
  • 15 files, 7 commits
Mining#12 of 17
P3 · new feature
  • P3 because it improves developer tooling for simulating mining-pool coinbase payouts
  • Eliminates the need to construct raw blocks manually when testing regtest mining structures
Ranking notes
RPC / REST / ZMQ#44 of 55
P3 · user request
  • P3 because it improves test-RPC flexibility by allowing multiple outputs and default mempool mining
  • Developers testing coinbase distributions avoid manually assembling custom transaction lists
  • Ranking pass: Moved down 15: regtest-only developer convenience with no external consumer.
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Updates the `generateblock` RPC to accept multiple outputs (addresses or descriptors) for the coinbase transaction, optionally specifying fixed satoshi amounts for each output while dividing any remaining reward evenly. If no output is provided, the coinbase reward is burned into an OP_RETURN script. Additionally, the `transactions` parameter is made optional, mining transactions from the mempool by default when omitted while mining an empty block when passed an empty array.

Problem: Developers testing mining-pool payouts (such as Ocean or Braidpool) or non-standard coinbase distributions on regtest cannot generate blocks with multiple coinbase outputs without manually constructing and submitting raw blocks. Additionally, `generateblock` previously required an explicit transaction list and could not automatically mine transactions already in the mempool.

Evidence of importance:

  • PR description cites testing requirements for multi-recipient coinbase blocks referenced by SuperTestnet
  • Commit 0bc85108df: 'Allow generateblock to mine empty blocks, blocks with a pre-set of transactions or mine transactions from the mempool.'
  • Commit 565f7f636c: 'Allow to add multiple outputs to the coinbase transaction when using generateblock.'

Scope: Touches `src/rpc/mining.cpp` to modify `generateblock` parameter handling and coinbase construction, and updates several functional tests to omit redundant raw dummy outputs.

Risk of a mistake: medium (rpc_api). Flaws in custom coinbase splitting or mempool template construction in generateblock could produce invalid blocks or fail RPC execution during regtest/testing workflows.

Changed since the previous assessment: Added release notes in doc/release-notes-32468.md and updated the submit argument extraction to use self.Arg<bool>("submit").

Reviewability

Ready

Nothing known that would invalidate a review now.

Waiting on (from the thread read):

  • reviewer: review following author rebase 2026-09-24

Agreement

Strong

substantive support, no open objection (supertestnet)

Thread notes: Author rebased onto master with no new claims or reviews raised.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
maflcko (member)objection, maintenancemodifying core consensus/node miner logic in src/node to accommodate test-only mining behavior introduces dead code and maintenance burdenfixed · fix pushed · addressed by moving logic away from src/node · v1, not yet re-checkedchangedyes2025-05-11: 'Generally, I am not sure about modifying real code to accommodate test-only code. It would be better to not modify `src/node` at all and just put the test-only code in the test-only code paths.'
Status from: 2025-05-12: polespinasa: 'Tried to follow your approach, actually it makes things easier :)'
andrewtoth (member)objection, approachadding a new generatetomany RPC incurs code bloat, extra test maintenance, and deprecation cycles when extending generateblock is more flexible and fixes reward fee issuesfixed · fix pushed · author removed generatetomany and squashed commits · v1, not yet re-checkedchangedyes2025-05-12: 'New RPCs require adding more code to test, and once added must go through a deprecation cycle to be removed (if they can be removed at all without disrupting too many users).'
Status from: 2025-05-25: polespinasa: 'Squashed all commits and removed the first approach (`generatetomany`)'
achow101 (member)objection, interfacerequiring an array rather than continuing to accept a string breaks backwards compatibility for scripts and automated tests using generateblockfixed · fix pushed · added backwards compatibility support for string argument · v1, not yet re-checkedchangedyes2025-05-28: 'Although this RPC is only used by tests, I don't think we should be breaking backwards compatibility here. It's equally easy to determine whether this parameter is a string, so we can accept a string '
Status from: 2025-09-26: polespinasa: '{ "generateblock", 0, "outputs", /*also_string=*/true},'
andrewtoth (member)objection, correctnessomitting the transaction parameter in existing functional tests changes their behavior to mine the mempool instead of generating empty blocksfixed · fix pushed · author restored transactions=[] in tests · v1, not yet re-checkedansweredyes2026-03-22: 'Otherwise this should be backwards compatible, and mining the mempool instead of an empty block can be a behavior change in the tests.'
Status from: 2026-03-25: polespinasa: 'I will add back the `transactions=[]` you are right that is a behavior change and this PR should not be changing that. T'
stickies-v (member)objection, interfacelimiting the RPC interface to equal splits rather than supporting custom reward amounts handicaps its usefulness for the sake of CLI conveniencefixed · fix pushed · custom split rewards implemented · v1, not yet re-checkedchangedyes2026-04-21: 'Custom rewards are the general solution, why not just implement that right away? It's useful to keep the CLI commands ergonomic, but I think it's a mistake to handicap the RPC interface just to make C'
Status from: 2026-09-16: polespinasa: 'Bicaru20 implemented the custom split rewards.'

Support:

  • supertestnet (none) (2025-05-12): The generatetomany command would be particularly useful for simulating protocols that send money to multiple recipients directly from a coinbase, as several pools do now, like ocean and braidpool.

Participants:

  • andrewtoth (member, objection, 9 statements 2025-05-10 to 2026-03-22): objected to creating a new RPC instead of extending generateblock, and flagged behavioral changes in tests
  • supertestnet (none, support, 3 statements 2025-05-10 to 2025-05-12): supported feature to simulate protocols paying multiple coinbase recipients like ocean and braidpool
  • a1denvalu3 (none, support, 3 statements 2025-05-11 to 2025-05-11): supported the feature and collaborated on remainder reward splitting logic
  • maflcko (member, objection, 12 statements 2025-05-11 to 2025-07-17): objected to modifying production miner code in src/node for test-only logic
  • mzumsande (member, question, 1 statements 2025-05-12 to 2025-05-12): asked for motivation to be documented on GitHub rather than Twitter
  • naiyoma (member, neutral, 6 statements 2025-05-24 to 2025-08-31): asked for clarification between approaches, summarized testing, and offered style nits
  • achow101 (member, objection, 4 statements 2025-05-28 to 2025-05-29): objected to breaking backwards compatibility for single string parameter in generateblock
  • sedited (member, question, 1 statements 2026-04-18 to 2026-04-18): asked if custom split rewards were planned to be included in this PR
  • stickies-v (member, objection, 1 statements 2026-04-21 to 2026-04-21): objected to limiting the RPC interface to equal splits instead of implementing custom rewards directly

Files

153 lines under test/bench/ci.

  • src/rpc/mining.cpp +125/-36
  • test/functional/rpc_generate.py +118/-3
  • test/functional/p2p_outbound_eviction.py +5/-5
  • doc/release-notes-32468.md +5/-0
  • test/functional/feature_block.py +2/-2
  • test/functional/feature_assumeutxo.py +1/-1
  • test/functional/feature_fastprune.py +1/-1
  • test/functional/mempool_sigoplimit.py +1/-1
  • test/functional/mempool_truc.py +1/-1
  • test/functional/mempool_updatefromblock.py +1/-1
  • test/functional/rpc_blockchain.py +1/-1
  • test/functional/rpc_getblockstats.py +1/-1
  • test/functional/rpc_txoutproof.py +1/-1
  • test/functional/wallet_bumpfee.py +1/-1
  • src/rpc/client.cpp +1/-0

Card

The short text the ranking pass compares across PRs.

This PR expands the generateblock RPC to support multiple coinbase recipients with optional custom satoshi allocations, falling back to burning the subsidy in OP_RETURN if no outputs are supplied. It also makes the transactions argument optional, allowing blocks to directly pull from the mempool unless an explicit list or empty array is provided. This addresses friction for developers testing multi-recipient coinbase distribution setups like mining pools on regtest. Importance is evidenced by testing needs cited in the description and cleanup across numerous functional tests that previously worked around the restriction.

Data

dossier JSON · extract JSON · model ledger, generated 2026-09-25T01:22, confidence high, input hash 41a57197e4ed058d
thread read through 2026-09-24 (88 statements), head 4dfb2bab4f
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: RPC/REST/ZMQ

Categories

Mining

P3 · new feature

Improves developer-facing tooling by allowing simulation of multi-recipient mining pool coinbase structures (such as Ocean or Braidpool) directly through generateblock.

Membership: Modifies src/rpc/mining.cpp to support multi-recipient coinbase distribution and mempool transaction gathering.

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

RPC / REST / ZMQ

P3 · user request (ranking pass: Moved down 15: regtest-only developer convenience with no external consumer.)

Extends generateblock to support multiple coinbase outputs and optional transaction arguments, resolving a friction point for developers testing multi-recipient coinbase payouts without having to construct raw blocks.

Membership: Labeled RPC/REST/ZMQ; modifies generateblock parameter parsing and default behavior in src/rpc/mining.cpp and src/rpc/client.cpp.

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