confidential: implement Encode/Decode for confidential commitments

This commit introduces the `decoder_state_machine` macro which generates
(a lot of) the boilerplate needed to implement the encoding::Decoder
trait. This includes internal enums, wrapper types to hide the internal
enums, the state machine accounting, impls of std::error::Error, etc
etc.

I got Claude 4 to write a detailed doccomment, from which I deleted a
bunch of fluff. But all the code in the macro was hand-written based on
my implementing this decoder state machine a dozen times across the
codebase. (My original implementations are thrown away and not included
in this PR.)

Author: apoelstra

src/confidential/asset.rs

@@ -10,14 +10,17 @@ use secp256k1_zkp::{self, Generator, Secp256k1, Signing, Tweak, ZERO_TWEAK};
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+use super::CommitmentEncoder;
 use crate::encode::{self, Decodable, Encodable};
+use crate::encoding;
 use crate::issuance::AssetId;
 
 type ExplicitInner = AssetId;
 type ConfInner = Generator;
 
 const EXPLICIT_LEN: usize = 32;
 const CONFIDENTIAL_LEN: usize = 33;
+const CONFIDENTIAL_LEN_LESS_PREFIX: usize = CONFIDENTIAL_LEN - 1;
 const CONF_PREFIX_1: u8 = 0x0a;
 const CONF_PREFIX_2: u8 = 0x0b;
 
@@ -344,3 +347,112 @@ impl<'de> Deserialize<'de> for BlindingFactor {
         }
     }
 }
+
+encoding::encoder_newtype_exact! {
+    /// Encoder for the [`Asset`] type.
+    #[derive(Clone, Debug)]
+    pub struct Encoder<'e>(CommitmentEncoder<'e>);
+}
+
+impl encoding::Encode for Asset {
+    type Encoder<'e> = Encoder<'e>;
+
+    fn encoder(&self) -> Self::Encoder<'_> {
+        Encoder::new(match *self {
+            Self::Null => CommitmentEncoder::Null(0),
+            Self::Explicit(ref id) => CommitmentEncoder::Explicit32(Some(1), id.as_byte_array()),
+            Self::Confidential(ref gen) => CommitmentEncoder::Explicit33(gen.serialize()),
+        })
+    }
+}
+
+decoder_state_machine! {
+    /// A decoder for the [`Asset`] type.
+    pub struct Decoder(enum DecoderInner {
+        Done(Asset),
+        Errored,
+        DecodePrefix {
+            decoder: encoding::ArrayDecoder<1>,
+            => transition_decode_prefix(prefix, ...) -> Result {
+                match prefix {
+                    [0] => Ok(DecoderInner::Done(Asset::Null)),
+                    [1] => {
+                        Ok(DecoderInner::DecodeExplicit { decoder: encoding::ArrayDecoder::default() })
+                    },
+                    [prefix @ (CONF_PREFIX_1 | CONF_PREFIX_2)] => {
+                        Ok(DecoderInner::DecodeConfidential { decoder: encoding::ArrayDecoder::default(), prefix })
+                    },
+                    [prefix] => Err(DecoderErrorInner::InvalidConfidentialPrefix { prefix })
+                }
+            }
+        },
+        DecodeExplicit {
+            decoder: encoding::ArrayDecoder<EXPLICIT_LEN>
+            => transition_decode_explicit(bytes, ...) -> Result {
+                Ok(DecoderInner::Done(Asset::Explicit(AssetId::from_byte_array(bytes))))
+            }
+        },
+        DecodeConfidential {
+            decoder: encoding::ArrayDecoder<CONFIDENTIAL_LEN_LESS_PREFIX>,
+            prefix: u8
+            => transition_decode_confidential(x_coord, ...) -> Result {
+                let mut bytes = [0; CONFIDENTIAL_LEN];
+                bytes[0] = prefix;
+                bytes[1..].copy_from_slice(&x_coord);
+                let gen = ConfInner::from_slice(&bytes)
+                    .map_err(DecoderErrorInner::InvalidCommitment)?;
+                Ok(DecoderInner::Done(Asset::Confidential(gen)))
+            }
+        },
+    });
+
+    /// A decoder error for the [`Asset`] type.
+    #[derive(Clone, PartialEq, Eq, Debug)]
+    pub struct DecoderError(enum DecoderErrorInner {
+        [macro-inserted decoder variants]
+        /// Confidential prefix was not one of the two allowable values.
+        InvalidConfidentialPrefix {
+            prefix: u8,
+        },
+        /// Malformed confidential commitment.
+        InvalidCommitment(secp256k1_zkp::Error),
+    });
+}
+
+impl fmt::Display for DecoderError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        use DecoderErrorInner as Inner;
+        match self.0 {
+            Inner::DecodePrefix(_) => f.write_str("failed to decode prefix"),
+            Inner::DecodeExplicit(_) => f.write_str("failed to decode explicit value"),
+            Inner::DecodeConfidential(_) => f.write_str("failed to decode confidential value"),
+            Inner::InvalidConfidentialPrefix { prefix, .. } => {
+                write!(
+                    f,
+                    "confidential prefix 0x{:02x} was not one of 0, 1, 0x{:02x} or 0x{:02x}",
+                    prefix, CONF_PREFIX_1, CONF_PREFIX_2,
+                )
+            }
+            Inner::InvalidCommitment(_) => f.write_str("failed to parse confidential commitment"),
+        }
+    }
+}
+
+impl std::error::Error for DecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        use DecoderErrorInner as Inner;
+        match self.0 {
+            Inner::DecodePrefix(ref e) => Some(e),
+            Inner::DecodeExplicit(ref e) => Some(e),
+            Inner::DecodeConfidential(ref e) => Some(e),
+            Inner::InvalidConfidentialPrefix { .. } => None,
+            Inner::InvalidCommitment(ref e) => Some(e),
+        }
+    }
+}
+
+impl Default for Decoder {
+    fn default() -> Self {
+        Self(DecoderInner::DecodePrefix { decoder: encoding::ArrayDecoder::default() })
+    }
+}

