Integrate JDP with PPLNS via ext 0x0003 (Dynamic Coinbase Outputs)

[warioishere]

Summary

Implements pool-side support for the sv2-spec ext 0x0003 (Dynamic Coinbase Outputs) extension, so PPLNS / Group-Solo payouts can be delivered through the Job Declaration Protocol without custodial hand-off.

When a JDC negotiates 0x0003, it sends a per-declared-job RequestCoinbaseOutputs(token, prev_hash, pool_revenue) to the JDS. The pool computes the multi-output distribution from current PPLNS state and the JDC-reported revenue, applies dust-suppression, caches the response for validation, and replies with the consensus-serialized Vec<TxOut>. The JDC carries those outputs into its DeclareMiningJob.coinbase_tx_suffix. JDCs that do not negotiate 0x0003 see no behavioural change — vanilla §6.4.3 single-output stays intact.

What changed

Wire-level (src/models/sv2/)

• New Sv2RequestCoinbaseOutputs codec triple (/.Success / /.Error) in sv2-extensions-messages.ts.
• SV2_EXTENSION_TYPE_DYNAMIC_COINBASE_OUTPUTS = 0x0003 + extension-local msg-type codes (0x00/0x01/0x02).
• Frames carry extension_type = 0x0003 per spec §3.4.1.

Service (src/services/job-declaration.service.ts)

• New handleRequestCoinbaseOutputs(req, minerAddress):
  • stale-prev-hash when JDC's prev_hash diverges from pool's current view
  • revenue-too-large when pool_revenue > 1.5× template.coinbasevalue
  • invalid-mining-job-token for unknown / expired tokens (gated by client)
  • internal on transient errors
• computeDynamicOutputs resolves mode (solo / pplns / group-solo), calls the relevant payout service with the JDC-reported revenue, applies dust suppression (sub-294-sat outputs → internal pending).
• Response cache keyed by (token, requestId), bound to prev_hash. When the pool observes a new prev_hash via observePrevHash, all entries bound to the old one are evicted (template-bound TTL, no wall-clock TTL). This keeps cached responses fresh relative to the current payout window without drifting.
• findEmittedOutputsForJob(token, prev_hash) lookup for DeclareMiningJob validation.

Client (src/models/JobDeclarationClient.ts)

• Dispatch for extension_type=0x0003 / msgType=0x00.
• allocatedTokens now stores minerAddress at allocation time so RequestCoinbaseOutputs can resolve the distribution for the correct miner.
• AllocateMiningJobToken.Success carries the §6.4.3 single-output fallback regardless of negotiation — no more static-weights TLV on the wire.
• validateCoinbaseOutputs matches the declared coinbase against (a) any cached RequestCoinbaseOutputs.Success emission for this token, falling back to (b) the §6.4.3 single-output presence check (matches the spec §3.4 fallback path).
• extractPoolOutputPairs parses (script, amount) pairs for the strict dynamic-match path.

Why this replaces an earlier static-weights draft

An earlier revision of this PR (commit a18ee40, now superseded by ca349d4) implemented the static-weights design that was on the sv2-spec PR before review feedback landed. Per @TheBlueMatt's review on stratum-mining/sv2-spec#195, that model has a structural problem:

• Per-miner amounts depend on revenue, not just weights. A 1 % miner is paid 5 000 sat on a 500 000-sat block but 25 sat on a 2 500-sat block — and the latter is dust under every standard output type, so the real pool policy is to suppress the output and accumulate the amount in pending. A static weight vector cannot express that switching behaviour.
• Weights drift continuously. In a sliding-window PPLNS payout every accepted share shifts the proportions; a vector frozen at AllocateMiningJobToken.Success is stale within minutes. Reissuing a fresh token per refresh reintroduces the same round-trip the static design was meant to avoid, with worse semantics (re-negotiating the token rather than re-fetching outputs).

The new dynamic-outputs design moves the output-set decision from token allocation to declared-job time. The JDS computes the output list at request time using its current internal state and the JDC-reported revenue. Dust thresholds, pending-balance rerouting, per-miner output caps, payout consolidation — all of these become JDS-internal policy without further wire-format surface.

Spec side is tracked at stratum-mining/sv2-spec#195.

Cache invalidation policy

The validation cache is template-bound, not block-found-bound (per user direction during design):

• Each emitted response is tied to the request's prev_hash.
• When the pool's internal prev_hash advances (next block on the chain), all cache entries bound to the old prev_hash are evicted (observePrevHash does this on the next RequestCoinbaseOutputs call that arrives with the new prev_hash).
• A DeclareMiningJob with an old prev_hash would fail validation anyway (Bitcoin consensus). The cache invalidation is for memory hygiene, not for safety.

Why not block-found-bound: between blocks (~10 min on mainnet) the PPLNS share window changes continuously as new shares enter. Caching responses for the whole inter-block period would re-serve stale distributions that don't include shares submitted by non-JDP miners during the window. Each Request now triggers a fresh computation from current pool state; the cache is just for "what did I emit, so I can validate against it."

Tests

Suite	Status
src/models/sv2/sv2-extensions-messages.spec.ts	New: Request/Success/Error wire codecs, 26 tests
src/models/JobDeclarationClient.spec.ts	New: dispatch path, frame-build, validation, fallback, 10 tests
src/services/job-declaration.service.spec.ts	New: PPLNS / Group-Solo paths, dust suppression, stale-prev-hash, revenue-too-large, cache eviction, 33 tests
docs/jdp-extensions-spec-conformance.md	Updated to reference ca349d4 and the new design
Full suite (regtest + PG-E2E enabled)	1053/1053 ✅

Test plan

• npx tsc --noEmit clean
• PG_E2E=1 PGHOST=… npx jest --runInBand → 1053 tests across 97 suites pass with regtest bitcoind + blitzpool-test-pg up
• Vanilla JDP (no 0x0003): AllocateMiningJobToken.Success carries §6.4.3 single-output, no trailing TLV. Pinned by JobDeclarationClient.spec.ts.
• 0x0003 negotiated: Request → Success carries Bitcoin-consensus Vec<TxOut> with real amounts. Pinned by service spec.
• Stale-prev-hash: divergent prev_hash → Error frame, nothing cached. Pinned.
• Dust suppression: sub-dust amounts dropped, count reflected in Vec<TxOut> count byte. Pinned.

Upstream alignment

• sv2-spec PR: Add Extension 0x0003: Dynamic Coinbase Outputs stratum-mining/sv2-spec#195 (now reflects the dynamic-outputs design)
• Original discussion: RFC: non-custodial payouts via Sv2 JD stratum-mining/sv2-spec#192
• Original proposal venue: JDC: Support proportional coinbase output value distribution for PPLNS pools stratum-mining/sv2-apps#388

When the spec PR lands and a 0x0003-aware JDC implementation exists, multi-output JDP goes live with no further code changes needed pool-side.

[plebhash]

@warioishere can you elaborate on your motivations for multi-output coinbase?

the Sv2 JDP spec does allow JDS to establish multiple outputs via AllocateMiningJobToken.Success, and SRI JDC is able to accomodate for that

but unfortunately, Sv2 JDP spec does not allow non-custodial pooled payouts via multi-output (ala Ocean style); only the first output is standardized as the pool payout output

[plebhash]

we want to eventually enable non-custodial pooled payouts, but a Sv2 protocol extension will be required for that

---

edit:

oh sorry, just realized there's some extra context here:

stratum-mining/sv2-apps#388

diving into it now, will report back (either there or here) later today

[plebhash]

cross referencing: stratum-mining/sv2-apps#388 (comment)