Crate bitcoin_consensus_encoding

Expand description

§Rust Bitcoin Consensus Encoding

Traits and utilities for encoding and decoding Bitcoin data types in a consensus-consistent way, using a sans-I/O architecture.

Rather than reading from or writing to std::io::Read/std::io::Write traits directly, the codec types work with byte slices. This keeps codec logic I/O-agnostic, so the same implementation works in no_std environments, sync I/O, async I/O, and hash engines without duplicating logic or surfacing I/O errors in non-I/O contexts (e.g. when hashing an encoding).

Consensus encoding is the canonical byte representation of Bitcoin data types used across the peer-to-peer network and transaction serialization. This crate only supports deterministic encoding and will never support types like floats whose encoding is non-deterministic or platform-dependent.

§Encoding

Types implement Encode to produce an Encoder, which yields encoded bytes in chunks via Encoder::current_chunk and Encoder::advance. The caller drives the process by pulling chunks until advance returns EncoderStatus::Finished.

§Decoding

Types implement Decode to produce a Decoder, which consumes bytes via Decoder::push_bytes until it signals completion by returning Ok(DecoderStatus::Ready). The caller then calls Decoder::end to obtain the decoded value.

Unlike encoding, decoding is fallible. Both push_bytes and end return Result. I/O errors are handled by the caller, keeping the codec logic I/O-agnostic.

§Drivers

This crate provides free functions which drive codecs for common I/O interfaces. On the decoding side we provide:

decode_from_read: Decode from a stdlib buffered reader.
decode_from_read_unbuffered: Decode from a stdlib unbuffered reader (4k buffer on stack).
decode_from_read_unbuffered_with: As above with custom sized stack-allocated buffer.
decode_from_slice: Decode from a byte slice (errors if slice is not completely consumed).
decode_from_slice_unbounded: Slice can contain additional data after decoding completes.
decode_from_hex: Decode from a hex string without heap allocations.

Each function above takes a type parameter T: Decode to select the output type and its associated decoder. The following variants instead accept a Decoder type directly, instantiated with Default, and can be used when the output type does not implement Decode:

decode_from_read_with_decoder: Counterpart to decode_from_read.
decode_from_slice_with_decoder: Counterpart to decode_from_slice.
decode_from_slice_unbounded_with_decoder: Counterpart to decode_from_slice_unbounded.
decode_from_hex_with_decoder: Counterpart to decode_from_hex.

And on the encoding side we provide:

encode_to_writer: Encode to a stdlib writer.
drain_to_writer: Drain an encoder to a stdlib writer.
encode_to_vec: Encode to the heap.
drain_to_vec: Drain an encoder to the heap.
encode_to_hex: Encode to a hex string.
drain_to_hex: Drain an encoder to a hex string.

§Feature Flags

std - Enables std lib I/O driver functions and std::error::Error impls (implies alloc).
alloc - Enables encode_to_vec, Vec-based decoders, and allocation-based helpers.
hex - Enables decode_from_hex, decode_from_hex_with_decoder, encode_to_hex and drain_to_hex. Encoding also requires alloc.

Re-exports§

pub extern crate hex;
pub extern crate serde;

Re-exports§

pub use self::error::FromHexError;
pub use self::error::LengthPrefixExceedsMaxError;
pub use self::error::ReadError;
pub use self::error::ByteVecDecoderError;
pub use self::error::VecDecoderError;
pub use self::error::CompactSizeDecoderError;
pub use self::error::DecodeError;
pub use self::error::Decoder2Error;
pub use self::error::Decoder3Error;
pub use self::error::Decoder4Error;
pub use self::error::Decoder6Error;
pub use self::error::UnconsumedError;
pub use self::error::UnexpectedEofError;

Modules§

error: Error types for the whole crate.
serde_as_consensus: serde serialize and deserialize types using consensus encoding.

Macros§

encoder_newtype: Implements a newtype around an encoder.
encoder_newtype_exact: Implements a newtype around an exact-size encoder.

Structs§

ArrayDecoder: A decoder that expects exactly N bytes and returns them as an array.
ArrayEncoder: An encoder for a single array.
ArrayRefEncoder: An encoder for a reference to an array.
ByteVecDecoder: A decoder that decodes a byte vector.
BytesEncoder: An encoder for a single byte slice.
CompactSizeDecoder: Decodes a compact size encoded integer as a length prefix.
CompactSizeEncoder: Encoder for a compact size encoded integer.
CompactSizeU64Decoder: Decodes a compact size encoded integer as a raw u64.
Decoder2: A decoder which wraps two inner decoders and returns the output of both.
Decoder3: A decoder which decodes three objects, one after the other.
Decoder4: A decoder which decodes four objects, one after the other.
Decoder6: A decoder which decodes six objects, one after the other.
Encoder2: An encoder which encodes two objects, one after the other.
Encoder3: An encoder which encodes three objects, one after the other.
Encoder4: An encoder which encodes four objects, one after the other.
Encoder6: An encoder which encodes six objects, one after the other.
EncoderByteIter: Yields bytes from any Encoder instance.
PrefixedBytesEncoder: An encoder for a single byte slice, including a compact size length prefix.
PrefixedSliceEncoder: An encoder for a list of encodable types, including a length prefix.
SliceEncoder: An encoder for a list of encodable types.
VecDecoder: A decoder that decodes a vector of Ts.

Enums§

DecoderStatus: Indicates whether a decoder needs more data or is ready to finalize.
EncoderStatus: Indicates whether the encoder still has bytes available or it is finished.

Traits§

Decode: A Bitcoin object which can be consensus-decoded using a push decoder.
Decoder: A push decoder for a consensus-decodable object.
Encode: A Bitcoin object which can be consensus-encoded.
Encoder: An encoder for a consensus-encodable object.
ExactSizeEncoder: An encoder with a known size.

Functions§

check_decode: Checks that the given bytes decode to the expected value, panicking if they don’t.
check_decoder: Checks that the given decoder produces the expected value, panicking if it doesn’t.
check_encode: Checks that the given value encodes to expected, panicking if it doesn’t.
check_encoder: Checks that the given encoder yields expected, panicking if it doesn’t.
decode_from_hex: Decodes an object from a hex string without heap allocations.
decode_from_hex_with_decoder: Decodes an object from a hex string without heap allocations using a Decoder type.
decode_from_read: Decodes an object from a buffered reader.
decode_from_read_unbuffered: Decodes an object from an unbuffered reader using a fixed-size buffer.
decode_from_read_unbuffered_with: Decodes an object from an unbuffered reader using a custom-sized buffer.
decode_from_read_with_decoder: Decodes an object from a buffered reader using a Decoder type.
decode_from_slice: Decodes an object from a byte slice.
decode_from_slice_unbounded: Decodes an object from an unbounded byte slice.
decode_from_slice_unbounded_with_decoder: Decodes an object from an unbounded byte slice using a Decoder type.
decode_from_slice_with_decoder: Decodes an object from a byte slice using a Decoder type.
drain_to_hex: Drains the output of an Encoder into a hex string.
drain_to_vec: Drains the output of an Encoder into a vector.
drain_to_writer: Drains the output of an Encoder to a standard I/O writer.
encode_to_hex: Encodes an object into a hex string.
encode_to_vec: Encodes an object into a vector.
encode_to_writer: Encodes an object to a standard I/O writer.