src/confidential/mod.rs

@@ -25,17 +25,68 @@ mod range_proof;
 mod surjection_proof;
 mod value;
 
-use core::fmt;
+use core::{fmt, slice};
 
 use secp256k1_zkp;
 
-pub use self::asset::{Asset, BlindingFactor as AssetBlindingFactor};
-pub use self::nonce::Nonce;
+pub use self::asset::{
+    Asset, BlindingFactor as AssetBlindingFactor, Decoder as AssetDecoder,
+    DecoderError as AssetDecoderError, Encoder as AssetEncoder,
+};
+pub use self::nonce::{
+    Decoder as NonceDecoder, DecoderError as NonceDecoderError, Encoder as NonceEncoder, Nonce,
+};
 pub use self::range_proof::RangeProof;
 pub use self::surjection_proof::SurjectionProof;
-pub use self::value::{BlindingFactor as ValueBlindingFactor, Value};
-use crate::encode;
+pub use self::value::{
+    BlindingFactor as ValueBlindingFactor, Decoder as ValueDecoder,
+    DecoderError as ValueDecoderError, Encoder as ValueEncoder, Value,
+};
 use crate::issuance::AssetId;
+use crate::{encode, encoding};
+
+#[derive(Clone, Debug)]
+enum CommitmentEncoder<'e> {
+    Null(u8),
+    Explicit8(Option<u8>, [u8; 8]),
+    Explicit32(Option<u8>, &'e [u8; 32]),
+    Explicit33([u8; 33]),
+}
+
+impl encoding::Encoder for CommitmentEncoder<'_> {
+    fn current_chunk(&self) -> &[u8] {
+        match *self {
+            Self::Null(ref prefix) => slice::from_ref(prefix),
+            Self::Explicit8(ref prefix, ref arr) => prefix.as_ref().map_or(arr, slice::from_ref),
+            Self::Explicit32(ref prefix, arr) => prefix.as_ref().map_or(arr, slice::from_ref),
+            Self::Explicit33(ref arr) => arr,
+        }
+    }
+
+    fn advance(&mut self) -> encoding::EncoderStatus {
+        match *self {
+            Self::Explicit8(ref mut prefix @ Some(_), _)
+            | Self::Explicit32(ref mut prefix @ Some(_), _) => {
+                *prefix = None;
+                encoding::EncoderStatus::HasMore
+            }
+            _ => encoding::EncoderStatus::Finished,
+        }
+    }
+}
+
+impl encoding::ExactSizeEncoder for CommitmentEncoder<'_> {
+    fn len(&self) -> usize {
+        match *self {
+            Self::Null(_) => 1,
+            Self::Explicit8(Some(_), _) => 9,
+            Self::Explicit8(None, _) => 8,
+            Self::Explicit32(Some(_), _) => 33,
+            Self::Explicit32(None, _) => 32,
+            Self::Explicit33(_) => 33,
+        }
+    }
+}
 
 /// Error decoding hexadecimal string into tweak-like value.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -96,6 +147,7 @@ mod tests {
 
     use super::*;
     use crate::encode::Encodable as _;
