Skip to content

Commit 445048c

Browse files
GitGab19GitGab19
committed
worker specific hashrate tracking extension
1 parent 02b0963 commit 445048c

File tree

3 files changed

+120
-4
lines changed

3 files changed

+120
-4
lines changed

‎05-Mining-Protocol.md

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

255255
| Field Name | Data Type | Description |
256-
| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
256+
|-----------------------------------------| --------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
257257
| `<SubmitSharesStandard message fields>` |
258258
| 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. |
259259

‎09-Extensions.md

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

33
There are not yet any defined extensions.
4-
| Extenstion Type | Extension Name | Description / BIP |
5-
| -------------------- | -------------- | ---------------------------------------------------------------------------- |
6-
| (no channel_msg bit) | | |
4+
| Extension Type | Extension Name | Description / BIP |
5+
| -------------- |-----------------------------------|----------------------------------------------------------------------|
6+
| 0x0002 | Worker Specific Hashrate Tracking | Definition [here](./extensions/worker-specific-hashrate-tracking.md) |

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

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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](), where each extension is assigned a `Type (U16)` identifier negotiated between 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) | 2 bytes | Extension identifier (`0x0002`) |
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+
**Example TLV Encoding**:
27+
```
28+
[TYPE: 0x0002] [LENGTH: 0x000A] [VALUE: "Worker_001"]
29+
```
30+
(Where `"Worker_001"` is 10 bytes long)
31+
32+
33+
### 1.2 Extension Activation (Negotiation Process)
34+
35+
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.
36+
37+
#### Message Exchange Example
38+
39+
1. **Connection Setup**:
40+
```
41+
Client --- SetupConnection (connection details) ---> Server
42+
Client <--- SetupConnection.Success (connection accepted) ---- Server
43+
```
44+
45+
2. **Extension Request**:
46+
```
47+
Client --- RequestExtensions [0x0002] ---> Server
48+
```
49+
50+
3. **Server Response**:
51+
- If successful:
52+
```
53+
Client <--- RequestExtensions.Success [0x0002] ---- Server
54+
```
55+
- If an error occurs:
56+
```
57+
Client <--- RequestExtensions.Error [0x0002] ---- Server
58+
```
59+
60+
Once negotiated, the client MUST append the TLV containing `user_identity` to every `SubmitSharesExtended` message.
61+
62+
### 1.3 Behavior Based on Negotiation
63+
64+
- **If the extension is negotiated**:
65+
- The `user_identity` field **MUST** be included in `SubmitSharesExtended` as a TLV with Type `0x0002`.
66+
- **If the extension is not negotiated**:
67+
- The `user_identity` field **MUST** not be included.
68+
- The server **MUST** ignore any unexpected TLV fields.
69+
70+
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.
71+
72+
---
73+
74+
### 2. Extended `SubmitSharesExtended` Message Format
75+
After negotiation, the client appends TLV fields at the end of `SubmitSharesExtended`.
76+
Example with the `user_identity` extension enabled:
77+
```
78+
[SubmitSharesExtended Base Fields] + [0x0002] [LENGTH] ["Worker_001"]
79+
```
80+
Example Message in Bytes:
81+
```
82+
<BASE PAYLOAD> + 00 02 00 0A 57 6F 72 6B 65 72 5F 30 30 31
83+
```
84+
Where:
85+
86+
- `00 02` → TLV Type (Worker Identity)
87+
- `00 0A` → Length (10 bytes)
88+
- `57 6F 72 6B 65 72 5F 30 30 31` → "Worker_001" (UTF-8 encoded)
89+
90+
---
91+
92+
### 3. Bandwidth Consideration
93+
94+
Including the `user_identity` field in each share submission increases message size, depending on the length of the identifier (up to 32 bytes).
95+
96+
For example:
97+
- **Without `user_identity`**: Share message size ~70 bytes.
98+
- **With maximum `user_identity` (32 bytes)**: Share message size ~102 bytes.
99+
100+
In a scenario with 10 shares per minute per channel:
101+
- **Maximum increase**: 32 bytes × 10 = 320 bytes/min, or 19.2 KB/hour.
102+
- **Average increase (20 bytes)**: 200 bytes/min, or 12 KB/hour.
103+
104+
---
105+
106+
## 4. Implementation Notes
107+
108+
### 4.1 Job Difficulty Management
109+
110+
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.
111+
112+
### 4.2 Privacy Considerations
113+
114+
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.
115+
116+
---

0 commit comments

Comments
 (0)