Skip to content

extensions: allocate 0x0005 for algorithm selection and time-bounded work, 0x0006 for block found - #250

Closed
cdonnachie wants to merge 2 commits into
stratum-mining:mainfrom
cdonnachie:extensions-algo-selection-and-block-found
Closed

cdonnachie wants to merge 2 commits into
stratum-mining:mainfrom
cdonnachie:extensions-algo-selection-and-block-found

Conversation

@cdonnachie

@cdonnachie cdonnachie commented Nov 4, 2026 •

Copy link
Copy Markdown

Section 3.4.1 says allocation is requested from this repository, so this is
that request: two definition documents under extensions/ and two registry
rows.

There is a companion Discussion for the scoping question on the first one, which
is the part worth arguing about before the ids matter:
#251

On the ids. main ends at 0x0002. 0x0003 is claimed by the open and approved
#203 and 0x0004 by #249, which took it as "the next free id after #203's
0x0003"; these take the next free pair on the same reading. Renumber freely.
Nothing in either document depends on the value, and the implementation is
still on experimental ids, so a reassignment costs us one constant each.

The two are independent. If 0x0006 is rejected or belongs in core, drop
its row and its file and 0x0005 stands unchanged. They are in one PR because
together they are the whole of a deployed wire protocol, and splitting them
would leave whoever reads the registry with half of it.

0x0005, Algorithm Selection and Time-Bounded Work

Two mechanisms, one message each plus replies. No existing message changes and
no TLV fields are added.

Algorithm selection, for a chain mining several proof-of-work algorithms
concurrently with independent per-algorithm difficulty. Stratum v2 assumes one
function per chain, so today an upstream can only pin one algorithm per
listening port, which is a deployment constraint standing in for a protocol
field.

An upper bound on ntime, for a chain whose hash function depends on a time
epoch. The specification bounds ntime from below only, and says explicitly
that ntime_start is not the consensus minimum. A chain like X16RT derives its
hash chain from SHA256d(nTime & 0xffffff80), so a miner rolling across a
128-second boundary computes a correct hash of the wrong function. It is not a
rejected share, it is a wasted one, and it looks like bad luck at the miner and
like an invalid share at the pool.

Both failure modes are silent, which is the argument for putting them on the
wire rather than in documentation.

Why this is not a chain-specific allocation

I originally pitched this as Avian-specific, which was wrong and invited the
obvious answer. Neither mechanism is.

Time-bounded work applies to any proof of work whose function depends on a time
epoch. Algorithm selection applies to any chain mining several algorithms
concurrently with per-algorithm difficulty, which includes DigiByte, Myriad and
Verge. Each of those needs the same one statement: which algorithm does this
connection carry.

So pow_type here is a U8 whose values the chain defines, not this
extension. The extension specifies how an algorithm is selected and
acknowledged, not which algorithms exist. Avian's mapping appears only as an
example in section 4.6.

The alternative is each such chain squatting its own experimental id for
identical semantics, which is the collision the registry exists to prevent and
is what happens by default if nobody decides.

Choices in 0x0005 I would like reviewed

One id spanning Template Distribution and the Mining Protocol. The three
selection messages are byte-identical on both, being connection-scoped. Only
the time constraints differ, in how they key the work: template_id on one,
channel_id plus job_id on the other. A pool is a Template Distribution
client facing the node and a Mining server facing workers, so under two ids it
would negotiate two extensions for one capability. Section 4.1. Happy to split
it if that is the house style, but better now than after an allocation.

Two messages rather than one reinterpreted. TemplateTimeConstraints and
JobTimeConstraints carry the same four numbers keyed differently. One message
with an overloaded id field would be smaller and would let a pool confuse a
template id with a job id, which is the one mistake that cannot be caught at
runtime.

version_rolling_mask in the reply, always zero in the reference
implementation.
A chain encoding the algorithm inside the block version cannot
leave rolling to BIP320, whose mask covers bits 13-28 and so can fully contain
such a field. The field is there so a future version can open rolling without a
format change.

Normative error codes. SelectAlgorithm.Error names three values and
section 4.4 names two SubmitShares.Error values. error_code is a STR0_255
so inventing values is legal, but a client cannot act on a code it has never
been told about, and an extension whose only stated error type is "a STR0_255"
cannot be implemented against.

0x0006, Block Found Notification

One message, chain-agnostic, optional, and it MUST NOT appear in
required_extensions.

A client can already recognise a block candidate: SetNewPrevHash carries
nbits. What it cannot establish is what happened next, because
SubmitShares.Success means "accepted as a share" and SubmitSolution has no
reply at all. For a server paying by share that does not matter. For a
non-custodial or solo arrangement it is backwards, since consensus pays the
client directly for exactly these and the client cannot tell a block it won
from one that lost a race.

It asks a server for nothing it does not already hold. It knows the share met
the network target, because that is the test that made it forward the share,
and the next SetNewPrevHash tells it whether its node adopted the block.

