mining: add requestedOutputs field, e.g. for merged mining

Sjors commented at 5:41 pm on November 17, 2025: member

This adds a requestedOutputs field to BlockCreateOptions which lets the Mining IPC client request outputs to be added before the consensus mandatory commitments.

The main use case is being able to add OP_RETURN outputs for merged mining without patching BlockAssembler::CreateNewBlock().

It could potentially also be used to make payouts directly from the coinbase, but this is unsafe for any amount above the subsidy (this PR adds checks for that). In general a pool should add payout outputs after obtaining the block template, even a solo pool.

Although it’s possible to modify pool software to add merge mining outputs on top of the returned block template (e.g. by intercepting and modifying the Stratum v2 NewTemplate message), it may in practice be easier to do this when requesting a template.

Suggested in #33819 (comment).

Builds on:

#33819

DrahtBot renamed this:
~~mining: add requestedOutputs field, e.g. for merged mining~~
mining: add requestedOutputs field, e.g. for merged mining
on Nov 17, 2025

DrahtBot added the label Mining on Nov 17, 2025

DrahtBot commented at 5:41 pm on November 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/33890.

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:

#33795 (test: Ignore error message give from python because of PYTHON_GIL by kevkevinpal)
#33421 (node: add BlockTemplateCache by ismaelsadeeq)

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.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

Scan outputs from getCoinbase() outputs field for the -> Scan the outputs field from getCoinbase() for the [word order makes the sentence confusing; reordering clarifies that the “outputs” field of getCoinbase() should be scanned]

drahtbot_id_5_m

Sjors force-pushed on Nov 17, 2025

DrahtBot added the label CI failed on Nov 17, 2025

DrahtBot commented at 5:50 pm on November 17, 2025: contributor

🚧 At least one of the CI tasks failed. Task Linux->Windows cross, no tests: https://github.com/bitcoin/bitcoin/actions/runs/19438954140/job/55617155652 LLM reason (✨ experimental): Build failed due to a C++ compile error: missing initializer for BlockCreateOptions::requested_outputs, treated as an error by -Werror.

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.
A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.
An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

mining: add getCoinbase()

Introduce a new method intended to replace getCoinbaseTx(), which
provides a struct with everything clients need to construct a coinbase.
This is safer than providing a raw dummy coinbase that clients then have
to manipulate.

A new helper method ExtractCoinbaseTemplate() processes the dummy
coinbase transaction generated by BlockAssembler::CreateNewBlock
and produces a CoinbaseTemplate.

Expand the interface_ipc.py functional test to document its usage
and ensure equivalence.

73553c809e

mining: add requestedOutputs field

Allow Mining IPC clients to request specific outputs that should
be added to the coinbase.

The main use case for this is adding OP_RETURN outputs for merged
mining without patching BlockAssembler::CreateNewBlock().

dbdcb6e74a

Sjors force-pushed on Nov 18, 2025

DrahtBot removed the label CI failed on Nov 18, 2025

Sjors commented at 2:43 pm on November 18, 2025: member

@TheBlueMatt do you know of any merged mining open source projects and whether the approach here would make sense for them?

In https://github.com/stratum-mining/sv2-spec/issues/167#issuecomment-3547519952 you mention that a downside of adding configuration options to template requests is that it increases the potential number of distinct templates, making caching harder.

plebhash commented at 6:24 pm on November 18, 2025: none

is this aimed at Sv2? if not, please disregard everything below

even though the bitcoin_core_sv2 crate introduced via https://github.com/stratum-mining/sv2-apps/pull/59 is leveraging IPC to interact with Bitcoin Core, on the Rust side we’re still abstracting the IO around Sv2 Template Distribution Protocol, for which there’s no message that would be able to carry this kind of information

Although it’s possible to modify pool software to add merge mining outputs on top of the returned block template (e.g. by intercepting and modifying the Stratum v2 NewTemplate message)

NewTemplate is not really intercepted/modified… it becomes:

DeclareMiningJob + SetCustomMiningJob under Job Declaration Protocol
NewMiningJob or NewExtendedMiningJob under Mining Protocol

and when that happens, these messages get the appropriate outputs (be it payout or merged mining) as a natural flow of the protocol, which will eventually turn into valid PoW or Solution

it may in practice be easier to do this when requesting a template.

tbh I don’t think this will introduce any meaningful improvements to Sv2, and it will actually do the opposite if it requires a spec change so this can be integrated

Sjors commented at 9:15 am on November 19, 2025: member

is this aimed at Sv2?

Any consumer of the interface, but I mostly have Stratum v2 in mind.

if it requires a spec change so this can be integrated

As @ajtowns points out in the https://github.com/stratum-mining/sv2-spec/issues/167 thread it’s a bit odd that @TheBlueMatt states that merged-mining is “a key goal of Sv2” while the spec doesn’t even mention it.

In principle the change here doesn’t need a spec change. Miners who want merged-mining will patch something, and this just encourages them to patch the Template Provider rather than Bitcoin Core.

But I do think it would be useful to at least sketch out how merged-mining should interact with Stratum v2, so we can decide if it even makes sense to add an extra field here, or whether such outputs should be added at a later step.

Sjors commented at 6:43 pm on November 20, 2025: member

Going to close this because I don’t think it’s the right approach.

We want to keep templates as reusable as possible in order to support multiple clients (potentially even a public service, though the node would not be doing this directly).

With that in mind it seems better if clients take the template and then customize it by adding their own outputs, rather than us customising it for them.

Sjors closed this on Nov 20, 2025

mining: add requestedOutputs field, e.g. for merged mining #33890

Code Coverage & Benchmarks

Reviews

Conflicts

LLM Linter (✨ experimental)