[❄] Add SharedKey::grind_fingerprint (#230)

LLFourn · web-flow · commit af48ba1b7d6c · 2025-08-28T13:00:17.000+10:00
So we can do fingerprint grinding outside of chilldkg module.
diff --git a/schnorr_fun/src/frost/chilldkg/encpedpop.rs b/schnorr_fun/src/frost/chilldkg/encpedpop.rs
@@ -216,82 +216,45 @@ impl AggKeygenInput {
             .ok_or("the shared secret was zero")
     }
 
-    /// Grinds all polynomial coefficients to achieve a fingerprint by rejection sampling.
-    /// This is meant to be run by the coordinator.
+    /// Embeds a proof-of-work `fingerprint` into the aggregated polynomial.
     ///
-    /// This method modifies each non-constant coefficient of the polynomial through group
-    /// addition until the running hash (computed by sequentially incorporating coefficients)
-    /// has the required number of leading zero bits at each step.
+    /// This coordinator-only operation modifies the DKG output to include
+    /// a verifiable proof of work by grinding the polynomial coefficients.
+    /// The `fingerprint` specifies the required difficulty (number of leading
+    /// zero bits) and an optional tag to include in the hash.
     ///
-    /// The fingerprint is tied to the specific public key by including it in the hash.
+    /// The process:
+    /// 1. Grinds the shared key's polynomial to achieve the fingerprint
+    /// 2. Updates the aggregated polynomial with the ground coefficients
+    /// 3. Homomorphically applies the same tweaks to all encrypted shares
     ///
-    /// ## Parameters
-    /// - `fingerprint`: The fingerprint configuration specifying difficulty and tag
-    ///
-    /// ## Security
-    /// This modification does not affect the security of the DKG as it only modifies
-    /// non-constant polynomial coefficients which are malleable by the coordinator.
+    /// This modification preserves the security of the DKG because:
+    /// - The shared secret (constant term) remains unchanged
+    /// - Only non-constant coefficients are modified, which are already
+    ///   malleable by the coordinator
+    /// - The homomorphic property ensures all shares remain consistent
+    /// - Participants can verify the fingerprint matches the claimed difficulty
     pub fn grind_fingerprint<H: Hash32>(&mut self, fingerprint: Fingerprint) {
         if self.inner.agg_poly.is_empty() {
             return;
         }
 
-        // Get the public key (first coefficient) by aggregating key contributions
-        let public_key = self
-            .inner
-            .key_contrib
-            .iter()
-            .fold(Point::zero(), |agg, (point, _)| g!(agg + point))
-            .normalize();
-
-        // Start with hash including the tag with length prefix
-        let mut hash_state = H::default();
-        if !fingerprint.tag.is_empty() {
-            hash_state = hash_state.add([fingerprint.tag.len() as u8]);
-            hash_state = hash_state.add(fingerprint.tag.as_bytes());
-        }
-        hash_state = hash_state.add(public_key);
-
-        let mut tweaks = Vec::with_capacity(self.inner.agg_poly.len());
-
-        // Grind each coefficient in sequence, note that agg_poly only
-        // contains the non-constant coefficients.
-        for coeff_index in 0..self.inner.agg_poly.len() {
-            let mut total_tweak = Scalar::<Public, Zero>::zero();
-            let original_coeff = self.inner.agg_poly[coeff_index];
-            let mut current_coeff = original_coeff;
-
-            loop {
-                // Clone the hash state from previous coefficients and add current one
-                let hash = hash_state.clone().add(current_coeff);
-                // Check if hash has required number of leading zero bits
-                let hash_bytes: [u8; 32] = hash.clone().finalize_fixed().into();
-                if Fingerprint::leading_zero_bits(&hash_bytes[..])
-                    >= fingerprint.bit_length as usize
-                {
-                    // Update hash_state for next coefficient because the next coefficient hash
-                    // includes the current one.
-                    hash_state = hash;
-                    break;
-                }
-
-                // Add one more G to the coefficient
-                total_tweak += s!(1);
-                current_coeff = g!(current_coeff + G).normalize();
-            }
-
-            // Apply the final tweak to the polynomial coefficient
-            self.inner.agg_poly[coeff_index] = current_coeff;
-            tweaks.push(total_tweak);
-        }
-
-        // Apply all tweaks to encrypted shares at once
-        for (share_index, (_enc_key, encrypted_share)) in &mut self.encrypted_shares {
-            let mut power = *share_index;
-            for tweak in &tweaks {
-                *encrypted_share += s!(tweak * power).public();
-                power *= share_index;
-            }
+        let mut shared_key = self.shared_key();
+        let tweak_poly = shared_key.grind_fingerprint::<H>(fingerprint);
+        // replace our poly with the one that has the fingerprint
+        self.inner.agg_poly = shared_key.point_polynomial()[1..].to_vec();
+        debug_assert!(self.shared_key().check_fingerprint::<H>(&fingerprint));
+
+        for (share_index, (_encryption_key, encrypted_secret_share)) in &mut self.encrypted_shares {
+            // 💡 The share encryption is homomorphic so we can apply the tweak
+            // operations the same way as if the coordinator had a local copy of
+            // the the unencrypted secret share.
+            let mut tmp = SecretShare {
+                index: *share_index,
+                share: *encrypted_secret_share,
+            };
+            tmp.homomorphic_poly_add(&tweak_poly);
+            *encrypted_secret_share = tmp.share;
         }
     }
 }
diff --git a/schnorr_fun/src/frost/share.rs b/schnorr_fun/src/frost/share.rs
@@ -50,12 +50,12 @@ use secp256kfun::{poly, prelude::*};
 /// [`bech32m`]: https://bips.xyz/350
 
 #[derive(Copy, Clone, PartialEq, Eq)]
-pub struct SecretShare {
+pub struct SecretShare<S = Secret> {
     /// The scalar index for this secret share, usually this is a small number but it can take any
     /// value (other than 0).
     pub index: ShareIndex,
     /// The secret scalar which is the output of the polynomial evaluated at `index`
-    pub share: Scalar<Secret, Zero>,
+    pub share: Scalar<S, Zero>,
 }
 
 impl SecretShare {
@@ -68,7 +68,9 @@ impl SecretShare {
 
         poly::scalar::interpolate_and_eval_poly_at_0(&index_and_secret[..])
     }
+}
 
+impl<S: Secrecy> SecretShare<S> {
     /// Encodes the secret share to 64 bytes. The first 32 is the index and the second 32 is the
     /// secret.
     pub fn to_bytes(&self) -> [u8; 64] {
@@ -94,10 +96,26 @@ impl SecretShare {
             image: g!(self.share * G).normalize(),
         }
     }
+
+    /// Homomorphically adds a scalar polynomial to this secret share.
+    ///
+    /// Given a scalar polynomial, evaluates it at this share's index and adds
+    /// the result to the share value. This operation preserves the polynomial
+    /// relationship between shares due to the homomorphic properties of
+    /// Shamir's secret sharing.
+    ///
+    /// Afterwards the share so that it's no longer valid with original
+    /// [`SharedKey`] polynomial but is valid instead for the sum of the
+    /// original polynomial and the new one.
+    ///
+    /// [`Sharedkey`]: crate::frost::SharedKey
+    pub fn homomorphic_poly_add(&mut self, poly: &[Scalar<Public, Zero>]) {
+        self.share += poly::scalar::eval(poly, self.index);
+    }
 }
 
 secp256kfun::impl_fromstr_deserialize! {
-    name => "secp256k1 FROST share",
+    name => "secp256k1 FROST secret share",
     fn from_bytes(bytes: [u8;64]) -> Option<SecretShare> {
         SecretShare::from_bytes(bytes)
     }
@@ -234,6 +252,27 @@ impl<Z: ZeroChoice, T: PointType> PairedSecretShare<T, Z> {
         }
     }
 
+    /// Homomorphically adds a scalar polynomial to this paired secret share.
+    ///
+    /// See [`SecretShare::homomorphic_poly_add`] for more info.
+    #[must_use]
+    pub fn homomorphic_poly_add(
+        mut self,
+        poly: &[Scalar<Public, Zero>],
+    ) -> PairedSecretShare<Normal, Zero> {
+        // Apply the polynomial to the secret share
+        self.secret_share.homomorphic_poly_add(poly);
+        let pk_tweak = poly.first().copied().unwrap_or(Scalar::zero());
+
+        // Update the public key by the constant term
+        let public_key = g!(self.public_key + pk_tweak * G).normalize();
+
+        PairedSecretShare {
+            secret_share: self.secret_share,
+            public_key,
+        }
+    }
+
     /// Converts a `PairedSecretShare<T, Zero>` to a `PairedSecretShare<T, NonZero>`.
     ///
     /// If the paired shared key *was* actually zero ([`is_zero`] returns true) it returns `None`.
diff --git a/schnorr_fun/src/frost/shared_key.rs b/schnorr_fun/src/frost/shared_key.rs
@@ -1,7 +1,7 @@
 use super::{PairedSecretShare, SecretShare, ShareImage, ShareIndex, VerificationShare};
 use alloc::vec::Vec;
 use core::{marker::PhantomData, ops::Deref};
-use secp256kfun::{poly, prelude::*};
+use secp256kfun::{hash::Hash32, poly, prelude::*};
 
 /// A polynomial where the first coefficient (constant term) is the image of a secret `Scalar` that
 /// has been shared in a [Shamir's secret sharing] structure.
@@ -21,7 +21,7 @@ pub struct SharedKey<T = Normal, Z = NonZero> {
     ty: PhantomData<(T, Z)>,
 }
 
-impl<T: PointType, Z: ZeroChoice> SharedKey<T, Z> {
+impl<T: Normalized, Z: ZeroChoice> SharedKey<T, Z> {
     /// "pair" a secret share that belongs to this shared key so you can keep track of tweaks to the
     /// public key and the secret share together.
     ///
@@ -186,35 +186,32 @@ impl<T: PointType, Z: ZeroChoice> SharedKey<T, Z> {
         }
     }
 
-    /// Checks if the polynomial coefficients contain a fingerprint by verifying that
-    /// each coefficient (when hashed with all previous coefficients) has the required
-    /// number of leading zero bits.
+    /// Checks if the polynomial coefficients contain the specified `fingerprint`.
     ///
-    /// This is useful for detecting if shares come from the same DKG session or if
-    /// they have been corrupted.
+    /// Verifies that each non-constant coefficient, when hashed together with all
+    /// previous coefficients, produces a hash with at least `fingerprint.bit_length`
+    /// leading zero bits. This allows detection of shares from the same DKG session
+    /// and helps identify corrupted or mismatched shares.
     ///
-    /// ## Parameters
-    /// - `fingerprint`: The expected fingerprint configuration
-    ///
-    /// ## Returns
-    /// `true` if all coefficients match the fingerprint pattern, `false` otherwise
+    /// Returns `true` if all coefficients match the fingerprint pattern, `false`
+    /// if any coefficient fails to meet the difficulty requirement.
     pub fn check_fingerprint<H: crate::fun::hash::Hash32>(
         &self,
         fingerprint: &Fingerprint,
     ) -> bool {
         use crate::fun::hash::HashAdd;
 
-        if self.point_polynomial.is_empty() {
+        // the fingerprint is only placed on the non-constant coefficients so it
+        // can't be detected with a length 1 polynomial
+        if self.point_polynomial.len() <= 1 {
             return true;
         }
 
-        // Start with hash including the tag with length prefix
-        let mut hash_state = H::default();
-        if !fingerprint.tag.is_empty() {
-            hash_state = hash_state.add([fingerprint.tag.len() as u8]);
-            hash_state = hash_state.add(fingerprint.tag.as_bytes());
-        }
-        hash_state = hash_state.add(self.point_polynomial[0]);
+        let mut hash_state = H::default()
+            .add([fingerprint.tag.len() as u8])
+            .add(fingerprint.tag.as_bytes())
+            // the public key is unmolested by the fingerprint
+            .add(self.point_polynomial[0]);
 
         // Check each non-constant coefficient
         for i in 1..self.point_polynomial.len() {
@@ -231,6 +228,72 @@ impl<T: PointType, Z: ZeroChoice> SharedKey<T, Z> {
 
         true
     }
+
+    /// Grinds polynomial coefficients to embed the specified `fingerprint` through
+    /// proof-of-work.
+    ///
+    /// For each non-constant coefficient, repeatedly adds the generator point `G`
+    /// until the cumulative hash (including the tag, public key, and all previous
+    /// coefficients) has at least `fingerprint.bit_length` leading zero bits.
+    /// This process modifies the polynomial while preserving the shared secret.
+    ///
+    /// Returns a scalar polynomial where the constant term is always zero
+    /// and the remaining coefficients indicate how many times `G` was added
+    /// to each polynomial coefficient. This polynomial can be added to secret
+    /// shares using [`SecretShare::homomorphic_poly_add`] to maintain consistency.
+    ///
+    /// The computational cost increases exponentially with `bit_length`: each
+    /// additional bit doubles the expected work required.
+    pub fn grind_fingerprint<H: Hash32>(
+        &mut self,
+        fingerprint: Fingerprint,
+    ) -> Vec<Scalar<Public, Zero>> {
+        let mut tweaks = Vec::with_capacity(self.threshold());
+        // We don't mutate the first coefficient
+        tweaks.push(Scalar::<Public, _>::zero());
+
+        if self.point_polynomial.len() <= 1 {
+            // only mutate non-constant terms
+            return tweaks;
+        }
+
+        use secp256kfun::hash::HashAdd;
+        let mut hash_state = H::default()
+            .add([fingerprint.tag.len() as u8])
+            .add(fingerprint.tag.as_bytes())
+            // the public key is unmolested from the fingerprint grinding
+            .add(self.point_polynomial[0]);
+
+        for coeff in &mut self.point_polynomial[1..] {
+            let mut total_tweak = Scalar::<Public, Zero>::zero();
+            let mut current_coeff = *coeff;
+
+            loop {
+                // Clone the hash state from previous coefficients and add current one
+                let hash = hash_state.clone().add(current_coeff);
+                // Check if hash has required number of leading zero bits
+                let hash_bytes: [u8; 32] = hash.clone().finalize_fixed().into();
+                if Fingerprint::leading_zero_bits(&hash_bytes[..])
+                    >= fingerprint.bit_length as usize
+                {
+                    // Update hash_state for next coefficient because the next coefficient hash
+                    // includes the current one.
+                    hash_state = hash;
+                    break;
+                }
+
+                // Add one more G to the coefficient
+                total_tweak += s!(1);
+                current_coeff = g!(current_coeff + G).normalize();
+            }
+
+            // Apply the final tweak to the polynomial coefficient
+            *coeff = current_coeff;
+            tweaks.push(total_tweak);
+        }
+
+        tweaks
+    }
 }
 
 impl SharedKey {
@@ -376,8 +439,13 @@ bincode::impl_borrow_decode!(SharedKey<EvenY, NonZero>);
 
 /// Configuration for polynomial fingerprinting in DKG protocols.
 ///
-/// This allows coordinators to embed identifying information into polynomial coefficients
-/// to help detect when shares from different DKG sessions are mixed.
+/// A `Fingerprint` allows coordinators to embed proof-of-work into polynomial
+/// coefficients during distributed key generation. This helps detect when shares
+/// from different DKG sessions are accidentally mixed and provides resistance
+/// against resource exhaustion attacks.
+///
+/// The fingerprint is computed by hashing the public key with each subsequent
+/// coefficient, requiring each hash to have a minimum number of leading zero bits.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct Fingerprint {
     /// Number of leading zero bits required in the hash
