RFC: non-custodial payouts via Sv2 JD

[plebhash]

there's interest in the Sv2 community to enable non-custodial payouts via multiple coinbase outputs:

• JDC: Support proportional coinbase output value distribution for PPLNS pools sv2-apps#388
• Integrate JDP with PPLNS via ext 0x0003 (Dynamic Coinbase Outputs) warioishere/blitzpool#115

currently, Sv2 JDP does not allow for that

more specifically, 6.4.3 AllocateMiningJobToken.Success states that:

The following rules apply to AllocateMiningJobToken.Success.coinbase_tx_outputs:

• JDS MUST reserve the first output with a locking script where the pool payout will go. While this output is initally > set with a 0 amount of sats, this convention designates this locking script as the pool payout output.
• JDS MAY add more 0 value outputs in addition to the pool payout output.

Once JDC receives AllocateMiningJobToken.Success, the following rules apply to the subsequent DeclareMiningJob.coinbase_tx_suffix (if under Full-Template mode) and SetCustomMiningJob.coinbase_tx_outputs > (under both Full-Template and Coinbase-only modes) message fields:

• JDC MUST allocate sats into the pool payout output in order to qualify for pooled mining rewards. JDS and Pool SHOULD reject custom jobs that fail to do so.
• JDC MAY add more 0 value outputs in addition to the ones established by JDS.
• JDC MAY add more non-0 value outputs in addition to the ones established by JDS. In doing so, the template revenue is not fully allocated to the designated pool payout output, so Pool MAY pay proportionally smaller rewards for this job.
• JDC MAY arbitrarily reorder the outputs to something different from the original ordering of AllocateMiningJobToken.Success.coinbase_tx_outputs.
• Under Full-Template mode, the order of the outputs under DeclareMiningJob.coinbase_tx_suffix and SetCustomMiningJob.coinbase_tx_outputs MUST remain the same, even if they differ from the original AllocateMiningJobToken.Success.coinbase_tx_outputs.

In summary, the pool payout goes to one single output (standardized as the first output of AllocateMiningJobToken.Success.coinbase_tx_outputs), and JDC is free to add more outputs and shuffle them under any arbitrary ordering scheme.

[plebhash]

on stratum-mining/sv2-apps#388 @warioishere is proposing:

Add an optional field to AllocateMiningJobToken.Success:

| Field Name                    | Data Type        | Description                                                                 |
| ----------------------------- | ---------------- | --------------------------------------------------------------------------- |
| coinbase_tx_output_weights    | SEQ0_64K[U32]    | Proportional weights for each output in coinbase_tx_outputs. If empty,      |
|                               |                  | all reward goes to the first output (current behavior).                     |

The pool sends:

coinbase_tx_outputs: [TxOut(0, script_fee), TxOut(0, script_minerA), TxOut(0, script_minerB)]
coinbase_tx_output_weights: [200, 4900, 4900]

The JDC distributes coinbase_tx_value_remaining based on the weights. If the field is empty or missing, it falls back to the current behavior (everything into output[0]).

this can be achieved in two different ways:

• breaking change to Sv2 JDP spec
• protocol extension

[Fi3]

I'm leaning to use an extension here. Since is not something that is part of the original design, and looks like something that can become much more complex that just providing a list of addresses and percentages.

[plebhash]

and looks like something that can become much more complex that just providing a list of addresses and percentages

can you elaborate?

to me (at a first glance) the proposal seems pretty straightforward, how do you foresee people overcomplicating it?

[Fi3]

The JDC distributes coinbase_tx_value_remaining based on the weights

I don't understand it, isn't coinbase_tx_value_remaining subsidy + fees no? So we need to reasons in % here.

I think that since we are doing JDC such a system should at least account for fess in non proportional way so that miner that mines templates with higher fees are payed more.

Would be nice to have a way for the miner to communicate the shares that should be payed in the next token allocation so that pool can verify that shares do actually exist and have to be payed and can calculate the right amount and maybe communicate to the miner the total amount of work that are beeing payed in the next template so miner can apply pplns formula and see that pool is paying what expected (who communicate what to who is not important can be the other way around) and miner can verify with transparency system that the total work that get payed in the next allocated token is the right number so pool can not inflate pool's total hashrate. Both miner and pool can keep an inpendent and trustless accounting of what is beeing payed.