+    use crate::encoding;
 
     const VALUE_EXPLICIT: [u8; 9] = [1, 0, 0, 0, 0, 0, 0, 3, 232];
 
@@ -158,6 +210,9 @@ mod tests {
             assert_eq!(v.consensus_encode(&mut x).unwrap(), v.encoded_length());
             assert_eq!(x.len(), v.encoded_length());
             assert_eq!(x, *enc);
+
+            assert_eq!(encoding::encode_to_vec(v), *enc);
+            assert_eq!(encoding::decode_from_slice(enc), Ok(*v));
         }
 
         let nonce_encodings = [
@@ -177,6 +232,9 @@ mod tests {
             assert_eq!(v.consensus_encode(&mut x).unwrap(), v.encoded_length());
             assert_eq!(x.len(), v.encoded_length());
             assert_eq!(x, *enc);
+
+            assert_eq!(encoding::encode_to_vec(v), *enc);
+            assert_eq!(encoding::decode_from_slice(enc), Ok(*v));
         }
 
         let asset_encodings = [
@@ -196,6 +254,9 @@ mod tests {
             assert_eq!(v.consensus_encode(&mut x).unwrap(), v.encoded_length());
             assert_eq!(x.len(), v.encoded_length());
             assert_eq!(x, *enc);
+
+            assert_eq!(encoding::encode_to_vec(v), *enc);
+            assert_eq!(encoding::decode_from_slice(enc), Ok(*v));
         }
     }
 
@@ -207,20 +268,23 @@ mod tests {
         assert_eq!(x, Value::from_commitment(&commitment[..]).unwrap());
         commitment[0] = 42;
         assert!(Value::from_commitment(&commitment[..]).is_err());
+        assert_eq!(encoding::encode_to_vec(&x), VALUE_COMMITMENT1);
 
         let x = Asset::from_commitment(&ASSET_COMMITMENT1).unwrap();
         let commitment = x.commitment().unwrap();
         let mut commitment = commitment.serialize();
         assert_eq!(x, Asset::from_commitment(&commitment[..]).unwrap());
         commitment[0] = 42;
         assert!(Asset::from_commitment(&commitment[..]).is_err());
+        assert_eq!(encoding::encode_to_vec(&x), ASSET_COMMITMENT1);
 
         let x = Nonce::from_commitment(&NONCE_COMMITMENT1).unwrap();
         let commitment = x.commitment().unwrap();
         let mut commitment = commitment.serialize();
         assert_eq!(x, Nonce::from_commitment(&commitment[..]).unwrap());
         commitment[0] = 42;
         assert!(Nonce::from_commitment(&commitment[..]).is_err());
+        assert_eq!(encoding::encode_to_vec(&x), NONCE_COMMITMENT1);
     }
 
     #[cfg(feature = "serde")]

src/confidential/nonce.rs

@@ -10,14 +10,17 @@ use secp256k1_zkp::{self, PublicKey, Secp256k1, SecretKey, Signing};
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+use super::CommitmentEncoder;
 use crate::encode::{self, Decodable, Encodable};
+use crate::encoding;
 use crate::hashes::sha256d;
 
 type ExplicitInner = [u8; 32];
 type ConfInner = PublicKey;
 
 const EXPLICIT_LEN: usize = 32;
 const CONFIDENTIAL_LEN: usize = 33;
+const CONFIDENTIAL_LEN_LESS_PREFIX: usize = CONFIDENTIAL_LEN - 1;
 const CONF_PREFIX_1: u8 = 0x02;
 const CONF_PREFIX_2: u8 = 0x03;
 
@@ -247,3 +250,112 @@ impl<'de> Deserialize<'de> for Nonce {
         d.deserialize_seq(CommitVisitor)
     }
 }
