[❄] Add ShareImage (#226)

- Remove public key from VerificationShare which was only used to do a
sanity check. Instead I tried to improve documentation.

Author: LLFourn

schnorr_fun/src/frost/session.rs

@@ -55,23 +55,21 @@ impl CoordinatorSignSession {
     ///
     /// The `verification_share` is usually derived from either [`SharedKey::verification_share`] or
     /// [`PairedSecretShare::verification_share`].
+    ///
+    /// **Important**: The verification share must come from the same `SharedKey` that this session
+    /// was created for. If the key has been tweaked or modified since the session was created,
+    /// the verification will fail. Each verification share is tied to a specific polynomial and
+    /// cannot be reused across different keys or tweaked versions of the same key.
     pub fn verify_signature_share(
         &self,
-        verification_share: VerificationShare<impl PointType>,
+        verification_share: VerificationShare,
         signature_share: SignatureShare,
     ) -> Result<(), SignatureShareInvalid> {
-        let X = verification_share.share_image;
-        let index = verification_share.index;
-
-        // We need to know the verification share was generated against the session's key for
-        // further validity to have any meaning.
-        if verification_share.public_key != self.public_key() {
-            return Err(SignatureShareInvalid { index });
-        }
+        let X = verification_share.0.image;
+        let index = verification_share.0.index;
 
         let s = signature_share;
-        let lambda =
-            poly::eval_basis_poly_at_0(verification_share.index, self.nonces.keys().cloned());
+        let lambda = poly::eval_basis_poly_at_0(index, self.nonces.keys().cloned());
         let c = &self.challenge;
         let b = &self.binding_coeff;
         let [R1, R2] = self

schnorr_fun/src/frost/share.rs

@@ -1,3 +1,4 @@
+use super::ShareIndex;
 use secp256kfun::{poly, prelude::*};
 /// A *[Shamir secret share]*.
 ///
@@ -87,8 +88,11 @@ impl SecretShare {
     }
 
     /// Get the image of the secret share.
-    pub fn share_image(&self) -> Point<NonNormal, Public, Zero> {
-        g!(self.share * G)
+    pub fn share_image(&self) -> ShareImage {
+        ShareImage {
+            index: self.index,
+            image: g!(self.share * G).normalize(),
+        }
     }
 }
 
@@ -265,12 +269,12 @@ impl PairedSecretShare<Normal> {
 
 impl PairedSecretShare<EvenY> {
     /// Get the verification for the inner secret share.
-    pub fn verification_share(&self) -> VerificationShare<NonNormal> {
-        VerificationShare {
+    pub fn verification_share(&self) -> VerificationShare {
+        VerificationShare(ShareImage {
             index: self.index(),
-            share_image: self.secret_share.share_image(),
-            public_key: self.public_key,
-        }
+            // we don't use SecretShare::share_image because it normalizes which is unecessary here
+            image: g!(self.secret_share.share * G),
+        })
     }
 }
 
@@ -286,14 +290,7 @@ impl PairedSecretShare<EvenY> {
 ///
 /// [`share_image`]: SecretShare::share_image
 #[derive(Clone, Copy, Debug, PartialEq)]
-pub struct VerificationShare<T: PointType> {
-    /// The index of the share in the secret sharing
-    pub index: ShareIndex,
-    /// The image of the secret share
-    pub share_image: Point<T, Public, Zero>,
-    /// The public key that this is a share of
-    pub public_key: Point<EvenY>,
-}
+pub struct VerificationShare(pub(crate) ShareImage<NonNormal>);
 
 #[cfg(feature = "share_backup")]
 mod share_backup {
@@ -501,7 +498,45 @@ mod share_backup {
 #[cfg(feature = "share_backup")]
 pub use share_backup::BackupDecodeError;
 
-use super::ShareIndex;
+/// The public image of a secret share, consisting of an index and the corresponding point.
+///
+/// A `ShareImage` represents the public information about a share: the index at
+/// which the polynomial was evaluated and the image of the secret share. This
+/// can be shared publicly and used to reconstruct the shared public key and the polynomial
+/// from a threshold number of share images using [`SharedKey::from_share_images`].
+///
+/// [`SharedKey::from_share_images`]: crate::frost::SharedKey::from_share_images
+#[derive(Clone, Copy, Debug)]
+#[cfg_attr(
+    feature = "bincode",
+    derive(bincode::Encode, bincode::Decode),
+    bincode(
+        encode_bounds = "Point<T, Public, Zero>: bincode::Encode",
+        decode_bounds = "Point<T, Public, Zero>: bincode::Decode<__Context>",
+        borrow_decode_bounds = "Point<T, Public, Zero>: bincode::BorrowDecode<'__de, __Context>"
+    )
+)]
+#[cfg_attr(
+    feature = "serde",
+    derive(crate::fun::serde::Deserialize, crate::fun::serde::Serialize),
+    serde(crate = "crate::fun::serde"),
+    serde(bound(
+        serialize = "Point<T, Public, Zero>: crate::fun::serde::Serialize",
+        deserialize = "Point<T, Public, Zero>: crate::fun::serde::Deserialize<'de>"
+    ))
+)]
+pub struct ShareImage<T = Normal> {
+    /// The index where the polynomial was evaluated
+    pub index: ShareIndex,
+    /// The image of the secret share (G * share_scalar)
+    pub image: Point<T, Public, Zero>,
+}
+
+impl<T: PointType> PartialEq for ShareImage<T> {
+    fn eq(&self, other: &Self) -> bool {
+        self.index == other.index && self.image == other.image
+    }
+}
 
 #[cfg(test)]
 mod test {

schnorr_fun/src/frost/shared_key.rs

@@ -1,4 +1,4 @@
-use super::{PairedSecretShare, SecretShare, ShareIndex, VerificationShare};
+use super::{PairedSecretShare, SecretShare, ShareImage, ShareIndex, VerificationShare};
 use alloc::vec::Vec;
 use core::{marker::PhantomData, ops::Deref};
 use secp256kfun::{poly, prelude::*};
@@ -179,8 +179,11 @@ impl<T: PointType, Z: ZeroChoice> SharedKey<T, Z> {
     /// contains a share image).
     ///
     /// [`verification_share`]: Self::verification_share
-    pub fn share_image(&self, index: ShareIndex) -> Point<NonNormal, Public, Zero> {
-        poly::point::eval(&self.point_polynomial, index)
+    pub fn share_image(&self, index: ShareIndex) -> ShareImage {
+        ShareImage {
+            index,
+            image: poly::point::eval(&self.point_polynomial, index).normalize(),
+        }
     }
 
     /// Checks if the polynomial coefficients contain a fingerprint by verifying that
@@ -268,7 +271,7 @@ impl SharedKey<Normal, Zero> {
     ///
     /// If all the share images are correct and you have at least a threshold of them then you'll
     /// get the original shared key. If you put in a wrong share you won't get the right answer and
-    /// there will be no error.
+    /// there will be **no error**.
     ///
     /// Note that a "share image" is not a concept that we really use in the core of this library
     /// but you can get one from a share with [`SecretShare::share_image`].
@@ -277,26 +280,29 @@ impl SharedKey<Normal, Zero> {
     ///
     /// ⚠ You can't just take any points you want and pass them in here and hope it's secure.
     /// They need to be from a securely generated key.
-    pub fn from_share_images(
-        shares: &[(ShareIndex, Point<impl PointType, Public, impl ZeroChoice>)],
-    ) -> Self {
-        let poly = poly::point::interpolate(shares);
+    pub fn from_share_images(share_images: impl IntoIterator<Item = ShareImage>) -> Self {
+        let shares: Vec<(ShareIndex, Point<Normal, Public, Zero>)> = share_images
+            .into_iter()
+            .map(|img| (img.index, img.image))
+            .collect();
+        let poly = poly::point::interpolate(&shares);
         let poly = poly::point::normalize(poly);
         SharedKey::from_inner(poly.collect())
     }
 }
 
 impl SharedKey<EvenY> {
-    /// The verification shares of each party in the key.
+    /// Creates a verification share for a party at the given index.
     ///
-    /// The verification share is the image of their secret share.
-    pub fn verification_share(&self, index: ShareIndex) -> VerificationShare<NonNormal> {
-        let share_image = poly::point::eval(&self.point_polynomial, index);
-        VerificationShare {
-            index,
-            share_image,
-            public_key: self.public_key(),
-        }
+    /// The verification share is the image of the party's secret share evaluated from this key's polynomial.
+    ///
+    /// **Important**: The returned `VerificationShare` can only be used to verify signatures
+    /// against the specific `SharedKey` that created it. You must ensure you're verifying
+    /// against the correct shared key. If the polynomial has been tweaked or modified,
+    /// you'll need to get a new verification share from the modified key.
+    pub fn verification_share(&self, index: ShareIndex) -> VerificationShare {
+        let image = poly::point::eval(&self.point_polynomial, index);
+        VerificationShare(ShareImage { index, image })
     }
 }