Merge #803: Make musig serialized length constants part of the API of secp256k1::musig

58f19da musig: Rename musig constants to use _SIZE suffix (Daniel Roberts)
90ba850 musig: move serialized data length constants (Daniel Roberts)
5f027ac musig: reword docs for serialized data length constants (Daniel Roberts)

Pull request description:

  This PR:

  - (hopefully) disambiguates the documentation for these constants. Less is more I think, the serialized format is meant to be opaque afaik(?).
  - Moves the serialized size constants into the `musig` module (they aren't used in sys-secp256k1 module at all, and there's no precedent for such constants in there).
  - Drops the `MUSIG_` prefix from these constants under the assumption they are unambiguous in-context (can always refer to them with `musig::CONSTANT` anyway
  - Leaves the "private" size constants in sys-secp256k1 because they're used there, and even though there's no precedent, it seems reasonable
  - Renames the `_LEN` suffix to `_SIZE` to match other constants in rust-secp256k1

ACKs for top commit:
  apoelstra:
    ACK 58f19da; successfully ran local tests

Tree-SHA512: f054c74df1924cc0eed04e7a9173cc3c15882cd41e0ad08fb84f59a3ed8c8bf4e9d04ca2a8c07faa4189b91fa03d4097458ff95c00abe6e7eb44e87bf3145fb8

Author: apoelstra

secp256k1-sys/src/lib.rs

@@ -1429,91 +1429,77 @@ impl<T: CPtr> CPtr for Option<T> {
         }
     }
 }
-/// Total length (in bytes) of the key aggregation context.
+/// Total size (in bytes) of the key aggregation context.
 /// This structure packs all metadata needed for aggregating individual public keys
 /// into a single MuSig2 aggregated key (including coefficients and any extra metadata).
-pub const MUSIG_KEYAGG_LEN: usize = 197;
+pub const MUSIG_KEYAGG_SIZE: usize = 197;
 
-/// Length (in bytes) of the secret nonce structure used in a MuSig2 session.
+/// Size (in bytes) of the secret nonce structure used in a MuSig2 session.
 /// It holds the secret (ephemeral) nonces used internally for nonce derivation
 /// before the corresponding public nonces are computed.
-pub const MUSIG_SECNONCE_LEN: usize = 132;
+pub const MUSIG_SECNONCE_SIZE: usize = 132;
 
-/// Length (in bytes) of the public nonce structure.
+/// Size (in bytes) of the public nonce structure.
 /// This is derived from the secret nonce and shared among participants to build
 /// nonce commitments in the MuSig2 protocol.
-pub const MUSIG_PUBNONCE_LEN: usize = 132;
+pub const MUSIG_PUBNONCE_SIZE: usize = 132;
 
-/// Length (in bytes) of the aggregated nonce structure.
+/// Size (in bytes) of the aggregated nonce structure.
 /// Represents the combined nonce obtained by aggregating the individual public nonces
 /// from all participants for the final signature computation.
-pub const MUSIG_AGGNONCE_LEN: usize = 132;
+pub const MUSIG_AGGNONCE_SIZE: usize = 132;
 
-/// Serialized length (in bytes) of the aggregated nonce.
-/// This is the compact form (typically using a compressed representation) used for
-/// transmitting or storing the aggregated nonce.
-pub const MUSIG_AGGNONCE_SERIALIZED_LEN: usize = 66;
-
-/// Serialized length (in bytes) of an individual public nonce.
-/// This compact serialized form is what gets exchanged between signers.
-pub const MUSIG_PUBNONCE_SERIALIZED_LEN: usize = 66;
-
-/// Length (in bytes) of the session structure.
+/// Size (in bytes) of the session structure.
 /// The session object holds all state needed for a MuSig2 signing session (e.g. aggregated nonce,
 /// key aggregation info, and other state necessary for computing partial signatures).
-pub const MUSIG_SESSION_LEN: usize = 133;
+pub const MUSIG_SESSION_SIZE: usize = 133;
 
-/// Length (in bytes) of the internal representation of a partial signature.
+/// Size (in bytes) of the internal representation of a partial signature.
 /// This structure include magic bytes ([0xeb, 0xfb, 0x1a, 0x32]) alongside the actual signature scalar.
