Merge pull request #215 from dalek-cryptography/circuit-notes-edit

some more circuit tweaks

Author: cathieyun

benches/r1cs.rs

@@ -84,20 +84,20 @@ impl KShuffleGadget {
         }
 
         // Make last x multiplier for i = k-1 and k-2
-        let (_, _, last_mulx_out) = cs.add_intermediate_constraint(x[k - 1] - z, x[k - 2] - z);
+        let (_, _, last_mulx_out) = cs.add_partial_constraint(x[k - 1] - z, x[k - 2] - z);
 
         // Make multipliers for x from i == [0, k-3]
         let first_mulx_out = (0..k - 2).rev().fold(last_mulx_out, |prev_out, i| {
-            let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), x[i] - z);
+            let (_, _, o) = cs.add_partial_constraint(prev_out.into(), x[i] - z);
             o
         });
 
         // Make last y multiplier for i = k-1 and k-2
-        let (_, _, last_muly_out) = cs.add_intermediate_constraint(y[k - 1] - z, y[k - 2] - z);
+        let (_, _, last_muly_out) = cs.add_partial_constraint(y[k - 1] - z, y[k - 2] - z);
 
         // Make multipliers for y from i == [0, k-3]
         let first_muly_out = (0..k - 2).rev().fold(last_muly_out, |prev_out, i| {
-            let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), y[i] - z);
+            let (_, _, o) = cs.add_partial_constraint(prev_out.into(), y[i] - z);
             o
         });
 

docs/aggregation-api.md

@@ -1,4 +1,5 @@
-The `aggregation` module contains the API for performing the aggregated multiparty computation protocol.
+The `range_proof_mpc` module contains the API for performing the aggregated multiparty computation protocol for joint range proof proving.
+
 Only the range proofs are supported, while aggregation of constraint system proofs is under development.
 
 API for the aggregated multiparty computation protocol 

src/errors.rs

