Allow coinbase output updates independently of transaction-template changes

[lorbax]

A pool may need to change coinbase outputs while miners continue working on exactly the same ordered transactions—for example, to update payout destinations, merged-mining commitments or channel commitments. These changes should not inherently require another transaction declaration or retransmission of all the unchanged mining-job data.

In Full-Template mode, the declared coinbase is part of the approved work. When authorization binds that coinbase, changing its outputs can require another JDS approval even though the selected transactions remain unchanged. This couples live mining management to transaction-template validation. The motivation for this proposal is to provide a lightweight Mining Protocol mechanism for updating coinbase outputs while preserving the transaction-template identity and the client’s ability to include and order its own outputs. Updates within the existing validation and resource constraints could proceed without another JDS round trip. The same mechanism could also reduce redundant job distribution for ordinary pool-selected work.

A broader solution would move coinbase construction, payout requirements and other mining management entirely into the Mining Protocol, leaving JDS responsible for transaction-template validation and block propagation. That would provide a clearer separation, but requires substantial redesign.

A smaller proposal could introduce coinbase output updates while keeping the transaction-template identity stable.

Proposed messages

Introduce two Mining Protocol messages:

SetCoinbaseOutputs (Server → Client)

Updates the pool-specified coinbase outputs for an existing job. For ordinary pool-selected work, the message supplies the complete output list and its ordering. For JD work, including Coinbase-only, it replaces the pool's previous output requirements. The downstream combines these requirements with its miner-owned outputs and TP requirements.

Field Name	Data Type	Description
channel_id	U32	Mining channel identifier.
job_id	U32	Identifier of the existing job whose coinbase outputs are being updated. The job identifier and ordered non-coinbase transactions MUST remain unchanged.
coinbase_tx_outputs	B0_64K	Bitcoin transaction outputs supplied by the pool. CompactSize-prefixed array of consensus-serialized outputs, interpreted according to the work type above.

SetCoinbaseOutputsSuccess (Client → Server)

Only used for Custom Jobs introduced through SetCustomMiningJob, in either Full-Template or Coinbase-only mode. This response communicates the final ordered output list after the downstream combines the pool’s requirements with its miner-owned outputs and TP requirements. For ordinary pool-selected work, SetCoinbaseOutputs already supplies the complete ordered output list. No SetCoinbaseOutputsSuccess response is exchanged, and the pool MUST NOT wait for one.

Field Name	Data Type	Description
channel_id	U32	Mining channel identifier from the corresponding SetCoinbaseOutputs message.
job_id	U32	Existing job identifier from the corresponding SetCoinbaseOutputs message.
coinbase_tx_outputs	B0_64K	Complete, final, ordered coinbase output list. CompactSize-prefixed array of consensus-serialized outputs, including all required outputs.

For this proposal, job_id identifies the ordered non-coinbase transaction template. Updating only the coinbase outputs would not increment the job counter, repeat transaction exchange, or require another SetCustomMiningJob / SetCustomMiningJobSuccess exchange.

Output ownership and ordering

The interpretation would depend on the work being updated:

• Ordinary pool-selected work: The pool supplies the complete output list and its ordering. The proxy reconstructs the coinbase using the existing job data and distributes updated work downstream, without requiring another full NewExtendedMiningJob from the pool.

• JD work, including Coinbase-only: The message replaces the pool’s output requirements. JDC combines them with its miner-owned outputs and TP requirements, then returns the exact resulting output list in SetCoinbaseOutputsSuccess.

JD clients would retain the ability to reorder and interleave outputs. There would be no mandatory pool outputs + client outputs concatenation. The previous pool outputs are replaced; they are not retained alongside the new ones. Coinbase output updates MUST preserve the validated witness commitment and the coinbase witness reserved value. Outputs MAY be reordered, but the effective BIP141 commitment after the update MUST remain the validated commitment. The downstream and pool MUST check
this before activating the updated work. Changes to the non-coinbase transactions or their witnesses require normal template validation. The pool checks that its required outputs are included with the appropriate amounts and multiplicity. The completed coinbase must also preserve the applicable commitments and satisfy reward, weight, sigops and witness-commitment constraints. These are checks on the coinbase change, without repeating validation of unchanged transactions. Coinbase output updates must fit within the resources reserved by TP. An update exceeding that reservation may require JDC to contact TP and obtain a compatible template before activating the updated work. This could change the selected transactions and require another declaration. How reservations can be increased during a session remains a design question. JDC remains responsible for constructing work that preserves its own and TP’s requirements. The payout-output convention must distinguish an adjustable payout amount from genuinely zero-valued outputs.

