Merge rust-bitcoin#4998: primitives: Implement decoding traits

39bf86b primitives: Implement decoders (Tobin C. Harding)
63af008 Use scriptPubkey instead of script public key (Tobin C. Harding)

Pull request description:

  Things that need careful attention please:
  
  - The state machine in `TransactionDecoder`
  - The `WitnessDecoder::empty` kludge


ACKs for top commit:
  apoelstra:
    ACK 39bf86b; successfully ran local tests


Tree-SHA512: e04c6eb9e4b675dd71f65607339d42c5610315a4b9b0d7a88d8191a86af4696277a0042a714bf0236d17374543f5544d813def927c0023a00b259452b7507fca

Author: apoelstra

Cargo-minimal.lock

@@ -142,6 +142,7 @@ dependencies = [
  "bitcoin-units",
  "bitcoin_hashes 0.16.0",
  "hex-conservative 0.3.0",
+ "hex_lit",
  "serde",
  "serde_json",
 ]

Cargo-recent.lock

@@ -141,6 +141,7 @@ dependencies = [
  "bitcoin-units",
  "bitcoin_hashes 0.16.0",
  "hex-conservative 0.3.0",
+ "hex_lit",
  "serde",
  "serde_json",
 ]

primitives/Cargo.toml

@@ -36,6 +36,7 @@ serde = { version = "1.0.195", default-features = false, features = ["derive", "
 [dev-dependencies]
 serde_json = "1.0.68"
 bincode = "1.3.1"
+hex_lit = "0.1.1"
 
 [package.metadata.docs.rs]
 all-features = true

primitives/src/block.rs

@@ -7,20 +7,28 @@
 //! module describes structures and functions needed to describe
 //! these blocks and the blockchain.
 
+use core::convert::Infallible;
 use core::fmt;
 #[cfg(feature = "alloc")]
 use core::marker::PhantomData;
 
 #[cfg(feature = "arbitrary")]
 use arbitrary::{Arbitrary, Unstructured};
-use encoding::{CompactSizeEncoder, Encodable, Encoder2, SliceEncoder};
+use encoding::Encodable;
+#[cfg(feature = "alloc")]
+use encoding::{CompactSizeEncoder, Decodable, Decoder, Decoder6, Encoder2, SliceEncoder};
 use hashes::{sha256d, HashEngine as _};
+use internals::write_err;
 
+#[cfg(feature = "alloc")]
+use crate::pow::{CompactTargetDecoder, CompactTargetDecoderError};
 #[cfg(feature = "alloc")]
 use crate::prelude::Vec;
+#[cfg(feature = "alloc")]
+use crate::transaction::{TxMerkleNodeDecoder, TxMerkleNodeDecoderError};
 use crate::{BlockTime, CompactTarget, TxMerkleNode};
 #[cfg(feature = "alloc")]
-use crate::{Transaction, WitnessMerkleNode};
+use crate::{BlockTimeDecoder, BlockTimeDecoderError, Transaction, WitnessMerkleNode};
 
 #[rustfmt::skip]                // Keep public re-exports separate.
 #[doc(inline)]
@@ -30,7 +38,9 @@ pub use units::block::{BlockHeight, BlockHeightInterval, BlockMtp, BlockMtpInter
 pub use units::block::TooBigForRelativeHeightError;
 
 #[doc(inline)]
-pub use crate::hash_types::{BlockHash, BlockHashEncoder, WitnessCommitment};
+pub use crate::hash_types::{
+    BlockHash, BlockHashDecoder, BlockHashDecoderError, BlockHashEncoder, WitnessCommitment,
+};
 
 /// Marker for whether or not a block has been validated.
 ///
@@ -295,6 +305,139 @@ impl Encodable for Header {
     }
 }
 
+/// The decoder for the [`Header`] type.
+#[cfg(feature = "alloc")]
+pub struct HeaderDecoder(
+    Decoder6<
+        VersionDecoder,
+        BlockHashDecoder,
+        TxMerkleNodeDecoder,
+        BlockTimeDecoder,
+        CompactTargetDecoder,
+        encoding::ArrayDecoder<4>, // Nonce
+        HeaderDecoderError,
+    >,
+);
+
+#[cfg(feature = "alloc")]
+impl Decoder for HeaderDecoder {
+    type Output = Header;
+    type Error = HeaderDecoderError;
+
+    #[inline]
+    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
+        self.0.push_bytes(bytes)
+    }
+
+    #[inline]
+    fn end(self) -> Result<Self::Output, Self::Error> {
+        let (version, prev_blockhash, merkle_root, time, bits, nonce) = self.0.end()?;
+        let nonce = u32::from_le_bytes(nonce);
+        Ok(Header { version, prev_blockhash, merkle_root, time, bits, nonce })
+    }
+
+    #[inline]
+    fn read_limit(&self) -> usize { self.0.read_limit() }
+}
+
+#[cfg(feature = "alloc")]
+impl Decodable for Header {
+    type Decoder = HeaderDecoder;
+    fn decoder() -> Self::Decoder {
+        HeaderDecoder(Decoder6::new(
+            VersionDecoder::new(),
+            BlockHashDecoder::new(),
+            TxMerkleNodeDecoder::new(),
+            BlockTimeDecoder::new(),
+            CompactTargetDecoder::new(),
+            encoding::ArrayDecoder::new(),
+        ))
+    }
+}
+
+/// An error consensus decoding a `Header`.
+#[cfg(feature = "alloc")]
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum HeaderDecoderError {
+    /// Error while decoding the `version`.
+    Version(VersionDecoderError),
+    /// Error while decoding the `prev_blockhash`.
+    PrevBlockhash(BlockHashDecoderError),
+    /// Error while decoding the `merkle_root`.
+    MerkleRoot(TxMerkleNodeDecoderError),
+    /// Error while decoding the `time`.
+    Time(BlockTimeDecoderError),
+    /// Error while decoding the `bits`.
+    Bits(CompactTargetDecoderError),
+    /// Error while decoding the `nonce`.
+    Nonce(encoding::UnexpectedEofError),
+}
+
+#[cfg(feature = "alloc")]
+impl From<Infallible> for HeaderDecoderError {
+    fn from(never: Infallible) -> Self { match never {} }
+}
+
+#[cfg(feature = "alloc")]
+impl From<VersionDecoderError> for HeaderDecoderError {
+    fn from(e: VersionDecoderError) -> Self { Self::Version(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl From<BlockHashDecoderError> for HeaderDecoderError {
+    fn from(e: BlockHashDecoderError) -> Self { Self::PrevBlockhash(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl From<TxMerkleNodeDecoderError> for HeaderDecoderError {
+    fn from(e: TxMerkleNodeDecoderError) -> Self { Self::MerkleRoot(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl From<BlockTimeDecoderError> for HeaderDecoderError {
+    fn from(e: BlockTimeDecoderError) -> Self { Self::Time(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl From<CompactTargetDecoderError> for HeaderDecoderError {
+    fn from(e: CompactTargetDecoderError) -> Self { Self::Bits(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl From<encoding::UnexpectedEofError> for HeaderDecoderError {
+    fn from(e: encoding::UnexpectedEofError) -> Self { Self::Nonce(e) }
+}
+
+#[cfg(feature = "alloc")]
+impl fmt::Display for HeaderDecoderError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match *self {
+            Self::Version(ref e) => write_err!(f, "header decoder error"; e),
+            Self::PrevBlockhash(ref e) => write_err!(f, "header decoder error"; e),
+            Self::MerkleRoot(ref e) => write_err!(f, "header decoder error"; e),
+            Self::Time(ref e) => write_err!(f, "header decoder error"; e),
+            Self::Bits(ref e) => write_err!(f, "header decoder error"; e),
+            Self::Nonce(ref e) => write_err!(f, "header decoder error"; e),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+#[cfg(feature = "alloc")]
+impl std::error::Error for HeaderDecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match *self {
+            Self::Version(ref e) => Some(e),
+            Self::PrevBlockhash(ref e) => Some(e),
+            Self::MerkleRoot(ref e) => Some(e),
+            Self::Time(ref e) => Some(e),
+            Self::Bits(ref e) => Some(e),
+            Self::Nonce(ref e) => Some(e),
+        }
+    }
+}
+
 impl From<Header> for BlockHash {
     #[inline]
     fn from(header: Header) -> BlockHash { header.block_hash() }
@@ -391,6 +534,65 @@ impl Encodable for Version {
     }
 }
 
+/// The decoder for the [`Version`] type.
+pub struct VersionDecoder(encoding::ArrayDecoder<4>);
+
+impl VersionDecoder {
+    /// Constructs a new [`Version`] decoder.
+    pub fn new() -> Self { Self(encoding::ArrayDecoder::new()) }
+}
+
+impl Default for VersionDecoder {
+    fn default() -> Self { Self::new() }
+}
+
+impl encoding::Decoder for VersionDecoder {
+    type Output = Version;
+    type Error = VersionDecoderError;
+
+    #[inline]
+    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
+        Ok(self.0.push_bytes(bytes)?)
+    }
+
+    #[inline]
+    fn end(self) -> Result<Self::Output, Self::Error> {
+        let n = i32::from_le_bytes(self.0.end()?);
+        Ok(Version::from_consensus(n))
+    }
+
+    #[inline]
+    fn read_limit(&self) -> usize { self.0.read_limit() }
+}
+
+impl encoding::Decodable for Version {
+    type Decoder = VersionDecoder;
+    fn decoder() -> Self::Decoder { VersionDecoder(encoding::ArrayDecoder::<4>::new()) }
+}
+
+/// An error consensus decoding an `Version`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VersionDecoderError(encoding::UnexpectedEofError);
+
+impl From<Infallible> for VersionDecoderError {
+    fn from(never: Infallible) -> Self { match never {} }
+}
+
+impl From<encoding::UnexpectedEofError> for VersionDecoderError {
+    fn from(e: encoding::UnexpectedEofError) -> Self { Self(e) }
+}
+
+impl fmt::Display for VersionDecoderError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write_err!(f, "version decoder error"; self.0)
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for VersionDecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
+}
+
 #[cfg(feature = "arbitrary")]
 #[cfg(feature = "alloc")]
 impl<'a> Arbitrary<'a> for Block {

primitives/src/hash_types/block_hash.rs

@@ -2,7 +2,7 @@
 
 //! The `BlockHash` type.
 
-#[cfg(not(feature = "hex"))]
+use core::convert::Infallible;
 use core::fmt;
 #[cfg(feature = "hex")]
 use core::str;
@@ -13,6 +13,7 @@ use encoding::Encodable;
 use hashes::sha256d;
 #[cfg(feature = "hex")]
 use hex::FromHex as _;
+use internals::write_err;
 
 /// A bitcoin block hash.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -41,3 +42,62 @@ impl Encodable for BlockHash {
         BlockHashEncoder(encoding::ArrayEncoder::without_length_prefix(self.to_byte_array()))
     }
 }
+
+/// The decoder for the [`BlockHash`] type.
+pub struct BlockHashDecoder(encoding::ArrayDecoder<32>);
+
+impl BlockHashDecoder {
+    /// Constructs a new [`BlockHash`] decoder.
+    pub fn new() -> Self { Self(encoding::ArrayDecoder::new()) }
+}
+
+impl Default for BlockHashDecoder {
+    fn default() -> Self { Self::new() }
+}
+
+impl encoding::Decoder for BlockHashDecoder {
+    type Output = BlockHash;
+    type Error = BlockHashDecoderError;
+
+    #[inline]
+    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
+        Ok(self.0.push_bytes(bytes)?)
+    }
+
+    #[inline]
+    fn end(self) -> Result<Self::Output, Self::Error> {
+        let a = self.0.end()?;
+        Ok(BlockHash::from_byte_array(a))
+    }
+
+    #[inline]
+    fn read_limit(&self) -> usize { self.0.read_limit() }
+}
+
+impl encoding::Decodable for BlockHash {
+    type Decoder = BlockHashDecoder;
+    fn decoder() -> Self::Decoder { BlockHashDecoder(encoding::ArrayDecoder::<32>::new()) }
+}
+
+/// An error consensus decoding an `BlockHash`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BlockHashDecoderError(encoding::UnexpectedEofError);
+
+impl From<Infallible> for BlockHashDecoderError {
+    fn from(never: Infallible) -> Self { match never {} }
+}
+
+impl From<encoding::UnexpectedEofError> for BlockHashDecoderError {
+    fn from(e: encoding::UnexpectedEofError) -> Self { Self(e) }
+}
+
+impl fmt::Display for BlockHashDecoderError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write_err!(f, "sequence decoder error"; self.0)
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for BlockHashDecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
+}

primitives/src/hash_types/mod.rs

@@ -19,10 +19,10 @@ mod wtxid;
 #[rustfmt::skip]                // Keep public re-exports separate.
 #[doc(inline)]
 pub use self::{
-    block_hash::{BlockHash, BlockHashEncoder},
+    block_hash::{BlockHash, BlockHashDecoder, BlockHashDecoderError, BlockHashEncoder},
     ntxid::Ntxid,
-    transaction_merkle_node::{TxMerkleNode, TxMerkleNodeEncoder},
-    txid::Txid,
+    transaction_merkle_node::{TxMerkleNode, TxMerkleNodeEncoder, TxMerkleNodeDecoder, TxMerkleNodeDecoderError},
+    txid::{Txid},
     wtxid::Wtxid,
     witness_commitment::WitnessCommitment,
     witness_merkle_node::WitnessMerkleNode,