Repository navigation
extensions: allocate 0x0005 for algorithm selection and time-bounded work, 0x0006 for block found - #250
extensions: allocate 0x0005 for algorithm selection and time-bounded work, 0x0006 for block found#250cdonnachie wants to merge 2 commits into
Conversation
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.
|
@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. |
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.
…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.
Section 3.4.1 says allocation is requested from this repository, so this is
that request: two definition documents under
extensions/and two registryrows.
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
0x0006is rejected or belongs in core, dropits row and its file and
0x0005stands unchanged. They are in one PR becausetogether 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 WorkTwo 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 timeepoch. The specification bounds
ntimefrom below only, and says explicitlythat
ntime_startis not the consensus minimum. A chain like X16RT derives itshash chain from
SHA256d(nTime & 0xffffff80), so a miner rolling across a128-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_typehere is aU8whose values the chain defines, not thisextension. 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_idon one,channel_idplusjob_idon the other. A pool is a Template Distributionclient 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.
TemplateTimeConstraintsandJobTimeConstraintscarry the same four numbers keyed differently. One messagewith 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_maskin the reply, always zero in the referenceimplementation. 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.Errornames three values andsection 4.4 names two
SubmitShares.Errorvalues.error_codeis aSTR0_255so 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 NotificationOne message, chain-agnostic, optional, and it MUST NOT appear in
required_extensions.A client can already recognise a block candidate:
SetNewPrevHashcarriesnbits. What it cannot establish is what happened next, becauseSubmitShares.Successmeans "accepted as a share" andSubmitSolutionhas noreply 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
SetNewPrevHashtells it whether its node adopted the block.Two things I would point a reviewer at:
confirmedis deliberately narrow. It means one node had this block as itsactive 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_typeand 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_typerule 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.mdrather than in oneextension'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. Blocknotifications are, today, message
0x05inside that same extension, which isthe 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
0x0005is a mainnet blocker for us rather than apreference. I would still rather it be scoped correctly than allocated quickly.
Implementation and the full wire specification:
AvianNetwork/Avian#267
🤖 Generated with Claude Code