Two things I would point a reviewer at:

confirmed is deliberately narrow. It means one node had this block as its
active tip at the moment the server looked. Not a depth, not a reorganisation
guarantee, not a claim about the network. A block that lost a race gets no
second message, because a server cannot tell that from one still propagating,
so absence is unresolved rather than failure.

Section 4.1 is the one I would most like someone to disagree with, and it is
not really about this message. Extensions Negotiation agrees an
extension_type and carries no per-extension version or supported-message list,
so negotiating an extension does not negotiate every message it will ever
contain. This message began inside a larger extension that clients were required
to negotiate, and clients built before it existed received it, treated it as a
protocol violation, ended the session, and carried on hashing into a connection
nobody was serving.

An ignore-unknown-msg_type rule fixes that for the future and is worth having,
but it licenses optional additions only, it has to be in place before the
addition, and it cannot be retrofitted to deployed software. Putting the
capability behind its own id fixes it for software already in the field, because
a client that does not know about it never asks for it and is never sent it.
That is why this is a separate extension rather than a sixth message in
0x0005.

If that general rule belongs in 09-Extensions.md rather than in one
extension's notes, say so and I will move it. It applies to every extension, not
just this one.

On whether it belongs here at all: quite possibly it belongs in core, and I
would be glad to see it become a core message. It is offered as an extension
because the gap is live, the capability is strictly additive, and an extension
can be negotiated by the peers that want it without waiting on a protocol
version. Section 4.2 says so in the document.

Status

Both implemented and running, on experimental ids.

Algorithm selection and the time constraints are on 0x4001. Block
notifications are, today, message 0x05 inside that same extension, which is
the mistake section 4.1 of the second document describes: they move to an
extension of their own as part of this submission, and the move is the reason
the section is written the way it is.

Since 3.4 says experimental values must not be present in production equipment,
an allocation for 0x0005 is a mainnet blocker for us rather than a
preference. I would still rather it be scoped correctly than allocated quickly.

Implementation and the full wire specification:
AvianNetwork/Avian#267


🤖 Generated with Claude Code

Two silent failure modes motivate this, both of which a chain can only
work around today by deployment convention rather than by protocol.

A chain mining several proof-of-work algorithms concurrently, with
independent per-algorithm difficulty, has no way to say which algorithm
a connection carries. Stratum V2 assumes one function per chain, so an
upstream can only pin an algorithm per listening port. `SelectAlgorithm`
makes that one statement explicit, with `pow_type` left as a `U8` the
chain defines rather than this extension.

A chain whose hash function depends on a time epoch has no upper bound
on `ntime`. The specification bounds it from below only, and says
`ntime_start` is not the consensus minimum. X16RT derives its hash chain
from SHA256d(nTime & 0xffffff80), so a client rolling `ntime` past a
128-second boundary computes a correct hash of the wrong function: not a
rejected share, a wasted one, which looks like bad luck downstream and
like an invalid share upstream. `TemplateTimeConstraints` and
`JobTimeConstraints` carry absolute bounds, because an in-place template
refresh does not re-send `SetNewPrevHash` and so cannot re-anchor a mask.

Neither mechanism is chain-specific. Algorithm selection applies to any
multi-algorithm chain, DigiByte, Myriad and Verge among them, and time
bounds to any epoch-dependent proof of work. Avian's own values appear
only as an example.

0x0005 is the next free id after the open claims in stratum-mining#203 and stratum-mining#249.
A client can already recognise a block candidate, because `SetNewPrevHash`
carries `nbits`. What it cannot establish is what became of the share it
submitted. `SubmitShares.Success` means "accepted as a share" and is sent
for shares that are not blocks; `PushSolution` has no reply at all. For a
server paying by share that is unremarkable. For a non-custodial or solo
arrangement it is backwards, since consensus pays the client directly for
exactly those blocks and the client cannot tell one it won from one that
lost a race.

`BlockFound` asks a server for nothing it does not already hold. It knows
the share met the network target, because that is the test that made it
forward the share, and the next `SetNewPrevHash` tells it whether its node
adopted the block. `confirmed` is therefore deliberately narrow: one node
had this block as its active tip when the server looked. A block that lost
a race gets no second message, since a server cannot distinguish that from
one still propagating, so absence is unresolved rather than failure.

This is a separate extension rather than a sixth message in 0x0005, and
section 4.1 argues the general case. Extensions Negotiation agrees an
`extension_type` and carries no per-extension version or supported-message
list, so negotiating an extension does not negotiate every message it will
ever contain. This message began inside a required chain-specific
extension; clients built before it existed received it, treated it as a
protocol violation, closed the session and went on hashing into a
connection nobody was serving. An ignore-unknown-msg_type rule fixes that
going forward but licenses optional additions only, must precede the
addition, and cannot be retrofitted to deployed software. A separate id
fixes it for software already in the field.

