const_sv2/
lib.rs

1//! This crate provides all constants used in the SV2 protocol.
2//! These constants are essential for message framing, encryption, and
3//! protocol-specific identifiers across various SV2 components, including
4//! Mining, Job Declaration, and Template Distribution protocols.
5//!
6//! It also includes definitions for key encryption settings and message types,
7//! ensuring consistency and accuracy when working with SV2's binary protocol.
8//! These constants are used throughout the system to ensure that SV2
9//! messages are formatted and interpreted correctly.
10//!
11//! ### Discriminants for Stratum V2 (sub)protocols
12//! Discriminants are unique identifiers used to distinguish between different
13//! Stratum V2 (sub)protocols. Each protocol within the SV2 ecosystem has a
14//! specific discriminant value that indicates its type, enabling the correct
15//! interpretation and handling of messages. These discriminants ensure that
16//! messages are processed by the appropriate protocol handlers,
17//! thereby facilitating seamless communication across different components of
18//! the SV2 architecture. More info can be found [on Chapter 03 of the Stratum V2 specs](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#3-protocol-overview).
19
20//!
21//! ### Message Types
22//! Message types in the SV2 protocol define the specific operations and data
23//! exchanges between participants. Each type corresponds to a distinct action
24//! or information transfer, facilitating communication in various contexts such
25//! as mining operations, job declarations, and template distribution. Properly
26//! identifying and handling these message types is crucial for maintaining
27//! protocol compliance and ensuring seamless interactions within the SV2
28//! ecosystem. The message types are categorized into common types and those
29//! specific to each subprotocol, providing clarity on their intended use and
30//! interaction patterns.
31//!
32//! ### Channel Bits
33//! The `channel bits` indicate whether a message is associated with a specific
34//! channel. If the most significant bit of the `extension_type` (referred to as
35//! `channel_msg`) is set, the message is related to a channel and includes a
36//! `channel_id`. In this case, the first 4 bytes of the payload represent the
37//! `channel_id` the message is destined for.
38
39#![no_std]
40
41/// Identifier for the extension_type field in the SV2 frame, indicating no
42/// extensions.
43pub const EXTENSION_TYPE_NO_EXTENSION: u16 = 0;
44
45/// Size of the SV2 frame header in bytes.
46pub const SV2_FRAME_HEADER_SIZE: usize = 6;
47
48// It's not used anywhere.
49// Refactoring: deprecate it.
50pub const SV2_FRAME_HEADER_LEN_OFFSET: usize = 3;
51
52// It's not used anywhere.
53// Refactoring: deprecate it.
54pub const SV2_FRAME_HEADER_LEN_END: usize = 3;
55
56/// Maximum size of an SV2 frame chunk in bytes.
57pub const SV2_FRAME_CHUNK_SIZE: usize = 65535;
58
59/// Size of the MAC for supported AEAD encryption algorithm (ChaChaPoly).
60pub const AEAD_MAC_LEN: usize = 16;
61
62/// Size of the encrypted SV2 frame header, including the MAC.
63// Refactoring: declared in sv2-ffi, and imported in framing_sv2/src/header.rs
64// header.rs is then imported into codec_sv2 just for this constant
65pub const ENCRYPTED_SV2_FRAME_HEADER_SIZE: usize = SV2_FRAME_HEADER_SIZE + AEAD_MAC_LEN;
66
67/// Size of the Noise protocol frame header in bytes.
68// Refactoring: declared in sv2-ffi, and imported in framing_sv2/src/header.rs
69// header.rs is then imported into codec_sv2 just for this constant
70pub const NOISE_FRAME_HEADER_SIZE: usize = 2;
71
72// Refactoring: declared in sv2-ffi, and imported in framing_sv2/src/header.rs
73// header.rs is then imported into codec_sv2 just for this constant, and the
74// const there is not even used
75pub const NOISE_FRAME_HEADER_LEN_OFFSET: usize = 0;
76
77// It's not used anywhere.
78// Refactoring: deprecate it.
79pub const NOISE_FRAME_MAX_SIZE: usize = u16::MAX as usize;
80
81/// Size in bytes of the encoded elliptic curve point using ElligatorSwift
82/// encoding. This encoding produces a 64-byte representation of the
83/// X-coordinate of a secp256k1 curve point.
84pub const ELLSWIFT_ENCODING_SIZE: usize = 64;
85
86// Refactoring: the alias could be created where it's imported, or we could just
87// use one name everywhere
88pub const RESPONDER_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_SIZE;
89
90// This is the same as AEAD_MAC_LEN.
91// Refactoring: deprecate it.
92pub const MAC: usize = 16;
93
94/// Size in bytes of the encrypted ElligatorSwift encoded data, which includes
95/// the original ElligatorSwift encoded data and a MAC for integrity
96/// verification.
97pub const ENCRYPTED_ELLSWIFT_ENCODING_SIZE: usize = ELLSWIFT_ENCODING_SIZE + MAC;
98
99/// Size in bytes of the SIGNATURE_NOISE_MESSAGE, which contains information and
100/// a signature for the handshake initiator, formatted according to the Noise
101/// Protocol specifications.
102pub const SIGNATURE_NOISE_MESSAGE_SIZE: usize = 74;
103
104/// Size in bytes of the encrypted signature noise message, which includes the
105/// SIGNATURE_NOISE_MESSAGE and a MAC for integrity verification.
106pub const ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE: usize = SIGNATURE_NOISE_MESSAGE_SIZE + MAC;
107
108/// Size in bytes of the handshake message expected by the initiator,
109/// encompassing:
110/// - ElligatorSwift encoded public key
111/// - Encrypted ElligatorSwift encoding
112/// - Encrypted SIGNATURE_NOISE_MESSAGE
113pub const INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_SIZE
114    + ENCRYPTED_ELLSWIFT_ENCODING_SIZE
115    + ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE;
116
117/// If protocolName is less than or equal to 32 bytes in length, use
118/// protocolName with zero bytes appended to make 32 bytes. Otherwise, apply
119/// HASH to it. For name = "Noise_NX_Secp256k1+EllSwift_ChaChaPoly_SHA256", we
120/// need the hash. More info can be found [at this link](https://github.com/stratum-mining/sv2-spec/blob/main/04-Protocol-Security.md#451-handshake-act-1-nx-handshake-part-1---e).
121pub const NOISE_HASHED_PROTOCOL_NAME_CHACHA: [u8; 32] = [
122    46, 180, 120, 129, 32, 142, 158, 238, 31, 102, 159, 103, 198, 110, 231, 14, 169, 234, 136, 9,
123    13, 80, 63, 232, 48, 220, 75, 200, 62, 41, 191, 16,
124];
125
126// len = 1
127// 47,53,45,41 = AESG
128// We're dropping support for AESG.
129// Refactoring: deprecate it.
130pub const NOISE_SUPPORTED_CIPHERS_MESSAGE: [u8; 5] = [1, 0x47, 0x53, 0x45, 0x41];
131
132// Discriminants for distinct Stratum V2 (sub)protocols. More info at https://github.com/stratum-
133// mining/sv2-spec/blob/main/03-Protocol-Overview.md#3-protocol-overview
134pub const SV2_MINING_PROTOCOL_DISCRIMINANT: u8 = 0;
135pub const SV2_JOB_DECLARATION_PROTOCOL_DISCRIMINANT: u8 = 1;
136// Refactoring: rename this into SV2_TEMPLATE_DISTRIBUTION_PROTOCOL_DISCRIMINANT
137pub const SV2_TEMPLATE_DISTR_PROTOCOL_DISCRIMINANT: u8 = 2;
138
139// Common message types used across all Stratum V2 (sub)protocols.
140pub const MESSAGE_TYPE_SETUP_CONNECTION: u8 = 0x0;
141pub const MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS: u8 = 0x1;
142pub const MESSAGE_TYPE_SETUP_CONNECTION_ERROR: u8 = 0x2;
143pub const MESSAGE_TYPE_CHANNEL_ENDPOINT_CHANGED: u8 = 0x3;
144
145// Mining Protocol message types.
146pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL: u8 = 0x10;
147pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL_SUCCESS: u8 = 0x11;
148pub const MESSAGE_TYPE_OPEN_MINING_CHANNEL_ERROR: u8 = 0x12;
149pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL: u8 = 0x13;
150// Refactoring: fix typo with MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCESS
151pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCES: u8 = 0x14;
152pub const MESSAGE_TYPE_NEW_MINING_JOB: u8 = 0x15;
153pub const MESSAGE_TYPE_UPDATE_CHANNEL: u8 = 0x16;
154pub const MESSAGE_TYPE_UPDATE_CHANNEL_ERROR: u8 = 0x17;
155pub const MESSAGE_TYPE_CLOSE_CHANNEL: u8 = 0x18;
156pub const MESSAGE_TYPE_SET_EXTRANONCE_PREFIX: u8 = 0x19;
157pub const MESSAGE_TYPE_SUBMIT_SHARES_STANDARD: u8 = 0x1a;
158pub const MESSAGE_TYPE_SUBMIT_SHARES_EXTENDED: u8 = 0x1b;
159pub const MESSAGE_TYPE_SUBMIT_SHARES_SUCCESS: u8 = 0x1c;
160pub const MESSAGE_TYPE_SUBMIT_SHARES_ERROR: u8 = 0x1d;
161pub const MESSAGE_TYPE_NEW_EXTENDED_MINING_JOB: u8 = 0x1f;
162pub const MESSAGE_TYPE_MINING_SET_NEW_PREV_HASH: u8 = 0x20;
163pub const MESSAGE_TYPE_SET_TARGET: u8 = 0x21;
164pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB: u8 = 0x22;
165pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_SUCCESS: u8 = 0x23;
166pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_ERROR: u8 = 0x24;
167
168// Refactoring: we need to move this to 0x04 and shift SETGROUPCHANNEL to 0x25
169// (we are not specs compliant now)
170pub const MESSAGE_TYPE_RECONNECT: u8 = 0x25;
171pub const MESSAGE_TYPE_SET_GROUP_CHANNEL: u8 = 0x26;
172
173// Job Declaration Protocol message types.
174pub const MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN: u8 = 0x50;
175pub const MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN_SUCCESS: u8 = 0x51;
176pub const MESSAGE_TYPE_IDENTIFY_TRANSACTIONS: u8 = 0x53;
177pub const MESSAGE_TYPE_IDENTIFY_TRANSACTIONS_SUCCESS: u8 = 0x54;
178pub const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS: u8 = 0x55;
179pub const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS: u8 = 0x56;
180pub const MESSAGE_TYPE_DECLARE_MINING_JOB: u8 = 0x57;
181pub const MESSAGE_TYPE_DECLARE_MINING_JOB_SUCCESS: u8 = 0x58;
182pub const MESSAGE_TYPE_DECLARE_MINING_JOB_ERROR: u8 = 0x59;
183pub const MESSAGE_TYPE_SUBMIT_SOLUTION_JD: u8 = 0x60;
184
185// Template Distribution Protocol message types.
186pub const MESSAGE_TYPE_COINBASE_OUTPUT_CONSTRAINTS: u8 = 0x70;
187pub const MESSAGE_TYPE_NEW_TEMPLATE: u8 = 0x71;
188pub const MESSAGE_TYPE_SET_NEW_PREV_HASH: u8 = 0x72;
189pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA: u8 = 0x73;
190pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS: u8 = 0x74;
191pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR: u8 = 0x75;
192pub const MESSAGE_TYPE_SUBMIT_SOLUTION: u8 = 0x76;
193
194// The `channel bits` indicate whether a message is associated with a specific
195// channel. If the most significant bit of the `extension_type` (referred to as
196// `channel_msg`) is set, the message is related to a channel and includes a
197// `channel_id`. In this case, the first 4 bytes of the payload represent the
198// `channel_id` the message is destined for. For the Job Declaration and
199// Template Distribution protocols, the `channel_msg` bit is always unset.
200
201pub const CHANNEL_BIT_SETUP_CONNECTION: bool = false;
202pub const CHANNEL_BIT_SETUP_CONNECTION_SUCCESS: bool = false;
203pub const CHANNEL_BIT_SETUP_CONNECTION_ERROR: bool = false;
204pub const CHANNEL_BIT_CHANNEL_ENDPOINT_CHANGED: bool = true;
205
206// For the Template Distribution protocol, the channel bit is always unset.
207pub const CHANNEL_BIT_COINBASE_OUTPUT_CONSTRAINTS: bool = false;
208pub const CHANNEL_BIT_NEW_TEMPLATE: bool = false;
209pub const CHANNEL_BIT_SET_NEW_PREV_HASH: bool = false;
210pub const CHANNEL_BIT_REQUEST_TRANSACTION_DATA: bool = false;
211pub const CHANNEL_BIT_REQUEST_TRANSACTION_DATA_SUCCESS: bool = false;
212pub const CHANNEL_BIT_REQUEST_TRANSACTION_DATA_ERROR: bool = false;
213pub const CHANNEL_BIT_SUBMIT_SOLUTION: bool = false;
214
215// In the Job Declaration protocol, the `channel_msg` bit is always unset,
216// except for `SUBMIT_SOLUTION_JD`, which requires a specific channel reference.
217pub const CHANNEL_BIT_ALLOCATE_MINING_JOB_TOKEN: bool = false;
218pub const CHANNEL_BIT_ALLOCATE_MINING_JOB_TOKEN_SUCCESS: bool = false;
219pub const CHANNEL_BIT_DECLARE_MINING_JOB: bool = false;
220pub const CHANNEL_BIT_DECLARE_MINING_JOB_SUCCESS: bool = false;
221pub const CHANNEL_BIT_DECLARE_MINING_JOB_ERROR: bool = false;
222pub const CHANNEL_BIT_IDENTIFY_TRANSACTIONS: bool = false;
223pub const CHANNEL_BIT_IDENTIFY_TRANSACTIONS_SUCCESS: bool = false;
224pub const CHANNEL_BIT_PROVIDE_MISSING_TRANSACTIONS: bool = false;
225pub const CHANNEL_BIT_PROVIDE_MISSING_TRANSACTIONS_SUCCESS: bool = false;
226pub const CHANNEL_BIT_SUBMIT_SOLUTION_JD: bool = true;
227
228// Channel bits in the Mining protocol vary depending on the message.
229pub const CHANNEL_BIT_CLOSE_CHANNEL: bool = true;
230pub const CHANNEL_BIT_NEW_EXTENDED_MINING_JOB: bool = true;
231pub const CHANNEL_BIT_NEW_MINING_JOB: bool = true;
232pub const CHANNEL_BIT_OPEN_EXTENDED_MINING_CHANNEL: bool = false;
233pub const CHANNEL_BIT_OPEN_EXTENDED_MINING_CHANNEL_SUCCES: bool = false;
234pub const CHANNEL_BIT_OPEN_MINING_CHANNEL_ERROR: bool = false;
235pub const CHANNEL_BIT_OPEN_STANDARD_MINING_CHANNEL: bool = false;
236pub const CHANNEL_BIT_OPEN_STANDARD_MINING_CHANNEL_SUCCESS: bool = false;
237pub const CHANNEL_BIT_RECONNECT: bool = false;
238pub const CHANNEL_BIT_SET_CUSTOM_MINING_JOB: bool = false;
239pub const CHANNEL_BIT_SET_CUSTOM_MINING_JOB_ERROR: bool = false;
240pub const CHANNEL_BIT_SET_CUSTOM_MINING_JOB_SUCCESS: bool = false;
241pub const CHANNEL_BIT_SET_EXTRANONCE_PREFIX: bool = true;
242pub const CHANNEL_BIT_SET_GROUP_CHANNEL: bool = false;
243pub const CHANNEL_BIT_MINING_SET_NEW_PREV_HASH: bool = true;
244pub const CHANNEL_BIT_SET_TARGET: bool = true;
245pub const CHANNEL_BIT_SUBMIT_SHARES_ERROR: bool = true;
246pub const CHANNEL_BIT_SUBMIT_SHARES_EXTENDED: bool = true;
247pub const CHANNEL_BIT_SUBMIT_SHARES_STANDARD: bool = true;
248pub const CHANNEL_BIT_SUBMIT_SHARES_SUCCESS: bool = true;
249pub const CHANNEL_BIT_UPDATE_CHANNEL: bool = true;
250pub const CHANNEL_BIT_UPDATE_CHANNEL_ERROR: bool = true;
const_sv2/lib.rs

const_sv2/
lib.rs
