From 0b2ec8965f994ec2ac2aa85d23eb28c501d53281 Mon Sep 17 00:00:00 2001
From: therealyingtong <yingtong@z.cash>
Date: Thu, 12 Nov 2020 15:32:00 +0800
Subject: [PATCH] Update documentation in polycommit verifier

---
 src/poly/commitment/verifier.rs | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/poly/commitment/verifier.rs b/src/poly/commitment/verifier.rs
index 70791e7..d786c74 100644
--- a/src/poly/commitment/verifier.rs
+++ b/src/poly/commitment/verifier.rs
@@ -38,8 +38,8 @@ impl<'a, C: CurveAffine> Guard<'a, C> {
         self.msm
     }
 
-    /// Lets caller supply the purported G point and simply appends it to
-    /// return an updated MSM.
+    /// Lets caller supply the purported G point and simply appends
+    /// [-z1] G to return an updated MSM.
     pub fn use_g(mut self, g: C) -> (MSM<'a, C>, Accumulator<C>) {
         self.msm.append_term(self.neg_z1, g);
 
@@ -51,7 +51,7 @@ impl<'a, C: CurveAffine> Guard<'a, C> {
         (self.msm, accumulator)
     }
 
-    /// Computes the g value when given a potential scalar as input.
+    /// Computes G + H, where G = ⟨s, params.g⟩ and H is used for blinding
     pub fn compute_g(&self) -> C {
         let s = compute_s(&self.challenges_sq, self.allinv);
 
@@ -159,9 +159,11 @@ impl<C: CurveAffine> Proof<C> {
         let c_packed = transcript.squeeze().get_lower_128();
         let c: C::Scalar = get_challenge_scalar(Challenge(c_packed));
 
-        // Check
-        // [c] P + [c * v] U + [c] sum(L_i * u_i^2) + [c] sum(R_i * u_i^-2) + delta - [z1] G - [z1 * b] U - [z1 - z2] H
-        // = 0
+        // Construct
+        // [c] P + [c * v] U + [c] sum(L_i * u_i^2) + [c] sum(R_i * u_i^-2) + delta - [z1 * b] U + [z1 - z2] H
+        // = [z1] (G + H)
+        // The computation of [z1] (G + H) happens in either Guard::use_challenges()
+        // or Guard::use_g().
 
         let b = compute_b(x, &challenges, &challenges_inv);
 
@@ -171,6 +173,7 @@ impl<C: CurveAffine> Proof<C> {
         commitment_msm.scale(c);
         msm.add_msm(&commitment_msm);
 
+        // [c] sum(L_i * u_i^2) + [c] sum(R_i * u_i^-2)
         for scalar in &mut extra_scalars {
             *scalar *= &c;
         }
@@ -185,7 +188,7 @@ impl<C: CurveAffine> Proof<C> {
         // delta
         msm.append_term(Field::one(), self.delta);
 
-        // - [z1 - z2] H
+        // + [z1 - z2] H
         msm.add_to_h_scalar(self.z1 - &self.z2);
 
         let guard = Guard {