From b45a37febb736d84064b35d71c2e8416622298f5 Mon Sep 17 00:00:00 2001
From: Sean Bowe <ewillbefull@gmail.com>
Date: Mon, 5 Mar 2018 16:00:04 -0700
Subject: [PATCH] Add comments and reorder some generators.

---
 src/circuit/mod.rs |  4 +--
 src/jubjub/mod.rs  | 67 +++++++++++++++++++++++++++++++++++++---------
 2 files changed, 56 insertions(+), 15 deletions(-)

diff --git a/src/circuit/mod.rs b/src/circuit/mod.rs
index 1d0bc7b..e41736b 100644
--- a/src/circuit/mod.rs
+++ b/src/circuit/mod.rs
@@ -527,7 +527,7 @@ fn test_input_circuit_with_bls12_381() {
 
         assert!(cs.is_satisfied());
         assert_eq!(cs.num_constraints(), 97379);
-        assert_eq!(cs.hash(), "db283e10d01d6c3c4d23cd3c05a7ae8f1a7d8091a39f8d8b604e610ca6a3e496");
+        assert_eq!(cs.hash(), "cae701c7acd6fee80b8dfc547855f44dcb3eb6cf64e434afa8c77a93bafd9d0e");
     }
 }
 
@@ -565,6 +565,6 @@ fn test_output_circuit_with_bls12_381() {
 
         assert!(cs.is_satisfied());
         assert_eq!(cs.num_constraints(), 7827);
-        assert_eq!(cs.hash(), "ccb2ad9a6d492e708da155305064a3b8af5d29b4b766cf08ac415a478aae4cc6");
+        assert_eq!(cs.hash(), "f9c01583d089117e01ee5d0dcc8d8d0d1f6c4af0a420a9981a5af9a572df26f1");
     }
 }
diff --git a/src/jubjub/mod.rs b/src/jubjub/mod.rs
index 189d434..dfc34a2 100644
--- a/src/jubjub/mod.rs
+++ b/src/jubjub/mod.rs
@@ -34,26 +34,80 @@ pub mod montgomery;
 #[cfg(test)]
 pub mod tests;
 
+/// Fixed generators of the Jubjub curve of unknown
+/// exponent.
+#[derive(Copy, Clone)]
+pub enum FixedGenerators {
+    /// The prover will demonstrate knowledge of discrete log
+    /// with respect to this base when they are constructing
+    /// a proof, in order to authorize proof construction.
+    ProvingPublicKey = 0,
+
+    /// The note commitment is randomized over this generator.
+    NoteCommitmentRandomness = 1,
+
+    /// The node commitment is randomized again by the position
+    /// in order to supply the nullifier computation with a
+    /// unique input w.r.t. the note being spent, to prevent
+    /// Faerie gold attacks.
+    NullifierPosition = 2,
+
+    /// The value commitment is used to check balance between
+    /// inputs and outputs. The value is placed over this
+    /// generator.
+    ValueCommitmentValue = 3,
+    /// The value commitment is randomized over this generator,
+    /// for privacy.
+    ValueCommitmentRandomness = 4,
+
+    /// The spender proves discrete log with respect to this
+    /// base at spend time.
+    SpendingKeyGenerator = 5,
+
+    Max = 6
+}
+
+/// This is an extension to the pairing Engine trait which
+/// offers a scalar field for the embedded curve (Jubjub)
+/// and some pre-computed parameters.
 pub trait JubjubEngine: Engine {
     type Fs: PrimeField + SqrtField;
     type Params: JubjubParams<Self>;
 }
 
+/// The pre-computed parameters for Jubjub, including curve
+/// constants and various limits and window tables.
 pub trait JubjubParams<E: JubjubEngine>: Sized {
+    /// The `d` constant of the twisted Edwards curve.
     fn edwards_d(&self) -> &E::Fr;
+    /// The `A` constant of the birationally equivalent Montgomery curve.
     fn montgomery_a(&self) -> &E::Fr;
+    /// The `A` constant, doubled.
     fn montgomery_2a(&self) -> &E::Fr;
+    /// The scaling factor used for conversion from the Montgomery form.
     fn scale(&self) -> &E::Fr;
+    /// Returns the generators (for each segment) used in all Pedersen commitments.
     fn pedersen_hash_generators(&self) -> &[edwards::Point<E, PrimeOrder>];
+    /// Returns the maximum number of chunks per segment of the Pedersen hash.
     fn pedersen_hash_chunks_per_generator(&self) -> usize;
+    /// Returns the pre-computed window tables [-4, 3, 2, 1, 1, 2, 3, 4] of different
+    /// magnitudes of the Pedersen hash segment generators.
     fn pedersen_circuit_generators(&self) -> &[Vec<Vec<(E::Fr, E::Fr)>>];
 
+    /// Returns the number of chunks needed to represent a full scalar during fixed-base
+    /// exponentiation.
     fn fixed_base_chunks_per_generator(&self) -> usize;
+    /// Returns a fixed generator.
     fn generator(&self, base: FixedGenerators) -> &edwards::Point<E, PrimeOrder>;
+    /// Returns a window table [0, 1, ..., 8] for different magntitudes of some
+    /// fixed generator.
     fn circuit_generators(&self, FixedGenerators) -> &[Vec<(E::Fr, E::Fr)>];
 }
 
+/// Point of unknown order.
 pub enum Unknown { }
+
+/// Point of prime order.
 pub enum PrimeOrder { }
 
 pub mod fs;
@@ -63,19 +117,6 @@ impl JubjubEngine for Bls12 {
     type Params = JubjubBls12;
 }
 
-/// Fixed generators of the Jubjub curve of unknown
-/// exponent.
-#[derive(Copy, Clone)]
-pub enum FixedGenerators {
-    NoteCommitmentRandomness = 0,
-    ProvingPublicKey = 1,
-    ValueCommitmentValue = 2,
-    ValueCommitmentRandomness = 3,
-    NullifierPosition = 4,
-    SpendingKeyGenerator = 5,
-    Max = 6
-}
-
 pub struct JubjubBls12 {
     edwards_d: Fr,
     montgomery_a: Fr,