Skip to content

Commit d64c93b

Browse files
GitGab19GitGab19
committed
extensions-negotiation definition
1 parent 02b0963 commit d64c93b

File tree

3 files changed

+142
-4
lines changed

3 files changed

+142
-4
lines changed

‎03-Protocol-Overview.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,11 @@ If a device is aware of the semantics of a given extension type, it MUST process
126126

127127
Messages with an unknown `extension_type` which are to be processed locally (as defined above) MUST be discarded and ignored.
128128

129-
Extensions MUST require version negotiation with the recipient of the message to check that the extension is supported before sending non-version-negotiation messages for it.
129+
### 3.4.1 Implementing Extensions Support
130+
131+
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.
132+
133+
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.
130134
This prevents the needlessly wasted bandwidth and potentially serious performance degradation of extension messages when the recipient does not support them.
131135

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

‎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+
| 0x0001 | Extensions Negotiation | Definition [here](./extensions/extensions-negotiation.md) |

‎extensions/extensions-negotiation.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Stratum V2 Extension: Extensions Negotiation
2+
3+
## 0. Abstract
4+
5+
This document defines a Stratum V2 extension to negotiate support for other protocol extensions between clients and servers.
6+
7+
The mechanism allows clients to request support for a list of extensions immediately after the `SetupConnection` message exchange. The server responds with either:
8+
- `RequestExtensions.Success`, listing the supported extensions.
9+
- `RequestExtensions.Error`, listing the unsupported extensions and extensions required by the receiver.
10+
11+
This negotiation ensures that both parties can establish a common set of features before exchanging further protocol messages.
12+
13+
Terms like "MUST," "MUST NOT," "REQUIRED," etc., follow RFC2119 standards.
14+
15+
---
16+
17+
## 1. Overview
18+
19+
### 1.1 Negotiating Extensions
20+
21+
After the successful SetupConnection exchange, clients MUST send a `RequestExtensions` message to indicate the extensions they wish to use. The server responds with:
22+
- `RequestExtensions.Success`, confirming which extensions are supported.
23+
- `RequestExtensions.Error`, identifying unsupported extensions and required extensions from the responder.
24+
25+
Clients MUST NOT use any features from extensions that are not confirmed as supported by the server.
26+
27+
#### Message Exchange Example
28+
29+
- **Connection Setup**:
30+
```
31+
Client --- SetupConnection (connection details) ---> Server
32+
Client <--- SetupConnection.Success (connection accepted) ---- Server
33+
```
34+
35+
- **Extension Negotiation**:
36+
```
37+
Client --- RequestExtensions (list of requested U16) ---> Server
38+
39+
Server Response:
40+
If successful:
41+
Client <--- RequestExtensions.Success (list of supported U16) ---- Server
42+
43+
If an error occurs:
44+
Client <--- RequestExtensions.Error (unsupported U16, requested U16) ---- Server
45+
```
46+
47+
---
48+
49+
## 2. Messages Defined by This Extension
50+
51+
### `RequestExtensions` (Client -> Server)
52+
53+
| Field Name | Data Type | Description |
54+
|----------------------|--------------|-----------------------------------------------|
55+
| request_id | U16 | Unique identifier for pairing the response. |
56+
| requested_extensions | SEQ0_64K[U16]| List of requested extension identifiers. |
57+
58+
### `RequestExtensions.Success` (Server -> Client)
59+
60+
| Field Name | Data Type | Description |
61+
|----------------------|--------------|-----------------------------------------------|
62+
| request_id | U16 | Unique identifier for pairing the response. |
63+
| supported_extensions | SEQ0_64K[U16]| List of supported extension identifiers. |
64+
65+
### `RequestExtensions.Error` (Server -> Client)
66+
67+
| Field Name | Data Type | Description |
68+
|------------------------|--------------|-----------------------------------------------------------------------------------------|
69+
| request_id | U16 | Unique identifier for pairing the response. |
70+
| unsupported_extensions | SEQ0_64K[U16]| List of unsupported extension identifiers. |
71+
| required_extensions | SEQ0_64K[U16]| List of extension identifiers the server requires but were not requested by the client. |
72+
73+
---
74+
75+
## 3. Message Types
76+
77+
| Message Type (8-bit) | channel_msg_bit | Message Name |
78+
|----------------------|-----------------|---------------------------|
79+
| 0x00 | 0 | RequestExtensions |
80+
| 0x01 | 0 | RequestExtensions.Success |
81+
| 0x02 | 0 | RequestExtensions.Error |
82+
83+
---
84+
85+
## 4. Implementation Notes
86+
87+
1. **Error Handling**:
88+
- Servers MUST respond with `RequestExtensions.Error` if none of the requested extensions are supported.
89+
- If the server **requires** certain extensions but they were not included in the request, it MUST list them in the `requested_extensions` field of `RequestExtensions.Error`.
90+
91+
2. **Ordering**:
92+
- The `RequestExtensions` message MUST be sent immediately after `SetupConnection.Success` and before any other protocol-specific messages.
93+
- The response to `RequestExtensions` MUST be received before proceeding with any further protocol-specific messages.
94+
95+
#### 3. **Backward Compatibility**:
96+
- **Server Behavior**:
97+
- Servers that do not support this extension will ignore the `RequestExtensions` message.
98+
99+
- **Client Behavior**:
100+
- Clients MUST NOT send any further extension-specific messages until they receive a `RequestExtensions.Success` or `RequestExtensions.Error` response.
101+
- Clients MAY implement the following timeout and reconnection strategy:
102+
1. After sending `RequestExtensions`, wait for a timeout of 2x the initial connection time
103+
2. If no response is received within this timeout:
104+
- Reconnect to the same server
105+
- Attempt the extension negotiation again
106+
3. If still no response after 5x the initial connection time:
107+
- Reconnect one final time
108+
- Proceed without any extensions
109+
4. If the total connection time exceeds approximately 1 second:
110+
- Consider switching to a fallback pool
111+
- This strategy ensures that:
112+
- The first reconnection serves as a basic connectivity check
113+
- The total connection time remains reasonable for mining operations
114+
- Clients can gracefully fallback to non-extension operation
115+
- Users can switch to alternative pools if connection times are too high
116+
117+
This ensures clients can handle servers that do not implement extensions negotiation gracefully while maintaining reasonable connection times for mining operations.
118+
119+
4. **Example Use Case**:
120+
A client requesting support for extensions `0x0002` and `0x0003`:
121+
```
122+
Client --- RequestExtensions [0x0002, 0x0003] ---> Server
123+
Client <--- RequestExtensions.Success [0x0002] ---- Server
124+
```
125+
The client now knows that extension `0x0003` is not supported and must adapt its behavior accordingly.
126+
127+
128+
5. **Example Use Case with Server Requesting Extensions**:
129+
A server requiring extension `0x0005`, but the client did not include it in its request:
130+
```
131+
Client --- RequestExtensions [0x0002, 0x0003] ---> Server
132+
Client <--- RequestExtensions.Error [unsupported: 0x0003, required: 0x0005] ---- Server
133+
```
134+
The client now knows that the server requires extension `0x0005` and MAY choose to retry with a modified request.

0 commit comments

Comments
 (0)