Added documentation for the sigma module

Author: GOURIOU Lénaïck

src/toolbox/mod.rs

@@ -39,6 +39,7 @@ pub mod batch_verifier;
 pub mod prover;
 /// Implements proof verification of compact and batchable proofs.
 pub mod verifier;
+/// Contains lower-level tools that allow programmable specification of proof statements.
 pub mod sigma;
 
 use curve25519_dalek::ristretto::{CompressedRistretto, RistrettoPoint};

src/toolbox/sigma/fiat_shamir.rs

@@ -1,16 +1,56 @@
+//! Fiat-Shamir transformation for Sigma protocols.
+//!
+//! This module defines `NISigmaProtocol`, a generic non-interactive Sigma protocol wrapper,
+//! based on applying the Fiat-Shamir heuristic using a transcript codec.
+//!
+//! It transforms an interactive Sigma protocol into a non-interactive one,
+//! by deriving challenges deterministically from previous protocol messages
+//! via a cryptographic sponge function (transcript).
+//!
+//! # Usage
+//! This struct is generic over:
+//! - `P`: the underlying Sigma protocol (`SigmaProtocol` trait).
+//! - `C`: the transcript codec (`TranscriptCodec` trait).
+//! - `G`: the group used for commitments and operations (`Group` trait).
+//!
+//! # Example
+//! ```
+//! use lox_zkp::toolbox::sigma::fiat_shamir::NISigmaProtocol;
+//!
+//! let protocol = SchnorrProof { morphismp: statement };
+//! let mut nizk = NISigmaProtocol::<_, KeccakTranscript<G>, G>::new(b"context", protocol);
+//! let proof = nizk.prove(&witness, &mut rng);
+//! assert!(nizk.verify(&proof).is_ok());
+//! ```
+
 use rand::{RngCore, CryptoRng};
 use crate::toolbox::sigma::SigmaProtocol;
 use crate::toolbox::sigma::transcript::TranscriptCodec;
 use group::Group;
 
+/// A Fiat-Shamir transformation of a Sigma protocol into a non-interactive proof.
+///
+/// `NISigmaProtocol` wraps an interactive Sigma protocol `P`
+/// and a hash-based transcript `C`, to produce non-interactive proofs.
+/// 
+/// It manages the domain separation, transcript reset,
+/// proof generation, and proof verification.
+///
+/// # Type Parameters
+/// - `P`: the Sigma protocol implementation.
+/// - `C`: the transcript codec used for Fiat-Shamir.
+/// - `G`: the group on which the protocol operates.
 pub struct NISigmaProtocol<P, C, G>
 where
     G: Group,
     P: SigmaProtocol<Commitment = Vec<G>, Challenge = <G as Group>::Scalar>,
     C: TranscriptCodec<G>,
 {
+    /// Domain separation string for the Fiat-Shamir transform.
     domain_sep: Vec<u8>,
+    /// Current transcript state.
     hash_state: C,
+    /// Underlying Sigma protocol.
     sigmap: P,
 }
 
