doc comments added for jubjub wrapper

Author: curiecrypt

mithril-stm/src/signature_scheme/schnorr_signature/jubjub/curve_points.rs

@@ -9,49 +9,59 @@ use std::ops::{Add, Mul};
 use super::{BaseFieldElement, ScalarFieldElement};
 use crate::{StmResult, signature_scheme::SchnorrSignatureError};
 
+/// Represents a point in affine coordinates on the Jubjub curve
 #[derive(Clone)]
 pub(crate) struct AffinePoint(JubjubAffinePoint);
 
 impl AffinePoint {
+    /// Converts a projective point to its affine representation
     pub(crate) fn from_projective_point(projective_point: ProjectivePoint) -> Self {
         AffinePoint(JubjubAffinePoint::from(projective_point.0))
     }
 
+    /// Retrieves the u-coordinate of the affine point
     pub(crate) fn get_u(&self) -> BaseFieldElement {
         BaseFieldElement(self.0.get_u())
     }
 
+    /// Retrieves the v-coordinate of the affine point
     pub(crate) fn get_v(&self) -> BaseFieldElement {
         BaseFieldElement(self.0.get_v())
     }
 }
 
 impl From<&PrimeOrderProjectivePoint> for AffinePoint {
+    /// Converts a prime order projective point to its affine representation
     fn from(prime_order_projective_point: &PrimeOrderProjectivePoint) -> Self {
         AffinePoint(JubjubAffinePoint::from(JubjubExtended::from(
             prime_order_projective_point.0,
         )))
     }
 }
 