+
+encoding::encoder_newtype_exact! {
+    /// Encoder for the [`Nonce`] type.
+    #[derive(Clone, Debug)]
+    pub struct Encoder<'e>(CommitmentEncoder<'e>);
+}
+
+impl encoding::Encode for Nonce {
+    type Encoder<'e> = Encoder<'e>;
+
+    fn encoder(&self) -> Self::Encoder<'_> {
+        Encoder::new(match *self {
+            Self::Null => CommitmentEncoder::Null(0),
+            Self::Explicit(ref id) => CommitmentEncoder::Explicit32(Some(1), id),
+            Self::Confidential(ref gen) => CommitmentEncoder::Explicit33(gen.serialize()),
+        })
+    }
+}
+
+decoder_state_machine! {
+    /// A decoder for the [`Nonce`] type.
+    pub struct Decoder(enum DecoderInner {
+        Done(Nonce),
+        Errored,
+        DecodePrefix {
+            decoder: encoding::ArrayDecoder<1>,
+            => transition_decode_prefix(prefix, ...) -> Result {
+                match prefix {
+                    [0] => Ok(DecoderInner::Done(Nonce::Null)),
+                    [1] => {
+                        Ok(DecoderInner::DecodeExplicit { decoder: encoding::ArrayDecoder::default() })
+                    },
+                    [prefix @ (CONF_PREFIX_1 | CONF_PREFIX_2)] => {
+                        Ok(DecoderInner::DecodeConfidential { decoder: encoding::ArrayDecoder::default(), prefix })
+                    },
+                    [prefix] => Err(DecoderErrorInner::InvalidConfidentialPrefix { prefix })
+                }
+            }
+        },
+        DecodeExplicit {
+            decoder: encoding::ArrayDecoder<EXPLICIT_LEN>
+            => transition_decode_explicit(bytes, ...) -> Result {
+                Ok(DecoderInner::Done(Nonce::Explicit(bytes)))
+            }
+        },
+        DecodeConfidential {
+            decoder: encoding::ArrayDecoder<CONFIDENTIAL_LEN_LESS_PREFIX>,
+            prefix: u8
+            => transition_decode_confidential(x_coord, ...) -> Result {
+                let mut bytes = [0; CONFIDENTIAL_LEN];
+                bytes[0] = prefix;
+                bytes[1..].copy_from_slice(&x_coord);
+                let gen = ConfInner::from_slice(&bytes)
+                    .map_err(DecoderErrorInner::InvalidCommitment)?;
+                Ok(DecoderInner::Done(Nonce::Confidential(gen)))
+            }
+        },
+    });
+
+    /// A decoder error for the [`Nonce`] type.
+    #[derive(Clone, PartialEq, Eq, Debug)]
+    pub struct DecoderError(enum DecoderErrorInner {
+        [macro-inserted decoder variants]
+        /// Confidential prefix was not one of the two allowable values.
+        InvalidConfidentialPrefix {
+            prefix: u8,
+        },
+        /// Malformed confidential commitment.
+        InvalidCommitment(bitcoin::secp256k1::Error),
+    });
+}
+
+impl fmt::Display for DecoderError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        use DecoderErrorInner as Inner;
+        match self.0 {
+            Inner::DecodePrefix(_) => f.write_str("failed to decode prefix"),
+            Inner::DecodeExplicit(_) => f.write_str("failed to decode explicit value"),
+            Inner::DecodeConfidential(_) => f.write_str("failed to decode confidential value"),
+            Inner::InvalidConfidentialPrefix { prefix, .. } => {
+                write!(
+                    f,
+                    "confidential prefix 0x{:02x} was not one of 0, 1, 0x{:02x} or 0x{:02x}",
+                    prefix, CONF_PREFIX_1, CONF_PREFIX_2,
+                )
+            }
+            Inner::InvalidCommitment(_) => f.write_str("failed to parse confidential commitment"),
+        }
+    }
+}
+
+impl std::error::Error for DecoderError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        use DecoderErrorInner as Inner;
+        match self.0 {
+            Inner::DecodePrefix(ref e) => Some(e),
+            Inner::DecodeExplicit(ref e) => Some(e),
+            Inner::DecodeConfidential(ref e) => Some(e),
+            Inner::InvalidConfidentialPrefix { .. } => None,
+            Inner::InvalidCommitment(ref e) => Some(e),
+        }
+    }
+}
+
+impl Default for Decoder {
+    fn default() -> Self {
+        Self(DecoderInner::DecodePrefix { decoder: encoding::ArrayDecoder::default() })
+    }
+}