test(verification): add Sage test vectors and enhance documentation

- test: implement hard-coded Sage test vectors for automatic verification
- docs: add documentation for CompactProtocol, ProofBuilder, and error handling

Author: nougzarm

src/errors.rs

@@ -6,6 +6,8 @@
 //! 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
 use thiserror::Error;
 /// An error during proving or verification, such as a verification failure.
 #[derive(Debug, Error)]
@@ -21,5 +23,5 @@ pub enum ProofError {
     NotImplemented(&'static str),
     /// Serialization of a group element/scalar failed
     #[error("Serialization of a group element/scalar failed")]
-    GroupSerialisationFailure,
+    GroupSerializationFailure,
 }

src/group_serialisation.rs renamed to src/group_serialization.rs

@@ -16,7 +16,7 @@
 pub mod errors;
 pub mod fiat_shamir;
 pub mod group_morphism;
-pub mod group_serialisation;
+pub mod group_serialization;
 pub mod proof_builder;
 pub mod proof_composition;
 pub mod schnorr_protocol;
@@ -25,7 +25,7 @@ pub mod r#trait;
 pub use errors::*;
 pub use fiat_shamir::*;
 pub use group_morphism::*;
-pub use group_serialisation::*;
+pub use group_serialization::*;
 pub use proof_builder::*;
 pub use proof_composition::*;
 pub use r#trait::*;

src/lib.rs

@@ -106,17 +106,25 @@ where
         self.protocol.prove_batchable(&witness_tmp, rng)
     }
 
-    /// Verifies a serialized proof against the current statement.
+    /// Verifies a serialized batchable proof against the current statement.
     ///
     /// # Parameters
-    /// - `proof`: A byte slice containing the serialized proof
+    /// - `proof`: A byte slice containing the serialized batchable proof
     ///
     /// # Returns
     /// `Ok(())` if the proof is valid, or a [`ProofError`] if verification fails.
     pub fn verify(&mut self, proof: &[u8]) -> Result<(), ProofError> {
         self.protocol.verify_batchable(proof)
     }
 
+    /// Generates a compact proof for the current statement using the given witness.
+    ///
+    /// # Parameters
+    /// - `witness`: A list of scalars (one per allocated scalar variable)
+    /// - `rng`: A random number generator
+    ///
+    /// # Returns
+    /// A serialized proof as a vector of bytes in compact ('challenge', 'response') format.
     pub fn prove_compact(
         &mut self,
         witness: &[<G as Group>::Scalar],
@@ -126,6 +134,13 @@ where
         self.protocol.prove_compact(&witness_tmp, rng)
     }
 
+    /// Verifies a serialized compact proof against the current statement.
+    ///
+    /// # Parameters
+    /// - `proof`: A byte slice containing the serialized compact proof
+    ///
+    /// # Returns
+    /// `Ok(())` if the proof is valid, or a [`ProofError`] if verification fails.
     pub fn verify_compact(&mut self, proof: &[u8]) -> Result<(), ProofError> {
         self.protocol.verify_compact(proof)
     }

src/proof_builder.rs