+/// Represents a point in projective coordinates on the Jubjub curve
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct ProjectivePoint(pub(crate) JubjubExtended);
 
 impl ProjectivePoint {
+    /// Hashes input bytes to a projective point on the Jubjub curve
     pub(crate) fn hash_to_projective_point(input: &[u8]) -> Self {
         ProjectivePoint(JubjubExtended::hash_to_point(input))
     }
 
+    /// Retrieves the (u, v) coordinates of the projective point in affine representation
     pub(crate) fn get_coordinates(&self) -> (BaseFieldElement, BaseFieldElement) {
         let affine_point = AffinePoint::from_projective_point(*self);
 
         (affine_point.get_u(), affine_point.get_v())
     }
 
+    /// Converts the projective point to its byte representation
     pub(crate) fn to_bytes(self) -> [u8; 32] {
         self.0.to_bytes()
     }
 
+    /// Constructs a projective point from its byte representation
     pub(crate) fn from_bytes(bytes: &[u8]) -> StmResult<Self> {
         let mut projective_point_bytes = [0u8; 32];
         projective_point_bytes
@@ -63,6 +73,7 @@ impl ProjectivePoint {
         }
     }
 
+    /// Checks if the projective point is of prime order
     pub(crate) fn is_prime_order(self) -> bool {
         self.0.is_prime_order().into()
     }
@@ -71,6 +82,7 @@ impl ProjectivePoint {
 impl Add for ProjectivePoint {
     type Output = ProjectivePoint;
 
+    /// Adds two projective points
     fn add(self, other: ProjectivePoint) -> ProjectivePoint {
         ProjectivePoint(self.0 + other.0)
     }
@@ -79,26 +91,31 @@ impl Add for ProjectivePoint {
 impl Mul<ProjectivePoint> for ScalarFieldElement {
     type Output = ProjectivePoint;
 
+    /// Multiplies a projective point by a scalar field element
+    /// Returns the resulting projective point
     fn mul(self, point: ProjectivePoint) -> ProjectivePoint {
         ProjectivePoint(point.0 * self.0)
     }
 }
 
 impl From<PrimeOrderProjectivePoint> for ProjectivePoint {
+    /// Converts a prime order projective point to a projective point
     fn from(prime_order_projective_point: PrimeOrderProjectivePoint) -> Self {
         ProjectivePoint(JubjubExtended::from(prime_order_projective_point.0))
     }
 }
 
+/// Represents a point of prime order in projective coordinates on the Jubjub curve
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub(crate) struct PrimeOrderProjectivePoint(pub(crate) JubjubSubgroup);
 
 impl PrimeOrderProjectivePoint {
+    /// Creates the generator point of the prime order subgroup
     pub(crate) fn create_generator() -> Self {
         PrimeOrderProjectivePoint(JubjubSubgroup::generator())
     }
 
-    /// Check if the given point is on the curve using its coordinates
+    /// Checks if the given point is on the curve using its coordinates
     pub(crate) fn is_on_curve(&self) -> StmResult<PrimeOrderProjectivePoint> {
         let point_affine_representation = AffinePoint::from(self);
         let (x, y) = (
@@ -119,10 +136,12 @@ impl PrimeOrderProjectivePoint {
         Ok(*self)
     }
 
+    /// Converts the prime order projective point to its byte representation
     pub(crate) fn to_bytes(self) -> [u8; 32] {
         self.0.to_bytes()
     }
 
+    /// Constructs a prime order projective point from its byte representation
     pub(crate) fn from_bytes(bytes: &[u8]) -> StmResult<Self> {
         let mut prime_order_projective_point_bytes = [0u8; 32];
         prime_order_projective_point_bytes
@@ -140,6 +159,7 @@ impl PrimeOrderProjectivePoint {
 impl Add for PrimeOrderProjectivePoint {
     type Output = PrimeOrderProjectivePoint;
 
+    /// Adds two prime order projective points
     fn add(self, other: PrimeOrderProjectivePoint) -> PrimeOrderProjectivePoint {
         PrimeOrderProjectivePoint(self.0 + other.0)
     }
@@ -148,6 +168,8 @@ impl Add for PrimeOrderProjectivePoint {
 impl Mul<PrimeOrderProjectivePoint> for ScalarFieldElement {
     type Output = PrimeOrderProjectivePoint;
 
+    /// Multiplies a prime order projective point by a scalar field element
+    /// Returns the resulting prime order projective point
     fn mul(self, point: PrimeOrderProjectivePoint) -> PrimeOrderProjectivePoint {
         PrimeOrderProjectivePoint(point.0 * self.0)
     }

mithril-stm/src/signature_scheme/schnorr_signature/jubjub/field_elements.rs

@@ -6,10 +6,12 @@ use std::ops::{Add, Mul, Sub};
 
 use crate::{StmResult, signature_scheme::SchnorrSignatureError};
 
+/// Represents an element in the base field of the Jubjub curve
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct BaseFieldElement(pub(crate) JubjubBase);
 
 impl BaseFieldElement {
+    /// Retrieves the multiplicative identity element of the base field
     pub(crate) fn get_one() -> Self {
         BaseFieldElement(JubjubBase::ONE)
     }
@@ -18,6 +20,7 @@ impl BaseFieldElement {
 impl Add for BaseFieldElement {
     type Output = BaseFieldElement;
 
+    /// Adds two base field elements
     fn add(self, other: BaseFieldElement) -> BaseFieldElement {
         BaseFieldElement(self.0 + other.0)
     }
@@ -26,6 +29,7 @@ impl Add for BaseFieldElement {
 impl Sub for &BaseFieldElement {
     type Output = BaseFieldElement;
 
+    /// Subtracts one base field element from another
     fn sub(self, other: &BaseFieldElement) -> BaseFieldElement {
         BaseFieldElement(self.0 - other.0)
     }
@@ -34,6 +38,7 @@ impl Sub for &BaseFieldElement {
 impl Mul for BaseFieldElement {
     type Output = BaseFieldElement;
 
+    /// Multiplies two base field elements
     fn mul(self, other: BaseFieldElement) -> BaseFieldElement {
         BaseFieldElement(self.0 * other.0)
     }
@@ -42,33 +47,40 @@ impl Mul for BaseFieldElement {
 impl Mul for &BaseFieldElement {
     type Output = BaseFieldElement;
 
+    /// Multiplies a base field element by another base field element
     fn mul(self, other: &BaseFieldElement) -> BaseFieldElement {
         BaseFieldElement(self.0 * other.0)
     }
 }
 
+/// Represents an element in the scalar field of the Jubjub curve
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct ScalarFieldElement(pub(crate) JubjubScalar);
 
 impl ScalarFieldElement {
+    /// Generates a new random scalar field element
     pub(crate) fn new_random_scalar(rng: &mut (impl RngCore + CryptoRng)) -> Self {
         ScalarFieldElement(JubjubScalar::random(rng))
     }
 
+    /// Checks if the scalar field element is zero
     pub(crate) fn is_zero(&self) -> bool {
         if self.0 == JubjubScalar::zero() {
             return true;
         }
         false
     }
 
+    /// Checks if the scalar field element is one
     pub(crate) fn is_one(&self) -> bool {
         if self.0 == JubjubScalar::one() {
             return true;
         }
         false
     }
 
+    /// Generates a new random non-zero scalar field element
+    /// Returns an error if unable to generate a non-zero scalar after 100 attempts
     pub(crate) fn new_random_nonzero_scalar(
         rng: &mut (impl RngCore + CryptoRng),
     ) -> StmResult<Self> {
@@ -81,10 +93,12 @@ impl ScalarFieldElement {
         Err(anyhow!(SchnorrSignatureError::RandomScalarGeneration))
     }
 
+    /// Converts the scalar field element to its byte representation
     pub(crate) fn to_bytes(self) -> [u8; 32] {
         self.0.to_bytes()
     }
 
+    /// Constructs a scalar field element from its byte representation
     pub(crate) fn from_bytes(bytes: &[u8]) -> StmResult<Self> {
         let mut scalar_bytes = [0u8; 32];
         scalar_bytes.copy_from_slice(
@@ -105,6 +119,7 @@ impl ScalarFieldElement {
 impl Mul for ScalarFieldElement {
     type Output = ScalarFieldElement;
 
+    /// Multiplies two scalar field elements
     fn mul(self, other: ScalarFieldElement) -> ScalarFieldElement {
         ScalarFieldElement(self.0 * other.0)
     }
@@ -113,6 +128,7 @@ impl Mul for ScalarFieldElement {
 impl Sub for ScalarFieldElement {
     type Output = ScalarFieldElement;
 
+    /// Subtracts one scalar field element from another
     fn sub(self, other: ScalarFieldElement) -> ScalarFieldElement {
         ScalarFieldElement(self.0 - other.0)
     }

mithril-stm/src/signature_scheme/schnorr_signature/jubjub/poseidon_digest.rs

@@ -6,6 +6,8 @@ use super::{BaseFieldElement, ScalarFieldElement};
 /// A DST (Domain Separation Tag) to distinguish between use of Poseidon hash
 const DST_SIGNATURE: JubjubBase = JubjubBase::from_raw([0u64, 0, 0, 0]);
 
+/// Computes a truncated Poseidon digest over the provided base field elements
+/// Returns a scalar field element as the digest
 pub(crate) fn compute_truncated_digest(input: &[BaseFieldElement]) -> ScalarFieldElement {
     let mut poseidon_input = vec![DST_SIGNATURE];
     poseidon_input.extend(input.iter().map(|i| i.0).collect::<Vec<JubjubBase>>());