Approval and block propagation

When accepting the initial SetCustomMiningJob, the pool verifies the JDS token and records the accepted job. Subsequent coinbase updates are authorized through SetCoinbaseOutputs and completed by SetCoinbaseOutputsSuccess. The pool checks these updates against the accepted job’s constraints, without requesting another JDS approval or verifying the original coinbase-bound token against the modified coinbase. The pool must be able to verify that authorization without contacting JDS.

For Full-Template operation, replace:

PushSolution.extranonce: B0_32

with:

PushSolution.coinbase_tx: B0_64K

This carries the actual complete solved coinbase, including extranonce and witness data, following TDP’s SubmitSolution.
PushSolution should also include an explicit reference to the approved declaration. JDS can then reconstruct the block from the supplied coinbase and retained transactions, rather than relying on its most recent declaration or cached coinbase. Consequently, it is not needed to forward the every coinbase output update to JDS.

Properties to preserve

• No direct Pool–JDS communication: JDC carries the approval to the pool and the solved coinbase to JDS.
• JDS retains declaration recognition, validation and block propagation in Full-Template mode.
• Optimistic startup remains available: Once the initial template, output requirements and extranonce assignment are known, downstream work can begin as before, with shares buffered until initial Mining acceptance.
• Coinbase-only retains its privacy tradeoff: JDS does not receive or validate the transactions, and JDC/TP continue handling block propagation.

For a smaller first change, AllocateMiningJobTokenSuccess.coinbase_tx_outputs could remain the initial advertisement, with subsequent Mining messages replacing those requirements. Moving the initial advertisement into a channel-scoped Mining message would make that allocation field redundant, but needs a bootstrap rule before a custom job_id exists.

Activation and compatibility

Keeping the same job ID requires an explicit rule for activating updated coinbases and handling shares already in flight. SetCoinbaseOutputsSuccess could provide an ordered cutover boundary, but then late shares using the previous coinbase would need to be discarded. Retaining older coinbases for validation is another possibility, with additional processing and retention costs. These semantics require an explicitly negotiated extension or protocol revision.

Use cases