@@ -120,15 +120,15 @@ where
 
     fn deserialize_batchable(&self, data: &[u8]) -> Result<(Self::Commitment, Self::Response), ProofError> {
         if data.len() < 4 {
-            return Err(ProofError::GroupSerialisationFailure); // not enough bytes to contain the length suffix
+            return Err(ProofError::GroupSerializationFailure); // not enough bytes to contain the length suffix
         }
 
         // Split off the last 4 bytes as the trailer
         let (proof_data, len_bytes) = data.split_at(data.len() - 4);
         let len0 = u32::from_le_bytes(len_bytes.try_into().unwrap()) as usize;
 
         if proof_data.len() < len0 {
-            return Err(ProofError::GroupSerialisationFailure); // length hint exceeds available bytes
+            return Err(ProofError::GroupSerializationFailure); // length hint exceeds available bytes
         }
 
         let (ser0, ser1) = proof_data.split_at(len0);
@@ -309,7 +309,7 @@ where
         // The challenge is appended as `Challenge::Repr`, which must be a fixed size
         let repr_len = <C as PrimeField>::Repr::default().as_ref().len();
         if data.len() < repr_len + 4 {
-            return Err(ProofError::GroupSerialisationFailure);
+            return Err(ProofError::GroupSerializationFailure);
         }
 
         let len0_bytes = &data[data.len() - 4..];
@@ -318,15 +318,15 @@ where
 
         let len0 = u32::from_le_bytes(len0_bytes.try_into().unwrap()) as usize;
         if proof_data.len() < len0 {
-            return Err(ProofError::GroupSerialisationFailure);
+            return Err(ProofError::GroupSerializationFailure);
         }
 
         let mut repr = <C as PrimeField>::Repr::default();
         repr.as_mut().copy_from_slice(ch0_bytes);
 
         let result_ctoption = C::from_repr(repr);
         if (!result_ctoption.is_some()).into() {
-            return Err(ProofError::GroupSerialisationFailure);
+            return Err(ProofError::GroupSerializationFailure);
         }
         let ch0 = result_ctoption.unwrap();
 

src/proof_composition.rs

@@ -5,7 +5,7 @@
 //! through a group morphism abstraction (see Maurer09).
 
 use crate::{
-    group_serialisation::*,
+    group_serialization::*,
     CompactProtocol, GroupMorphismPreimage, ProofError,
     SigmaProtocol,
 };
@@ -131,7 +131,7 @@ where
             let end = start + commit_size;
 
             let slice = &data[start..end];
-            let elem = deserialize_element(slice).ok_or(ProofError::GroupSerialisationFailure)?;
+            let elem = deserialize_element(slice).ok_or(ProofError::GroupSerializationFailure)?;
             commitments.push(elem);
         }
 
@@ -140,7 +140,7 @@ where
             let end = start + response_size;
 
             let slice = &data[start..end];
-            let scalar = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerialisationFailure)?;
+            let scalar = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerializationFailure)?;
             responses.push(scalar);
         }
 
@@ -206,14 +206,14 @@ where
         let mut responses: Self::Response = Vec::new();
 
         let slice = &data[0..response_size];
-        let challenge = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerialisationFailure)?;
+        let challenge = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerializationFailure)?;
 
         for i in 0..response_nb {
             let start = (i + 1) * response_size;
             let end = start + response_size;
 
             let slice = &data[start..end];
-            let scalar = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerialisationFailure)?;
+            let scalar = deserialize_scalar::<G>(slice).ok_or(ProofError::GroupSerializationFailure)?;
             responses.push(scalar);
         }
 

src/schnorr_protocol.rs

@@ -60,10 +60,7 @@ pub trait SigmaProtocol {
         response: &Self::Response,
     ) -> Result<(), ProofError>;
 
