From f27fd59fa6149b12e9b51e5da46559ed6f0e7757 Mon Sep 17 00:00:00 2001
From: Luke Parker <lukeparker5132@gmail.com>
Date: Mon, 29 Sep 2025 23:24:53 -0400
Subject: [PATCH] Update documentation within `modular-frost`

Resolves https://github.com/serai-dex/serai/issues/675.
---
 crypto/frost/src/algorithm.rs | 16 ++++++++++++----
 crypto/frost/src/sign.rs      |  6 ++++++
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/crypto/frost/src/algorithm.rs b/crypto/frost/src/algorithm.rs
index 26847c43..721b4afe 100644
--- a/crypto/frost/src/algorithm.rs
+++ b/crypto/frost/src/algorithm.rs
@@ -28,8 +28,10 @@ impl<A: Send + Sync + Clone + PartialEq + Debug + WriteAddendum> Addendum for A
 
 /// Algorithm trait usable by the FROST signing machine to produce signatures..
 pub trait Algorithm<C: Curve>: Send + Sync {
-  /// The transcript format this algorithm uses. This likely should NOT be the IETF-compatible
-  /// transcript included in this crate.
+  /// The transcript format this algorithm uses.
+  ///
+  /// This MUST NOT be the IETF-compatible transcript included in this crate UNLESS this is an
+  /// IETF-specified ciphersuite.
   type Transcript: Sync + Clone + Debug + Transcript;
   /// Serializable addendum, used in algorithms requiring more data than just the nonces.
   type Addendum: Addendum;
@@ -69,8 +71,10 @@ pub trait Algorithm<C: Curve>: Send + Sync {
   ) -> Result<(), FrostError>;
 
   /// Sign a share with the given secret/nonce.
+  ///
   /// The secret will already have been its lagrange coefficient applied so it is the necessary
   /// key share.
+  ///
   /// The nonce will already have been processed into the combined form d + (e * p).
   fn sign_share(
     &mut self,
@@ -85,6 +89,7 @@ pub trait Algorithm<C: Curve>: Send + Sync {
   fn verify(&self, group_key: C::G, nonces: &[Vec<C::G>], sum: C::F) -> Option<Self::Signature>;
 
   /// Verify a specific share given as a response.
+  ///
   /// This function should return a series of pairs whose products should sum to zero for a valid
   /// share. Any error raised is treated as the share being invalid.
   #[allow(clippy::type_complexity, clippy::result_unit_err)]
@@ -99,8 +104,10 @@ pub trait Algorithm<C: Curve>: Send + Sync {
 mod sealed {
   pub use super::*;
 
-  /// IETF-compliant transcript. This is incredibly naive and should not be used within larger
-  /// protocols.
+  /// IETF-compliant transcript.
+  ///
+  /// This is incredibly naive and MUST NOT be used within larger protocols. No guarantees are made
+  /// about its safety EXCEPT as used with the IETF-specified FROST ciphersuites.
   #[derive(Clone, Debug)]
   pub struct IetfTranscript(pub(crate) Vec<u8>);
   impl Transcript for IetfTranscript {
@@ -131,6 +138,7 @@ pub(crate) use sealed::IetfTranscript;
 /// HRAm usable by the included Schnorr signature algorithm to generate challenges.
 pub trait Hram<C: Curve>: Send + Sync + Clone {
   /// HRAm function to generate a challenge.
+  ///
   /// H2 from the IETF draft, despite having a different argument set (not being pre-formatted).
   #[allow(non_snake_case)]
   fn hram(R: &C::G, A: &C::G, m: &[u8]) -> C::F;
diff --git a/crypto/frost/src/sign.rs b/crypto/frost/src/sign.rs
index 25151d5a..870f0653 100644
--- a/crypto/frost/src/sign.rs
+++ b/crypto/frost/src/sign.rs
@@ -102,6 +102,7 @@ pub trait PreprocessMachine: Send {
   type SignMachine: SignMachine<Self::Signature, Preprocess = Self::Preprocess>;
 
   /// Perform the preprocessing round required in order to sign.
+  ///
   /// Returns a preprocess message to be broadcast to all participants, over an authenticated
   /// channel.
   fn preprocess<R: RngCore + CryptoRng>(self, rng: &mut R)
@@ -235,6 +236,8 @@ pub trait SignMachine<S>: Send + Sync + Sized {
   /// Takes in the participants' preprocess messages. Returns the signature share to be broadcast
   /// to all participants, over an authenticated channel. The parties who participate here will
   /// become the signing set for this session.
+  ///
+  /// The caller MUST only use preprocesses obtained via this machine's `read_preprocess` function.
   fn sign(
     self,
     commitments: HashMap<Participant, Self::Preprocess>,
@@ -421,7 +424,10 @@ pub trait SignatureMachine<S>: Send + Sync {
   fn read_share<R: Read>(&self, reader: &mut R) -> io::Result<Self::SignatureShare>;
 
   /// Complete signing.
+  ///
   /// Takes in everyone elses' shares. Returns the signature.
+  ///
+  /// The caller MUST only use shares obtained via this machine's `read_shares` function.
   fn complete(self, shares: HashMap<Participant, Self::SignatureShare>) -> Result<S, FrostError>;
 }