update header after const_sv2 crate documentation

update header after `const_sv2` crate documentation
stratum-mining · Oct 2, 2024 · d84c53c · d84c53c
1 parent f941152
commit d84c53c
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 45 deletions.
diff --git a/protocols/v2/const-sv2/README.md b/protocols/v2/const-sv2/README.md
@@ -5,7 +5,7 @@
 
 `const_sv2` is a Rust crate that provides essential constants for the SV2 (Stratum V2) protocol. These constants are crucial for message framing, encryption, and protocol-specific identifiers across various SV2 components, including Mining, Job Declaration, and Template Distribution protocols.
 
-## Features
+## Main Components
 
 - **Protocol Constants**: Define key protocol discriminants, message types, and sizes for the SV2 binary protocol.
 - **Encryption Support**: Includes constants for encryption using ChaChaPoly and ElligatorSwift encoding.

diff --git a/protocols/v2/const-sv2/src/lib.rs b/protocols/v2/const-sv2/src/lib.rs
@@ -1,4 +1,4 @@
-//! This crate serves as the central repository for all constants used in the SV2 protocol.
+//! This crate provides all constants used in the SV2 protocol.
 //! These constants are essential for message framing, encryption, and protocol-specific
 //! identifiers across various SV2 components, including Mining, Job Declaration, and Template Distribution protocols.
 //!
@@ -12,7 +12,7 @@
 //! enabling the correct interpretation and handling of messages.
 //! These discriminants ensure that messages are processed by the appropriate protocol handlers,
 //! thereby facilitating seamless communication across different components of the SV2 architecture.
-//! More info at <https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#3-protocol-overview>
+//! 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).
 
 //!
 //! ### Message Types
@@ -103,7 +103,7 @@ pub const INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_S
 /// If protocolName is less than or equal to 32 bytes in length, use protocolName with zero bytes
 /// appended to make 32 bytes. Otherwise, apply HASH to it. For name =
 /// "Noise_NX_Secp256k1+EllSwift_ChaChaPoly_SHA256", we need the hash.