@@ -20,14 +60,14 @@ where
     P: SigmaProtocol<Commitment = Vec<G>, Challenge = <G as Group>::Scalar>,
     C: TranscriptCodec<G>,
 {
-    // Create new NIZK transformator.
+    /// Creates a new non-interactive Sigma protocol, identified by a domain separator (usually fixed per protocol instantiation), and an initialized Sigma protocol instance.
     pub fn new(iv: &[u8], instance: P) -> Self {
         let domain_sep = iv.to_vec();
         let hash_state = C::new(iv);
         Self { domain_sep, hash_state, sigmap: instance }
     }
 
-    // Generate new non-interactive proof
+    /// Produces a non-interactive proof for a witness and serializes it as a vector of bytes.
     pub fn prove(
         &mut self,
         witness: &P::Witness,
@@ -49,7 +89,7 @@ where
         self.sigmap.serialize_batchable(&commitment, &challenge, &response)
     }
 
-    /// Verification of non-interactive proof
+    /// Verify a non-interactive serialized proof and returns a Result: `Ok(())` if the proof verifies successfully, `Err(())` otherwise.
     pub fn verify(&mut self, proof: &Vec<u8>) -> Result<(), ()> {
         self.hash_state = C::new(&self.domain_sep);
 

src/toolbox/sigma/group_morphism.rs

@@ -1,17 +1,37 @@
+//! # Group Morphism and Preimage Handling
+//!
+//! This module provides utilities for describing and manipulating **linear group morphisms**,
+//! supporting sigma protocols over group-based statements (e.g., discrete logarithms, DLEQ proofs). See Maurer09.
+//!
+//! It includes:
+//! - `LinearCombination`: a sparse representation of scalar multiplication relations
+//! - `Morphism`: a collection of linear combinations acting on group elements
+//! - `GroupMorphismPreimage`: a higher-level structure managing morphisms and their associated images
+
 use group::{Group, GroupEncoding};
 
+/// A sparse linear combination of scalars and group elements.
+///
+/// Stores indices into external lists of scalars and group elements.
+/// Used to define individual constraints inside a Morphism.
 pub struct LinearCombination {
     pub scalar_indices: Vec<usize>,
     pub element_indices: Vec<usize>,
 }
 
+/// A Morphism represents a list of linear combinations over group elements.
+///
+/// It supports dynamic allocation of scalars and elements,
+/// and evaluates by performing multi-scalar multiplications.
+
 pub struct Morphism<G: Group> {
     pub linear_combination: Vec<LinearCombination>,
     pub group_elements: Vec<G>,
     pub num_scalars: usize,
     pub num_elements: usize,
 }
 
+/// Perform a simple multi-scalar multiplication (MSM) over scalars and points.
 fn msm_pr<G: Group>(scalars: &[G::Scalar], bases: &[G]) -> G {
     let mut acc = G::identity();
     for (s, p) in scalars.iter().zip(bases.iter()) {
@@ -21,6 +41,7 @@ fn msm_pr<G: Group>(scalars: &[G::Scalar], bases: &[G]) -> G {
 }
 
 impl<G: Group> Morphism<G> {
+    /// Creates a new empty Morphism.
     pub fn new() -> Self {
         Self {
             linear_combination: Vec::new(),
@@ -30,14 +51,19 @@ impl<G: Group> Morphism<G> {
         }
     }
 
+    /// Adds a new linear combination constraint.
     pub fn append(&mut self, lc: LinearCombination) {
         self.linear_combination.push(lc);
     }
 
+    /// Returns the number of constraint statements.
     pub fn num_statements(&self) -> usize {
         self.linear_combination.len()
     }
 
+    /// Evaluate the Morphism given a set of scalar values.
+    ///
+    /// Computes all linear combinations using the provided scalars and returns their group outputs.
     pub fn evaluate(&self, scalars: &[<G as Group>::Scalar]) -> Vec<G> {
         self.linear_combination.iter().map(|lc| {
             let coefficients: Vec<_> = lc.scalar_indices.iter().map(|&i| scalars[i].clone()).collect();
@@ -47,32 +73,44 @@ impl<G: Group> Morphism<G> {
     }
 }
 
+/// A wrapper struct coupling a Morphism and the corresponding expected image elements.
+///
+/// Provides a higher-level API to build proof instances from sparse constraints. The equations are manipulated solely through 2 lists: 
+/// - the index of a set of Group elements (maintained in Morphism)
+/// - the index of a set of scalars (provided as input for the execution)
 pub struct GroupMorphismPreimage<G>
 where
     G: Group + GroupEncoding,
 {
+    /// The underlying morphism describing the structure of the statement.
     pub morphism: Morphism<G>,
+    /// Indices pointing to elements representing the "target" images for each constraint.
     pub image: Vec<usize>,
 }
 
 impl<G> GroupMorphismPreimage<G>
 where
     G: Group + GroupEncoding,
 {
+    /// Create a new empty GroupMorphismPreimage.
     pub fn new() -> Self {
         Self {
             morphism: Morphism::new(),
             image: Vec::new(),
         }
     }
 
+    /// Computes the number of bytes needed when serializing all the current commitments.
     pub fn commit_bytes_len(&self) -> usize {
         let repr_len = <G::Repr as Default>::default()
             .as_ref()
             .len();  // size of encoded point
         self.morphism.num_statements() * repr_len  // total size of a commit
     }
 
+    /// Append a new equation relating scalars to group elements.
+    ///
+    /// `lhs` is the index of the image, and `rhs` is a list of (scalar_idx, element_idx) pairs.
     pub fn append_equation(&mut self, lhs: usize, rhs: &[(usize, usize)]) {
         let lc = LinearCombination {
             scalar_indices: rhs.iter().map(|&(s, _)| s).collect(),
@@ -82,15 +120,17 @@ where
         self.image.push(lhs);
     }
 
-    // Allocate n new Scalar's
+    /// Allocate space for `n` new scalars and return their indices.
     pub fn allocate_scalars(&mut self, n: usize) -> Vec<usize> {
         let start = self.morphism.num_scalars;
         let indices: Vec<usize> = (start..start + n).collect();
         self.morphism.num_scalars += n;
         indices
     }
 
-    // Allocate n new emplacments for Group elements (completed with set_elements for assignation)
+    /// Allocate space for `n` new group elements and return their indices.
+    ///
+    /// The allocated elements are initially set to the identity.
     pub fn allocate_elements(&mut self, n: usize) -> Vec<usize> {
         let start = self.morphism.num_elements;
         let indices: Vec<usize> = (start..start + n).collect();
@@ -101,12 +141,14 @@ where
         indices
     }
 
+    /// Set the value of group elements at a given index, inside the list of allocated group elements.
     pub fn set_elements(&mut self, elements: &[(usize, G)]) {
         for &(i, ref elt) in elements {
             self.morphism.group_elements[i] = elt.clone();
         }
     }
 
+    /// Return the group elements corresponding to the image indices.
     pub fn image(&self) -> Vec<G> {
         let mut result = Vec::new();
         for i in &self.image {

src/toolbox/sigma/mod.rs

@@ -3,6 +3,7 @@ pub mod proof_composition;
 pub mod fiat_shamir;
 pub mod group_morphism;
 pub mod schnorr_proof;
+/// Defines the transcript for a Sigma Protocol
 pub mod transcript;
 
 pub use r#trait::{SigmaProtocol, SigmaProtocolSimulator};

src/toolbox/sigma/proof_composition.rs

@@ -1,8 +1,24 @@
+//! Sigma protocol composition: AND and OR constructions.
+//!
+//! This module provides combinators to compose two Sigma protocols
+//! into a new protocol proving statements with logical AND or OR relations.
+//!
+//! # Overview
+//! - `AndProtocol<P, Q>`: Proves both substatements (`P` and `Q`) simultaneously.
+//! - `OrProtocol<P, Q>`: Proves knowledge of a witness for *one* substatement, without revealing which one (using simulation for the other).
+//!
+//! These constructions preserve zero-knowledge properties and follow standard Sigma protocol composition techniques.
+
 use crate::toolbox::sigma::{SigmaProtocol, SigmaProtocolSimulator};
 use rand::{Rng, CryptoRng};
 use ff::PrimeField;
 
-
+/// Logical AND composition of two Sigma protocols.
+///
+/// The prover must know witnesses for both subprotocols `P` and `Q`.
+///
+/// # Example
+/// Proves that two independent statements hold simultaneously.
 pub struct AndProtocol<P, Q> 
 where
     P: SigmaProtocol,
@@ -17,9 +33,10 @@ where
     P: SigmaProtocol,
     Q: SigmaProtocol
 {
-        pub fn new(protocol0: P, protocol1: Q) -> Self {
-            Self {protocol0, protocol1}
-        }
+    /// Create a new `AndProtocol` from two Sigma protocols.
+    pub fn new(protocol0: P, protocol1: Q) -> Self {
+        Self {protocol0, protocol1}
+    }
 }
 
 impl<P, Q> SigmaProtocol for AndProtocol<P, Q> 
@@ -72,6 +89,10 @@ where
     }
 }
 
+/// Logical OR composition of two Sigma protocols.
+///
+/// The prover knows a witness for **one** subprotocol `P` *or* `Q`,
+/// but does not reveal which. This uses simulation to hide the other statement.
 pub struct OrProtocol<P, Q>
 where
     P: SigmaProtocol,
@@ -86,18 +107,23 @@ where
     P: SigmaProtocol,
     Q: SigmaProtocol
 {
-        pub fn new(protocol0: P, protocol1: Q) -> Self {
-            Self {protocol0, protocol1}
-        }
+    /// Create a new `OrProtocol` from two Sigma protocols.
+    pub fn new(protocol0: P, protocol1: Q) -> Self {
+        Self {protocol0, protocol1}
+    }
 }
 
+/// Enum to wrap either the left or right variant in an OR proof.
 pub enum OrEnum<L, R> {
     Left(L),
     Right(R),
 }
 
+/// Internal state for a simulated transcript in an OR proof.
 pub struct OrState<P: SigmaProtocol> (P::Challenge, P::Response);
 
+
+/// Enum to describe which side (left or right) is simulated in an OR proof.
 pub enum OrTranscription<P, Q>
 where
     P: SigmaProtocol,
@@ -107,6 +133,7 @@ where
     Right(OrState<Q>)
 }
 
+
 impl<P, Q, C> SigmaProtocol for OrProtocol<P, Q> 
 where 
     C: PrimeField,
@@ -116,10 +143,9 @@ where
     Q::Response: Clone,
     {
     type Commitment = (P::Commitment, Q::Commitment); 
-    // Here ProverState = (real index, real prover state = (r, &real witness), fake transcription)
-    type ProverState = (usize, OrEnum<P::ProverState, Q::ProverState>, OrTranscription<P, Q>);
-    type Response = (P::Challenge, P::Response, Q::Response);  // The two responses
-    type Witness = (usize, OrEnum<P::Witness, Q::Witness>); // Index of the witness and witness
+    type ProverState = (usize, OrEnum<P::ProverState, Q::ProverState>, OrTranscription<P, Q>); // ProverState = (real index, real prover state = (r, &real witness), fake transcription)
+    type Response = (P::Challenge, P::Response, Q::Response);
+    type Witness = (usize, OrEnum<P::Witness, Q::Witness>); // Index of the real witness, and Enum to wrap the real witness
     type Challenge = P::Challenge;
 
     fn prover_commit(