Deprecate ElligatorSwiftParty in favor of Party

The initial naming of ElligatorSwiftParty wasn't very descriptive, so it
will be deprecated in favor of a more descriptive `Party` enum

Author: shinghim

src/ellswift.rs

@@ -154,7 +154,7 @@ impl ElligatorSwift {
     /// ```
     /// # #[cfg(feature = "alloc")] {
     ///     use secp256k1::{
-    ///         ellswift::{ElligatorSwift, ElligatorSwiftParty},
+    ///         ellswift::{ElligatorSwift, Party},
     ///         PublicKey, SecretKey, XOnlyPublicKey, Secp256k1,
     ///     };
     ///     use core::str::FromStr;
@@ -167,8 +167,8 @@ impl ElligatorSwift {
     ///     let alice_es = ElligatorSwift::from_seckey(&secp, alice_sk, None);
     ///     let bob_es = ElligatorSwift::from_seckey(&secp, bob_sk, None);
     ///
-    ///     let alice_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, alice_sk, ElligatorSwiftParty::A, None);
-    ///     let bob_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, bob_sk, ElligatorSwiftParty::B, None);
+    ///     let alice_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, alice_sk, Party::Initiator, None);
+    ///     let bob_shared_secret = ElligatorSwift::shared_secret(alice_es, bob_es, bob_sk, Party::Responder, None);
     ///
     ///     assert_eq!(alice_shared_secret, bob_shared_secret);
     /// # }
@@ -177,18 +177,19 @@ impl ElligatorSwift {
         ellswift_a: ElligatorSwift,
         ellswift_b: ElligatorSwift,
         secret_key: SecretKey,
-        party: ElligatorSwiftParty,
+        party: impl Into<Party>,
         data: Option<&[u8]>,
     ) -> ElligatorSwiftSharedSecret {
         let mut shared_secret = [0u8; 32];
+        let p: Party = party.into();
         unsafe {
             let ret = ffi::secp256k1_ellswift_xdh(
                 ffi::secp256k1_context_no_precomp,
                 shared_secret.as_mut_c_ptr(),
                 ellswift_a.as_c_ptr(),
                 ellswift_b.as_c_ptr(),
                 secret_key.as_c_ptr(),
-                party.to_ffi_int(),
+                p.to_ffi_int(),
                 ffi::secp256k1_ellswift_xdh_hash_function_bip324,
                 data.as_c_ptr() as *mut c_void,
             );
@@ -206,22 +207,23 @@ impl ElligatorSwift {
         ellswift_a: ElligatorSwift,
         ellswift_b: ElligatorSwift,
         secret_key: SecretKey,
-        party: ElligatorSwiftParty,
+        party: impl Into<Party>,
         mut hash_function: F,
     ) -> ElligatorSwiftSharedSecret
     where
         F: FnMut([u8; 32], [u8; 64], [u8; 64]) -> ElligatorSwiftSharedSecret,
     {
         let mut shared_secret = [0u8; 32];
         let hashfp = hash_callback::<F>;
+        let p: Party = party.into();
         unsafe {
             let ret = ffi::secp256k1_ellswift_xdh(
                 ffi::secp256k1_context_no_precomp,
                 shared_secret.as_mut_c_ptr(),
                 ellswift_a.0.as_c_ptr(),
                 ellswift_b.0.as_c_ptr(),
                 secret_key.as_c_ptr(),
-                party.to_ffi_int(),
+                p.to_ffi_int(),
                 Some(hashfp),
                 &mut hash_function as *mut F as *mut c_void,
             );
@@ -291,13 +293,17 @@ impl ElligatorSwiftSharedSecret {
 /// This distinction is important because the different parties compute different
 /// hashes of the shared secret.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[deprecated(since = "0.30.0", note = "Use `Party` instead")]
+#[allow(deprecated)]
 pub enum ElligatorSwiftParty {
     /// We are the initiator of the ECDH
     A,
     /// We are the responder of the ECDH
     B,
 }
 
+#[allow(deprecated)]
+#[allow(dead_code)] // We aren't using this anymore in this library, but users might be using it
 impl ElligatorSwiftParty {
     fn to_ffi_int(self) -> c_int {
         match self {
@@ -307,6 +313,34 @@ impl ElligatorSwiftParty {
     }
 }
 
+/// Represents the two parties in ECDH
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Party {
+    /// The party that starts the key exchange or communication process
+    Initiator,
+    /// The party that responds to the initiator's communications
+    Responder,
+}
+
+#[allow(deprecated)]
+impl From<ElligatorSwiftParty> for Party {
+    fn from(value: ElligatorSwiftParty) -> Self {
+        match value {
+            ElligatorSwiftParty::A => Party::Initiator,
+            ElligatorSwiftParty::B => Party::Responder,
+        }
+    }
+}
+
+impl Party {
+    fn to_ffi_int(self) -> c_int {
+        match self {
+            Party::Initiator => 0,
+            Party::Responder => 1,
+        }
+    }
+}
+
 impl FromStr for ElligatorSwift {
     fn from_str(hex: &str) -> Result<Self, Self::Err> {
         let mut ser = [0u8; 64];
@@ -345,7 +379,7 @@ mod tests {
 
     use crate::ellswift::ElligatorSwift;
     #[cfg(all(not(secp256k1_fuzz), feature = "alloc"))]
-    use crate::ellswift::{ElligatorSwiftParty, ElligatorSwiftSharedSecret};
+    use crate::ellswift::{ElligatorSwiftSharedSecret, Party};
     #[cfg(all(not(secp256k1_fuzz), feature = "alloc"))]
     use crate::SecretKey;
     use crate::{from_hex, PublicKey, XOnlyPublicKey};
@@ -391,7 +425,7 @@ mod tests {
             ell,
             ell,
             SecretKey::from_slice(&priv32).unwrap(),
-            ElligatorSwiftParty::A,
+            Party::Initiator,
             |_, _, _| ElligatorSwiftSharedSecret([0xff; 32]),
         );
         assert_eq!(pk, ElligatorSwiftSharedSecret([0xff; 32]));
@@ -605,8 +639,7 @@ mod tests {
                 )
             };
             let sec_key = SecretKey::from_slice(&my_secret).unwrap();
-            let initiator =
-                if initiator == 0 { ElligatorSwiftParty::B } else { ElligatorSwiftParty::A };
+            let initiator = if initiator == 0 { Party::Responder } else { Party::Initiator };
 
             let shared = ElligatorSwift::shared_secret(el_a, el_b, sec_key, initiator, None);