• Channel-difficulty commitment: Update the commitment without redeclaring unchanged transactions. This is relevant to DEMAND’s transparency system.
• Merged mining: Refresh an auxiliary-chain commitment independently of Bitcoin transaction selection, as needed for Rootstock (https://dev.rootstock.io/node-operators/merged-mining/getting-started/).
• Direct coinbase payouts: Update recipients and amounts as a P2Pool-style accounting window (https://en.bitcoin.it/wiki/P2Pool#Payout_logic) advances.
• Payout address or script rotation: Change the reward destination or custody arrangement during a session.
• Lighter work selection: Update outputs while reusing the existing coinbase prefix, Merkle path and other job parameters instead of retransmitting an entire NewExtendedMiningJob or another round of declaration for JD downstreams.

[lorbax]

To clarify the scope: this discussion is not specifically aimed at solving payout distribution, as addressed by PR #195 and PR #203. Payout distribution introduces additional accounting and policy questions, including recipient selection, allocation of amounts, dust handling and accounting-window updates. Both proposals involve JDS in payout management and rely on coordination or shared payout state between JDS and Pool. This does not necessarily require a direct network connection, but it makes payout information part of JDS’s responsibilities.

The mechanism discussed here is more general: the pool updates coinbase output requirements through the Mining Protocol, without requiring JDS to track live payout state. Payout distribution is one possible application, alongside other coinbase commitments and ordinary non-JD work. In Full-Template mode, JDS would still validate the declared work and receive the complete solved coinbase for block propagation. The aim is to keep live coinbase-output management in the mining relationship.

[plebhash]

thanks for the proposal @lorbax

I'll break down my thoughts and feedback in different threads under this Github Discussion so we can keep the discussion focused on specific topics.

[plebhash]

before going through the details of this proposal I feel I need to challenge a core assumption, and hopefully reveal a blindspot on how the spec is being interpreted.

it seems we're assuming that when the difficulty target of a channel is modified (via SetTarget), whatever job is currently now follows a new difficulty target.

that is not true.

since the inception of sv2-spec repo in 2022, we had this sentence on the definition of SetTarget:

The message is not applicable for already received jobs with future_job=False, as their maximum target remains stable.

while some terminology has changed since then (there's no future_job field on job messages anymore, that semantics now is on ntime_start + SetNewPrevHash), the core point remains:

• difficulty target is a property of channel state
• a job inherits its difficulty target from current channel state at the moment it is activated (or committed via SetCustomMiningJob)
• the same active job can never have its difficulty target changed. once the channel state has been updated with the new target, only the next active job will carry it.

---

now, I do understand how DMND SLICE brings the pre-requisite of committing the difficulty target to the coinbase tx, and nothing of what I clarified above dismisses that: committing the difficulty target inside the coinbase tx is still important because shares need to be auditable in a way that vanilla Sv2 does not allow.

so yeah, we still need a protocol extension!

but it is important that we clarify which problems need a solution, and which problems do not.

more specifically, there's no obstacle for share validation.

as long as the Mining Server:

• knows about the difficulty target that was associated with the channel when the job was activated
• knows about the coinbase tx that's associated with the job (as well as the rules on how diff target is committed inside of it)

it already has everything it needs to validate shares.

note: with regards to share validation, channels_sv2 correctly implements everything that's required here.

---

now, onto the extension design:

hopefully my clarifications above make it clear why there's no need to add a new message, because the same job cannot change its own difficulty target without contradicting some fundamental properties of Sv2 Mining Protocol

so I think DMND SLICE could benefit from a much simpler extension:

as soon as the extension is enacted via the RequestExtensions handshake, the following rules take place:

• JDC MUST commit a coinbase tx that carries the difficulty target currently associated with its channel into every SetCustomMiningJob, and the server MUST reject a SetCustomMiningJob whose commitment differs from the channel's current target (or that carries no commitment at all)
• after receiving a SetTarget message, JDC MUST send a new SetCustomMiningJob with the same token as the last one it sent, but with a coinbase tx that commits to this new difficulty target, and the server MUST accept token reuse for jobs that differ only in the target commitment

where in the coinbase tx the difficulty target is committed remains an open-ended question... during WG call, it was proposed that it was committed to scriptSig instead of an OP_RETURN output (personally I don't really have any preferences)

so in this alternative approach, the difficulty target would go into SetCustomMiningJob.coinbase_prefix instead of SetCustomMiningJob.coinbase_tx_outputs

and finally:

• PushSolution gets a TLV extension for target, where JDS knows exactly where to place it (scriptSig or OP_RETURN) against the coinbase that was declared via DeclareMiningJob

note: with regards to creating jobs with non-vanilla Sv2 logic, channels_sv2 recently got a new PrebuiltJob API that allows the user to bypass the internal job factory and mutate the channel state with jobs created under different criteria (v9.0.0 already published to crates.io)

[lorbax]

Hi @plebhash, thank you for the time spent reviewing.
I would like to point out that what I wrote goes much further than simply committing the difficulty. My leading idea is to detach the coinbase and its managment from the job and put it in a specific message. This is a substantial redesign, so I thought the message above SetCoinbaseOutputs as a smaller step, while still preserving enough functionality.
You are right, my proposal is not coherent, as the SetTarget does not apply to the current job (i.e. only shares for a new job will be produced against the new target). The extension proposal that you wrote actually works without requiring communication
POOL <--> JDS, which is a good thing (even if it is no clear why this can't be handled by a clever use of a TLV field on SetTarget message). My concern is its scope: it handles one particular coinbase modification, while other use cases need similar functionality.
For example, it appears that the extension that you proposed does not handle the case where a pool requires a jd-downstream to add a specific coinbase output. As for my understanding, there is currently no machinery for it and, imo is something that we definitely want to include in the future. AllocateMiningJobToken.Success advertises those requirements during allocation, but using it for unsolicited updates would itself require new semantics and too many communication rounds for a simple coinbase output update. Note also that even in the non-jd case, if the pool wants to do that must send a blob of 400-500 bytes before arriving to coinbase_suffix. Moreover, if a pool happens to save the jobs for whatever reason, this may be a non neglictible worsening.

It seems worth exploring whether a common mechanism could support these cases. The whole point here is the actual need for enough flexibility to allow the pool to change a coinbase output on the fly without wasting resources.

Finally, at DEMAND we chose coinbase outputs because the 100-byte scriptSig budget is shared by the block height, extranonce, tags and other commitments, and can become tight quickly. Using scriptSig is a valid option for small commitments, but not for general use. Also, compared to using the coinbase outputs, it is likely harder to implement.

[plebhash]

fair enough, I guess we don't necessarily need to narrow down the scope of the extension to the difficulty use-case only.

but I would make some adjustments to the original proposal:

---

first, I must say I'm not a fan of keeping a new modified coinbase under the same job_id.

this invites unnecessary edge cases and races for share validation, as described on Activation and compatibility section of the original post above.

so IMO the SetCoinbaseOutputs proposed above should carry past_job_id + new_job_id instead of job_id, so that we bypass edge cases for share validation.

---

we also need to establish how JDC is supposed to identify the output that potentially carries the new target

that could be achieved either by rules around ordering of outputs, or by imposing some specific syntax for the OP_RETURN that uniquely attributes special semantics to this specific output

personally, I would go with a special syntax and leave output ordering arbitrary... something like:

value:          0x0000000000000000            (8 bytes, zero)
script length:  0x28                          (40 bytes)
script:         0x6a                          OP_RETURN
                0x26                          push of 38 bytes
                0x746172676574                "target", 6-byte ASCII tag
                <target>                      32 bytes, U256 as defined in §3.1 (little-endian)

the 0x746172676574 aka "target" magic bytes allow us to uniquely distinguish this output from other potential arbitrary use-cases

a coinbase tx MUST carry at most one output with this tag, and the server MUST reject jobs with more than one.

we should allow for the possibility for this specific output to be absent, because not every implementer will need to commit difficulty targets on coinbase outputs

---

then yeah, as I mentioned above, no need to replace PushSolution.extranonce with PushSolution.coinbase_tx

just append coinbase_tx_outputs to PushSolution as TLV

---

we also need to establish how this special output takes precedence over SetTarget:

• the target output acts as a SetTarget applied to the channel immediately before the job carrying it is activated, so that job inherits it from channel state as any job does: the server MUST validate shares for that job against it, and JDC MUST treat it as the current channel target from that point on
• a job whose coinbase carries no target output keeps the rules of 5.3.21 and inherits the current channel target at activation
• the committed value is bound by the same max_target rule as SetTarget, including the tolerance for a crossing UpdateChannel, and JDC MUST answer a push that violates it with SetCoinbaseOutputs.Error

SetCoinbaseOutputs.Error also covers:

• a duplicate target output
• a push exceeding the blockspace reserved at AllocateMiningJobToken.Success
• an unknown past_job_id or channel_id

[lorbax]

First of all, I want to remark that even if this at the beginning looked like a proposal, it is really meant as a discussion. If someone else shows up with a better design, I am more than happy. IMO what matters is to give some flexibility to the coinbase management.

I like you idea of putting a job_id update.

SetCoinbaseOutputs (Server → Client)

Field Name	Data Type	Description
channel_id	U32	Mining channel identifier.
job_id	U32	Identifier of the existing job used as the basis for the update. Its ordered non-coinbase transactions MUST remain unchanged in the new job.
new_job_id	U32	Identifier assigned by the pool to the new job containing the updated coinbase outputs. MUST differ from job_id and MUST NOT already identify a valid or pending job on this channel.
coinbase_tx_outputs	B0_64K	Bitcoin transaction outputs supplied by the pool. CompactSize-prefixed array of consensus-serialized outputs, interpreted according to the work type above.

in this way shares for old job can still get accepted while that job remains valid and retained. The new job reuses the accepted transaction template and unchanged job data, without another JDS declaration or retransmission of the full job. This is the diagram

sequenceDiagram
    participant P as Pool
    participant C as Client / proxy
    P->>C: SetCoinbaseOutputs(job_id=42, new_job_id=43, requirements)
    Note over P: Job 42 remains valid with C0 / T0. Job 43 is pending
    C->>P: Shares for job 42
    C->>P: SetCoinbaseOutputsSuccess(new_job_id=43, final outputs C1)
    Note over P: Validate and accept job 43 with C1 / T1
    C->>P: Shares for job 43
    C->>P: Late shares for job 42
    Note over P: Validate each share using its job's coinbase and target

Loading

---

About this

just append coinbase_tx_outputs to PushSolution as TLV

this is true, but why not append the whole transaction like in the message SubmitSolution in TDP? In this way, if we ever wanna do something similar with coinbase prefix, we already have some machinery.

---

we also need to establish how this special output takes precedence over SetTarget

here an important remark must be made. In the design above there is no channel-control semantics to application-specific output tags. This gives it already quite an amount of flexibility, which is a good thing. I wouldn't kill it by specializing to a particular use case, like difficulty update. Let's say that we agree to an extension as the above, call it Extension A, which only adds the capability for changing coinbase ouputs on the fly. On top of A, we can have a second Extension B that add semantics for difficulty updates. We can then discuss what to do with SetTarget within B. That said, my idea is that SetCoinbaseOutputs with a difficulty commit contains all the data that is transported by SetTarget, so I would say that with B activated, that message is deprecated. To summarize:

1. The initial target comes at channel opening
2. Subsequent target changes arrive through A’s coinbase-output updates.
3. The updated coinbase and target become effective together.
4. Old job keeps the old target, new jobs are mined with the new target.
5. If UpdateChannel.max_target < pool target, the pool must send a new target via SetCoinbaseOutputs

How does this look?

Also, we don't have to stick to commit the target in the coinbase. At demand we committed the difficulty encoded in few bytes. This save space, but it is an implementation detail.

[lorbax]

Two more things.

---

First, also the .Success message needs a slight modification, since a non-jd downstream has no outputs to add.

SetCoinbaseOutputsSuccess (Client → Server)

Acknowledges the new job proposed by SetCoinbaseOutputs. For custom jobs, this response also supplies the final ordered coinbase outputs constructed by the downstream.

Field Name	Data Type	Description
channel_id	U32	Mining channel identifier from the corresponding SetCoinbaseOutputs message.
new_job_id	U32	Identifier of the new job, matching SetCoinbaseOutputs.new_job_id.
coinbase_tx_outputs	OPTION[B0_64K]	None for non-JD work; the complete final ordered output list for JD work. See the rules below.

For non-JD work, coinbase_tx_outputs MUST be None. The outputs supplied in SetCoinbaseOutputs.coinbase_tx_outputs are already the complete final ordered list, and this response acknowledges their use for new_job_id.

For JD work, including both Full-Template and Coinbase-only custom jobs introduced through SetCustomMiningJob, coinbase_tx_outputs MUST be Some(...) containing the complete final ordered output list as a CompactSize-prefixed array of consensus-serialized outputs. This list MUST include every output supplied in the corresponding SetCoinbaseOutputs message, including repeated occurrences. The downstream MAY reorder the pool-supplied outputs and add its own outputs. It MUST return the complete resulting list even if it made no changes to the supplied list. If a JD response is None or omits any required output, the pool MUST close the connection.

---

Second, regarding SetCoinbaseOutputs message: for JD work, the outputs supplied in the latest successfully acknowledged SetCoinbaseOutputs replace the pool's previous output requirements for that channel. Every subsequent SetCustomMiningJob sent on the same channel after that acknowledgment MUST include all those outputs in SetCustomMiningJob.coinbase_tx_outputs, including repeated occurrences, until those requirements are replaced by a later successfully acknowledged update.. The downstream MAY reorder the pool-required outputs and add its own outputs, and MUST include the TP-required outputs for the new template.