Merge rust-bitcoin#5008: Units decoders with phantoms

43077e8 consensus_encoding: API update (Nick Johnson)
9f721bb consensus_encoding: fix up error message (Nick Johnson)
88c6c3b units: Implement decoding traits (Tobin C. Harding)
e36cc96 consensus_encoding: rename UnexptectedEof (Nick Johnson)

Pull request description:

  tcharding 's decoder work rebased on top of the phantom errors (rust-bitcoin#5001) if we go that route. Plus some encoding feature flag gates.


ACKs for top commit:
  apoelstra:
    ACK 43077e8; successfully ran local tests
  tcharding:
    ACK 43077e8


Tree-SHA512: 95ab4798d87282495331877792c9dc5b24d8bf61dfcbeaf840ab7dbcaa79793057f31b3d3bf5d09b64af357a55b26af234f0e0ca9fb975bc196fb338c13753a9

Author: apoelstra

api/units/all-features.txt

@@ -4,22 +4,6 @@
 
 use super::Decoder;
 
-/// Not enough bytes given to decoder.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct UnexpectedEof {
-    /// Number of bytes missing to complete decoder.
-    missing: usize,
-}
-
-impl core::fmt::Display for UnexpectedEof {
-    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        write!(f, "not enough bytes for decoder, {} more bytes required", self.missing)
-    }
-}
-
-#[cfg(feature = "std")]
-impl std::error::Error for UnexpectedEof {}
-
 /// A decoder that expects exactly N bytes and returns them as an array.
 pub struct ArrayDecoder<const N: usize> {
     buffer: [u8; N],
@@ -37,7 +21,7 @@ impl<const N: usize> Default for ArrayDecoder<N> {
 
 impl<const N: usize> Decoder for ArrayDecoder<N> {
     type Output = [u8; N];
-    type Error = UnexpectedEof;
+    type Error = UnexpectedEofError;
 
     fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
         let remaining_space = N - self.bytes_written;
@@ -59,7 +43,7 @@ impl<const N: usize> Decoder for ArrayDecoder<N> {
         if self.bytes_written == N {
             Ok(self.buffer)
         } else {
-            Err(UnexpectedEof { missing: N - self.bytes_written })
+            Err(UnexpectedEofError { missing: N - self.bytes_written })
         }
     }
 }
@@ -355,3 +339,19 @@ where
         Ok((first, second, third, fourth, fifth, sixth))
     }
 }
+
+/// Not enough bytes given to decoder.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UnexpectedEofError {
+    /// Number of bytes missing to complete decoder.
+    missing: usize,
+}
+
+impl core::fmt::Display for UnexpectedEofError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "not enough bytes for decoder, {} more bytes required", self.missing)
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for UnexpectedEofError {}

consensus_encoding/src/decode/decoders.rs

@@ -23,7 +23,7 @@ mod decode;
 mod encode;
 
 pub use self::decode::decoders::{
-    ArrayDecoder, Decoder2, Decoder3, Decoder4, Decoder6, UnexpectedEof,
+    ArrayDecoder, Decoder2, Decoder3, Decoder4, Decoder6, UnexpectedEofError,
 };
 pub use self::decode::{Decodable, Decoder};
 #[cfg(feature = "alloc")]

consensus_encoding/src/lib.rs

@@ -4,7 +4,7 @@
 
 use consensus_encoding::{
     ArrayDecoder, ArrayEncoder, Decodable, Decoder, Decoder2, Decoder6, Encodable, Encoder,
-    Encoder2, Encoder6, UnexpectedEof,
+    Encoder2, Encoder6, UnexpectedEofError,
 };
 
 const EMPTY: &[u8] = &[];
@@ -30,17 +30,17 @@ impl Encodable for CompositeData {
 /// A unified error type for [`CompositeDataDecoder`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 enum CompositeError {
-    Eof(UnexpectedEof),
+    Eof(UnexpectedEofError),
 }
 
-impl From<UnexpectedEof> for CompositeError {
-    fn from(eof: UnexpectedEof) -> Self { CompositeError::Eof(eof) }
+impl From<UnexpectedEofError> for CompositeError {
+    fn from(eof: UnexpectedEofError) -> Self { CompositeError::Eof(eof) }
 }
 
 impl core::fmt::Display for CompositeError {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            CompositeError::Eof(eof) => write!(f, "Error in first array: {}", eof),
+            CompositeError::Eof(eof) => write!(f, "Composite error: {}", eof),
         }
     }
 }
@@ -115,7 +115,7 @@ fn composition_nested() {
     }
     assert_eq!(encoded_bytes, data);
 
