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 Protocols, which can **only** be extended via TLV fields), 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 of the base frame 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,30 @@ 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 [email protected].
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
+
**Important note on extension type allocation:** Extensions that introduce new messages (non-TLV extensions) and extensions that only add TLV fields to existing messages (TLV extensions) share the same namespace for `extension_type` identifiers without any categorical distinction. Both types of extensions must request allocation from the same registry (this repository), and the `extension_type` value alone does not indicate whether an extension defines new messages or only adds TLV fields.
138
+
139
+
**Example scenarios:**
140
+
141
+
1. Core protocol messages such as `SetupConnection`, `SubmitSharesExtended`, etc., have `extension_type = 0x0000` in their frame headers.
142
+
143
+
2. The [Extensions Negotiation extension](./extensions/0x0001-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.
144
+
145
+
3. When the [Worker-Specific Hashrate Tracking extension](./extensions/0x0002-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`.
146
+
147
+
4. If a hypothetical extension `0x0003` introduces a completely new message type called `CustomNewMessageType`, that message's frame would have `extension_type = 0x0003`.
148
+
149
+
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.
150
+
127
151
Extensions are left largely undefined in this BIP, however, there are some basic requirements that all extensions must comply with/be aware of.
128
152
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
153
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,20 +157,20 @@ If a device is aware of the semantics of a given extension type, it MUST process
133
157
134
158
Messages with an unknown `extension_type` which are to be processed locally (as defined above) MUST be discarded and ignored.
135
159
136
-
### 3.4.1 Implementing Extensions Support
160
+
### 3.4.2 Implementing Extensions Support
137
161
138
-
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.
162
+
To support extensions, an implementation MUST first implement [Extension 1](./extensions/0x0001-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
163
140
164
Extensions MUST require negotiation with the recipient of the message to check that the extension is supported before sending non-version-negotiation messages for it.
141
165
This prevents the needlessly wasted bandwidth and potentially serious performance degradation of extension messages when the recipient does not support them.
142
166
143
167
See `ChannelEndpointChanged` message in Common Protocol Messages for details about how extensions interact with dynamic channel reconfiguration in proxies.
144
168
145
-
## 3.4.1 Stratum V2 TLV Encoding Model
169
+
###3.4.3 Stratum V2 TLV Encoding Model
146
170
147
171
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
172
149
-
### TLV Structure
173
+
####TLV Structure
150
174
151
175
Each TLV-encoded field follows this format:
152
176
@@ -163,14 +187,14 @@ Each TLV-encoded field follows this format:
163
187
- If the **Length** is `0x0000`, the **Value** field is omitted.
164
188
- When multiple fields extend the same message type, their order **MUST** match the order defined in the extension.
165
189
166
-
### Usage Guidelines
190
+
#####Usage Guidelines
167
191
168
192
-**TLV fields MUST be placed at the end of the message payload.** This ensures compatibility with existing Stratum V2 messages.
169
193
-**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
194
-**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
195
-**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
196
173
-
### Example: Extending `SubmitSharesExtended`
197
+
#####Example: Extending `SubmitSharesExtended`
174
198
175
199
If extension **0x0002** (Worker-Specific Hashrate Tracking) is negotiated, clients must append the following TLV field to `SubmitSharesExtended`:
When implementing extensions, it's important to understand how the `extension_type` field in the message frame header should be set:
6
+
7
+
- The `extension_type` field identifies the extension that **introduced and defined the non-TLV fields** of a message.
8
+
- For messages defined in the core specification, `extension_type` MUST be `0x0000`.
9
+
- For new messages introduced by an extension, `extension_type` MUST be set to that extension's identifier.
10
+
- When an extension modifies an existing message using TLV fields, the `extension_type` in the frame header **does not change** - it remains set to the extension that originally defined the message structure (or `0x0000` for core messages).
11
+
12
+
For a detailed explanation with examples, see [Section 3.4.1 Extension Type Field Usage](./03-Protocol-Overview.md#341-extension-type-field-usage) in the Protocol Overview.
13
+
14
+
## Extension Registry
15
+
3
16
| Extension Type | Extension Name | Description / BIP |
Copy file name to clipboardExpand all lines: extensions/0x0001-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.1 Extension Type Field Usage](../03-Protocol-Overview.md#341-extension-type-field-usage) in the Protocol Overview.
0 commit comments