Crate bitcoin_consensus_encoding

Expand description

§Rust Bitcoin Consensus Encoding

Traits and utilities for encoding and decoding Bitcoin data types 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). This crate only supports deterministic encoding and will never support types like floats whose encoding is non-deterministic or platform-dependent.

Consensus encoding is the canonical byte representation of Bitcoin data types used across the peer-to-peer network and transaction serialization. Bitcoin types which support consensus encoding implement the Encode and Decode traits.

§Encoding

Consensus encodable 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

Consensus encodable 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 functions which take a consensus encodable type parameter T: Decode to select the output type’s associated decoder.

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.

The following variants instead accept an agnostic 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 similar functions for consensus encodable types.

encode_to_writer: Encode to a stdlib writer.
encode_to_vec: Encode to the heap.
encode_to_hex: Encode to a hex string.

As well as variants for agnostic Encoder types.

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

§Collections

This crate provides types for encoding and decoding sequences of items. On the decoding side, VecDecoder decodes a length-prefixed sequence of consensus encodable types into a Vec. VecDecoderWith and ExactVecDecoderWith are the underlying implementations, bound directly on Decoder allowing them to be used with decoder types that do not have a corresponding Decode implementation.

On the encoding side, SliceEncoder and PrefixedSliceEncoder encode slices of consensus encodable types without and with a compact-size length prefix respectively.

The lower-level IterEncoder drives any iterator whose items implement Encoder.

§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.
ExactVecDecoderWith: A decoder for a vector of exactly count items, where the count is known at construction.
IterEncoder: An encoder that drives a sequence of encoders yielded by an iterator.
PrefixedBytesEncoder: An encoder for a single byte slice, including a compact size length prefix.
PrefixedSliceEncoder: An encoder for a list of consensus encodable types, including a length prefix.
SliceEncoder: An encoder for a list of consensus encodable types.
VecDecoder: A decoder for a vector of consensus decodable types.
VecDecoderWith: A decoder for a compact sized length-prefixed vector of items, generic over the item decoder type.

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 that consumes bytes in chunks.
Encode: A Bitcoin object which can be consensus encoded.
Encoder: A pull based encoder that yields bytes in chunks.
ExactSizeEncoder: An encoder with a known size.

Functions§

check_decode: Checks that the given bytes decode to the expected consensus decodable 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 a consensus encodable 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 a consensus decodable type 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 a consensus decodable type from a buffered reader.
decode_from_read_unbuffered: Decodes a consensus decodable type from an unbuffered reader using a fixed-size buffer.
decode_from_read_unbuffered_with: Decodes a consensus decodable type 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 a consensus decodable type from a byte slice.
decode_from_slice_unbounded: Decodes a consensus decodable type 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 a consensus encodable type into a hex string.
encode_to_vec: Encodes a consensus encodable type into a vector.
encode_to_writer: Encodes a consensus encodable type to a standard I/O writer.