implement Encode/Decode for TxOut

Author: apoelstra

rustfmt.toml

@@ -2,6 +2,8 @@ ignore = [
     "/",
     "!/src/lib.rs",
     "!/src/confidential/*.rs",
+    "!/src/transaction/decoders.rs",
+    "!/src/transaction/encoders.rs",
     "!/src/transaction/pegin_witness.rs"
 ]
 hard_tabs = false

src/internal_macros.rs

@@ -794,6 +794,29 @@ macro_rules! decoder_state_machine {
 ///
 /// # Syntax
 ///
+/// There are two invocation patterns:
+///
+/// ## Direct Error Wrapping
+/// ```ignore
+/// decoder_newtype! {
+///     /// Documentation for the decoder struct
+///     pub struct DecoderName(InnerDecoderType);
+///
+///     /// Documentation for the error struct
+///     pub struct ErrorName(InnerErrorName);
+///     const ERROR_DISPLAY = "output of the Display::fmt function";
+///
+///     impl Decode for TargetType {
+///         fn convert_inner(output_var) -> Result<_, InnerErrorName> {
+///             // Conversion logic -- returns `InnerErrorName` for errors!
+///         }
+///     }
+/// }
+/// ```
+///
+/// In this case `InnerErrorName` must be an already-existing error type.
+///
+/// ## Error Enum Wrapping
 /// ```ignore
 /// decoder_newtype! {
 ///     /// Documentation for the decoder struct
@@ -811,12 +834,14 @@ macro_rules! decoder_state_machine {
 ///
 ///     impl Decode for TargetType {
 ///         fn convert_inner(output_var) -> Result<_, ErrorName> {
-///             // Conversion logic
+///             // Conversion logic -- returns `ErrorName` for errors!
 ///         }
 ///     }
 /// }
 /// ```
 ///
+/// In this case `InnerErrorName` will be generated as a private enum by the macro.
+///
 /// # Generated Code
 ///
 /// The macro generates:
@@ -826,8 +851,10 @@ macro_rules! decoder_state_machine {
 /// - `Decoder` trait implementation with `push_bytes`, `end`, and `read_limit` methods
 /// - `Decode` trait implementation for the target type
 ///
-/// The macro does **not** generate a `fmt::Display` or `std::error::Error` impl
-/// for `ErrorName`, so the user must implement these outside of the macro.
+/// **When using the enum pattern, the macro does not generate a `fmt::Display` or
+/// `std::error::Error` impl for `ErrorName`. The user must implement these outside
+/// of the macro.** When using the non-enum pattern, both `Display` and `Error` are
+/// generated by the macro.
 ///
 /// # Parameters
 ///
@@ -843,9 +870,15 @@ macro_rules! decoder_state_machine {
 ///
 /// The conversion function:
 /// - Takes the inner decoder's output as its parameter
-/// - Returns `Result<TargetType, ErrorName>`
+/// - Returns `Result<TargetType, ErrorName>` for enum pattern, `Result<TargetType, InnerErrorName>`
+///   for direct-wrapping pattern.
 /// - Is called automatically when the inner decoder completes
-/// - Can return custom errors defined in the error enum
+/// - Can return custom errors defined in the error enum (enum pattern only)
+///
+/// # Pattern Selection
+///
+/// - Use **direct error wrapping** when conversion cannot fail or only needs to propagate the inner decoder's errors
+/// - Use **error enum wrapping** when conversion can fail with custom error types
 ///
 /// # Error Handling
 ///
@@ -856,6 +889,37 @@ macro_rules! decoder_state_machine {
 ///
 /// # Example Usage
 ///
+/// ## Direct Error Wrapping
+/// ```ignore
+/// decoder_newtype! {
+///     /// Decoder for the [`TxOut`] type.
+///     #[derive(Default)]
+///     pub struct TxOutDecoder(Decoder4< crate::confidential::AssetDecoder,
+///         crate::confidential::ValueDecoder,
+///         crate::confidential::NonceDecoder,
+///         crate::script::ScriptDecoder,
+///     >);
+///
+///     /// Decoder error for the [`TxOut`] type.
+///     #[derive(Clone, PartialEq, Eq, Debug)]
+///     pub struct TxOutDecoderError(Decoder4Error<
+///         crate::confidential::AssetDecoderError,
+///         crate::confidential::ValueDecoderError,
+///         crate::confidential::NonceDecoderError,
+///         crate::script::ScriptDecoderError,
+///     >);
+///     const ERROR_DISPLAY = "error decoding transaction output witness";
+///
+///     impl Decode for TxOut {
+///         fn convert_inner(output) -> Result<_, TxOutDecoderErrorInner> {
+///             let (asset, value, nonce, script_pubkey) = output;
+///             Ok(TxOut { asset, value, nonce, script_pubkey, witness: TxOutWitness::empty() })
+///         }
+///     }
+/// }
+/// ```
+///
+/// ## Error Enum Wrapping
 /// ```ignore
 /// decoder_newtype! {
 ///     /// Decoder for range proofs
@@ -877,6 +941,73 @@ macro_rules! decoder_state_machine {
 /// }
 /// ```
 macro_rules! decoder_newtype {
+    // With directly wrapped inner error
+    (
+        $(#[$($struct_attr:tt)*])*
+        pub struct $outer_ty:ident($inner_ty:ty);
+
+        $(#[$($error_struct_attr:tt)*])*
+        pub struct $error_ty:ident($inner_ty_error:ty);
+
+        const ERROR_DISPLAY = $error_display:expr;
+
+        impl Decode for $target_ty:ty {
+            fn convert_inner($output:ident) -> Result<_, $error_inner1:ty> {
+                $($output_fn_inner:tt)*
+            }
+        }
+    ) => {
+        $(#[$($struct_attr)*])*
+        pub struct $outer_ty($inner_ty);
+
+        $(#[$($error_struct_attr)*])*
+        pub struct $error_ty($inner_ty_error);
+
+        impl core::fmt::Display for $error_ty {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                f.write_str($error_display)
+            }
+        }
+
+        impl std::error::Error for $error_ty {
+            fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+                Some(&self.0)
+            }
+        }
+
+        impl $crate::encoding::Decoder for $outer_ty {
+            type Output = $target_ty;
+            type Error = $error_ty;
+
+            fn push_bytes(
+                &mut self,
+                bytes: &mut &[u8],
+            ) -> Result<$crate::encoding::DecoderStatus, Self::Error> {
+                self.0
+                    .push_bytes(bytes)
+                    .map_err($error_ty)
+            }
+
+            fn end(self) -> Result<Self::Output, Self::Error> {
+                let $output = self.0
+                    .end()
+                    .map_err($error_ty)?;
+                let converted = {
+                    $($output_fn_inner)*
+                };
+                converted.map_err($error_ty)
+            }
+
+            fn read_limit(&self) -> usize {
+                self.0.read_limit()
+            }
+        }
+
+        impl $crate::encoding::Decode for $target_ty{
+            type Decoder = $outer_ty;
+        }
+    };
+    // With inner error enum
     (
         $(#[$($struct_attr:tt)*])*
         pub struct $outer_ty:ident($inner_ty:ty);

src/lib.rs

@@ -97,8 +97,8 @@ pub use crate::sighash::SchnorrSighashType;
 pub use crate::transaction::{
     AssetIssuance, EcdsaSighashType, OutPoint, PeginData, PeginDataDecoder, PeginDataEncoder,
     PeginWitness, PeginWitnessDecoder, PeginWitnessDecoderError, PeginWitnessEncoder, PegoutData,
-    Sequence, Transaction, TxIn, TxInWitness, TxOut, TxOutWitness, Witness, WitnessDecoder,
-    WitnessDecoderError, WitnessEncoder,
+    Sequence, Transaction, TxIn, TxInWitness, TxOut, TxOutDecoder, TxOutDecoderError, TxOutEncoder,
+    TxOutWitness, Witness, WitnessDecoder, WitnessDecoderError, WitnessEncoder,
 };
 
 // Encode a compact size to a slice without allocating

src/script.rs

@@ -31,6 +31,7 @@ use secp256k1_zkp::{Verification, Secp256k1};
 #[cfg(feature = "serde")] use serde;
 
 use crate::encode::{self, Decodable, Encodable};
+use crate::encoding;
 use crate::{opcodes, ScriptHash, WScriptHash, PubkeyHash, WPubkeyHash};
 
 use bitcoin::PublicKey;
@@ -943,6 +944,36 @@ impl Decodable for Script {
     }
 }
 
+encoding::encoder_newtype_exact! {
+    /// Encoder for a [`Script`].
+    #[derive(Clone, Debug)]
+    pub struct ScriptEncoder<'e>(encoding::PrefixedBytesEncoder<'e>);
+}
+
+impl encoding::Encode for Script {
+    type Encoder<'e> = ScriptEncoder<'e>;
+    fn encoder(&self) -> Self::Encoder<'_> {
+        ScriptEncoder::new(encoding::PrefixedBytesEncoder::new(self.as_bytes()))
+    }
+}
+
+decoder_newtype! {
+    /// Decoder for a [`Script`].
+    #[derive(Default)]
+    pub struct ScriptDecoder(encoding::ByteVecDecoder);
+
+    /// Decoder error for the [`Script`] type.
+    #[derive(Clone, PartialEq, Eq, Debug)]
+    pub struct ScriptDecoderError(encoding::ByteVecDecoderError);
+    const ERROR_DISPLAY = "failed to decode script";
+
+    impl Decode for Script {
+        fn convert_inner(bytes) -> Result<_, _> {
+            Ok(Script::from(bytes))
+        }
+    }
+}
+
 #[cfg(test)]
 mod test {
     use bitcoin::PublicKey;

src/transaction/decoders.rs

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Transaction Decoders
+//!
+//! These are encapsulated because there are many of them, but in the end we
+//! only expose the top-level ones outside of this module.
+
+use core::fmt;
+
+use super::{TxOut, TxOutWitness};
+use crate::encoding::{Decoder4, Decoder4Error};
+
+decoder_newtype! {
+    /// Decoder for the [`TxOut`] type.
+    #[derive(Default)]
+    pub struct TxOutDecoder(Decoder4<
+        crate::confidential::AssetDecoder,
+        crate::confidential::ValueDecoder,
+        crate::confidential::NonceDecoder,
+        crate::script::ScriptDecoder,
+    >);
+
+
+    /// Decoder error for the [`TxOut`] type.
+    #[derive(Clone, PartialEq, Eq, Debug)]
+    pub struct TxOutDecoderError(Decoder4Error<
+            crate::confidential::AssetDecoderError,
+            crate::confidential::ValueDecoderError,
+            crate::confidential::NonceDecoderError,
+            crate::script::ScriptDecoderError,
+    >);
+    const ERROR_DISPLAY = "error decoding transaction output witness";
+
+    impl Decode for TxOut {
+        fn convert_inner(output) -> Result<_, TxOutDecoderErrorInner> {
+            let (asset, value, nonce, script_pubkey) = output;
+            Ok(TxOut { asset, value, nonce, script_pubkey, witness: TxOutWitness::empty() })
+        }
+    }
+}

src/transaction/encoders.rs

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Transaction Encoders
+//!
+//! These are encapsulated because there are many of them, but in the end we
+//! only expose the top-level ones outside of this module.
+
+use super::TxOut;
+use crate::encoding::{encoder_newtype_exact, Encode, Encoder4};
+
+encoder_newtype_exact! {
+    /// Encoder for the [`TxOut`] type.
+    #[derive(Clone, Debug)]
+    pub struct TxOutEncoder<'e>(Encoder4<
+        crate::confidential::AssetEncoder<'e>,
+        crate::confidential::ValueEncoder<'e>,
+        crate::confidential::NonceEncoder<'e>,
+        crate::script::ScriptEncoder<'e>,
+    >);
+}
+
+impl Encode for TxOut {
+    type Encoder<'e> = TxOutEncoder<'e>;
+
+    fn encoder(&self) -> Self::Encoder<'_> {
+        TxOutEncoder::new(Encoder4::new(
+            self.asset.encoder(),
+            self.value.encoder(),
+            self.nonce.encoder(),
+            self.script_pubkey.encoder(),
+        ))
+    }
+}

src/transaction/mod.rs

@@ -15,6 +15,8 @@
 //! # Transactions
 //!
 
+mod decoders;
+mod encoders;
 mod pegin_witness;
 mod witness;
 
@@ -37,6 +39,8 @@ use secp256k1_zkp::{
     Tweak, ZERO_TWEAK,
 };
 
+pub use self::decoders::{TxOutDecoder, TxOutDecoderError};
+pub use self::encoders::TxOutEncoder;
 pub use self::pegin_witness::{
     PeginData, PeginDataDecoder, PeginDataEncoder,
     PeginWitness, PeginWitnessDecoder, PeginWitnessDecoderError, PeginWitnessEncoder};