framing_sv2

framing_sv2 provides utilities for framing messages sent between Sv2 roles, handling both Sv2 message and Noise handshake frames.

The Sv2 protocol is binary, with fixed message framing. Each message begins with the extension type, message type, and message length (six bytes in total), followed by a variable length message. The message framing is outlined below (according to Sv2 specs ):

Some bits of the extension_type field can also be repurposed for signaling on how the frame should be handled across channels.

The least significant bit of extension_type (i.e.bit 15, 0-indexed, aka channel_msg) indicates a message which is specific to a channel, whereas if the most significant bit is unset, the message is to be interpreted by the immediate receiving device.

Note that the channel_msg bit is ignored in the extension lookup, i.e.an extension_type of 0x8ABC is for the same "extension" as 0x0ABC.

If the channel_msg bit is set, the first four bytes of the payload field is a U32 representing the channel_id this message is destined for (these bytes are repeated in the message framing descriptions below).

Note that for the Job Declaration and Template Distribution Protocols the channel_msg bit is always unset.

Main Components

• Header: Defines the 6-byte Sv2 message header with information about the message payload, including its extension type, if it is associated with a specific mining channel, the type of message (e.g. SetupConnection, NewMiningJob, etc.) and the payload length.
• Sv2 Framing: Use for serializing Sv2 messages.
• Noise Handshake Framing: Use for serializing Noise protocol handshake messages.

Usage

To include this crate in your project, run:

cargo add framing_sv2

This crate can be built with the following feature flags:

• with_buffer_pool: Enables buffer pooling for more efficient memory management.
• with_serde: builds binary_sv2 and buffer_sv2 crates with serde-based encoding and decoding. Note that this feature flag is only used for the Message Generator, and deprecated for any other kind of usage. It will likely be fully deprecated in the future.

Examples

This crate provides an example demonstrating how to serialize and deserialize Sv2 message frames:

1. Sv2 Frame: Constructs, serializes, and deserialize a regular Sv2 message frame (Sv2Frame).