-pub const MUSIG_PART_SIG_LEN: usize = 36;
-
-/// Serialized length (in bytes) of a partial signature.
-/// This is the compact form (typically just the 32-byte scalar) that is used when communicating
-/// partial signatures to be combined into the final signature.
-pub const MUSIG_PART_SIG_SERIALIZED_LEN: usize = 32;
+pub const MUSIG_PART_SIG_SIZE: usize = 36;
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct MusigKeyAggCache([c_uchar; MUSIG_KEYAGG_LEN]);
-impl_array_newtype!(MusigKeyAggCache, c_uchar, MUSIG_KEYAGG_LEN);
+pub struct MusigKeyAggCache([c_uchar; MUSIG_KEYAGG_SIZE]);
+impl_array_newtype!(MusigKeyAggCache, c_uchar, MUSIG_KEYAGG_SIZE);
 impl_raw_debug!(MusigKeyAggCache);
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq)]
-pub struct MusigSecNonce([c_uchar; MUSIG_SECNONCE_LEN]);
-impl_array_newtype!(MusigSecNonce, c_uchar, MUSIG_SECNONCE_LEN);
+pub struct MusigSecNonce([c_uchar; MUSIG_SECNONCE_SIZE]);
+impl_array_newtype!(MusigSecNonce, c_uchar, MUSIG_SECNONCE_SIZE);
 impl_raw_debug!(MusigSecNonce);
 
 impl MusigSecNonce {
-    pub fn dangerous_from_bytes(bytes: [c_uchar; MUSIG_SECNONCE_LEN]) -> Self {
+    pub fn dangerous_from_bytes(bytes: [c_uchar; MUSIG_SECNONCE_SIZE]) -> Self {
         MusigSecNonce(bytes)
     }
 
-    pub fn dangerous_into_bytes(self) -> [c_uchar; MUSIG_SECNONCE_LEN] { self.0 }
+    pub fn dangerous_into_bytes(self) -> [c_uchar; MUSIG_SECNONCE_SIZE] { self.0 }
 }
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct MusigPubNonce([c_uchar; MUSIG_PUBNONCE_LEN]);
-impl_array_newtype!(MusigPubNonce, c_uchar, MUSIG_PUBNONCE_LEN);
+pub struct MusigPubNonce([c_uchar; MUSIG_PUBNONCE_SIZE]);
+impl_array_newtype!(MusigPubNonce, c_uchar, MUSIG_PUBNONCE_SIZE);
 impl_raw_debug!(MusigPubNonce);
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct MusigAggNonce([c_uchar; MUSIG_AGGNONCE_LEN]);
-impl_array_newtype!(MusigAggNonce, c_uchar, MUSIG_AGGNONCE_LEN);
+pub struct MusigAggNonce([c_uchar; MUSIG_AGGNONCE_SIZE]);
+impl_array_newtype!(MusigAggNonce, c_uchar, MUSIG_AGGNONCE_SIZE);
 impl_raw_debug!(MusigAggNonce);
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct MusigSession([c_uchar; MUSIG_SESSION_LEN]);
-impl_array_newtype!(MusigSession, c_uchar, MUSIG_SESSION_LEN);
+pub struct MusigSession([c_uchar; MUSIG_SESSION_SIZE]);
+impl_array_newtype!(MusigSession, c_uchar, MUSIG_SESSION_SIZE);
 impl_raw_debug!(MusigSession);
 
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct MusigPartialSignature([c_uchar; MUSIG_PART_SIG_LEN]);
-impl_array_newtype!(MusigPartialSignature, c_uchar, MUSIG_PART_SIG_LEN);
+pub struct MusigPartialSignature([c_uchar; MUSIG_PART_SIG_SIZE]);
+impl_array_newtype!(MusigPartialSignature, c_uchar, MUSIG_PART_SIG_SIZE);
 impl_raw_debug!(MusigPartialSignature);
 
 #[cfg(secp256k1_fuzz)]

src/musig.rs

@@ -17,6 +17,19 @@ use crate::{
     Verification, XOnlyPublicKey,
 };
 
+/// Serialized size (in bytes) of the aggregated nonce.
+/// The serialized form is used for transmitting or storing the aggregated nonce.
+pub const AGGNONCE_SERIALIZED_SIZE: usize = 66;
+
+/// Serialized size (in bytes) of an individual public nonce.
+/// The serialized form is used for transmission between signers.
+pub const PUBNONCE_SERIALIZED_SIZE: usize = 66;
+
+/// Serialized size (in bytes) of a partial signature.
+/// The serialized form is used for transmitting partial signatures to be
+/// aggregated into the final signature.
+pub const PART_SIG_SERIALIZED_SIZE: usize = 32;
+
 /// Musig parsing errors
 #[derive(Debug, Clone, Copy, Eq, PartialEq, PartialOrd, Ord, Hash)]
 pub enum ParseError {
@@ -244,9 +257,9 @@ impl fmt::Display for PartialSignature {
 impl core::str::FromStr for PartialSignature {
     type Err = ParseError;
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        let mut res = [0u8; ffi::MUSIG_PART_SIG_SERIALIZED_LEN];
+        let mut res = [0u8; PART_SIG_SERIALIZED_SIZE];
         match from_hex(s, &mut res) {
-            Ok(ffi::MUSIG_PART_SIG_SERIALIZED_LEN) => PartialSignature::from_byte_array(&res),
+            Ok(PART_SIG_SERIALIZED_SIZE) => PartialSignature::from_byte_array(&res),
             _ => Err(ParseError::MalformedArg),
         }
     }
@@ -274,7 +287,7 @@ impl<'de> serde::Deserialize<'de> for PartialSignature {
             d.deserialize_bytes(super::serde_util::BytesVisitor::new(
                 "a raw MuSig2 partial signature",
                 |slice| {
-                    let bytes: &[u8; ffi::MUSIG_PART_SIG_SERIALIZED_LEN] =
+                    let bytes: &[u8; PART_SIG_SERIALIZED_SIZE] =
                         slice.try_into().map_err(|_| ParseError::MalformedArg)?;
 
                     Self::from_byte_array(bytes)
@@ -286,8 +299,8 @@ impl<'de> serde::Deserialize<'de> for PartialSignature {
 
 impl PartialSignature {
     /// Serialize a PartialSignature as a byte array.
-    pub fn serialize(&self) -> [u8; ffi::MUSIG_PART_SIG_SERIALIZED_LEN] {
-        let mut data = MaybeUninit::<[u8; ffi::MUSIG_PART_SIG_SERIALIZED_LEN]>::uninit();
+    pub fn serialize(&self) -> [u8; PART_SIG_SERIALIZED_SIZE] {
+        let mut data = MaybeUninit::<[u8; PART_SIG_SERIALIZED_SIZE]>::uninit();
         unsafe {
             if ffi::secp256k1_musig_partial_sig_serialize(
                 ffi::secp256k1_context_no_precomp,
@@ -308,9 +321,7 @@ impl PartialSignature {
     /// # Errors:
     ///
     /// - MalformedArg: If the signature [`PartialSignature`] is out of curve order
-    pub fn from_byte_array(
-        data: &[u8; ffi::MUSIG_PART_SIG_SERIALIZED_LEN],
-    ) -> Result<Self, ParseError> {
+    pub fn from_byte_array(data: &[u8; PART_SIG_SERIALIZED_SIZE]) -> Result<Self, ParseError> {
         let mut partial_sig = MaybeUninit::<ffi::MusigPartialSignature>::uninit();
         unsafe {
             if ffi::secp256k1_musig_partial_sig_parse(
@@ -673,14 +684,14 @@ impl SecretNonce {
     ///
     /// See <https://blockstream.com/2019/02/18/musig-a-new-multisignature-standard/>
     /// for more details about these risks.
-    pub fn dangerous_into_bytes(self) -> [u8; secp256k1_sys::MUSIG_SECNONCE_LEN] {
+    pub fn dangerous_into_bytes(self) -> [u8; secp256k1_sys::MUSIG_SECNONCE_SIZE] {
         self.0.dangerous_into_bytes()
     }
 
     /// Function to create a new [`SecretNonce`] from a 32 byte array.
     ///
     /// Refer to the warning on [`SecretNonce::dangerous_into_bytes`] for more details.
-    pub fn dangerous_from_bytes(array: [u8; secp256k1_sys::MUSIG_SECNONCE_LEN]) -> Self {
+    pub fn dangerous_from_bytes(array: [u8; secp256k1_sys::MUSIG_SECNONCE_SIZE]) -> Self {
         SecretNonce(ffi::MusigSecNonce::dangerous_from_bytes(array))
     }
 }
@@ -714,9 +725,9 @@ impl fmt::Display for PublicNonce {
 impl core::str::FromStr for PublicNonce {
     type Err = ParseError;
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        let mut res = [0u8; ffi::MUSIG_PUBNONCE_SERIALIZED_LEN];
+        let mut res = [0u8; PUBNONCE_SERIALIZED_SIZE];
         match from_hex(s, &mut res) {
-            Ok(ffi::MUSIG_PUBNONCE_SERIALIZED_LEN) => PublicNonce::from_byte_array(&res),
+            Ok(PUBNONCE_SERIALIZED_SIZE) => PublicNonce::from_byte_array(&res),
             _ => Err(ParseError::MalformedArg),
         }
     }
@@ -744,7 +755,7 @@ impl<'de> serde::Deserialize<'de> for PublicNonce {
             d.deserialize_bytes(super::serde_util::BytesVisitor::new(
                 "a raw MuSig2 public nonce",
                 |slice| {
-                    let bytes: &[u8; ffi::MUSIG_PUBNONCE_SERIALIZED_LEN] =
+                    let bytes: &[u8; PUBNONCE_SERIALIZED_SIZE] =
                         slice.try_into().map_err(|_| ParseError::MalformedArg)?;
 
                     Self::from_byte_array(bytes)
@@ -756,8 +767,8 @@ impl<'de> serde::Deserialize<'de> for PublicNonce {
 
 impl PublicNonce {
     /// Serialize a PublicNonce
-    pub fn serialize(&self) -> [u8; ffi::MUSIG_PUBNONCE_SERIALIZED_LEN] {
-        let mut data = [0; ffi::MUSIG_PUBNONCE_SERIALIZED_LEN];
+    pub fn serialize(&self) -> [u8; PUBNONCE_SERIALIZED_SIZE] {
+        let mut data = [0; PUBNONCE_SERIALIZED_SIZE];
         unsafe {
             if ffi::secp256k1_musig_pubnonce_serialize(
                 ffi::secp256k1_context_no_precomp,
@@ -778,9 +789,7 @@ impl PublicNonce {
     /// # Errors:
     ///
     /// - MalformedArg: If the [`PublicNonce`] is 132 bytes, but out of curve order
-    pub fn from_byte_array(
-        data: &[u8; ffi::MUSIG_PUBNONCE_SERIALIZED_LEN],
-    ) -> Result<Self, ParseError> {
+    pub fn from_byte_array(data: &[u8; PUBNONCE_SERIALIZED_SIZE]) -> Result<Self, ParseError> {
         let mut pub_nonce = MaybeUninit::<ffi::MusigPubNonce>::uninit();
         unsafe {
             if ffi::secp256k1_musig_pubnonce_parse(
@@ -831,9 +840,9 @@ impl fmt::Display for AggregatedNonce {
 impl core::str::FromStr for AggregatedNonce {
     type Err = ParseError;
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        let mut res = [0u8; ffi::MUSIG_AGGNONCE_SERIALIZED_LEN];
+        let mut res = [0u8; AGGNONCE_SERIALIZED_SIZE];
         match from_hex(s, &mut res) {
-            Ok(ffi::MUSIG_AGGNONCE_SERIALIZED_LEN) => AggregatedNonce::from_byte_array(&res),
+            Ok(AGGNONCE_SERIALIZED_SIZE) => AggregatedNonce::from_byte_array(&res),
             _ => Err(ParseError::MalformedArg),
         }
     }
@@ -861,7 +870,7 @@ impl<'de> serde::Deserialize<'de> for AggregatedNonce {
             d.deserialize_bytes(super::serde_util::BytesVisitor::new(
                 "a raw MuSig2 aggregated nonce",
                 |slice| {
-                    let bytes: &[u8; ffi::MUSIG_AGGNONCE_SERIALIZED_LEN] =
+                    let bytes: &[u8; AGGNONCE_SERIALIZED_SIZE] =
                         slice.try_into().map_err(|_| ParseError::MalformedArg)?;
 
                     Self::from_byte_array(bytes)
@@ -941,8 +950,8 @@ impl AggregatedNonce {
     }
 
     /// Serialize a AggregatedNonce into a 66 bytes array.
-    pub fn serialize(&self) -> [u8; ffi::MUSIG_AGGNONCE_SERIALIZED_LEN] {
-        let mut data = [0; ffi::MUSIG_AGGNONCE_SERIALIZED_LEN];
+    pub fn serialize(&self) -> [u8; AGGNONCE_SERIALIZED_SIZE] {
+        let mut data = [0; AGGNONCE_SERIALIZED_SIZE];
         unsafe {
             if ffi::secp256k1_musig_aggnonce_serialize(
                 ffi::secp256k1_context_no_precomp,
@@ -963,9 +972,7 @@ impl AggregatedNonce {
     /// # Errors:
     ///
     /// - MalformedArg: If the byte slice is 66 bytes, but the [`AggregatedNonce`] is invalid
-    pub fn from_byte_array(
-        data: &[u8; ffi::MUSIG_AGGNONCE_SERIALIZED_LEN],
-    ) -> Result<Self, ParseError> {
+    pub fn from_byte_array(data: &[u8; AGGNONCE_SERIALIZED_SIZE]) -> Result<Self, ParseError> {
         let mut aggnonce = MaybeUninit::<ffi::MusigAggNonce>::uninit();
         unsafe {
             if ffi::secp256k1_musig_aggnonce_parse(