Skip to content

extensions: add 0x0004 Requested Payout Outputs - #249

Closed
CyberAshven wants to merge 1 commit into
stratum-mining:mainfrom
CyberAshven:extension-requested-payout-outputs
Closed

CyberAshven wants to merge 1 commit into
stratum-mining:mainfrom
CyberAshven:extension-requested-payout-outputs

Conversation

@CyberAshven

Copy link
Copy Markdown

Defines a Job Declaration extension for pools whose coinbase outputs depend on the template being mined. The JDC sends the JDS the template's height, previous hash, target, revenue and coinbase scriptSig prefix, and receives the exact output set.

As discussed in #203, such pools are outside 0x0003's design, which publishes one distribution per accounting window. This proposes the request/response shape on its own. It keeps #202's RequestPayoutOutputs (#195 had the same shape) and adds:

Addition Why
height, prev_hash, nbits and coinbase_prefix in the request The outputs can commit to the previous block or share and to the client's scriptSig.
EXACT_OUTPUTS flag For validators that rebuild the whole coinbase and compare it byte for byte. Only a witness commitment may follow the returned outputs.
Coinbase version, input sequence and lock time in the reply Such validators fix these too.
PayoutOutputsStale The outputs move with the pool's state, so the JDC re-requests before its next declaration.

stale-payout-outputs is treated as an honest race, as 0x0003 treats its own stale code. The cost is one round trip per declared job; the JDC keeps hashing meanwhile and may request ahead.

Implementation: a BCH P2Pool node serves this as a JDS under the experimental id 0x5052 (CyberAshven/BitcoinCash-p2poolv2#47). In a test against two BCHN regtest nodes, a client built on SRI's crates mined in both modes using only the outputs from the reply. In Coinbase-only mode, the block also carried a fee from a transaction the pool never saw.

0x0004 is the next free id after #203's 0x0003.

Some non-custodial pools pay miners from the coinbase with outputs that
depend on the template being mined: its height, previous hash, target,
revenue and the client's coinbase scriptSig. A share chain that commits to
the previous share and to the client's scriptSig, and whose nodes rebuild
every coinbase, is one example. A payout distribution published ahead of
time cannot express such outputs.

This extension lets a JDC send the JDS those template inputs and receive
the exact output set. It keeps the RequestPayoutOutputs design proposed in
stratum-mining#202, and adds:
- the template fields;
- an EXACT_OUTPUTS flag with the required coinbase version, input sequence
  and lock time;
- a PayoutOutputsStale message.

As suggested in stratum-mining#203, it is proposed as a separate extension rather than
as a mode of 0x0003.
@plebhash

plebhash commented Nov 4, 2026

Copy link
Copy Markdown
Member

@CyberAshven I'll keep this short, because the problem is the premise rather than the message layout.

Sv2 JDP exists so that a miner can select its own transactions while a Pool keeps share accounting and pays out.

P2Poolv2 already gives a miner both without JDP: each node builds the template from its own bitcoind, and every node recomputes and validates every share's coinbase, which is the property the share chain exists for. A JDC that mines to someone else's share-chain node through this extension keeps the first property, which it already had, and gives up the second: §8 of your text says so, "the JDC trusts the JDS to compute the output set". Since a JDC needs a Template Provider, i.e. a full node, either way, running its own share-chain node costs it nothing extra and gives the validation back. There is no configuration in which a miner is better off with this extension than without it.

The original P2Poolv2 project has no Sv2 JDP integration for a reason, and its docs position it as an alternative to Sv2 JDP rather than a consumer of it. We have had close interactions with the core P2PoolV2 developers and it's rough consensus amongst ourselves that there's no point in mixing Sv2 JDP with it, even if for "experimental" reasons.

When it comes to protocol design you should be extremely careful with what sycophantic AI agents tell you, because I'm afraid you're wasting your time on a dead-end pursuit here. Whatever innovation you think you are achieving by mixing these two different protocols is a hallucinated mirage at best.

Finally: this repository specifies Stratum V2 for Bitcoin, and an extension with no Bitcoin adopter, serving a use case the project it targets does not have, is out of scope for this repository.

I'm sorry but I'll have to close this.

@plebhash plebhash closed this Nov 4, 2026
@CyberAshven

CyberAshven commented Nov 5, 2026 •

Copy link
Copy Markdown
Author

Short answers to your points:

  • Validation: a miner who runs its own share-chain node should use it, and extensions: add 0x0004 Requested Payout Outputs #249 should say so up front.
  • "No configuration in which a miner is better off": there is one: a full-node runner mining on someone else's share-chain node.
    • Today that node picks the miner's transactions and computes its payout.
    • With this extension the miner picks the transactions, under the same payout trust. That is the pool role the Job Declaration chapter describes: "only responsible for accounting shares and distributing rewards".
    • It's a narrow gain: one round trip per job, and the client can't add outputs of its own. But it is a gain in what that chapter calls "a key feature of Stratum V2".
  • Fallback (section 6.2), the strongest case: miners don't always set things up the way a protocol designer would. Some run a full node with a JD client and a fallback list, and put an external share-chain node in that list. Without the extension our share-chain node can't be in the list at all: it refuses a plain JDP coinbase with invalid-coinbase-tx.
    • The exposure is real and bounded. As you say, every node recomputes and validates every share's coinbase, so a wrong output set can't put false credit into the share chain.
    • What the miner can lose is unpaid work, plus any block found in that window, whose coinbase pays what it says.
    • We're taking your validation point into the experimental extension, so that the check happens before mining. The job token carries every term the outputs depend on except the PPLNS weights.
      • The JDC will be able to check, with no other node, that the share commitment credits its own identity.
      • Before mining, it will ask a second, independent share-chain node to recompute the same output set from the same token at the same tip.
      • Cheating would then need two nodes colluding, and that covers a block found in the window too.
  • "Costs nothing extra": a share-chain node is a second always-on daemon with its own peers, storage and sync. It costs less than the full node, but it isn't nothing.
  • Bitcoin work: average-gary/sv2-p2pool, a separate pool built on p2poolv2, runs a JDS for JDCs on testnet4.
  • Bitcoin Cash: a Bitcoin Cash P2Pool implementation serves it, a JD client for the Knuth node uses it, and the two are being tested together on regtest.
  • AI: AI helps me write. The need is mine: my P2Pool v2 fork for Bitcoin Cash has to support SV2 Job Declaration, so full-node runners can mine on it with their own templates.
  • Scope: I understand if a Bitcoin Cash need is out of scope here.

If that is what you prefer, this work will carry on as an experimental extension (0x5052) outside this repository. I strongly believe in it, and it is not AI-driven.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants