add and clean docs

privacy-scaling-explorations · Nov 28, 2023 · c9ca18a · c9ca18a
1 parent ccef23e
commit c9ca18a
Show file tree

Hide file tree

Showing 5 changed files with 15 additions and 9 deletions.
diff --git a/src/pluto_eris/fields/fp.rs b/src/pluto_eris/fields/fp.rs
@@ -26,7 +26,7 @@ use serde::{Deserialize, Serialize};
 /// is the base field of the Pluto curve.
 /// The internal representation of this type is seven 64-bit unsigned
 /// integers in little-endian order which account for the 446 bits required to be represented.
-///`Fp` values are always in Montgomery form; i.e., Fp(a) = aR mod p, with R = 2^448.
+/// `Fp` values are always in Montgomery form; i.e., Fp(a) = aR mod p, with R = 2^448.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "derive_serde", derive(Serialize, Deserialize))]
 pub struct Fp(pub(crate) [u64; 7]);

diff --git a/src/pluto_eris/fields/fp12.rs b/src/pluto_eris/fields/fp12.rs
@@ -313,10 +313,16 @@ impl Field for Fp12 {
     }
 
     fn sqrt(&self) -> CtOption<Self> {
+        // The square root method is typically only required for finding y-coordinate
+        // given the x-coordinate of an EC point. Fields over which we have not
+        // defined a curve do not need this method.
         unimplemented!()
     }
 
     fn sqrt_ratio(_num: &Self, _div: &Self) -> (Choice, Self) {
+        // The square root method is typically only required for finding y-coordinate
+        // given the x-coordinate of an EC point. Fields over which we have not
+        // defined a curve do not need this method.
         unimplemented!()
     }
 

diff --git a/src/pluto_eris/fields/fp6.rs b/src/pluto_eris/fields/fp6.rs
@@ -452,7 +452,8 @@ impl Field for Fp6 {
     }
 }
 
-pub const FROBENIUS_COEFF_FP6_C1: [Fp2; 6] = [
+/// Fp2 coefficients for the efficient computation of Frobenius Endomorphism in Fp6.
+pub(crate) const FROBENIUS_COEFF_FP6_C1: [Fp2; 6] = [
     // Fp2(v^3)**(((p^0) - 1) / 3)
     Fp2::ONE,
     // Fp2(v^3)**(((p^1) - 1) / 3)
@@ -554,7 +555,8 @@ pub const FROBENIUS_COEFF_FP6_C1: [Fp2; 6] = [
     },
 ];
 
-pub const FROBENIUS_COEFF_FP6_C2: [Fp2; 6] = [
+/// Fp2 coefficients for the efficient computation of Frobenius Endomorphism in Fp6.
+pub(crate) const FROBENIUS_COEFF_FP6_C2: [Fp2; 6] = [
     // Fp2(v^3)**(((2p^0) - 2) / 3)
     Fp2::ONE,
     // Fp2(v^3)**(((2p^1) - 2) / 3)

diff --git a/src/pluto_eris/fields/fq.rs b/src/pluto_eris/fields/fq.rs
@@ -24,10 +24,9 @@ use serde::{Deserialize, Serialize};
 /// `q = 0x24000000000024000130e0000d7f70e4a803ca76f439266f443f9a5c7a8a6c7be4a775fe8e177fd69ca7e85d60050af41ffffcd300000001`
 ///
 /// is the scalar field of the Pluto curve (and the base field of the Eris curve).
-
 /// The internal representation of this type is seven 64-bit unsigned
 /// integers in little-endian order which account for the 446 bits required to be represented.
-///`Fq` values are always in Montgomery form; i.e., Fq(a) = aR mod q, with R = 2^448.
+/// `Fq` values are always in Montgomery form; i.e., Fq(a) = aR mod q, with R = 2^448.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "derive_serde", derive(Serialize, Deserialize))]
 pub struct Fq(pub(crate) [u64; 7]);
@@ -155,8 +154,8 @@ const DELTA: Fq = Fq::from_raw([
     0x657946fe07116ce,
 ]);
 
-// /// `ZETA^3 = 1 mod q` where `ZETA^2 != 1 mod q`
-// /// `0x9000000000006c000392a0001afee1c9500792ae3039253e641ba35817a29ffaf50be000032cfffffffe`
+/// `ZETA^3 = 1 mod q` where `ZETA^2 != 1 mod q`
+/// `0x9000000000006c000392a0001afee1c9500792ae3039253e641ba35817a29ffaf50be000032cfffffffe`
 
 const ZETA: Fq = Fq::from_raw([
     0xe000032cfffffffe,
@@ -196,6 +195,7 @@ field_bits_7_limbs!(Fq, MODULUS, MODULUS_LIMBS_32);
 prime_field_legendre!(Fq);
 
 impl Fq {
+    /// Return field element size in bytes.
     pub const fn size() -> usize {
         SIZE
     }

diff --git a/src/pluto_eris/fields/mod.rs b/src/pluto_eris/fields/mod.rs
@@ -451,7 +451,6 @@ macro_rules! field_arithmetic_7_limbs {
             /// Squares this element.
             #[inline]
             pub const fn square(&self) -> $field {
-                // self.mul(self)
                 let (r1, carry) = mac(0, self.0[0], self.0[1], 0);
                 let (r2, carry) = mac(0, self.0[0], self.0[2], carry);
                 let (r3, carry) = mac(0, self.0[0], self.0[3], carry);
@@ -517,7 +516,6 @@ macro_rules! field_arithmetic_7_limbs {
             #[inline]
             pub const fn mul(&self, rhs: &Self) -> $field {
                 // Schoolbook multiplication
-
                 let (r0, carry) = mac(0, self.0[0], rhs.0[0], 0);
                 let (r1, carry) = mac(0, self.0[0], rhs.0[1], carry);
                 let (r2, carry) = mac(0, self.0[0], rhs.0[2], carry);