Merge pull request #18 from Yoii-Inc/fix/#14_add_comment_to_function

Fix/#14 add comment to function

src/preprocessing.rs

@@ -1,4 +1,13 @@
+//! An implementation of the preprocessing of MPC.
+//! Concrete implementation is based on "5. The Preprocessing Phase" in [`DPSZ11`].
+//!
+//! [`DPSZ11`]: https://eprint.iacr.org/2011/535.pdf
+
 pub mod zkpopk {
+    //! An implementation of the ZKPoPK (Zero-Knowledge Proof of Plaintext Knowledge) in MPC.
+    //! Concrete implementation is based on "4. Zero-Knowledge Proof of Plaintext Knowledge" and Fig.10 in "A.1 Zero-Knowledge Proof" in [`DPSZ11`].
+    //!
+    //! [`DPSZ11`]: https://eprint.iacr.org/2011/535.pdf
 
     use crate::she::{Ciphertext, Encodedtext, Plaintexts, PublicKey, SHEParameters};
 
@@ -10,6 +19,17 @@ pub mod zkpopk {
     use rand::{thread_rng, Rng};
     use rand_distr::uniform::UniformSampler;
 
+    /// Parameters for ZKPoPK (Zero-Knowledge Proof of Plaintext Knowledge).
+    ///
+    /// This struct holds various parameters used in the context of ZKPoPK.
+    ///
+    /// - `v`: Number of ciphertexts, typically set to `2 * sec - 1`.
+    /// - `n`: Degree of Encodedtext.
+    /// - `tau`: A parameter used to describe the upper bound of plaintext.
+    /// - `sec`: Security parameter.
+    /// - `d`: A parameter used to describe the upper bound of randomness.
+    /// - `rho`: A parameter used to describe the upper bound of randomness.
+    ///
     pub struct Parameters {
         v: i32,
         n: usize,
@@ -628,7 +648,15 @@ fn verify_bracket_share(bracket_share: &BracketShare, parameters: &Parameters) -
     flag
 }
 
-// initialize
+/// Initializes the preprocessing phase.
+///
+/// # Arguments
+/// * `parameters` - preprocessing parameters in SPDZ.
+/// * `she_params` - SHE(Somewhat Homomorphic Encryption) parameters.
+///
+/// # Returns
+/// The BracketShare of global public key.
+///
 pub fn initialize(parameters: &Parameters, she_params: &SHEParameters) -> BracketShare {
     let n = 3;
 
@@ -709,6 +737,18 @@ pub fn initialize(parameters: &Parameters, she_params: &SHEParameters) -> Bracke
     )
 }
 
+/// Generate BracketShare and AngleShare of random number.
+///
+/// # Arguments
+/// * `e_alpha` - Encrypted alpha.
+/// * `pk - The public key.
+/// * `sk` - The secret key.
+/// * `parameters` - preprocessing parameters in SPDZ.
+/// * `she_params` - SHE(Somewhat Homomorphic Encryption) parameters.
+///
+/// # Returns
+/// The BracketShare and AngleShare of random number.
+///
 pub fn pair(
     e_alpha: &Ciphertext,
     pk: &PublicKey,
@@ -766,6 +806,18 @@ pub fn pair(
     (r_bracket, r_angle)
 }
 
+/// Generate Multiplication tirples.
+///
+/// # Arguments
+/// * `e_alpha` - Encrypted alpha.
+/// * `pk` - The public key.
+/// * `sk` - The secret key.
+/// * `parameters` - preprocessing parameters in SPDZ.
+/// * `she_params` - SHE(Somewhat Homomorphic Encryption) parameters.
+///
+/// # Returns
+/// The AngleShare of (a, b, c) where c = a * b.
+///
 pub fn triple(
     e_alpha: &Ciphertext,
     pk: &PublicKey,

src/she.rs

@@ -1,3 +1,8 @@
+//! An implementation of the SHE (somewhat homomorphic encryption) of MPC.
+//! Concrete implementation is based on "6. Concrete Instantiation of the Abstract Scheme based on LWE" in [`DPSZ11`].
+//!
+//! [`DPSZ11`]: https://eprint.iacr.org/2011/535.pdf
+
 pub mod ciphertext;
 pub mod encodedtext;
 pub mod plaintext;
@@ -16,6 +21,16 @@ pub use plaintext::{Plaintext, Plaintextish, Plaintexts};
 use rand::Rng;
 use rand_distr::{Distribution, Normal};
 
+/// Parameters for a Somewhat Homomorphic Encryption Scheme (SHE).
+///
+/// This struct holds various parameters used in the context of a Somewhat Homomorphic Encryption Scheme.
+///
+/// - `s`: The length of the Plaintext.
+/// - `n`: The degree of the polynomial (length of Encodedtext), which should match the length of the plaintext.
+/// - `p`: The modulus of the Plaintext.
+/// - `q`: The modulus of the Encodedtext.
+/// - `std_dev`: The standard deviation for generating random numbers from a Gaussian distribution.
+///
 pub struct SHEParameters {
     // length of Plaintext
     s: usize,
@@ -75,6 +90,16 @@ impl PublicKey {
     }
 }
 
+/// From Gaussian distribution, generate Encodedtext.
+///
+/// # Arguments
+/// * `she_params` - SHE(Somewhat Homomorphic Encryption) parameters.
+/// * `dimension` - the length of desired Encodedtext.
+/// * `rng` - random number generator.
+///
+/// # Returns
+/// The randomly generated Encodedtext its length = dimension.
+///
 pub fn get_gaussian<T: Rng>(
     she_params: &SHEParameters,
     dimension: usize,

src/she/polynomial.rs

@@ -7,6 +7,17 @@ use ark_poly::{
 };
 use ark_std::log2;
 
+/// Interpolate a polynomial such that it passes through specified points.
+/// This function calculates an interpolated polynomial that passes through a set of given points.
+///
+/// # Arguments
+///
+/// * `eval_at` - A vector containing the x-values of the points to interpolate.
+/// * `evals` - A vector containing the corresponding y-values of the points to interpolate.
+///
+/// # Returns
+/// An `Option` containing the coefficients of the interpolated polynomial. Returns `None` if interpolation fails.
+///
 pub fn interpolate<F: FftField>(eval_at: &Vec<F>, evals: &Vec<F>) -> Option<Vec<F>> {
     let n = eval_at.len();
     let m = evals.len();
@@ -57,6 +68,15 @@ pub fn interpolate<F: FftField>(eval_at: &Vec<F>, evals: &Vec<F>) -> Option<Vec<
     Some(res_coeff)
 }
 
+/// Substitute a value into a polynomial.
+///
+/// # Arguments
+/// * `polynomial` - The polynomial to substitute into.
+/// * `variable` - The value to substitute.
+///
+/// # Returns
+/// The result of the substitution.
+///
 pub fn substitute<F: Field>(polynomial: &[F], variable: &F) -> F {
     let mut result = F::zero();
     for (i, coefficient) in polynomial.iter().enumerate() {
@@ -65,12 +85,22 @@ pub fn substitute<F: Field>(polynomial: &[F], variable: &F) -> F {
     result
 }
 
+/// Compute the roots of the cyclotomic polynomial \Phi_(2 * length)(X) on F. where length is expected to be a power of two.
+///
+/// # Arguments
+/// * `length` - The length of the roots.
+///
+/// # Returns
+/// The vector of (2 * length)-th roots of the cyclotomic polynomial.
+///
+/// # Notes
+/// The cyclotomic polynomial \Phi_N(X) is defined as the minimal polynomial of the primitive N-th root of unity.
+/// If N is a power of two, then \Phi_N(X) = X^(N/2) + 1. For example, \Phi_8(X) = X^4 + 1.
+/// let r is a one of the roots of the cyclotomic polynomial \Phi_N(X) on F, then returns [r, r^2, r^3, r^4, ..., r^length].
+///
+/// TWO_ADIC_ROOT_OF_UNITY = 2^s-th root of unity in Fp (s = F::FftParams::TWO_ADICITY).
+///
 pub fn cyclotomic_moduli<F: FftField>(length: usize) -> Vec<F> {
-    // moduli: lengthは本来N-1だが、sで切り捨て
-    // N-1個の根は、円分多項式Phi_N(X) on Fpの根である
-
-    // N=sである。N * 2=mである。mは2の冪である。m=2^kであるとき(ただし、1<=k<47)、moduliは、TWO_ADIC_ROOT_OF_UNITY^{2^(47-k)}のi乗である。
-
     let k = log2(length * 2);
     let s = F::FftParams::TWO_ADICITY;
     assert!(k < s);
@@ -109,6 +139,16 @@ fn poly_remainder<F: Field>(a: &[F], b: &[F], degree: usize) -> Vec<F> {
     r
 }
 
+/// Compute the remainder of a polynomial division on F.
+///
+/// # Arguments
+/// * `a` - The first polynomial.
+/// * `b` - The second polynomial.
+/// * `expect_length` - The degree of the remainder (Fill in 0 when it becomes shorter than that length.).
+///
+/// # Returns
+/// The residue of the polynomial division a % b.
+///
 pub fn poly_remainder2<F: Field>(a: &[F], b: &[F], expect_length: usize) -> Vec<F> {
     let a_poly = DensePolynomial::from_coefficients_vec(a.to_vec());
     let b_poly = DensePolynomial::from_coefficients_vec(b.to_vec());