I think that starting with only what have been proposed is more than eanugh, but I'm sure that we are going to modify it add/change things. So an extension IMO is much better (since is more flexible) than changing the protocol.

[warioishere]

Hey Fi3, thanks for the detailed thoughts, let me go through them.

value_remaining — Editorial Clarification

On the value_remaining question first: yes, coinbase_tx_value_remaining is subsidy + fees combined, and the weights are effectively per-mille on that remainder. We called them U32 to leave headroom, but in practice they always normalize to 100%. We can tighten the spec text so that's unambiguous — that part is purely editorial.

Fee-Split Idea — Separate Design Decision

On the fee-split idea, I get what you're pointing at. Under JDC the miner is the one picking the template, so intuitively their fee contribution should factor back into the payout. That's a legitimate pool-policy choice, but it's genuinely a separate design decision from ours.

Our's PPLNS semantics pay proportionally on the total block reward, same as classical PPLNS implementations. Some pools might want a subsidy/fee split, others won't. I don't think this proposal should dictate that — if we mix it in we're coupling two independent design debates, and the result is neither clean.

If it turns out useful later, a follow-up extension (or a v2 of this one) can add a separate fee_weights array alongside the existing one without breaking anything.

Trustless Share-Accounting — Future Protocol

The trustless share-accounting piece is the bigger one, and I want to be honest: that's a whole protocol on its own. What we need to solve here is narrow — how does the pool tell the JDC the on-chain payout split? What you're describing is how miner and pool can keep an independent ledger of the underlying shares so neither can cheat the other.

Both worth solving, but mashing them into one proposal is how small things become multi-year projects. My suggestion: we leave the payout mechanics as-is in this extension, and note explicitly in the spec text that it's compatible with a future share-attestation extension. That way no door is closed, and whoever picks up the attestation work later doesn't have to fight an already-embedded assumption.

Extension vs Breaking-Change

On the extension vs breaking-change call, you're right — let's go with an extension. It fits the nature of what we're adding (optional, opt-in, niche for custodial pools), and more importantly it gives us both a path forward: the maintainers aren't forced to carry a feature the majority of deployments won't touch, and anyone who wants to iterate on top of it later has the versioning room to do so.

That directly addresses your "this is going to grow" concern — the growth lives in extension revisions, not in the core JDP.

So if it's an extension, I'm happy to write it up. Looking at the repo structure I'd put it under
extensions/0x0003-coinbase-output-weights.md (or whatever number you'd like to allocate), following
the shape of the existing 0x0002-worker-specific-hashrate-tracking — intro + message additions +
wire format + fallback semantics — and add the row to the registry in 09-Extensions.md.

Scope stays tight: just the weights field on AllocateMiningJobToken.Success, plus a paragraph noting
the extension is forward-compatible with future work around fee-split policy and share attestation,
so whoever picks those up later has clear room.

Want me to open a PR against sv2-spec with the draft, and we iterate from there? If there's a
preferred number or you'd rather park it somewhere else (own discussion, separate doc in the
sv2-apps tree first, etc.), just say and I'll adapt.

[warioishere]

Thanks for moving this here @plebhash and for the clear summary.

Agreed that Option A violates spec — the "0 value outputs" constraint is explicit, so that's off the table.

On the question of breaking change vs protocol extension for Option B: we don't have a strong preference. Both work for us on the pool side. Here's how I see the tradeoffs:

Protocol Extension:

• Doesn't force every JDP implementation to handle a field they'll never use
• Realistic take: most pools are custodial and pay via wallet, so multi-output coinbase payouts is a niche use case
• Cleaner separation — pools that want non-custodial payouts opt in, everyone else is unaffected

Breaking Change (new optional field):

• Simpler — no extension negotiation overhead
• A new optional field with fallback behavior (empty = current behavior) is technically not breaking — no existing code stops working

Happy to go either way. The pool-side implementation is ready regardless — we just need to know the wire format so we can serialize the weights correctly.

One thing to consider: the weights need to be recalculated with every new template since the PPLNS share window changes over time. The current JDC token lifecycle already handles this well — tokens are consumed on each new template and a fresh one is requested, so the pool can deliver updated weights with each token.

[plebhash]

new extension proposal: #203

alternative to #202 and #195