Expand description
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.
§Cross-Language Interoperability
To support foreign function interface (FFI) use cases, the module includes CError
and CVec
types that represent SV2 data and errors in a format suitable for cross-language compatibility.
§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 simplifiedIoError
representation. - Standard I/O errors (
std::io::Error
) are used whenno_std
is disabled.
§FFI Interoperability
Provides utilities for FFI (Foreign Function Interface) to enable data passing between Rust and other languages. Includes:
CVec
: Represents a byte vector for safe passing between C and Rust.CError
: A C-compatible error type.CVec2
: Manages collections ofCVec
objects across FFI boundaries.
Facilitates integration of SV2 functionality into cross-language projects.
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§
- CVec
- A struct to facilitate transferring a
Vec<u8>
across FFI boundaries. - CVec2
- A struct to manage a collection of
CVec
objects across FFI boundaries. - Seq0255
Seq0255
represents a sequence with a maximum length of 255 elements. This structure uses a generic typeT
and a lifetime parameter'a
.- Seq064K
Seq064K
represents a sequence with a maximum length of 65535 elements. This structure uses a generic typeT
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§
- CError
CError
is a foreign function interface (FFI)-compatible version of theError
enum to facilitate cross-language compatibility.- Encodable
Field - 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.- Size
Hint - The
SizeHint
trait provides a mechanism to return the encoded bytes size of a decodable type. - Sv2Data
Type 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§
- _c_
export_ cvec - Exported FFI functions for interoperability with C code for CVec
- _c_
export_ cvec2 - Exported FFI functions for interoperability with C code for CVec2
- _c_
export_ u24 - Exported FFI functions for interoperability with C code for u24
- cvec2_
push ⚠ - Adds a
CVec
to aCVec2
. - cvec_
from_ ⚠buffer - Creates a
CVec
from a buffer that was allocated in C. - free_
vec - Frees the underlying memory of a
CVec
. - free_
vec_ 2 - Frees the underlying memory of a
CVec2
and all its elements. - from_
bytes - Decodes an SV2-encoded byte slice into the specified data type.
- init_
cvec2 ⚠ - Initializes an empty
CVec2
. - 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. - U32As
Ref - 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.