stratum-mining · GitGab19 · Sep 6, 2024
diff --git a/protocols/v2/const-sv2/src/lib.rs b/protocols/v2/const-sv2/src/lib.rs
@@ -1,99 +1,157 @@
-//! Central repository for all the sv2 constants
+//! This crate serves as the central repository for 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.
+//!
+//! It also includes definitions for key encryption settings and message types, ensuring consistency and accuracy
+//! when working with SV2's binary protocol. These constants are used throughout the system to ensure that SV2
+//! messages are formatted and interpreted correctly.
+
 #![cfg_attr(feature = "no_std", no_std)]
 
+/// Identifier for the extension_type field in the SV2 frame, indicating no extensions.
+// SHOULD WE DEFINE IT? It's not used anywhere than ffi
 pub const EXTENSION_TYPE_NO_EXTENSION: u16 = 0;
 
+/// Size of the SV2 frame header in bytes.
 pub const SV2_FRAME_HEADER_SIZE: usize = 6;
+
+// WHAT IS THIS? It's not used anywhere, just declared in ffi
 pub const SV2_FRAME_HEADER_LEN_OFFSET: usize = 3;
+
+// WHAT IS THIS? It's not used anywhere, just declared in ffi
 pub const SV2_FRAME_HEADER_LEN_END: usize = 3;
+
+/// Maximum size of an SV2 frame chunk in bytes.
 pub const SV2_FRAME_CHUNK_SIZE: usize = 65535;
 
-// For now only CHACHA and AES are supported both have a MAC of 16 bytes
+/// Size of the MAC for supported AEAD encryption algorithm (ChaChaPoly).
 pub const AEAD_MAC_LEN: usize = 16;
 
+/// Size of the encrypted SV2 frame header, including the MAC.
+// Declared in ffi, and imported in framing_sv2/src/header.rs
+// TAKE NOTE: header.rs is then imported into codec_sv2 just for this constant
 pub const ENCRYPTED_SV2_FRAME_HEADER_SIZE: usize = SV2_FRAME_HEADER_SIZE + AEAD_MAC_LEN;
+
+/// Size of the Noise protocol frame header in bytes.
+// Declared in ffi, and imported in framing_sv2/src/header.rs
+// TAKE NOTE: header.rs is then imported into codec_sv2 just for this constant
 pub const NOISE_FRAME_HEADER_SIZE: usize = 2;
+
+// Declared in ffi, and imported in framing_sv2/src/header.rs
+// TAKE NOTE: header.rs is then imported into codec_sv2 just for this constant, and the const there is not even used
 pub const NOISE_FRAME_HEADER_LEN_OFFSET: usize = 0;
+
+// WHAT IS THIS? It's not used anywhere
 pub const NOISE_FRAME_MAX_SIZE: usize = u16::MAX as usize;
 
+/// 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.
 pub const ELLSWIFT_ENCODING_SIZE: usize = 64;
+
+// Does it make sense to just create an alias for this here? I think it could be created where it's imported
 pub const RESPONDER_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_SIZE;
+
+// Is this a different MAC with respect to the f ?
 pub const MAC: usize = 16;
+
+/// Size in bytes of the encrypted ElligatorSwift encoded data, which includes the original
+/// ElligatorSwift encoded data and a MAC for integrity verification.
 pub const ENCRYPTED_ELLSWIFT_ENCODING_SIZE: usize = 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.
 pub const SIGNATURE_NOISE_MESSAGE_SIZE: usize = 74;
+
+/// Size in bytes of the encrypted signature noise message, which includes the SIGNATURE_NOISE_MESSAGE
+/// and a MAC for integrity verification.
 pub const ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE: usize = 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
 pub const INITIATOR_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_SIZE
     + ENCRYPTED_ELLSWIFT_ENCODING_SIZE
     + ENCRYPTED_SIGNATURE_NOISE_MESSAGE_SIZE;
 
 /// 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
 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,
 ];
 
 // len = 1
 // 47,53,45,41 = AESG
+// SHOULDN'T WE REMOVE THIS?
 pub const NOISE_SUPPORTED_CIPHERS_MESSAGE: [u8; 5] = [1, 0x47, 0x53, 0x45, 0x41];
 
