You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| extension_type | U16 | Unique identifier of the extension associated with this protocol message|
95
+
| extension_type | U16 | Unique identifier of the extension associated with this protocol message. For messages defined in the core specification (Common, Mining, Job Declaration, and Template Distribution Protocol), this field MUST be set to 0. For messages introduced by an extension, this field MUST be set to that extension's identifier. Note that even if a message is later modified by a different extension through TLV fields, the extension_type remains set to the extension that originally defined the message structure.|
96
96
| msg_type | U8 | Unique identifier of this protocol message |
97
97
| msg_length | U24 | Length of the protocol message, not including this header |
98
98
| payload | BYTES | Message-specific payload of length msg_length. If the MSB in extension_type (the channel_msg bit) is set the first four bytes are defined as a U32 "channel_id", though this definition is repeated in the message definitions below and these 4 bytes are included in msg_length. |
@@ -124,6 +124,28 @@ While extensions SHOULD have BIPs written describing their full functionality, `
124
124
This is done by sending an email with a brief description of the intended use case to the Bitcoin Protocol Development List and extensions@stratumprotocol.org.
125
125
(Note that these contacts may change in the future, please check the latest version of this BIP prior to sending such a request.)
126
126
127
+
### 3.4.1 Extension Type Field Usage
128
+
129
+
The `extension_type` field in the message frame header indicates which extension introduced and defined the non-TLV (Type-Length-Value) fields of a message. This is important for proper message parsing and understanding message ownership:
130
+
131
+
-**Core protocol messages** (Common, Mining, Job Declaration, and Template Distribution Protocol messages) MUST have `extension_type` set to `0x0000`.
132
+
133
+
-**Extension-specific messages** (new messages introduced by an extension) MUST have `extension_type` set to the identifier of the extension that introduced them.
134
+
135
+
-**Messages modified via TLV fields**: When an extension adds TLV fields to an existing message (whether a core protocol message or a message from another extension), the `extension_type` field MUST NOT change. It continues to identify the extension that originally defined the message's non-TLV structure.
136
+
137
+
**Example scenarios:**
138
+
139
+
1. Core protocol messages such as `SetupConnection`, `SubmitSharesExtended`, etc., have `extension_type = 0x0000` in their frame headers.
140
+
141
+
2. The [Extensions Negotiation extension](./extensions/extensions-negotiation.md) (`0x0001`) introduces three new messages: `RequestExtensions`, `RequestExtensions.Success`, and `RequestExtensions.Error`. These messages have `extension_type = 0x0001` in their frame headers because that extension defined their structure.
142
+
143
+
3. When the [Worker-Specific Hashrate Tracking extension](./extensions/worker-specific-hashrate-tracking.md) (`0x0002`) adds a TLV field containing `user_identity` to the existing `SubmitSharesExtended` message, the message frame still has `extension_type = 0x0000` because the core protocol defined the non-TLV fields. The TLV addition doesn't change the frame's `extension_type`.
144
+
145
+
4. If a hypothetical extension `0x0003` introduces a completely new message type called `CustomNewMessageType`, that message's frame would have `extension_type = 0x0003`.
146
+
147
+
5. If later, another extension `0x0004` wanted to add TLV fields to `CustomNewMessageType` from example 4, those messages would still have `extension_type = 0x0003` in their frame header, as that's the extension that defined the message's base structure.
148
+
127
149
Extensions are left largely undefined in this BIP, however, there are some basic requirements that all extensions must comply with/be aware of.
128
150
For unknown `extension_type`'s, the `channel_msg` bit in the `extension_type` field determines which device the message is intended to be processed on: if set, the channel endpoint (i.e. either an end mining device, or a pool server) is the final recipient of the message, whereas if unset, the final recipient is the endpoint of the connection on which the message is sent.
129
151
Note that in cases where channels are aggregated across multiple devices, the proxy which is aggregating multiple devices into one channel forms the channel’s "endpoint" and processes channel messages.
@@ -133,7 +155,7 @@ If a device is aware of the semantics of a given extension type, it MUST process
133
155
134
156
Messages with an unknown `extension_type` which are to be processed locally (as defined above) MUST be discarded and ignored.
135
157
136
-
### 3.4.1 Implementing Extensions Support
158
+
### 3.4.2 Implementing Extensions Support
137
159
138
160
To support extensions, an implementation MUST first implement [Extension 1](./extensions/extensions-negotiation.md), which defines the basic protocol for requesting and negotiating support for extensions. This extension must be included in any protocol implementation that plans to support additional protocol extensions.
139
161
@@ -142,11 +164,11 @@ This prevents the needlessly wasted bandwidth and potentially serious performanc
142
164
143
165
See `ChannelEndpointChanged` message in Common Protocol Messages for details about how extensions interact with dynamic channel reconfiguration in proxies.
144
166
145
-
## 3.4.1 Stratum V2 TLV Encoding Model
167
+
###3.4.3 Stratum V2 TLV Encoding Model
146
168
147
169
To ensure a consistent and extensible way of adding optional fields to existing messages, **Stratum V2 supports Type-Length-Value (TLV) encoding** for protocol extensions. This model allows for structured, backward-compatible extensions while ensuring that unknown fields can be safely ignored.
148
170
149
-
### TLV Structure
171
+
####TLV Structure
150
172
151
173
Each TLV-encoded field follows this format:
152
174
@@ -163,14 +185,14 @@ Each TLV-encoded field follows this format:
163
185
- If the **Length** is `0x0000`, the **Value** field is omitted.
164
186
- When multiple fields extend the same message type, their order **MUST** match the order defined in the extension.
165
187
166
-
### Usage Guidelines
188
+
#####Usage Guidelines
167
189
168
190
-**TLV fields MUST be placed at the end of the message payload.** This ensures compatibility with existing Stratum V2 messages.
169
191
-**TLV fields MUST be ordered by `extension_type`.** Since all extensions are negotiated beforehand, the recipient MUST process TLV fields in order of `extension_type` and use their `Type` identifiers to correctly interpret them.
170
192
-**Order of TLV fields within the same extension MUST be respected.** If an extension defines multiple TLV fields to extend a single message, they **MUST** appear in the exact order specified by the extension’s documentation.
171
193
-**Length constraints MUST be respected.** Each extension must specify the valid length range for its TLV fields. If a TLV field exceeds the maximum length allowed by its specification, the recipient MUST reject the message.
172
194
173
-
### Example: Extending `SubmitSharesExtended`
195
+
####Example: Extending `SubmitSharesExtended`
174
196
175
197
If extension **0x0002** (Worker-Specific Hashrate Tracking) is negotiated, clients must append the following TLV field to `SubmitSharesExtended`:
Copy file name to clipboardExpand all lines: extensions/extensions-negotiation.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -80,6 +80,8 @@ Clients MUST NOT use any features from extensions that are not confirmed as supp
80
80
| 0x01 | 0 | RequestExtensions.Success |
81
81
| 0x02 | 0 | RequestExtensions.Error |
82
82
83
+
**Note on Message Framing:** All messages defined by this extension MUST have `extension_type = 0x0001` in their message frame headers, as this extension introduced and defined these messages. For more details on `extension_type` field usage, see [Section 3.4.0 Extension Type Field Usage](../03-Protocol-Overview.md#341-extension-type-field-usage) in the Protocol Overview.
0 commit comments