Operations, comments and tests

Author: hdvanegasm

src/math/ec/mod.rs

@@ -8,12 +8,14 @@ pub mod secp256k1;
 pub trait EllipticCurve<const LIMBS: usize>:
     Serialize + for<'a> Deserialize<'a> + PartialEq + Copy + Clone
 {
+    /// Field of coefficients of the elliptic curve.
     type ScalarField: FiniteField<LIMBS>;
 
     /// Field in which the elliptic curve is defined. The points in the elliptic curve will be
     /// pairs in this field.
     type PrimeField: FiniteField<LIMBS>;
 
+    /// The zero point in the elliptic courve group.
     const ZERO: Self;
 
     /// Returns the generator of the curve.

src/math/ec/secp256k1.rs

@@ -23,14 +23,17 @@ pub struct Secp256k1(
 pub struct AffinePoint(Secp256k1PrimeField, Secp256k1PrimeField);
 
 impl AffinePoint {
+    /// Returns the x-coordinate of the affine point.
     pub fn x(&self) -> &Secp256k1PrimeField {
         &self.0
     }
 
+    /// Returns the y-coordinate of the affine point.
     pub fn y(&self) -> &Secp256k1PrimeField {
         &self.1
     }
 
+    /// Checks if the affine point lies in the elliptic curve.
     pub fn is_valid(&self) -> bool {
         let b = Secp256k1PrimeField::from(7);
         let lhs = self.y().mul(self.y());
@@ -78,6 +81,7 @@ impl Secp256k1 {
         self.z().eq(&Secp256k1PrimeField::ZERO)
     }
 
+    /// Doubles this point.
     pub fn dbl(&self) -> Self {
         let b3 = Secp256k1PrimeField::from(3 * 7);
 

src/math/field/secp256k1_prime.rs

@@ -4,10 +4,12 @@ use crypto_bigint::{rand_core::RngCore, NonZero, RandomMod, Uint, Zero};
 use serde::{Deserialize, Serialize};
 use std::ops::{Add, Div, Mul, Sub};
 
+/// Represents an element in the field in which secp256k1 is defined.
 #[derive(Debug, Copy, Clone, PartialEq, Hash, Eq, Serialize, Deserialize)]
 pub struct Secp256k1PrimeField(Uint<4>);
 
 impl Secp256k1PrimeField {
+    /// Created a new point in the field in which secp256k1 is defined.
     pub fn new(value: Uint<4>) -> Self {
         Self(value)
     }

src/math/field/secp256k1_scalar.rs

@@ -6,10 +6,12 @@ use std::ops::{Add, Div, Mul, Sub};
 
 const LIMBS: usize = 4;
 
+/// Represents a finite field modulo a secp256k1 prime order sub-group.
 #[derive(Debug, Copy, Clone, PartialEq, Hash, Eq, Serialize, Deserialize)]
 pub struct Secp256k1ScalarField(Uint<LIMBS>);
 
 impl Secp256k1ScalarField {
+    /// Computes the NAF representation of this field element.
     pub fn to_naf(&self) -> NafEncoding {
         let mut naf = NafEncoding::new(Self::BIT_SIZE + 1);
         let mut val = self.0;
@@ -115,6 +117,7 @@ impl Div<&Self> for Secp256k1ScalarField {
     }
 }
 
+/// Returns `true` if the bit in the position is 1, otherwise returns `false`.
 fn test_bit<const LIMBS: usize>(input: Uint<LIMBS>, pos: usize) -> bool {
     assert!((pos as u32) < LIMBS as u32 * Limb::BITS);
     let bits_per_limb = Limb::BITS;

src/math/poly.rs

@@ -40,10 +40,12 @@ impl<const LIMBS: usize, T: FiniteField<LIMBS>> Polynomial<LIMBS, T> {
         result
     }
 
+    /// Returns the coefficients of the polynomial.
     pub fn coefficients(&self) -> &[T] {
         &self.0
     }
 
+    /// Returns the degree of the polynomial.
     pub fn degree(&self) -> usize {
         self.0.len() - 1
     }
@@ -57,12 +59,18 @@ impl<const LIMBS: usize, T: FiniteField<LIMBS>> Polynomial<LIMBS, T> {
         Self(coefficients)
     }
 
+    /// Changes the value of the constant coefficient of the polynomial.
     pub fn set_constant_coeff(&mut self, value: T) {
         self[0] = value;
     }
 
+    /// Creates a polynomial from its coefficients.
+    ///
+    /// # Errors
+    ///
+    /// If the array of coefficients is empty, the function returns [`Error::EmptyCoefficients`].
     pub fn new(coef: Vec<T>) -> Result<Self, T> {
-        if coef.len() == 0 {
+        if coef.is_empty() {
             Err(Error::EmptyCoefficients)
         } else {
             Ok(Self(coef))
@@ -92,7 +100,12 @@ impl<const LIMBS: usize, const N: usize, T: FiniteField<LIMBS>> From<[T; N]>
     }
 }
 
-/// Computes the lagrange basis evaluated at `x`
+/// Computes the lagrange basis evaluated at `x`.
+///
+/// # Errors
+///
+/// The function returns [`Error::NotAllDifferentInterpolation`] if the list of nodes are not all
+/// different.
 pub fn compute_lagrange_basis<const LIMBS: usize, T: FiniteField<LIMBS>>(
     nodes: &[T],
     x: &T,
@@ -135,6 +148,10 @@ fn all_different<T: Ring>(list: &[T]) -> bool {
 }
 
 /// Computes the evaluation of the interpolated polynomial at `x`.
+///
+/// # Error
+///
+/// If the lagrange basis is not computed correctly, the function returns an [`Error`].
 pub fn interpolate_polynomial_at<const LIMBS: usize, T: FiniteField<LIMBS>>(
     evaluations: &[T],
     alphas: &[T],

src/math/ring.rs

@@ -21,10 +21,13 @@ pub trait Ring:
     + Copy
     + Hash
 {
+    /// Bit size of an element of the ring.
     const BIT_SIZE: usize;
+
     /// Additive identity of the ring.
     const ZERO: Self;
 
+    /// Number of limbs used to represent a ring element.
     const LIMBS: usize;
 
     /// Multiplicative identity of the ring.
@@ -36,5 +39,6 @@ pub trait Ring:
     /// Generates a random finite ring element with a provided pseudo-random generator.
     fn random<R: RngCore>(generator: &mut R) -> Self;
 
+    /// Returns a non-zero element from the ring sampled uniformly at random.
     fn random_non_zero<R: RngCore>(generator: &mut R) -> Self;
 }

src/math/vector.rs

@@ -3,8 +3,16 @@ use crypto_bigint::rand_core::RngCore;
 use serde::Serialize;
 use std::ops::{Add, Index, IndexMut, Mul, Sub};
 
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    #[error("the operands do not have the same dimension: {0:?} and {1:?}")]
+    IncompatibleDimension(usize, usize),
+}
+
+pub type Result<T> = std::result::Result<T, Error>;
+
 /// Vector whose elements belong to a ring.
-#[derive(Serialize, PartialEq, Eq, Debug)]
+#[derive(Serialize, PartialEq, Eq, Debug, Clone)]
 pub struct Vector<T: Ring>(Vec<T>);
 
 impl<T> Vector<T>
@@ -16,8 +24,9 @@ where
         self.0.len()
     }
 
+    /// Returns whether the vector has no elements.
     pub fn is_empty(&self) -> bool {
-        self.len() == 0
+        self.0.is_empty()
     }
 
     /// Generates a vector of zeroes.
@@ -40,12 +49,15 @@ where
     }
 
     /// Computes the dot product between two vectors.
-    pub fn dot(&self, other: &Vector<T>) -> T {
+    pub fn dot(&self, other: &Vector<T>) -> Result<T> {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
         let mut result = T::ZERO;
         for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
             result = result + &(*self_elem * other_elem);
         }
-        result
+        Ok(result)
     }
 }
 
@@ -82,43 +94,106 @@ impl<T> Add<&Vector<T>> for Vector<T>
 where
     T: Ring,
 {
-    type Output = Self;
+    type Output = Result<Self>;
 
     fn add(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
         let mut output = Vec::with_capacity(other.0.len());
         for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
             output.push(*self_elem + other_elem);
         }
-        Self(output)
+        Ok(Self(output))
+    }
+}
+
+impl<T> Add<&Vector<T>> for &Vector<T>
+where
+    T: Ring,
+{
+    type Output = Result<Vector<T>>;
+
+    fn add(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
+        let mut output = Vec::with_capacity(other.0.len());
+        for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
+            output.push(*self_elem + other_elem);
+        }
+        Ok(Vector(output))
     }
 }
 
 impl<T> Sub<&Vector<T>> for Vector<T>
 where
     T: Ring,
 {
-    type Output = Self;
+    type Output = Result<Self>;
+
+    fn sub(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
+        let mut output = Vec::with_capacity(other.0.len());
+        for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
+            output.push(*self_elem - other_elem);
+        }
+        Ok(Self(output))
+    }
+}
+
+impl<T> Sub<&Vector<T>> for &Vector<T>
+where
+    T: Ring,
+{
+    type Output = Result<Vector<T>>;
 
     fn sub(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
         let mut output = Vec::with_capacity(other.0.len());
         for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
             output.push(*self_elem - other_elem);
         }
-        Self(output)
+        Ok(Vector(output))
     }
 }
 
 impl<T> Mul<&Vector<T>> for Vector<T>
 where
     T: Ring,
 {
-    type Output = Self;
+    type Output = Result<Self>;
 
     fn mul(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
+        let mut output = Vec::with_capacity(other.0.len());
+        for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
+            output.push(*self_elem * other_elem);
+        }
+        Ok(Self(output))
+    }
+}
+
+impl<T> Mul<&Vector<T>> for &Vector<T>
+where
+    T: Ring,
+{
+    type Output = Result<Vector<T>>;
+
+    fn mul(self, other: &Vector<T>) -> Self::Output {
+        if self.len() != other.len() {
+            return Err(Error::IncompatibleDimension(self.len(), other.len()));
+        }
         let mut output = Vec::with_capacity(other.0.len());
         for (self_elem, other_elem) in self.0.iter().zip(other.0.iter()) {
             output.push(*self_elem * other_elem);
         }
-        Self(output)
+        Ok(Vector(output))
     }
 }

src/net/mod.rs

@@ -21,18 +21,23 @@ use std::{
 };
 use thiserror::Error;
 
+/// Error type for network errors.
 #[derive(Debug, Error)]
 pub enum NetworkError {
+    /// Encapsulates a TLS error.
     #[error("TLS error: {0:?}")]
     TlsError(rustls::Error),
 
+    /// This error is returned when there is an IO error.
     #[error("IO error: {0:?}")]
     IoError(io::Error),
 
+    /// This error encapsulates a channel error.
     #[error("channel error: {0:?}")]
     ChannelError(channel::ChannelError),
 }
 
+/// Special type for the network error.
 pub type Result<T> = std::result::Result<T, NetworkError>;
 
 // This packet can be changed such that the elements in it can be of multiple types.
@@ -71,17 +76,20 @@ impl Packet {
         self.0.len()
     }
 
+    /// Extract the first element in the packet.
     pub fn pop<'de, T>(&mut self) -> T
     where
         T: Deserialize<'de>,
     {
         todo!()
     }
 
+    /// Read the element at the given index inside the packet.
     pub fn read<T>(&self, _obj_idx: usize) -> T {
         todo!()
     }
 
+    /// Write an element at the end of the packet.
     pub fn write<T>(&mut self, _obj: T)
     where
         T: Serialize,
@@ -206,6 +214,12 @@ pub struct Network {
 }
 
 impl Network {
+    /// Configure the TLS channel according to the provided network configuration.
+    ///
+    /// # Error
+    ///
+    /// The function returns an error if the cerificate and the private key are not configured
+    /// correctly.
     fn configure_tls(config: &NetworkConfig<'static>) -> Result<(ClientConfig, ServerConfig)> {
         // Configure the client TLS
         let client_conf = ClientConfig::builder()
@@ -222,6 +236,15 @@ impl Network {
 
     /// Creates a new network using the ID of the current party and the number of parties connected
     /// to the network.
+    ///
+    /// # Error
+    ///
+    /// The function returns an error in the following cases:
+    /// - When the binding of the channel to a certain IP address is
+    /// not done correctly.
+    /// - When the TLS configuration is not done correctly.
+    /// - When the node is trying to connect as a server but is unable to accept the provided
+    /// client.
     pub fn create(id: usize, config: NetworkConfig<'static>) -> Result<Self> {
         log::info!("creating network");
         let n_parties = config.peer_ips.len();