+/// Discriminants for distinct Stratum V2 (sub)protocols. More info at https://github.com/stratum-
+/// mining/sv2-spec/blob/main/03-Protocol-Overview.md#3-protocol-overview
 pub const SV2_MINING_PROTOCOL_DISCRIMINANT: u8 = 0;
 pub const SV2_JOB_DECLARATION_PROTOCOL_DISCRIMINANT: u8 = 1;
+// RENAME in SV2_TEMPLATE_DISTRIBUTION_PROTOCOL_DISCRIMINANT
 pub const SV2_TEMPLATE_DISTR_PROTOCOL_DISCRIMINANT: u8 = 2;
 
-// COMMON MESSAGES TYPES
+/// Common message types used across all Stratum V2 (sub)protocols.
 pub const MESSAGE_TYPE_SETUP_CONNECTION: u8 = 0x0;
 pub const MESSAGE_TYPE_SETUP_CONNECTION_SUCCESS: u8 = 0x1;
 pub const MESSAGE_TYPE_SETUP_CONNECTION_ERROR: u8 = 0x2;
 pub const MESSAGE_TYPE_CHANNEL_ENDPOINT_CHANGED: u8 = 0x3;
-// TEMPLATE DISTRIBUTION PROTOCOL MESSAGES TYPES
-pub const MESSAGE_TYPE_COINBASE_OUTPUT_DATA_SIZE: u8 = 0x70;
-pub const MESSAGE_TYPE_NEW_TEMPLATE: u8 = 0x71;
-pub const MESSAGE_TYPE_SET_NEW_PREV_HASH: u8 = 0x72;
-pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA: u8 = 0x73;
-pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS: u8 = 0x74;
-pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR: u8 = 0x75;
-pub const MESSAGE_TYPE_SUBMIT_SOLUTION: u8 = 0x76;
-// JOB DECLARATION PROTOCOL MESSAGES TYPES
+
+/// Mining Protocol message types.
+pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL: u8 = 0x10;
+pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL_SUCCESS: u8 = 0x11;
+pub const MESSAGE_TYPE_OPEN_MINING_CHANNEL_ERROR: u8 = 0x12;
+pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL: u8 = 0x13;
+// Typo: MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCESS
+pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCES: u8 = 0x14;
+pub const MESSAGE_TYPE_NEW_MINING_JOB: u8 = 0x15;
+pub const MESSAGE_TYPE_UPDATE_CHANNEL: u8 = 0x16;
+pub const MESSAGE_TYPE_UPDATE_CHANNEL_ERROR: u8 = 0x17;
+pub const MESSAGE_TYPE_CLOSE_CHANNEL: u8 = 0x18;
+pub const MESSAGE_TYPE_SET_EXTRANONCE_PREFIX: u8 = 0x19;
+pub const MESSAGE_TYPE_SUBMIT_SHARES_STANDARD: u8 = 0x1a;
+pub const MESSAGE_TYPE_SUBMIT_SHARES_EXTENDED: u8 = 0x1b;
+pub const MESSAGE_TYPE_SUBMIT_SHARES_SUCCESS: u8 = 0x1c;
+pub const MESSAGE_TYPE_SUBMIT_SHARES_ERROR: u8 = 0x1d;
+pub const MESSAGE_TYPE_NEW_EXTENDED_MINING_JOB: u8 = 0x1f;
+pub const MESSAGE_TYPE_MINING_SET_NEW_PREV_HASH: u8 = 0x20;
+pub const MESSAGE_TYPE_SET_TARGET: u8 = 0x21;
+pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB: u8 = 0x22;
+pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_SUCCESS: u8 = 0x23;
+pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_ERROR: u8 = 0x24;
+
+// WE NEED TO MOVE THIS to 0x04 AND SHIFT the SETGROUPCHANNEL to 0x25 (we are not specs compliant now)
+pub const MESSAGE_TYPE_RECONNECT: u8 = 0x25;
+pub const MESSAGE_TYPE_SET_GROUP_CHANNEL: u8 = 0x26;
+
+/// Job Declaration Protocol message types.
 pub const MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN: u8 = 0x50;
 pub const MESSAGE_TYPE_ALLOCATE_MINING_JOB_TOKEN_SUCCESS: u8 = 0x51;
