fix(docs): add hyperlinks to structs in documentation and format code with cargo fmt (#9)

Co-authored-by: Maria Ghandour <[email protected]>

Author: MariaGhandour

src/codec/shake_codec.rs

@@ -1,14 +1,14 @@
 //! Implementation of a Fiat-Shamir codec using SHAKE128
 //!
-//! This module defines `ShakeCodec`, a concrete implementation of the `Codec`
+//! This module defines [`ShakeCodec`], a concrete implementation of the [`Codec`]
 //! trait. It uses the SHAKE128 extendable output function (XOF) from the Keccak family
 //! to generate Fiat-Shamir challenges for Sigma protocols.
 //!
 //! It allows commitments (group elements) to be absorbed into a codec,
 //! and produces scalar challenges by squeezing bytes from the hash state.
 //!
 //! # Usage
-//! - The prover and verifier absorb the same messages into identical `ShakeCodec` instances.
+//! - The prover and verifier absorb the same messages into identical [`ShakeCodec`] instances.
 //! - The prover and the verifier then squeeze the hash to generate a challenge scalar for the protocol. The verifier can check that the prover used the challenge output by the codec because he owns an identical codec.
 
 use ff::PrimeField;

src/codec/trait.rs

@@ -1,6 +1,6 @@
 //! Codec Trait
 //!
-//! This module defines the `Codec` trait, a generic interface to manage codecs of a protocol execution.
+//! This module defines the [`Codec`] trait, a generic interface to manage codecs of a protocol execution.
 
 pub trait DuplexSpongeInterface {
     fn new(iv: &[u8]) -> Self;
@@ -17,7 +17,7 @@ pub trait DuplexSpongeInterface {
 /// The output is deterministic for a given set of input. Thus, both Prover and Verifier can generate the codec on their sides and ensure the same inputs have been used in both side of the protocol.
 ///
 /// ## Minimal Implementation
-/// Types implementing `Codec` must define:
+/// Types implementing [`Codec`] must define:
 /// - `new`
 /// - `prover_message`
 /// - `verifier_challenge`

src/errors.rs

@@ -6,25 +6,25 @@
 //! These errors include:
 //! - Verification failures (e.g., when a proof does not verify correctly).
 //! - Mismatched parameters during batch verification.
-//! - Not implemented methods
-//! - Group element/scalar serialization failed
+//! - Unimplemented methods.
+//! - Group element or scalar serialization failures.
 use thiserror::Error;
 /// An error during proving or verification, such as a verification failure.
 #[derive(Debug, Error)]
 pub enum ProofError {
     /// Something is wrong with the proof, causing a verification failure.
     #[error("Verification failed.")]
     VerificationFailure,
-    /// Occurs during batch verification if the batch parameters do not have the right size.
+    /// Indicates a mismatch in parameter sizes during batch verification.
     #[error("Mismatched parameter sizes for batch verification.")]
     ProofSizeMismatch,
-    /// Occurs when a feature is not implemented yet.
-    #[error("The method is not yet implemented for this struct")]
+    /// Occurs when a feature has not been implemented yet.
+    #[error("The method is not yet implemented for this struct.")]
     NotImplemented(&'static str),
-    /// Serialization of a group element/scalar failed
-    #[error("Serialization of a group element/scalar failed")]
+    /// Serialization of a group element/scalar has failed.
+    #[error("Serialization of a group element/scalar failed.")]
     GroupSerializationFailure,
-    /// Other error
+    /// Other error.
     #[error("Other")]
     Other,
 }

src/fiat_shamir.rs

@@ -1,6 +1,6 @@
 //! Fiat-Shamir transformation for Sigma protocols.
 //!
-//! This module defines `NISigmaProtocol`, a generic non-interactive Sigma protocol wrapper,
+//! This module defines [`NISigmaProtocol`], a generic non-interactive Sigma protocol wrapper,
 //! based on applying the Fiat-Shamir heuristic using a codec.
 //!
 //! It transforms an interactive Sigma protocol into a non-interactive one,
@@ -9,9 +9,9 @@
 //!
 //! # Usage
 //! This struct is generic over:
-//! - `P`: the underlying Sigma protocol (`SigmaProtocol` trait).
-//! - `C`: the codec (`Codec` trait).
-//! - `G`: the group used for commitments and operations (`Group` trait).
+//! - `P`: the underlying Sigma protocol ([`SigmaProtocol`] trait).
+//! - `C`: the codec ([`Codec`] trait).
+//! - `G`: the group used for commitments and operations ([`Group`] trait).
 
 use crate::{codec::Codec, CompactProtocol, ProofError, SigmaProtocol};
 
@@ -26,7 +26,7 @@ type Transcript<P> = (
 
 /// A Fiat-Shamir transformation of a Sigma protocol into a non-interactive proof.
 ///
-/// `NISigmaProtocol` wraps an interactive Sigma protocol `P`
+/// [`NISigmaProtocol`] wraps an interactive Sigma protocol `P`
 /// and a hash-based codec `C`, to produce non-interactive proofs.
 ///
 /// It manages the domain separation, codec reset,
@@ -54,7 +54,14 @@ where
     P: SigmaProtocol<Commitment = Vec<G>, Challenge = <G as Group>::Scalar>,
     C: Codec<Challenge = <G as Group>::Scalar> + Clone,
 {
-    /// Creates a new non-interactive Sigma protocol, identified by a domain separator (usually fixed per protocol instantiation), and an initialized Sigma protocol instance.
+    /// Constructs a new [`NISigmaProtocol`] instance.
+    ///
+    /// # Parameters
+    /// - `iv`: Domain separation tag for the hash function (e.g., protocol name or context).
+    /// - `instance`: An instance of the interactive Sigma protocol.
+    ///
+    /// # Returns
+    /// A new [`NISigmaProtocol`] that can generate and verify non-interactive proofs.
     pub fn new(iv: &[u8], instance: P) -> Self {
         let hash_state = C::new(iv);
         Self {
@@ -63,7 +70,23 @@ where
         }
     }
 
-    /// Produces a non-interactive proof for a witness.
+    /// Generates a non-interactive proof for a witness.
+    ///
+    /// Executes the interactive protocol steps (commit, derive challenge via hash, respond),
+    /// and checks the result locally for consistency.
+    ///
+    /// # Parameters
+    /// - `witness`: The secret witness for the Sigma protocol.
+    /// - `rng`: A cryptographically secure random number generator.
+    ///
+    /// # Returns
+    /// A tuple of:
+    /// - `P::Commitment`: The prover's commitment(s).
+    /// - `P::Challenge`: The challenge derived via Fiat-Shamir.
+    /// - `P::Response`: The prover's response.
+    ///
+    /// # Panics
+    /// Panics if local verification fails.
     pub fn prove(
         &mut self,
         witness: &P::Witness,
@@ -86,7 +109,21 @@ where
         Ok((commitment, challenge, response))
     }
 
-    /// Verify a non-interactive proof and returns a Result: `Ok(())` if the proof verifies successfully, `Err(())` otherwise.
+    /// Verifies a non-interactive proof using the Fiat-Shamir transformation.
+    ///
+    /// # Parameters
+    /// - `commitment`: The commitment(s) sent by the prover.
+    /// - `challenge`: The challenge allegedly derived via Fiat-Shamir.
+    /// - `response`: The prover's response to the challenge.
+    ///
+    /// # Returns
+    /// - `Ok(())` if the proof is valid.
+    /// - `Err(ProofError::VerificationFailure)` if the challenge is invalid or the response fails to verify.
+    ///
+    /// # Errors
+    /// - Returns `ProofError::VerificationFailure` if:
+    ///   - The challenge doesn't match the recomputed one from the commitment.
+    ///   - The response fails verification under the Sigma protocol.
     pub fn verify(
         &mut self,
         commitment: &P::Commitment,
@@ -108,7 +145,17 @@ where
             false => Err(ProofError::VerificationFailure),
         }
     }
-
+    /// Generates a batchable, serialized non-interactive proof.
+    ///
+    /// # Parameters
+    /// - `witness`: The secret witness.
+    /// - `rng`: A cryptographically secure random number generator.
+    ///
+    /// # Returns
+    /// A serialized proof suitable for batch verification.
+    ///
+    /// # Panics
+    /// Panics if serialization fails (should not happen under correct implementation).
     pub fn prove_batchable(
         &mut self,
         witness: &P::Witness,
@@ -121,6 +168,19 @@ where
             .unwrap())
     }
 
+    /// Verifies a batchable non-interactive proof.
+    ///
+    /// # Parameters
+    /// - `proof`: A serialized batchable proof.
+    ///
+    /// # Returns
+    /// - `Ok(())` if the proof is valid.
+    /// - `Err(ProofError)` if deserialization or verification fails.
+    ///
+    /// # Errors
+    /// - Returns `ProofError::VerificationFailure` if:
+    ///   - The challenge doesn't match the recomputed one from the commitment.
+    ///   - The response fails verification under the Sigma protocol.
     pub fn verify_batchable(&mut self, proof: &[u8]) -> Result<(), ProofError> {
         let (commitment, response) = self.sigmap.deserialize_batchable(proof).unwrap();
 
@@ -144,6 +204,19 @@ where
     P: SigmaProtocol<Commitment = Vec<G>, Challenge = <G as Group>::Scalar> + CompactProtocol,
     C: Codec<Challenge = <G as Group>::Scalar> + Clone,
 {
+    /// Generates a compact serialized proof.
+    ///
+    /// Uses a more space-efficient representation compared to batchable proofs.
+    ///
+    /// # Parameters
+    /// - `witness`: The secret witness.
+    /// - `rng`: A cryptographically secure random number generator.
+    ///
+    /// # Returns
+    /// A compact, serialized proof.
+    ///
+    /// # Panics
+    /// Panics if serialization fails.
     pub fn prove_compact(
         &mut self,
         witness: &P::Witness,
@@ -156,6 +229,21 @@ where
             .unwrap())
     }
 
+    /// Verifies a compact proof.
+    ///
+    /// Recomputes the commitment from the challenge and response, then verifies it.
+    ///
+    /// # Parameters
+    /// - `proof`: A compact serialized proof.
+    ///
+    /// # Returns
+    /// - `Ok(())` if the proof is valid.
+    /// - `Err(ProofError)` if deserialization or verification fails.
+    ///
+    /// # Errors
+    /// - Returns `ProofError::VerificationFailure` if:
+    ///   - Deserialization fails.
+    ///   - The recomputed commitment or response is invalid under the Sigma protocol.
     pub fn verify_compact(&mut self, proof: &[u8]) -> Result<(), ProofError> {
         let (challenge, response) = self.sigmap.deserialize_compact(proof).unwrap();
         // Compute the commitments