Skip to content

Commit 66287a5

Browse files
GitGab19GitGab19
authored
Merge pull request #113 from GitGab19/extend-submit-shares-extended
Worker Specific Hashrate Tracking Extension
2 parents 344dec1 + c45dee7 commit 66287a5

File tree

4 files changed

+174
-2
lines changed

4 files changed

+174
-2
lines changed

‎03-Protocol-Overview.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,53 @@ This prevents the needlessly wasted bandwidth and potentially serious performanc
142142

143143
See `ChannelEndpointChanged` message in Common Protocol Messages for details about how extensions interact with dynamic channel reconfiguration in proxies.
144144

145+
## 3.4.1 Stratum V2 TLV Encoding Model
146+
147+
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+
149+
### TLV Structure
150+
151+
Each TLV-encoded field follows this format:
152+
153+
| **Field** | **Size** | **Description** |
154+
|------------|---------|----------------|
155+
| **Type** | 3 bytes (U16 + U8) | Identifies the TLV field. The first 2 bytes represent the `extension_type`, and the third byte represents the `field_type` within the extension context. |
156+
| **Length** | 2 bytes (U16) | Indicates the size (in bytes) of the Value field. |
157+
| **Value** | `N` bytes | The actual data of the extension field, of variable length. |
158+
159+
- The **Type** field consists of **3 bytes**, where:
160+
- The **first 2 bytes** (`U16`) correspond to the negotiated `extension_type`, ensuring modular and self-contained extensions.
161+
- The **third byte** (`U8`) specifies the `field_type` defined in the extension, allowing multiple fields to be added within the same message.
162+
- The **Length** field defines the exact size of the **Value**, allowing efficient message parsing.
163+
- If the **Length** is `0x0000`, the **Value** field is omitted.
164+
- When multiple fields extend the same message type, their order **MUST** match the order defined in the extension.
165+
166+
### Usage Guidelines
167+
168+
- **TLV fields MUST be placed at the end of the message payload.** This ensures compatibility with existing Stratum V2 messages.
169+
- **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+
- **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+
- **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+
173+
### Example: Extending `SubmitSharesExtended`
174+
175+
If extension **0x0002** (Worker-Specific Hashrate Tracking) is negotiated, clients must append the following TLV field to `SubmitSharesExtended`:
176+
```
177+
[TYPE: 0x0002 0x01] [LENGTH: 0x000A] [VALUE: "Worker_001"]
178+
```
179+
Encoded as:
180+
```
181+
00 02 01 00 0A 57 6F 72 6B 65 72 5F 30 30 31
182+
```
183+
184+
Where:
185+
- `00 02 01` → TLV Type (Extension `0x0002`, Field `0x01` — `user_identity`)
186+
- `00 0A` → Length = 10 bytes
187+
- `57 6F 72 6B 65 72 5F 30 30 31` → `"Worker_001"` (UTF-8 encoded)
188+
189+
A device processing `SubmitSharesExtended` **MUST scan for TLV fields** matching any negotiated extensions, allowing for future extensibility without breaking compatibility.
190+
191+
145192
## 3.5 Error Codes
146193

147194
The protocol uses string error codes.

‎05-Mining-Protocol.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ Only relevant for extended channels.
342342
The message is the same as `SubmitShares`, with the following additional field:
343343

344344
| Field Name | Data Type | Description |
345-
| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
345+
|-----------------------------------------| --------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
346346
| `<SubmitSharesStandard message fields>` |
347347
| extranonce | B0_32 | Extranonce bytes which need to be added to coinbase to form a fully valid submission (full coinbase = coinbase_tx_prefix + extranonce_prefix + extranonce + coinbase_tx_suffix). The size of the provided extranonce MUST be equal to the negotiated extranonce size from channel opening. |
348348

‎09-Extensions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 9. Extensions
22

3-
There are not yet any defined extensions.
43
| Extension Type | Extension Name | Description / BIP |
54
| -------------- | ---------------------- | --------------------------------------------------------- |
65
| 0x0001 | Extensions Negotiation | Definition [here](./extensions/extensions-negotiation.md) |
6+
| 0x0002 | Worker Specific Hashrate Tracking | Definition [here](./extensions/worker-specific-hashrate-tracking.md) |