-pub const MESSAGE_TYPE_DECLARE_MINING_JOB: u8 = 0x57;
-pub const MESSAGE_TYPE_DECLARE_MINING_JOB_SUCCESS: u8 = 0x58;
-pub const MESSAGE_TYPE_DECLARE_MINING_JOB_ERROR: u8 = 0x59;
 pub const MESSAGE_TYPE_IDENTIFY_TRANSACTIONS: u8 = 0x53;
 pub const MESSAGE_TYPE_IDENTIFY_TRANSACTIONS_SUCCESS: u8 = 0x54;
 pub const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS: u8 = 0x55;
 pub const MESSAGE_TYPE_PROVIDE_MISSING_TRANSACTIONS_SUCCESS: u8 = 0x56;
+pub const MESSAGE_TYPE_DECLARE_MINING_JOB: u8 = 0x57;
+pub const MESSAGE_TYPE_DECLARE_MINING_JOB_SUCCESS: u8 = 0x58;
+pub const MESSAGE_TYPE_DECLARE_MINING_JOB_ERROR: u8 = 0x59;
 pub const MESSAGE_TYPE_SUBMIT_SOLUTION_JD: u8 = 0x60;
-// MINING PROTOCOL MESSAGES TYPES
-pub const MESSAGE_TYPE_CLOSE_CHANNEL: u8 = 0x18;
-/// 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
-pub const MESSAGE_TYPE_NEW_EXTENDED_MINING_JOB: u8 = 0x1f;
-pub const MESSAGE_TYPE_NEW_MINING_JOB: u8 = 0x15;
-pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL: u8 = 0x13;
-pub const MESSAGE_TYPE_OPEN_EXTENDED_MINING_CHANNEL_SUCCES: u8 = 0x14;
-// in the spec page 21 is defined OpenMiningChannelError valid for both extended and standard
-// messages but in the spec page 40 are defined two different message types for
-// OpenStandardMiningChannelError and OpenExtendedMiningChannelError
-pub const MESSAGE_TYPE_OPEN_MINING_CHANNEL_ERROR: u8 = 0x12;
-pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL: u8 = 0x10;
-pub const MESSAGE_TYPE_OPEN_STANDARD_MINING_CHANNEL_SUCCESS: u8 = 0x11;
-pub const MESSAGE_TYPE_RECONNECT: u8 = 0x25;
-pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB: u8 = 0x22;
-pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_ERROR: u8 = 0x24;
-pub const MESSAGE_TYPE_SET_CUSTOM_MINING_JOB_SUCCESS: u8 = 0x23;
-pub const MESSAGE_TYPE_SET_EXTRANONCE_PREFIX: u8 = 0x19;
-pub const MESSAGE_TYPE_SET_GROUP_CHANNEL: u8 = 0x26;
-pub const MESSAGE_TYPE_MINING_SET_NEW_PREV_HASH: u8 = 0x20;
-pub const MESSAGE_TYPE_SET_TARGET: u8 = 0x21;
-pub const MESSAGE_TYPE_SUBMIT_SHARES_ERROR: u8 = 0x1d;
-pub const MESSAGE_TYPE_SUBMIT_SHARES_EXTENDED: u8 = 0x1b;
-pub const MESSAGE_TYPE_SUBMIT_SHARES_STANDARD: u8 = 0x1a;
-pub const MESSAGE_TYPE_SUBMIT_SHARES_SUCCESS: u8 = 0x1c;
-pub const MESSAGE_TYPE_UPDATE_CHANNEL: u8 = 0x16;
-pub const MESSAGE_TYPE_UPDATE_CHANNEL_ERROR: u8 = 0x17;
+
+/// Template Distribution Protocol message types.
+pub const MESSAGE_TYPE_COINBASE_OUTPUT_DATA_SIZE: u8 = 0x70;
+pub const MESSAGE_TYPE_NEW_TEMPLATE: u8 = 0x71;
+pub const MESSAGE_TYPE_SET_NEW_PREV_HASH: u8 = 0x72;
+pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA: u8 = 0x73;
+pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_SUCCESS: u8 = 0x74;
+pub const MESSAGE_TYPE_REQUEST_TRANSACTION_DATA_ERROR: u8 = 0x75;
+pub const MESSAGE_TYPE_SUBMIT_SOLUTION: u8 = 0x76;
+
+
+// WHAT'S THE PURPOSE OF THESE CHANNEL BITS???
 
 // COMMON MESSAGES CHANNEL BIT
 pub const CHANNEL_BIT_SETUP_CONNECTION: bool = false;