-/// More info at <https://github.com/stratum-mining/sv2-spec/blob/main/04-Protocol-Security.md#451-handshake-act-1-nx-handshake-part-1---e>
+/// 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).
 pub const NOISE_HASHED_PROTOCOL_NAME_CHACHA: [u8; 32] = [
     46, 180, 120, 129, 32, 142, 158, 238, 31, 102, 159, 103, 198, 110, 231, 14, 169, 234, 136, 9,
     13, 80, 63, 232, 48, 220, 75, 200, 62, 41, 191, 16,

diff --git a/protocols/v2/sv2-ffi/sv2.h b/protocols/v2/sv2-ffi/sv2.h
@@ -4,36 +4,54 @@
 #include <ostream>
 #include <new>
 
+/// Identifier for the extension_type field in the SV2 frame, indicating no extensions.
 static const uint16_t EXTENSION_TYPE_NO_EXTENSION = 0;
 
+/// Size of the SV2 frame header in bytes.
 static const uintptr_t SV2_FRAME_HEADER_SIZE = 6;
 
 static const uintptr_t SV2_FRAME_HEADER_LEN_OFFSET = 3;
 
 static const uintptr_t SV2_FRAME_HEADER_LEN_END = 3;
 
+/// Maximum size of an SV2 frame chunk in bytes.
 static const uintptr_t SV2_FRAME_CHUNK_SIZE = 65535;
 
+/// Size of the MAC for supported AEAD encryption algorithm (ChaChaPoly).
 static const uintptr_t AEAD_MAC_LEN = 16;
 
+/// Size of the encrypted SV2 frame header, including the MAC.
 static const uintptr_t ENCRYPTED_SV2_FRAME_HEADER_SIZE = (SV2_FRAME_HEADER_SIZE + AEAD_MAC_LEN);
 
+/// Size of the Noise protocol frame header in bytes.
 static const uintptr_t NOISE_FRAME_HEADER_SIZE = 2;
 
 static const uintptr_t NOISE_FRAME_HEADER_LEN_OFFSET = 0;
 
+/// Size in bytes of the encoded elliptic curve point using ElligatorSwift encoding.
+/// This encoding produces a 64-byte representation of the X-coordinate of a secp256k1 curve point.
 static const uintptr_t ELLSWIFT_ENCODING_SIZE = 64;
 
 static const uintptr_t RESPONDER_EXPECTED_HANDSHAKE_MESSAGE_SIZE = ELLSWIFT_ENCODING_SIZE;
 
 static const uintptr_t MAC = 16;
 
+/// Size in bytes of the encrypted ElligatorSwift encoded data, which includes the original
+/// ElligatorSwift encoded data and a MAC for integrity verification.
 static const uintptr_t ENCRYPTED_ELLSWIFT_ENCODING_SIZE = (ELLSWIFT_ENCODING_SIZE + MAC);
 
+/// Size in bytes of the SIGNATURE_NOISE_MESSAGE, which contains information and a signature
+/// for the handshake initiator, formatted according to the Noise Protocol specifications.
 static const uintptr_t SIGNATURE_NOISE_MESSAGE_SIZE = 74;
 
+/// Size in bytes of the encrypted signature noise message, which includes the SIGNATURE_NOISE_MESSAGE
+/// and a MAC for integrity verification.
 static const uintptr_t ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE = (SIGNATURE_NOISE_MESSAGE_SIZE + MAC);
 
+/// Size in bytes of the handshake message expected by the initiator, encompassing:
+/// - ElligatorSwift encoded public key
+/// - Encrypted ElligatorSwift encoding
+/// - Encrypted SIGNATURE_NOISE_MESSAGE
 static const uintptr_t INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE = ((ELLSWIFT_ENCODING_SIZE + ENCRYPTED_ELLSWIFT_ENCODING_SIZE) + ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE);
 
 static const uint8_t SV2_MINING_PROTOCOL_DISCRIMINANT = 0;
@@ -50,85 +68,83 @@ static const uint8_t MESSAGE_TYPE_SETUP_CONNECTION_ERROR = 2;
 
 static const uint8_t MESSAGE_TYPE_CHANNEL_ENDPOINT_CHANGED = 3;
 
-static const uint8_t MESSAGE_TYPE_COINBASE_OUTPUT_DATA_SIZE = 112;
+static const uint8_t MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL = 16;
 
-static const uint8_t MESSAGE_TYPE_NEW_TEMPLATE = 113;
+static const uint8_t MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL_SUCCESS = 17;
 
-static const uint8_t MESSAGE_TYPE_SET_NEW_PREV_HASH = 114;
+static const uint8_t MESSAGE_TYPE_OPEN_MINING_CHANNEL_ERROR = 18;
 
-static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA = 115;
+static const uint8_t MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL = 19;
 
-static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS = 116;
+static const uint8_t MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCES = 20;
 
-static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR = 117;
+static const uint8_t MESSAGE_TYPE_NEW_MINING_JOB = 21;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SOLUTION = 118;
+static const uint8_t MESSAGE_TYPE_UPDATE_CHANNEL = 22;
 
-static const uint8_t MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN = 80;
+static const uint8_t MESSAGE_TYPE_UPDATE_CHANNEL_ERROR = 23;
 
-static const uint8_t MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN_SUCCESS = 81;
+static const uint8_t MESSAGE_TYPE_CLOSE_CHANNEL = 24;
 
-static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB = 87;
+static const uint8_t MESSAGE_TYPE_SET_EXTRANONCE_PREFIX = 25;
 
-static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB_SUCCESS = 88;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_STANDARD = 26;
 
-static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB_ERROR = 89;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_EXTENDED = 27;
 
-static const uint8_t MESSAGE_TYPE_IDENTIFY_TRANSACTIONS = 83;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_SUCCESS = 28;
 
-static const uint8_t MESSAGE_TYPE_IDENTIFY_TRANSACTIONS_SUCCESS = 84;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_ERROR = 29;
 
-static const uint8_t MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS = 85;
+static const uint8_t MESSAGE_TYPE_NEW_EXTENDED_MINING_JOB = 31;
 
-static const uint8_t MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS = 86;
+static const uint8_t MESSAGE_TYPE_MINING_SET_NEW_PREV_HASH = 32;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SOLUTION_JD = 96;
+static const uint8_t MESSAGE_TYPE_SET_TARGET = 33;
 
-static const uint8_t MESSAGE_TYPE_CLOSE_CHANNEL = 24;
+static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB = 34;
 
-/// This has been cahnged before was 0x1e it can be that old Sv2 implementation still use the old
-/// one but this means that old impl are not following Sv2 spec
-static const uint8_t MESSAGE_TYPE_NEW_EXTENDED_MINING_JOB = 31;
+static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_SUCCESS = 35;
 
-static const uint8_t MESSAGE_TYPE_NEW_MINING_JOB = 21;
+static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_ERROR = 36;
 
-static const uint8_t MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL = 19;
+static const uint8_t MESSAGE_TYPE_RECONNECT = 37;
 
-static const uint8_t MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCES = 20;
+static const uint8_t MESSAGE_TYPE_SET_GROUP_CHANNEL = 38;
 
-static const uint8_t MESSAGE_TYPE_OPEN_MINING_CHANNEL_ERROR = 18;
+static const uint8_t MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN = 80;
 
-static const uint8_t MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL = 16;
+static const uint8_t MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN_SUCCESS = 81;
 
-static const uint8_t MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL_SUCCESS = 17;
+static const uint8_t MESSAGE_TYPE_IDENTIFY_TRANSACTIONS = 83;
 
-static const uint8_t MESSAGE_TYPE_RECONNECT = 37;
+static const uint8_t MESSAGE_TYPE_IDENTIFY_TRANSACTIONS_SUCCESS = 84;
 
-static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB = 34;
+static const uint8_t MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS = 85;
 
-static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_ERROR = 36;
+static const uint8_t MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS = 86;
 
-static const uint8_t MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_SUCCESS = 35;
+static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB = 87;
 
-static const uint8_t MESSAGE_TYPE_SET_EXTRANONCE_PREFIX = 25;
+static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB_SUCCESS = 88;
 
-static const uint8_t MESSAGE_TYPE_SET_GROUP_CHANNEL = 38;
+static const uint8_t MESSAGE_TYPE_DECLARE_MINING_JOB_ERROR = 89;
 
-static const uint8_t MESSAGE_TYPE_MINING_SET_NEW_PREV_HASH = 32;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SOLUTION_JD = 96;
 
-static const uint8_t MESSAGE_TYPE_SET_TARGET = 33;
+static const uint8_t MESSAGE_TYPE_COINBASE_OUTPUT_DATA_SIZE = 112;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_ERROR = 29;
+static const uint8_t MESSAGE_TYPE_NEW_TEMPLATE = 113;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_EXTENDED = 27;
+static const uint8_t MESSAGE_TYPE_SET_NEW_PREV_HASH = 114;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_STANDARD = 26;
+static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA = 115;
 
-static const uint8_t MESSAGE_TYPE_SUBMIT_SHARES_SUCCESS = 28;
+static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS = 116;
 
-static const uint8_t MESSAGE_TYPE_UPDATE_CHANNEL = 22;
+static const uint8_t MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR = 117;
 
-static const uint8_t MESSAGE_TYPE_UPDATE_CHANNEL_ERROR = 23;
+static const uint8_t MESSAGE_TYPE_SUBMIT_SOLUTION = 118;
 
 static const bool CHANNEL_BIT_SETUP_CONNECTION = false;