-    /// Serializes a proof transcript (commitment, challenge, response) to bytes for batching.
-    ///
-    /// # Panics
-    /// Panics if serialization is not supported for this protocol.
+    /// Serializes a proof transcript (commitment, challenge, response) to bytes batchable proof.
     fn serialize_batchable(
         &self,
         _commitment: &Self::Commitment,
@@ -73,12 +70,9 @@ pub trait SigmaProtocol {
         Err(ProofError::NotImplemented("serialize_batchable not implemented for this protocol"))
     }
 
-    /// Deserializes a proof transcript from bytes.
+    /// Deserializes a batchable proof from bytes.
     ///
     /// Returns `Some((commitment, response))` if parsing is successful, otherwise `None`.
-    ///
-    /// # Panics
-    /// Panics if deserialization is not supported for this protocol.
     fn deserialize_batchable(
         &self,
         _data: &[u8]
@@ -87,13 +81,25 @@ pub trait SigmaProtocol {
     }
 }
 
+/// A feature defining the behavior of a protocol for which it is possible to compact the proofs by omitting the commitments.
+///
+/// This is possible if it is possible to retrieve the commitments from the challenge and responses.
+/// This is what the get_commitment function is for.
+/// 
+/// ## Minimal Implementation
+/// Types implementing `CompactProtocol` must define:
+/// - `get_commitment`
 pub trait CompactProtocol: SigmaProtocol {
+    /// Returns the commitment for which ('commitment', 'challenge', 'response') is a valid transcription
+    /// 
+    /// This function allows to omit commitment in compact proofs of the type ('challenge', 'response')
     fn get_commitment(
         &self,
         challenge: &Self::Challenge,
         response: &Self::Response,
     ) -> Self::Commitment;
 
+    /// Serializes a proof transcript (commitment, challenge, response) to bytes compact proof.
     fn serialize_compact(
         &self,
         _commitment: &Self::Commitment,
@@ -103,6 +109,9 @@ pub trait CompactProtocol: SigmaProtocol {
         Err(ProofError::NotImplemented("serialize_compact not implemented for this protocol"))
     }
 
+    /// Deserializes a compact proof from bytes.
+    ///
+    /// Returns `Some((challenge, response))` if parsing is successful, otherwise `None`.
     fn deserialize_compact(
         &self,
         _data: &[u8]
@@ -124,19 +133,13 @@ pub trait SigmaProtocolSimulator: SigmaProtocol {
     /// Simulates a protocol transcript given a challenge.
     ///
     /// This serves to create zero-knowledge simulations without access to a witness.
-    ///
-    /// # Panics
-    /// Panics if simulation is not implemented for this protocol.
     fn simulate_proof(
         &self,
         challenge: &Self::Challenge,
         rng: &mut (impl Rng + CryptoRng),
     ) -> (Self::Commitment, Self::Response);
 
     /// Simulates an entire protocol transcript.
-    ///
-    /// # Panics
-    /// Panics if simulation is not implemented for this protocol.
     fn simulate_transcript(
         &self,
         rng: &mut (impl Rng + CryptoRng),

src/trait.rs

@@ -3,7 +3,7 @@ use group::{Group, GroupEncoding};
 use rand::{CryptoRng, Rng};
 
 use sigma_rs::{
-    group_serialisation::*,
+    group_serialization::*,
     GroupMorphismPreimage, ProofError, SigmaProtocol,
 };
 
@@ -121,7 +121,7 @@ where
             let end = start + point_size;
 
             let slice = &data[start..end];
-            let elem = deserialize_element(slice).ok_or(ProofError::GroupSerialisationFailure)?;
+            let elem = deserialize_element(slice).ok_or(ProofError::GroupSerializationFailure)?;
             commitments.push(elem);
         }
 
@@ -130,7 +130,7 @@ where
             let end = start + scalar_size;
 
             let slice = data[start..end].to_vec();
-            let scalar = deserialize_scalar::<G>(&slice).ok_or(ProofError::GroupSerialisationFailure)?;
+            let scalar = deserialize_scalar::<G>(&slice).ok_or(ProofError::GroupSerializationFailure)?;
             responses.push(scalar);
         }
 

tests/spec/custom_schnorr_protocol.rs

@@ -209,6 +209,7 @@ fn NI_discrete_logarithm(seed: &[u8], context: &[u8]) -> (Vec<Scalar>, Vec<u8>)
     let proof_bytes = nizk.prove_batchable(&witness, &mut rng);
     let verified = nizk.verify_batchable(&proof_bytes).is_ok();
     assert!(verified, "Fiat-Shamir Schnorr proof verification failed");
+    assert!(encode(&proof_bytes).as_bytes() == b"80c96c2822d816de609d4b72dd0b2a9409a3402338c977467225e7f506a60f3153a7f447450d7336c0ef15e4151349d91495306d216d5fe2ff3e660bcaf227c4794cb0e0887f5bcff6d4a6189cf9a494");
     (witness, proof_bytes)
 }
 
@@ -224,6 +225,7 @@ fn NI_dleq(seed: &[u8], context: &[u8]) -> (Vec<Scalar>, Vec<u8>) {
     let proof_bytes = nizk.prove_batchable(&witness, &mut rng);
     let verified = nizk.verify_batchable(&proof_bytes).is_ok();
     assert!(verified, "Fiat-Shamir Schnorr proof verification failed");
+    assert!(encode(&proof_bytes).as_bytes() == b"a01abd54895b7df2d476b2371e1796278a114f7dd1514e05cc1c0c07d40957268684c8887aa3f8cee33856ca325412f5a4fffa7226a983c8fcd9bb59dbb7a72e5c4eacd80958c3685d7abaa477ba6d738b35998ea1d0089166d17ea0a206d2991bf0b87f1f5c977f93fdccf9ec820d989656662f146460d48e56bfc2f6482285");
     (witness, proof_bytes)
 }
 
@@ -239,6 +241,7 @@ fn NI_pedersen_commitment(seed: &[u8], context: &[u8]) -> (Vec<Scalar>, Vec<u8>)
     let proof_bytes = nizk.prove_batchable(&witness, &mut rng);
     let verified = nizk.verify_batchable(&proof_bytes).is_ok();
     assert!(verified, "Fiat-Shamir Schnorr proof verification failed");
+    assert!(encode(&proof_bytes).as_bytes() == b"91c620e60e68502ab1e0f0fa6b9f7e3225f678596da80c0e950e4149078562518ad37ed6177c71ebd6e2ca5fc32457d8228aa82bf0293a2d70def71e0e1f434af472458907c4827b694987a903126dd050b3ed6234dcd4d176f05582d3dab5515f790c5cdc927972d631a2ddceb53edb");
     (witness, proof_bytes)
 }
 
@@ -254,6 +257,7 @@ fn NI_pedersen_commitment_dleq(seed: &[u8], context: &[u8]) -> (Vec<Scalar>, Vec
     let proof_bytes = nizk.prove_batchable(&witness, &mut rng);
     let verified = nizk.verify_batchable(&proof_bytes).is_ok();
     assert!(verified, "Fiat-Shamir Schnorr proof verification failed");
+    assert!(encode(&proof_bytes).as_bytes() == b"8e670749a002c02e0b343a47c0194743d9164d5026ddec0a9572a742748305f83b2fc679858f2f97debd72a08ec59dc38e5d6c8cc6cb284f4012d4eb41a807d1463ad0d8976f78baff1da1fdf2ad39027e8c66e0625b15740a72fc9e866f1d1014a32947fd44c55553eb2c13d21d639640b5d070987d8befea62367b235278d80a313d50f72e5c70de5fc1db95e042b3723344136144cc71c5515c5aa03d95d1");
     (witness, proof_bytes)
 }
 
@@ -269,6 +273,7 @@ fn NI_bbs_blind_commitment_computation(seed: &[u8], context: &[u8]) -> (Vec<Scal
     let proof_bytes = nizk.prove_batchable(&witness, &mut rng);
     let verified = nizk.verify_batchable(&proof_bytes).is_ok();
     assert!(verified, "Fiat-Shamir Schnorr proof verification failed");
+    assert!(encode(&proof_bytes).as_bytes() == b"803d5d4fdb311967832758ae7402d03304b570f97c0756e5385a50622d0ac7b5de87fe14d15041b1564ba4893a1187304ed12592b9ca9c5ca92a87c3960f0bcae541ddf880271c361cca15c67e13bc504cf96235363e99bb3e126b111c220c77427873389d2397cf0798d251ec82ced1649b5d0e9b2f95410a68b5b66158e50832488e540853a8c79a17d8b8290266ec150af102dd9ca4a6f076399da893b1f2caa78d192590708c02ab561eb3a01aa1");
     (witness, proof_bytes)
 }
 

tests/spec/sage_test_vectors.rs

@@ -1,11 +1,3 @@
-//! Serialization for Group Elements and Scalars
-//!
-//! This module defines the [`GroupSerialisation`] trait, which provides a unified interface
-//! for serializing and deserializing group elements and their associated scalar field elements.
-//!
-//! It is used throughout the Sigma protocol framework for encoding proof data, hashing to transcripts,
-//! and verifying correctness of received data.
-
 use group::{Group, GroupEncoding};
 use ff::PrimeField;
 use std::convert::TryInto;
@@ -34,7 +26,7 @@ use std::convert::TryInto;
 /// - `deserialize_element`: Attempts to decode a group element from bytes
 /// - `serialize_scalar`: Encodes a scalar field element into bytes
 /// - `deserialize_scalar`: Attempts to decode a scalar from bytes
-pub trait GroupSerialisation: Group + GroupEncoding {
+pub trait GroupSerialization: Group + GroupEncoding {
     /// Serializes a group element (e.g., elliptic curve point) into a canonical byte representation.
     ///
     /// This representation must be deterministic and compatible with the corresponding
@@ -66,7 +58,7 @@ use curve25519_dalek::{
 };
 
 
-impl GroupSerialisation for RistrettoPoint {
+impl GroupSerialization for RistrettoPoint {
     /// Serializes a `RistrettoPoint` to 32-byte compressed form.
     fn serialize_element(point: &Self) -> Vec<u8> {
         point.compress().to_bytes().to_vec()
@@ -101,7 +93,7 @@ impl GroupSerialisation for RistrettoPoint {
     }
 }
 
-impl GroupSerialisation for G1Projective {
+impl GroupSerialization for G1Projective {
     /// Serializes a `G1Projective` element using compressed affine representation (48 bytes).
     fn serialize_element(point: &G1Projective) -> Vec<u8> {
         let affine = G1Affine::from(point);