-    let mut decoder6: Decoder6<_, _, _, _, _, _, UnexpectedEof> = Decoder6::new(
+    let mut decoder6: Decoder6<_, _, _, _, _, _, UnexpectedEofError> = Decoder6::new(
         ArrayDecoder::<1>::new(),
         ArrayDecoder::<1>::new(),
         ArrayDecoder::<1>::new(),
@@ -139,7 +139,7 @@ fn composition_nested() {
 #[test]
 fn composition_extra_bytes() {
     // Test that Decoder2 consumes exactly what it needs and leaves extra bytes unconsumed.
-    let mut decoder2: Decoder2<_, _, UnexpectedEof> =
+    let mut decoder2: Decoder2<_, _, UnexpectedEofError> =
         Decoder2::new(ArrayDecoder::<2>::new(), ArrayDecoder::<3>::new());
     let mut bytes = &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08][..];
     let original_len = bytes.len();
@@ -167,22 +167,22 @@ fn composition_error_unification() {
     #[derive(Debug, Clone, PartialEq, Eq)]
     enum NestedError {
         BadChecksum,
-        UnexpectedEof(UnexpectedEof),
+        UnexpectedEof(UnexpectedEofError),
     }
 
-    impl From<UnexpectedEof> for NestedError {
-        fn from(eof: UnexpectedEof) -> Self { NestedError::UnexpectedEof(eof) }
+    impl From<UnexpectedEofError> for NestedError {
+        fn from(eof: UnexpectedEofError) -> Self { NestedError::UnexpectedEof(eof) }
     }
 
     /// Error for top level encoder.
     #[derive(Debug, Clone, PartialEq, Eq)]
     enum TopLevelError {
-        UnexpectedEof(UnexpectedEof),
+        UnexpectedEof(UnexpectedEofError),
         Validation(NestedError),
     }
 
-    impl From<UnexpectedEof> for TopLevelError {
-        fn from(eof: UnexpectedEof) -> Self { TopLevelError::UnexpectedEof(eof) }
+    impl From<UnexpectedEofError> for TopLevelError {
+        fn from(eof: UnexpectedEofError) -> Self { TopLevelError::UnexpectedEof(eof) }
     }
 
     impl From<NestedError> for TopLevelError {

consensus_encoding/tests/composition.rs

@@ -2,7 +2,7 @@
 
 //! Integration tests for decode module.
 
-use consensus_encoding::{ArrayDecoder, Decoder, UnexpectedEof};
+use consensus_encoding::{ArrayDecoder, Decoder, UnexpectedEofError};
 
 const EMPTY: &[u8] = &[];
 
@@ -50,5 +50,5 @@ fn decode_array_insufficient_data_error() {
     assert_eq!(data, EMPTY);
 
     let err = decoder.end().unwrap_err();
-    assert!(matches!(err, UnexpectedEof { .. }));
+    assert!(matches!(err, UnexpectedEofError { .. }));
 }

consensus_encoding/tests/decode.rs

@@ -137,8 +137,9 @@ impl fmt::Display for ParseAmountError {
             E::TooPrecise(ref error) => write_err!(f, "amount has a too high precision"; error),
             E::MissingDigits(ref error) => write_err!(f, "the input has too few digits"; error),
             E::InputTooLarge(ref error) => write_err!(f, "the input is too large"; error),
-            E::InvalidCharacter(ref error) =>
-                write_err!(f, "invalid character in the input"; error),
+            E::InvalidCharacter(ref error) => {
+                write_err!(f, "invalid character in the input"; error)
+            }
         }
     }
 }
@@ -389,3 +390,44 @@ impl fmt::Display for PossiblyConfusingDenominationError {
 impl std::error::Error for PossiblyConfusingDenominationError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None }
 }
+
+/// An error consensus decoding an `Amount`.
+#[cfg(feature = "encoding")]
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum AmountDecoderError {
+    /// Not enough bytes given to decoder.
+    UnexpectedEof(encoding::UnexpectedEofError),
+    /// Decoded amount is too big.
+    OutOfRange(OutOfRangeError),
+}
+
+#[cfg(feature = "encoding")]
+impl From<Infallible> for AmountDecoderError {
+    fn from(never: Infallible) -> Self { match never {} }
+}
+
+#[cfg(feature = "encoding")]
+impl From<encoding::UnexpectedEofError> for AmountDecoderError {
+    fn from(e: encoding::UnexpectedEofError) -> Self { Self::UnexpectedEof(e) }
+}
+
+#[cfg(feature = "encoding")]
+impl fmt::Display for AmountDecoderError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match *self {
+            Self::UnexpectedEof(ref e) => write_err!(f, "decode error"; e),
+            Self::OutOfRange(ref e) => write_err!(f, "decode error"; e),
+        }
+    }
+}
+
+#[cfg(all(feature = "std", feature = "encoding"))]
+impl std::error::Error for AmountDecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match *self {
+            Self::UnexpectedEof(ref e) => Some(e),
+            Self::OutOfRange(ref e) => Some(e),
+        }
+    }
+}

