update package name; make modules public and add docs

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "nova"
+name = "nova-snark"
 version = "0.1.0"
 authors = ["Srinath Setty <srinath@microsoft.com>"]
 edition = "2018"

src/errors.rs

@@ -1,5 +1,7 @@
+//! This module defines errors returned by the library.
 use core::fmt::Debug;
 
+/// Errors returned by Nova
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum NovaError {
   /// returned if the supplied row or col in (row,col,val) tuple is out of range

src/lib.rs

@@ -5,9 +5,9 @@
 #![deny(missing_docs)]
 
 mod commitments;
-mod errors;
+pub mod errors;
-mod r1cs;
+pub mod r1cs;
-mod traits;
+pub mod traits;
 
 use std::marker::PhantomData;
 

src/r1cs.rs

@@ -1,3 +1,4 @@
+//! This module defines R1CS related types and a folding scheme for (relaxed) R1CS
 #![allow(clippy::type_complexity)]
 use super::commitments::{CommitGens, CommitTrait, Commitment, CompressedCommitment};
 use super::errors::NovaError;
@@ -5,11 +6,13 @@ use super::traits::{Group, PrimeField};
 use itertools::concat;
 use rayon::prelude::*;
 
+/// Public parameters for a given R1CS
 pub struct R1CSGens<G: Group> {
   gens_W: CommitGens<G>,
   gens_E: CommitGens<G>,
 }
 
+/// A type that holds the shape of the R1CS matrices
 #[derive(Debug)]
 pub struct R1CSShape<G: Group> {
   num_cons: usize,
@@ -20,12 +23,14 @@ pub struct R1CSShape<G: Group> {
   C: Vec<(usize, usize, G::Scalar)>,
 }
 
+/// A type that holds a witness for a given R1CS instance
 #[derive(Clone, Debug)]
 pub struct R1CSWitness<G: Group> {
   W: Vec<G::Scalar>,
   E: Vec<G::Scalar>,
 }
 
+/// A type that holds an R1CS instance
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct R1CSInstance<G: Group> {
   comm_W: Commitment<G>,
@@ -35,6 +40,7 @@ pub struct R1CSInstance<G: Group> {
 }
 
 impl<G: Group> R1CSGens<G> {
+  /// Samples public parameters for the specified number of constraints and variables in an R1CS
   pub fn new(num_cons: usize, num_vars: usize) -> R1CSGens<G> {
     // generators to commit to witness vector `W`
     let gens_W = CommitGens::new(b"gens_W", num_vars);
@@ -47,6 +53,7 @@ impl<G: Group> R1CSGens<G> {
 }
 
 impl<G: Group> R1CSShape<G> {
+  /// Create an object of type `R1CSShape` from the explicitly specified R1CS matrices
   pub fn new(
     num_cons: usize,
     num_vars: usize,
@@ -129,6 +136,7 @@ impl<G: Group> R1CSShape<G> {
     Ok((Az, Bz, Cz))
   }
 
+  /// Checks if the R1CS instance is satisfiable given a witness and its shape
   pub fn is_sat(
     &self,
     gens: &R1CSGens<G>,
@@ -175,6 +183,7 @@ impl<G: Group> R1CSShape<G> {
     }
   }
 
+  /// A method to compute a commitment to the cross-term `T` given two R1CS instance-witness pairs
   pub fn commit_T(
     &self,
     gens: &R1CSGens<G>,
@@ -227,6 +236,7 @@ impl<G: Group> R1CSShape<G> {
 }
 
 impl<G: Group> R1CSWitness<G> {
+  /// A method to create a witness object using a vector of scalars
   pub fn new(
     S: &R1CSShape<G>,
     W: &[G::Scalar],
@@ -242,10 +252,12 @@ impl<G: Group> R1CSWitness<G> {
     }
   }
 
+  /// Commits to the witness using the supplied generators
   pub fn commit(&self, gens: &R1CSGens<G>) -> (Commitment<G>, Commitment<G>) {
     (self.W.commit(&gens.gens_W), self.E.commit(&gens.gens_E))
   }
 
+  /// Folds an incoming R1CSWitness into the current one
   pub fn fold(
     &self,
     W2: &R1CSWitness<G>,
@@ -275,6 +287,7 @@ impl<G: Group> R1CSWitness<G> {
 }
 
 impl<G: Group> R1CSInstance<G> {
+  /// A method to create an instance object using consitituent elements
   pub fn new(
     S: &R1CSShape<G>,
     comm_W: &Commitment<G>,
@@ -294,6 +307,7 @@ impl<G: Group> R1CSInstance<G> {
     }
   }
 
+  /// Folds an incoming R1CSInstance into the current one
   pub fn fold(
     &self,
     U2: &R1CSInstance<G>,

src/traits.rs

@@ -1,3 +1,4 @@
+//! This module defines various traits required by the users of the library to implement.
 use core::borrow::Borrow;
 use core::fmt::Debug;
 use core::ops::{Add, AddAssign, Mul, MulAssign, Neg, Sub, SubAssign};
@@ -53,9 +54,13 @@ pub trait Group:
   + ScalarMul<<Self as Group>::Scalar>
   + ScalarMulOwned<<Self as Group>::Scalar>
 {
+  /// A type representing an element of the scalar field of the group
   type Scalar: PrimeField + ChallengeTrait;
+
+  /// A type representing the compressed version of the group element
   type CompressedGroupElement: CompressedGroup<GroupElement = Self>;
 
+  /// A method to compute a multiexponentation
   fn vartime_multiscalar_mul<I, J>(scalars: I, points: J) -> Self
   where
     I: IntoIterator,
@@ -64,22 +69,29 @@ pub trait Group:
     J::Item: Borrow<Self>,
     Self: Clone;
 
+  /// Compresses the group element
   fn compress(&self) -> Self::CompressedGroupElement;
 
+  /// Attempts to create a group element from a sequence of bytes, 
+  /// failing with a `None` if the supplied bytes do not encode the group element
   fn from_uniform_bytes(bytes: &[u8]) -> Option<Self>;
 }
 
 /// Represents a compressed version of a group element
 pub trait CompressedGroup: Clone + Copy + Debug + Eq + Sized + Send + Sync + 'static {
+  /// A type that holds the decompressed version of the compressed group element
   type GroupElement: Group;
 
+  /// Decompresses the compressed group element
   fn decompress(&self) -> Option<Self::GroupElement>;
 
+  /// Returns a byte array representing the compressed group element
   fn as_bytes(&self) -> &[u8];
 }
 
 /// A helper trait to generate challenges using a transcript object
 pub trait ChallengeTrait {
+  /// Returns a Scalar representing the challenge using the transcript
   fn challenge(label: &'static [u8], transcript: &mut Transcript) -> Self;
 }