Crate binary_codec_sv2 

Defines types, encodings, and conversions between custom datatype and standard Rust type, providing abstractions for encoding, decoding, and error handling of SV2 data types.

Overview

Enables conversion between various Rust types and SV2-specific data formats for efficient network communication. Provides utilities to encode and decode data types according to the SV2 specifications.

Type Mappings

The following table illustrates how standard Rust types map to their SV2 counterparts:

bool     <-> BOOL
u8       <-> U8
u16      <-> U16
U24      <-> U24
u32      <-> U32
f32      <-> F32     // Not in the spec, but used
u64      <-> U64     
U256     <-> U256
Str0255  <-> STRO_255
Signature<-> SIGNATURE
B032     <-> B0_32   
B0255    <-> B0_255
B064K    <-> B0_64K
B016M    <-> B0_16M
[u8]     <-> BYTES
Pubkey   <-> PUBKEY
Seq0255  <-> SEQ0_255[T]
Seq064K  <-> SEQ0_64K[T]

Encoding & Decoding

Enables conversion between various Rust types and SV2-specific data formats for efficient network communication. Provides utilities to encode and decode data types according to the SV2 specifications.

• to_bytes: Encodes an SV2 data type into a byte vector.
• to_writer: Encodes an SV2 data type into a byte slice.
• from_bytes: Decodes an SV2-encoded byte slice into the specified data type.

Error Handling

Defines an Error enum for handling failure conditions during encoding, decoding, and data manipulation. Common errors include:

• Out-of-bounds accesses
• Size mismatches during encoding/decoding
• Invalid data representations, such as non-boolean values interpreted as booleans.

Build Options

Supports optional features like no_std for environments without standard library support. Error types are conditionally compiled to work with or without std.

Conditional Compilation

• With the no_std feature enabled, I/O-related errors use a simplified IoError representation.
• Standard I/O errors (std::io::Error) are used when no_std is disabled.

Modules

decodable

Provides an interface and implementation details for decoding complex data structures from raw bytes or I/O streams. Handles deserialization of nested and primitive data structures through traits, enums, and helper functions for managing the decoding process.

encodable

Provides an encoding framework for serializing various data types into bytes.

Structs

Seq0255

Seq0255 represents a sequence with a maximum length of 255 elements. This structure uses a generic type T and a lifetime parameter 'a.

Seq064K

Seq064K represents a sequence with a maximum length of 65535 elements. This structure uses a generic type T and a lifetime parameter 'a.

Sv2Option

The lifetime ’a is defined.

U24

Represents a 24-bit unsigned integer (U24), supporting SV2 serialization and deserialization. Only first 3 bytes of a u32 is considered to get the SV2 value, and rest are ignored (in little endian).

Enums

EncodableField

The EncodableField enum defines encodable fields, which may be a primitive or struct.

Error

Error types used within the protocol library to indicate various failure conditions.

Traits

Decodable

Custom deserialization of types from binary data.

Encodable

The Encodable trait defines the interface for encoding a type into bytes.

Fixed

Fixed is a trait is defining a single element representing a size of a constant.

GetMarker

Trait for retrieving the FieldMarker associated with a type.

GetSize

GetSize is a trait defining a single function that calculates the total size of an encodable type.

SizeHint

The SizeHint trait provides a mechanism to return the encoded bytes size of a decodable type.

Sv2DataType

Sv2DataType is a trait that defines methods for encoding and decoding Stratum V2 data. It is used for serializing and deserializing both fixed-size and dynamically-sized types.

Functions

from_bytes

Decodes an SV2-encoded byte slice into the specified data type.

to_bytes

Converts the provided SV2 data type to a byte vector based on the SV2 encoding format.

to_writer

Encodes the SV2 data type to the provided byte slice.

Type Aliases

B016M

Type alias for a variable-sized byte array with a maximum size of ~16 MB, represented using the Inner type with a 3-byte header.

B0255

Type alias for a variable-sized byte array with a maximum size of 255 bytes, represented using the Inner type with a 1-byte header.

B032

Type alias for a variable-sized byte array with a maximum size of 32 bytes, represented using the Inner type with a 1-byte header.

B064K

Type alias for a variable-sized byte array with a maximum size of 64 KB, represented using the Inner type with a 2-byte header.

PubKey

Type alias for a 32-byte public key represented using the Inner type with fixed-size configuration.

Signature

Type alias for a 64-byte cryptographic signature represented using the Inner type with fixed-size configuration.

Str0255

Type alias for a variable-sized string with a maximum size of 255 bytes, represented using the Inner type with a 1-byte header.

U32AsRef

Type alias for a 4-byte slice or owned data represented using the Inner type with fixed-size configuration.

U256

Type alias for a 32-byte slice or owned data (commonly used for cryptographic hashes or IDs) represented using the Inner type with fixed-size configuration.