‎extensions/worker-specific-hashrate-tracking.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Stratum V2 Extension: Worker-Specific Hashrate Tracking
2+
3+
## 0. Abstract
4+
5+
This document proposes a Stratum V2 extension to enable mining pools to track individual workers (`user_identity`) within extended channels. By extending the `SubmitSharesExtended` message via `Type-Length-Value (TLV)` encoding, pools can track worker-specific hashrate while preserving the existing channel structure.
6+
7+
Terms like "MUST," "MUST NOT," "REQUIRED," etc., follow RFC2119 standards.
8+
9+
---
10+
11+
## 1. Extension Overview
12+
13+
This extension modifies the existing `SubmitSharesExtended` message by introducing a **new TLV field** that contains the `user_identity` (worker name). The extension follows the [Stratum V2 TLV encoding model](../03-Protocol-Overview.md#341-stratum-v2-tlv-encoding-model), where each extension is assigned a `Type (U16)` identifier negotiated between the client and server.
14+
15+
### 1.1 TLV Format for `user_identity`
16+
When this extension is enabled, the client MUST append the following TLV field to `SubmitSharesExtended`:
17+
18+
| Field | Size | Description |
19+
|------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
20+
| Type (U16 \| U8) | 3 bytes | Unique identifier for the TLV field, structured as: <br> - **Extension Type (U16)**: `0x0002` (Worker-Specific Hashrate Tracking) <br> - **Field Type (U8)**: `0x01` (`user_identity`) |
21+
| Length (U16) | 2 bytes | Length of the value (max **32 bytes**) |
22+
| Value | `N` bytes | UTF-8 encoded `user_identity` (worker name) |
23+
24+
If `user_identity` is shorter than **32 bytes**, it MUST NOT be padded. The `Length` field MUST indicate the actual byte size.
25+
26+
---
27+
28+
### **Example TLV Encoding**
29+
30+
```
31+
[TYPE: 0x0002|0x01] [LENGTH: 0x000A] [VALUE: "Worker_001"]
32+
```
33+
(Where `"Worker_001"` is 10 bytes long)
34+
35+
**Breaking it down:**
36+
- `0x0002|0x01` → **Type (U16 | U8)**
37+
- `0x0002` (**U16 - Extension Type**) → Worker-Specific Hashrate Tracking
38+
- `0x01` (**U8 - Field Type**) → `user_identity`
39+
- `0x000A` → **Length** (10 bytes)
40+
- `"Worker_001"` → **Value** (UTF-8 encoded string)
41+
42+
### 1.2 Extension Activation (Negotiation Process)
43+
44+
To enable this extension, the initiator MUST send a `RequestExtensions` message immediately after the `SetupConnection` message, requesting extension `0x0002`. If the receiver supports it, it responds with a `RequestExtensions.Success` message.
45+
46+
#### Message Exchange Example
47+
48+
1. **Connection Setup**:
49+
```
50+
Client --- SetupConnection (connection details) ---> Server
51+
Client <--- SetupConnection.Success (connection accepted) ---- Server
52+
```
53+
54+
2. **Extension Request**:
55+
```
56+
Client --- RequestExtensions [0x0002] ---> Server
57+
```
58+
59+
3. **Server Response**:
60+
- If successful:
61+
```
62+
Client <--- RequestExtensions.Success [0x0002] ---- Server
63+
```
64+
- If an error occurs:
65+
```
66+
Client <--- RequestExtensions.Error [0x0002] ---- Server
67+
```
68+
69+
Once negotiated, the client MUST append the TLV containing `user_identity` to every `SubmitSharesExtended` message.
70+
71+
### 1.3 Behavior Based on Negotiation
72+
73+
- **If the extension is negotiated**:
74+
- The `user_identity` field **MUST** be included in `SubmitSharesExtended` as a TLV with Type `0x0002`.
75+
- **If the extension is not negotiated**:
76+
- The `user_identity` field **MUST** not be included.
77+
- The server **MUST** ignore any unexpected TLV fields.
78+
79+
Since all extensions are negotiated before use, **the order of TLV fields is not relevant**. The receiver **MUST** scan for TLV fields corresponding to known negotiated extensions.
80+
81+
---
82+
83+
### 2. Extended `SubmitSharesExtended` Message Format
84+
After negotiation, the client appends TLV fields at the end of `SubmitSharesExtended`.
85+
Example with the `user_identity` extension enabled:
86+
```
87+
[SubmitSharesExtended Base Fields] + [0x0002|0x01] [LENGTH] ["Worker_001"]
88+
```
89+
Example Message in Bytes:
90+
```
91+
<BASE PAYLOAD> + 00 02 01 00 0A 57 6F 72 6B 65 72 5F 30 30 31
92+
```
93+
Where:
94+
95+
- `00 02 01 ` → TLV Type (U16 | U8) (`extension_type = 0x0002`, `field_type = 0x01`)
96+
- `00 0A` → Length (10 bytes)
97+
- `57 6F 72 6B 65 72 5F 30 30 31` → "Worker_001" (UTF-8 encoded)
98+
99+
---
100+
101+
### 3. Bandwidth Consideration
102+
103+
Including the `user_identity` field in each share submission increases message size, depending on the length of the identifier (up to 32 bytes).
104+
105+
For example:
106+
- **Without `user_identity`**: Share message size ~70 bytes.
107+
- **With maximum `user_identity` (32 bytes)**: Share message size ~102 bytes.
108+
109+
In a scenario with 10 shares per minute per channel:
110+
- **Maximum increase**: 32 bytes × 10 = 320 bytes/min, or 19.2 KB/hour.
111+
- **Average increase (20 bytes)**: 200 bytes/min, or 12 KB/hour.
112+
113+
---
114+
115+
## 4. Implementation Notes
116+
117+
### 4.1 Job Difficulty Management
118+
119+
As the number of workers in a single extended channel increases, the time required to receive shares from all individual machines also increases. If a server wants to offer this monitoring, it should manage job difficulty accordingly to ensure timely processing of shares.
120+
121+
### 4.2 Privacy Considerations
122+
123+
Mining farms should be aware that sharing per-worker data with pools could reveal operational insights. This could potentially compromise the privacy of the mining farm's operations.
124+
125+
---

0 commit comments

Comments
 (0)