@@ -99,12 +99,6 @@ pub enum R1CSError {
     /// Occurs when there are insufficient generators for the proof.
     #[fail(display = "Invalid generators size, too few generators for proof")]
     InvalidGeneratorsLength,
-    /// Occurs when trying to use a missing variable assignment, for
-    /// instance if
-    /// [`Assignment::Missing`](::r1cs::Assignment::Missing) is passed
-    /// to a [`ProverCS`](::r1cs::ProverCS).
-    #[fail(display = "Variable does not have a value assignment.")]
-    MissingAssignment,
     /// Occurs when verification of an
     /// [`R1CSProof`](::r1cs::R1CSProof) fails.
     #[fail(display = "R1CSProof did not verify correctly.")]

src/r1cs/constraint_system.rs

@@ -6,7 +6,7 @@ use curve25519_dalek::scalar::Scalar;
 /// The interface for a constraint system, abstracting over the prover
 /// and verifier's roles.
 ///
-/// Statements to be proved by an [`R1CSProof`] are specified by
+/// Statements to be proved by an [`R1CSProof`](::r1cs::R1CSProof) are specified by
 /// programmatically constructing constraints.  These constraints need
 /// to be identical between the prover and verifier, since the prover
 /// and verifier need to construct the same statement.
@@ -16,35 +16,43 @@ use curve25519_dalek::scalar::Scalar;
 /// using the `ConstraintSystem` trait, so that the prover and
 /// verifier share the logic for specifying constraints.
 pub trait ConstraintSystem {
-    /// Constrain `left`, `right`, and `out` linear combinations such that:
-    /// `left` = `l_var` (by adding a constraint)
-    /// `right` = `r_var` (by adding a constraint)
-    /// `out` = `o_var` (by adding a constraint)
-    /// `l_var` * `r_var` = `o_var` (by allocating multiplier variables)
-    /// Where:
-    /// `l_var` is either `left.eval()` (prover) or `Missing` (verifier)
-    /// `r_var` is either `right.eval()` (prover) or `Missing` (verifier)
-    /// `o_var` is either `out.eval()` (prover) or `Missing` (verifier)
-    /// This is used when all three gates of a multiplication gate should be
-    /// constrained by linear constraints.
+    /// Allocate variables `left`, `right`, and `out`
+    /// with the implicit constraint that
+    /// ```text
+    /// left * right = out
+    /// ```
+    /// and the explicit constraints that
+    /// ```text
+    /// left = left_constraint
+    /// right = right_constraint
+    /// out = out_constraint
+    /// ```
+    /// This is used when all three multiplier variables can be constrained up-front.
+    ///
+    /// Returns `(left, right, out)` for use in further constraints.
     fn add_constraint(
         &mut self,
-        left: LinearCombination,
-        right: LinearCombination,
-        out: LinearCombination,
+        left_constraint: LinearCombination,
+        right_constraint: LinearCombination,
+        out_constraint: LinearCombination,
     ) -> (Variable, Variable, Variable);
 
-    /// Constrain `left` and `right` linear combinations such that:
-    /// `left` = `l_var` (by adding a constraint)
-    /// `right` = `r_var` (by adding a constraint)
-    /// `l_var` * `r_var` = `o_var` (by allocating multiplier variables)
-    /// Where:
-    /// `l_var` is either `left.eval()` (prover) or `Missing` (verifier)
-    /// `r_var` is either `right.eval()` (prover) or `Missing` (verifier)
-    /// `o_var` is either `left.eval() * right.eval()` (prover) or `Missing` (verifier)
-    /// This is used when only the left and right inputs of a multiplication gate
-    /// should be constrained by linear constraints.
-    fn add_intermediate_constraint(
+    /// Allocate variables `left`, `right`, and `out`
+    /// with the implicit constraint that
+    /// ```text
+    /// left * right = out
+    /// ```
+    /// and the explicit constraints that
+    /// ```text
+    /// left = left_constraint
+    /// right = right_constraint
+    /// ```
+    /// This is used when the output variable cannot be immediately
+    /// constrained (for instance, because it should be constrained to
+    /// match a variable that has not yet been allocated).
+    ///
+    /// Returns `(left, right, out)` for use in further constraints.
+    fn add_partial_constraint(
         &mut self,
         left: LinearCombination,
         right: LinearCombination,

src/r1cs/mod.rs

@@ -84,20 +84,20 @@
 //!         }
 //!
 //!         // Make last x multiplier for i = k-1 and k-2
-//!         let (_, _, last_mulx_out) = cs.add_intermediate_constraint(x[k - 1] - z, x[k - 2] - z);
+//!         let (_, _, last_mulx_out) = cs.add_partial_constraint(x[k - 1] - z, x[k - 2] - z);
 //!
 //!         // Make multipliers for x from i == [0, k-3]
 //!         let first_mulx_out = (0..k - 2).rev().fold(last_mulx_out, |prev_out, i| {
-//!             let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), x[i] - z);
+//!             let (_, _, o) = cs.add_partial_constraint(prev_out.into(), x[i] - z);
 //!             o
 //!         });
 //!
 //!         // Make last y multiplier for i = k-1 and k-2
-//!         let (_, _, last_muly_out) = cs.add_intermediate_constraint(y[k - 1] - z, y[k - 2] - z);
+//!         let (_, _, last_muly_out) = cs.add_partial_constraint(y[k - 1] - z, y[k - 2] - z);
 //!
 //!         // Make multipliers for y from i == [0, k-3]
 //!         let first_muly_out = (0..k - 2).rev().fold(last_muly_out, |prev_out, i| {
-//!             let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), y[i] - z);
+//!             let (_, _, o) = cs.add_partial_constraint(prev_out.into(), y[i] - z);
 //!             o
 //!         });
 //!

src/r1cs/proof.rs

@@ -10,12 +10,12 @@ use inner_product_proof::InnerProductProof;
 ///
 /// Statements are specified by writing gadget functions which add
 /// constraints to a [`ConstraintSystem`](::r1cs::ConstraintSystem)
-/// implementation.  To construct an `R1CSProof`, a prover constructs
+/// implementation.  To construct an [`R1CSProof`], a prover constructs
 /// a [`ProverCS`](::r1cs::ProverCS), then passes it to gadget
 /// functions to build the constraint system, then consumes the
 /// constraint system using
 /// [`ProverCS::prove`](::r1cs::ProverCS::prove) to produce an
-/// `R1CSProof`.  To verify an `R1CSProof`, a verifier constructs a
+/// [`R1CSProof`].  To verify an [`R1CSProof`], a verifier constructs a
 /// [`VerifierCS`](::r1cs::VerifierCS), then passes it to the same
 /// gadget functions to (re)build the constraint system, then consumes
 /// the constraint system using

src/r1cs/prover.rs

@@ -100,7 +100,7 @@ impl<'a, 'b> ConstraintSystem for ProverCS<'a, 'b> {
         (l_var, r_var, o_var)
     }
 
-    fn add_intermediate_constraint(
+    fn add_partial_constraint(
         &mut self,
         mut left: LinearCombination,
         mut right: LinearCombination,

src/r1cs/tests.rs

@@ -174,20 +174,20 @@ impl KShuffleGadget {
         }
 
         // Make last x multiplier for i = k-1 and k-2
-        let (_, _, last_mulx_out) = cs.add_intermediate_constraint(x[k - 1] - z, x[k - 2] - z);
+        let (_, _, last_mulx_out) = cs.add_partial_constraint(x[k - 1] - z, x[k - 2] - z);
 
         // Make multipliers for x from i == [0, k-3]
         let first_mulx_out = (0..k - 2).rev().fold(last_mulx_out, |prev_out, i| {
-            let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), x[i] - z);
+            let (_, _, o) = cs.add_partial_constraint(prev_out.into(), x[i] - z);
             o
         });
 
         // Make last y multiplier for i = k-1 and k-2
-        let (_, _, last_muly_out) = cs.add_intermediate_constraint(y[k - 1] - z, y[k - 2] - z);
+        let (_, _, last_muly_out) = cs.add_partial_constraint(y[k - 1] - z, y[k - 2] - z);
 
         // Make multipliers for y from i == [0, k-3]
         let first_muly_out = (0..k - 2).rev().fold(last_muly_out, |prev_out, i| {
-            let (_, _, o) = cs.add_intermediate_constraint(prev_out.into(), y[i] - z);
+            let (_, _, o) = cs.add_partial_constraint(prev_out.into(), y[i] - z);
             o
         });
 

src/r1cs/verifier.rs

@@ -13,19 +13,18 @@ use transcript::TranscriptProtocol;
 
 /// A [`ConstraintSystem`] implementation for use by the verifier.
 ///
-/// The lifecycle of a `VerifierCS` is as follows. The verification
+/// The lifecycle of a [`VerifierCS`] is as follows. The verification
 /// code assembles the commitments to the external inputs to the
 /// constraint system, then passes them, along with generators and a
 /// transcript, to [`VerifierCS::new`].  This initializes the
-/// `VerifierCS` and returns [`Variable`]s corresponding to the
+/// [`VerifierCS`] and returns [`Variable`]s corresponding to the
 /// inputs.
 ///
-/// The verifier can then pass the `VerifierCS` and the external
-/// variables to the same gadget code as the prover, using
-/// `Assignment::Missing` for witness variables, to build an identical
-/// constraint system to the one the prover built.  Finally, they pass
-/// the prover's [`R1CSProof`] to [`VerifierCS::verify`], which
-/// consumes the `VerifierCS` and verifies the proof.
+/// The verifier can then pass the [`VerifierCS`] and the external
+/// variables to the same gadget code as the prover, constructing an
+/// identical constraint system to the one the prover built.  Finally,
+/// they pass the prover's [`R1CSProof`] to [`VerifierCS::verify`],
+/// which consumes the [`VerifierCS`] and verifies the proof.
 pub struct VerifierCS<'a, 'b> {
     bp_gens: &'b BulletproofGens,
     pc_gens: &'b PedersenGens,
@@ -68,7 +67,7 @@ impl<'a, 'b> ConstraintSystem for VerifierCS<'a, 'b> {
         (l_var, r_var, o_var)
     }
 
-    fn add_intermediate_constraint(
+    fn add_partial_constraint(
         &mut self,
         mut left: LinearCombination,
         mut right: LinearCombination,