units/src/amount/error.rs

@@ -37,6 +37,9 @@ pub use self::{
     signed::SignedAmount,
     unsigned::Amount,
 };
+#[cfg(feature = "encoding")]
+#[doc(no_inline)]
+pub use self::error::AmountDecoderError;
 #[doc(no_inline)]
 pub use self::error::{OutOfRangeError, ParseAmountError, ParseDenominationError, ParseError};
 

units/src/amount/mod.rs

@@ -12,6 +12,8 @@ use arbitrary::{Arbitrary, Unstructured};
 use internals::const_casts;
 use NumOpResult as R;
 
+#[cfg(feature = "encoding")]
+use super::error::AmountDecoderError;
 use super::error::{ParseAmountErrorInner, ParseErrorInner};
 use super::{
     parse_signed_to_satoshi, split_amount_and_denomination, Denomination, Display, DisplayStyle,
@@ -576,6 +578,33 @@ impl encoding::Encodable for Amount {
     }
 }
 
+/// The decoder for the [`Amount`] type.
+#[cfg(feature = "encoding")]
+pub struct AmountDecoder(encoding::ArrayDecoder<8>);
+
+#[cfg(feature = "encoding")]
+impl encoding::Decoder for AmountDecoder {
+    type Output = Amount;
+    type Error = AmountDecoderError;
+
+    #[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 = u64::from_le_bytes(self.0.end()?);
+        Ok(Amount::from_sat(a).map_err(AmountDecoderError::OutOfRange)?)
+    }
+}
+
+#[cfg(feature = "encoding")]
+impl encoding::Decodable for Amount {
+    type Decoder = AmountDecoder;
+    fn decoder() -> Self::Decoder { AmountDecoder(encoding::ArrayDecoder::<8>::new()) }
+}
+
 #[cfg(feature = "arbitrary")]
 impl<'a> Arbitrary<'a> for Amount {
     fn arbitrary(u: &mut Unstructured<'a>) -> arbitrary::Result<Self> {

units/src/amount/unsigned.rs

@@ -157,6 +157,33 @@ impl encoding::Encodable for BlockHeight {
     }
 }
 
+/// The decoder for the [`BlockHeight`] type.
+#[cfg(feature = "encoding")]
+pub struct BlockHeightDecoder(encoding::ArrayDecoder<4>);
+
+#[cfg(feature = "encoding")]
+impl encoding::Decoder for BlockHeightDecoder {
+    type Output = BlockHeight;
+    type Error = encoding::UnexpectedEofError;
+
+    #[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 n = u32::from_le_bytes(self.0.end()?);
+        Ok(BlockHeight::from_u32(n))
+    }
+}
+
+#[cfg(feature = "encoding")]
+impl encoding::Decodable for BlockHeight {
+    type Decoder = BlockHeightDecoder;
+    fn decoder() -> Self::Decoder { BlockHeightDecoder(encoding::ArrayDecoder::<4>::new()) }
+}
+
 impl_u32_wrapper! {
     /// An unsigned block interval.
     ///

units/src/block.rs

@@ -417,6 +417,33 @@ impl encoding::Encodable for LockTime {
     }
 }
 
+/// The decoder for the [`LockTime`] type.
+#[cfg(feature = "encoding")]
+pub struct LockTimeDecoder(encoding::ArrayDecoder<4>);
+
+#[cfg(feature = "encoding")]
+impl encoding::Decoder for LockTimeDecoder {
+    type Output = LockTime;
+    type Error = encoding::UnexpectedEofError;
+
+    #[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 n = u32::from_le_bytes(self.0.end()?);
+        Ok(LockTime::from_consensus(n))
+    }
+}
+
+#[cfg(feature = "encoding")]
+impl encoding::Decodable for LockTime {
+    type Decoder = LockTimeDecoder;
+    fn decoder() -> Self::Decoder { LockTimeDecoder(encoding::ArrayDecoder::<4>::new()) }
+}
+
 impl From<Height> for LockTime {
     #[inline]
     fn from(h: Height) -> Self { LockTime::Blocks(h) }