Independent of 0x0005: dropping this commit leaves that extension intact.
@plebhash

plebhash commented Nov 4, 2026

Copy link
Copy Markdown
Member

@cdonnachie thanks for the write-up, and for building a Template Provider for your chain.

This repository specifies Stratum V2 for Bitcoin. The Mining Protocol is written against Bitcoin consensus (BIP320/BIP323 version bits, MAX_FUTURE_BLOCK_TIME, the Bitcoin P2P network), and 0x0005 exists, in its own words, for chains whose proof of work is not a single time-invariant function. Bitcoin's is, so no Bitcoin role will ever negotiate it, and it is out of scope here.

The registry also doesn't buy you what you're after. An extension id only has to be unique among peers that can share a connection, and an Avian pool and a Bitcoin pool never do. A fork of this spec for another chain keeps its own registry, and the §3.4 rule about experimental ids is that fork's to restate or drop.

On 0x0006: for Bitcoin the gap is small. A JDC publishes its own blocks to its Template Provider (JDP §6.2) and already knows the outcome, and a miner paid from the coinbase can watch the chain. The observation in your §4.1, that negotiation carries no per-extension version so adding a msg_type to a deployed extension breaks older peers, is a real gap in 0x0001 / §3.4, but it belongs in an issue on its own, not in an extension document.

Closing this and #251.

@plebhash plebhash closed this Nov 4, 2026
cdonnachie added a commit to AvianNetwork/Avian that referenced this pull request Nov 5, 2026
Both extension documents were submitted to the Stratum v2 registry and
declined as out of scope, with a ruling that settles more than it refuses:

  An extension id only has to be unique among peers that can share a
  connection, and an Avian pool and a Bitcoin pool never do. A fork of
  this spec for another chain keeps its own registry, and the 3.4 rule
  about experimental ids is that fork's to restate or drop.

  -- stratum-mining/sv2-spec#250

So 0x4001 is allocated rather than squatted, and the mainnet refusal in
ReadOptions was guarding a state that cannot arise. It was dead code as
well as wrong: AVIAN_EXTENSION_ID is a compile-time constant outside the
range the narrowed guard tested, so the branch could never be taken, and
the test asserting mainnet was refused had been left failing by that
narrowing. Two static_asserts in messages.h say the same thing earlier and
on every chain, and the test is now its inverse, which is the property
actually worth holding: a default configuration must serve every chain.

doc/sv2.md becomes the registry rather than a document waiting on one, and
says so. The caveat and the release note calling this development and
testnet only were wrong and are corrected. 0x5000-0x7fff stays documented
as the range this registry offers a third party to prototype in, which is
worth a convention even with nothing left to enforce it.

Three things follow from owning the registry.

Block notifications move to their own extension_type, 0x4002, and 0x05 of
0x4001 is simply free. 0x4001 is required, and a required extension cannot
carry an optional capability: negotiating it is mandatory, so a client has
no way to decline one message inside it. The number is freed rather than
burned because nothing carrying it was ever published, so there is no peer
anywhere that compiled it and nothing to protect by reserving it.

The ignore rule is promoted to a rule of the protocol here rather than of
one extension, with the three limits it needs. It licenses optional
additions only, because ignoring a message that changes which work is
valid is not safe. It binds the endpoint that receives and not the one
that forwards, so a proxy must forward what it does not recognise rather
than discard it. And it cannot be retrofitted onto a peer that has already
shipped, which is why a new capability goes behind its own extension_type.

Section 3.4.3's only worked TLV example contradicts section 3.1's type
table on byte order, rendering a U16 extension type and a U16 length
big-endian where the table says every multibyte type is little-endian.
Avian takes the normative table and tells implementers to take the rule
from the paragraph rather than the example, because the reference
implementation cannot settle it: the SRI crates implement no TLV at all.

Also specified, for the pool rather than for the node, since Template
Distribution has no channels: a channel declares its algorithm with a
pow_type TLV field on its open, overriding the connection's for itself,
fixed for that channel's life and inherited when absent.

All seven sv2 suites pass.
cdonnachie added a commit to cdonnachie/sv2-spec that referenced this pull request Nov 7, 2026
…2.md

Upstream declined the allocation request (stratum-mining#250) with the reading that a
fork for another chain keeps its own registry. This fork now does.

Section 3.4 states the registry, and that the experimental rule for
0x4000-0x7fff does not apply on an Avian connection. Section 3.4.2
carries the rule that an unknown msg_type inside a negotiated extension
is ignored rather than treated as a violation, and the 3.4.3 example is
rendered little-endian as 3.1 requires.

The two extension documents are renumbered to 0x4001 and 0x4002 and
brought in step with doc/sv2.md in Avian Core, which is the normative
text and wins where they differ: Avian's message names, the per-channel
TLV field, the SubmitSolution replies 0x05 and 0x06 with their error
codes, BIP323 in place of BIP320, and the ordering asymmetry between the
Template Distribution and Mining links.
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