refactor(proof-builder): migrate to new Protocol structure and add documentation

- refactor: update proof_builder to use the new generalized Protocol structure
- docs: add comprehensive documentation for updated proof_builder functionality

Author: nougzarm

src/fiat_shamir.rs

@@ -18,16 +18,25 @@ use crate::traits::{CompactProtocol, SigmaProtocol};
 
 use rand::{CryptoRng, RngCore};
 
+/// A trait that allows sigma protocols to have a Fiat-Shamir transform to have a
+/// deterministic challenge generation function.
+///
+/// Challenge generation occurs in two stages:
+/// - `push_commitment`: absorbs commitments to feed the codec
+/// - `get_challenge`: extracts the challenge from the codec
+///
+/// # Type Parameters
+/// - `C`: the codec used for the underlying determenitis function.
 pub trait FiatShamir<C: Codec>: SigmaProtocol {
     fn push_commitment(&self, codec: &mut C, commitment: &Self::Commitment);
 
     fn get_challenge(&self, codec: &mut C) -> Result<Self::Challenge, Error>;
 }
 
-/// Trait for accessing the underlying group morphism in a Sigma protocol.
+/// Structures implementing this trait must implicitly have one or more underlying [`GroupMorphism`] elements.
+///
+/// This trait allows the data of the morphisms underlying the structure to be absorbed into a codec.
 pub trait HasGroupMorphism {
-    /// Absorbs the morphism structure into a codec.
-    /// Only compatible with 64-bit platforms
     fn absorb_morphism_structure<C: Codec>(&self, codec: &mut C) -> Result<(), Error>;
 }
 
@@ -60,7 +69,6 @@ where
     pub sigmap: P,
 }
 
-// TODO: Write a serialization of the morphism to the transcript.
 impl<P, C> NISigmaProtocol<P, C>
 where
     P: SigmaProtocol<Challenge: PartialEq> + FiatShamir<C>,

src/proof_builder.rs

@@ -11,15 +11,16 @@
 //! - Allocates scalar and point variables for constructing group equations.
 //! - Appends equations representing statements to be proven.
 //! - Supports element assignment to statement variables.
+//! - Composes multiple protocols via AND and OR connections
 //! - Offers one-shot `prove` and `verify` methods.
 
-use crate::{codec::ShakeCodec, fiat_shamir::NISigmaProtocol, schnorr_protocol::SchnorrProtocol};
+use crate::{codec::ShakeCodec, fiat_shamir::NISigmaProtocol, protocol::Protocol};
 
-/// An alias for a [`SchnorrProtocol`] over a [`GroupMorphismPreimage`] and applies
+/// An alias for a [`Protocol`] on [`GroupMorphismPreimage`] and applies
 /// the Fiat-Shamir transform via [`NISigmaProtocol`].
 ///
 /// # Type Parameters
 /// - `G`: A group that implements both [`Group`] and [`GroupEncoding`].
 ///
 /// [`GroupMorphismPreimage`]: crate::GroupMorphismPreimage
-pub type NISchnorr<G> = NISigmaProtocol<SchnorrProtocol<G>, ShakeCodec<G>>;
+pub type NIProtocol<G> = NISigmaProtocol<Protocol<G>, ShakeCodec<G>>;

src/protocol.rs

@@ -1,4 +1,4 @@
-//! Implementation of a structure [`Protocol`] aimed at generalizing the SchnorrProtocol 
+//! Implementation of a structure [`Protocol`] aimed at generalizing the SchnorrProtocol
 //! using the compositions of the latter via AND and OR links
 //!
 //! This structure allows, for example, the construction of protocols of the form:
@@ -22,6 +22,12 @@ use crate::{
     traits::{SigmaProtocol, SigmaProtocolSimulator},
 };
 
+/// A protocol proving knowledge of a witness for a composition of SchnorrProtocol's.
+///
+/// This implementation generalizes [`SchnorrProtocol`] by using AND/OR links.
+///
+/// # Type Parameters
+/// - `G`: A cryptographic group implementing [`Group`] and [`GroupEncoding`].
 #[derive(Clone)]
 pub enum Protocol<G: Group + GroupEncoding> {
     Simple(SchnorrProtocol<G>),
@@ -47,13 +53,15 @@ where
     }
 }
 
+// Structure representing the Commitment type of Protocol as SigmaProtocol
 #[derive(Clone)]
 pub enum ProtocolCommitment<G: Group + GroupEncoding> {
     Simple(<SchnorrProtocol<G> as SigmaProtocol>::Commitment),
     And(Vec<ProtocolCommitment<G>>),
     Or(Vec<ProtocolCommitment<G>>),
 }
 
+// Structure representing the ProverState type of Protocol as SigmaProtocol
 #[derive(Clone)]
 pub enum ProtocolProverState<G: Group + GroupEncoding> {
     Simple(<SchnorrProtocol<G> as SigmaProtocol>::ProverState),
@@ -65,19 +73,22 @@ pub enum ProtocolProverState<G: Group + GroupEncoding> {
     ),
 }
 
+// Structure representing the Response type of Protocol as SigmaProtocol
 #[derive(Clone)]
 pub enum ProtocolResponse<G: Group + GroupEncoding> {
     Simple(<SchnorrProtocol<G> as SigmaProtocol>::Response),
     And(Vec<ProtocolResponse<G>>),
     Or(Vec<ProtocolChallenge<G>>, Vec<ProtocolResponse<G>>),
 }
 
+// Structure representing the Witness type of Protocol as SigmaProtocol
 pub enum ProtocolWitness<G: Group + GroupEncoding> {
     Simple(<SchnorrProtocol<G> as SigmaProtocol>::Witness),
     And(Vec<ProtocolWitness<G>>),
     Or(usize, Vec<ProtocolWitness<G>>),
 }
 
+// Structure representing the Challenge type of Protocol as SigmaProtocol
 type ProtocolChallenge<G> = <SchnorrProtocol<G> as SigmaProtocol>::Challenge;
 
 impl<G: Group + GroupEncoding> SigmaProtocol for Protocol<G> {

src/schnorr_protocol.rs

@@ -417,6 +417,11 @@ where
     C: Codec<Challenge = <G as Group>::Scalar>,
     G: Group + GroupEncoding,
 {
+    /// Absorbs commitments into the codec for future use of the codec
+    ///
+    /// # Parameters
+    /// - `codec`: the Codec that absorbs commitments
+    /// - `commitment`: a commitment of SchnorrProtocol
     fn push_commitment(&self, codec: &mut C, commitment: &Self::Commitment) {
         let mut data = Vec::new();
         for commit in commitment {
@@ -425,6 +430,13 @@ where
         codec.prover_message(&data);
     }
 
+    /// Generates a challenge from the codec that absorbed the commitments
+    ///
+    /// # Parameters
+    /// - `codec`: the Codec from which the challenge is generated
+    ///
+    /// # Returns
+    /// - A `challenge`` that can be used during a non-interactive protocol
     fn get_challenge(&self, codec: &mut C) -> Result<Self::Challenge, Error> {
         Ok(codec.verifier_challenge())
     }