Skip to content

Commit

Permalink
update header after const_sv2 crate documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@GitGab19
GitGab19 committed Oct 4, 2024
1 parent 2cfce2e commit a3f7b26
Show file tree
Hide file tree
Showing 3 changed files with 122 additions and 85 deletions.
2 changes: 1 addition & 1 deletion protocols/v2/const-sv2/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
102 changes: 59 additions & 43 deletions protocols/v2/const-sv2/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,45 @@
//! 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 protocols.
//! 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.
//!
//! 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
//! 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.
//!
//! ### Discriminants for Stratum V2 (sub)protocols
//! Discriminants are unique identifiers used to distinguish between different Stratum V2 (sub)protocols.
//! Each protocol within the SV2 ecosystem has a specific discriminant value that indicates its type,
//! 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>
//! Discriminants are unique identifiers used to distinguish between different
//! Stratum V2 (sub)protocols. Each protocol within the SV2 ecosystem has a
//! specific discriminant value that indicates its type, 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 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
//! Message types in the SV2 protocol define the specific operations and data exchanges between participants.
//! Each type corresponds to a distinct action or information transfer, facilitating communication in various
//! contexts such as mining operations, job declarations, and template distribution. Properly identifying and
//! handling these message types is crucial for maintaining protocol compliance and ensuring seamless
//! interactions within the SV2 ecosystem. The message types are categorized into common types and those
//! specific to each subprotocol, providing clarity on their intended use and interaction patterns.
//! Message types in the SV2 protocol define the specific operations and data
//! exchanges between participants. Each type corresponds to a distinct action
//! or information transfer, facilitating communication in various contexts such
//! as mining operations, job declarations, and template distribution. Properly
//! identifying and handling these message types is crucial for maintaining
//! protocol compliance and ensuring seamless interactions within the SV2
//! ecosystem. The message types are categorized into common types and those
//! specific to each subprotocol, providing clarity on their intended use and
//! interaction patterns.
//!
//! ### Channel Bits
//! The `channel bits` indicate whether a message is associated with a specific channel.
//! If the most significant bit of the `extension_type` (referred to as `channel_msg`) is set,
//! the message is related to a channel and includes a `channel_id`. In this case,
//! the first 4 bytes of the payload represent the `channel_id` the message is destined for.
//! The `channel bits` indicate whether a message is associated with a specific
//! channel. If the most significant bit of the `extension_type` (referred to as
//! `channel_msg`) is set, the message is related to a channel and includes a
//! `channel_id`. In this case, the first 4 bytes of the payload represent the
//! `channel_id` the message is destined for.
#![cfg_attr(feature = "no_std", no_std)]

/// Identifier for the extension_type field in the SV2 frame, indicating no extensions.
/// Identifier for the extension_type field in the SV2 frame, indicating no
/// extensions.
pub const EXTENSION_TYPE_NO_EXTENSION: u16 = 0;

/// Size of the SV2 frame header in bytes.
Expand Down Expand Up @@ -62,48 +70,54 @@ pub const ENCRYPTED_SV2_FRAME_HEADER_SIZE: usize = SV2_FRAME_HEADER_SIZE + AEAD_
pub const NOISE_FRAME_HEADER_SIZE: usize = 2;

// Refactoring: declared in sv2-ffi, and imported in framing_sv2/src/header.rs
// header.rs is then imported into codec_sv2 just for this constant, and the const there is not even used
// 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;

// It's not used anywhere.
// Refactoring: deprecate it.
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.
/// 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;

// Refactoring: the alias could be created where it's imported, or we could just use one name everywhere
// Refactoring: the alias could be created where it's imported, or we could just
// use one name everywhere
pub const RESPONDER_EXPECTED_HANDSHAKE_MESSAGE_SIZE: usize = ELLSWIFT_ENCODING_SIZE;

// This is the same as AEAD_MAC_LEN.
// Refactoring: deprecate it.
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.
/// 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.
/// 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.
/// 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:
/// 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>
/// 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 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,
Expand Down Expand Up @@ -151,7 +165,8 @@ 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;

// Refactoring: we need to move this to 0x04 and shift SETGROUPCHANNEL to 0x25 (we are not specs compliant now)
// Refactoring: we need to move this to 0x04 and shift 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;

Expand All @@ -176,11 +191,12 @@ 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;

// The `channel bits` indicate whether a message is associated with a specific channel.
// If the most significant bit of the `extension_type` (referred to as `channel_msg`) is set,
// the message is related to a channel and includes a `channel_id`. In this case,
// the first 4 bytes of the payload represent the `channel_id` the message is destined for.
// For the Job Declaration and Template Distribution protocols, the `channel_msg` bit is always unset.
// The `channel bits` indicate whether a message is associated with a specific
// channel. If the most significant bit of the `extension_type` (referred to as
// `channel_msg`) is set, the message is related to a channel and includes a
// `channel_id`. In this case, the first 4 bytes of the payload represent the
// `channel_id` the message is destined for. For the Job Declaration and
// Template Distribution protocols, the `channel_msg` bit is always unset.

pub const CHANNEL_BIT_SETUP_CONNECTION: bool = false;
pub const CHANNEL_BIT_SETUP_CONNECTION_SUCCESS: bool = false;
Expand Down
103 changes: 62 additions & 41 deletions protocols/v2/sv2-ffi/sv2.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,59 @@
#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;
Expand All @@ -50,85 +73,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;

Expand Down

0 comments on commit a3f7b26

Please sign in to comment.