bitcoin-consensus-encoding 1.2.0

Consensus encoding and decoding
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

// SPDX-License-Identifier: CC0-1.0

//! # 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`.

#![no_std]
// Coding conventions.
#![warn(missing_docs)]
#![warn(deprecated_in_future)]
#![doc(test(attr(warn(unused))))]

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;

#[cfg(feature = "hex")]
pub extern crate hex;
#[cfg(feature = "serde")]
pub extern crate serde;

mod compact_size;
mod decode;
mod encode;

pub mod error;
#[cfg(feature = "serde")]
pub mod serde_as_consensus;

#[doc(inline)]
pub use self::compact_size::{CompactSizeDecoder, CompactSizeEncoder, CompactSizeU64Decoder};
#[doc(inline)]
pub use self::decode::decoders::{ArrayDecoder, Decoder2, Decoder3, Decoder4, Decoder6};
#[cfg(feature = "alloc")]
#[doc(inline)]
pub use self::decode::decoders::{ByteVecDecoder, ExactVecDecoderWith, VecDecoder, VecDecoderWith};
#[doc(inline)]
pub use self::decode::{
    check_decode, check_decoder, decode_from_slice, decode_from_slice_unbounded,
    decode_from_slice_unbounded_with_decoder, decode_from_slice_with_decoder, Decode, Decoder,
    DecoderStatus,
};
#[cfg(feature = "hex")]
#[doc(inline)]
pub use self::decode::{decode_from_hex, decode_from_hex_with_decoder};
#[cfg(feature = "std")]
#[doc(inline)]
pub use self::decode::{
    decode_from_read, decode_from_read_unbuffered, decode_from_read_unbuffered_with,
    decode_from_read_with_decoder,
};
#[doc(inline)]
pub use self::encode::encoders::{
    ArrayEncoder, ArrayRefEncoder, BytesEncoder, Encoder2, Encoder3, Encoder4, Encoder6,
    PrefixedBytesEncoder, PrefixedSliceEncoder, SliceEncoder,
};
#[doc(inline)]
pub use self::encode::iter::IterEncoder;
#[doc(inline)]
pub use self::encode::{
    check_encode, check_encoder, Encode, Encoder, EncoderByteIter, EncoderStatus, ExactSizeEncoder,
};
#[cfg(feature = "alloc")]
#[cfg(feature = "hex")]
#[doc(inline)]
pub use self::encode::{drain_to_hex, encode_to_hex};
#[cfg(feature = "alloc")]
#[doc(inline)]
pub use self::encode::{drain_to_vec, encode_to_vec};
#[cfg(feature = "std")]
#[doc(inline)]
pub use self::encode::{drain_to_writer, encode_to_writer};
#[cfg(feature = "hex")]
#[doc(no_inline)]
pub use self::error::FromHexError;
#[cfg(feature = "alloc")]
#[doc(no_inline)]
pub use self::error::LengthPrefixExceedsMaxError;
#[cfg(feature = "std")]
#[doc(no_inline)]
pub use self::error::ReadError;
#[cfg(feature = "alloc")]
#[doc(no_inline)]
pub use self::error::{ByteVecDecoderError, VecDecoderError};
#[doc(no_inline)]
pub use self::error::{
    CompactSizeDecoderError, DecodeError, Decoder2Error, Decoder3Error, Decoder4Error,
    Decoder6Error, UnconsumedError, UnexpectedEofError,
};