update docs/comments

zk-sdk/src/sigma_proofs/percentage_with_cap.rs

@@ -36,18 +36,19 @@ use {
     subtle::{Choice, ConditionallySelectable, ConstantTimeGreater},
 };
 
-/// Byte length of a fee sigma proof.
+/// Byte length of a percentage-with-cap proof.
 const PERCENTAGE_WITH_CAP_PROOF_LEN: usize = UNIT_LEN * 8;
 
 /// Percentage-with-cap proof.
 ///
-/// The proof consists of two main components: `fee_max_proof` and `fee_equality_proof`. If the fee
-/// is greater than the maximum fee bound, then the `fee_max_proof` is properly generated and
-/// `fee_equality_proof` is simulated. If the fee is smaller than the maximum fee bound, the
-/// `fee_equality_proof` is properly generated and `fee_max_proof` is simulated.
+/// The proof consists of two main components: `percentage_max_proof` and
+/// `percentage_equality_proof`. If the encrypted amount is greater than the maximum cap value, then
+/// the `percentage_max_proof` is properly generated and `percentage_equality_proof` is simulated.
+/// If the encrypted amount is smaller than the maximum cap bound, the `percentage_equality_proof`
+/// is properly generated and `percentage_max_proof` is simulated.
 #[derive(Clone)]
 pub struct PercentageWithCapProof {
-    /// Proof that the committed fee amount equals the maximum fee bound
+    /// Proof that the committed amount equals the maximum cap bound
     percentage_max_proof: PercentageMaxProof,
 
     /// Proof that the "real" delta value is equal to the "claimed" delta value
@@ -114,7 +115,8 @@ impl PercentageWithCapProof {
         let mut transcript_percentage_above_max = transcript.clone();
         let mut transcript_percentage_below_max = transcript.clone();
 
-        // compute proof for both cases `fee_amount' >= `max_fee` and `fee_amount` < `max_fee`
+        // compute proof for both cases `percentage_amount' >= `max_value` and
+        // `percentage_amount` < `max_value`
         let proof_above_max = Self::create_proof_percentage_above_max(
             percentage_opening,
             delta_commitment,
@@ -133,8 +135,8 @@ impl PercentageWithCapProof {
 
         let below_max = u64::ct_gt(&max_value, &percentage_amount);
 
-        // choose one of `proof_fee_above_max` or `proof_fee_below_max` according to whether the
-        // fee amount is greater than `max_fee` or not
+        // choose one of `proof_above_max` or `proof_below_max` according to whether the
+        // percentage amount is greater than `max_value` or not
         let percentage_max_proof = PercentageMaxProof::conditional_select(
             &proof_above_max.percentage_max_proof,
             &proof_below_max.percentage_max_proof,
@@ -159,10 +161,10 @@ impl PercentageWithCapProof {
         }
     }
 
-    /// Creates a percentage-with-cap sigma proof assuming that the committed fee is greater than
-    /// the maximum fee bound.
+    /// Creates a percentage-with-cap proof assuming that the committed percentage is greater than
+    /// the maximum cap bound.
     ///
-    /// * `fee_opening` - The opening of the Pedersen commitment of the transfer fee
+    /// * `percentage_opening` - The opening of the Pedersen commitment of the value being proved
     /// * `delta_commitment` - The Pedersen commitment of the "real" delta value
     /// * `claimed_commitment` - The Pedersen commitment of the "claimed" delta value
     /// * `transcript` - The transcript that does the bookkeeping for the Fiat-Shamir heuristic
@@ -230,14 +232,13 @@ impl PercentageWithCapProof {
         }
     }
 
-    /// Creates a percentage-with-cap sigma proof assuming that the committed fee is less than the
-    /// maximum fee bound.
+    /// Creates a percentage-with-cap proof assuming that the committed amount is less than the
+    /// maximum cap bound.
     ///
-    /// * `fee_commitment` - The Pedersen commitment of the transfer fee
-    /// * `(delta_fee, delta_opening)` - The Pedersen commitment and opening of the "real" delta
-    /// value
-    /// * `claimed_opening` - The opening of the Pedersen commitment of the "claimed" delta value
-    /// * `max_fee` - The maximum fee bound
+    /// * `percentage_commitment` - The Pedersen commitment of the value to being proved
+    /// * `delta_opening` - The Pedersen commitment of the "real" delta value
+    /// * `delta_amount` - The "real" delta value
+    /// * `max_value` - The maximum cap bound
     /// * `transcript` - The transcript that does the bookkeeping for the Fiat-Shamir heuristic
     fn create_proof_percentage_below_max(
         percentage_commitment: &PedersenCommitment,
@@ -311,10 +312,10 @@ impl PercentageWithCapProof {
 
     /// Verifies a percentage-with-cap proof.
     ///
-    /// * `fee_commitment` - The Pedersen commitment of the transfer fee
+    /// * `percentage_commitment` - The Pedersen commitment of the value being proved
     /// * `delta_commitment` - The Pedersen commitment of the "real" delta value
     /// * `claimed_commitment` - The Pedersen commitment of the "claimed" delta value
-    /// * `max_fee` - The maximum fee bound
+    /// * `max_value` - The maximum cap bound
     /// * `transcript` - The transcript that does the bookkeeping for the Fiat-Shamir heuristic
     pub fn verify(
         self,
@@ -471,9 +472,9 @@ impl PercentageWithCapProof {
     }
 }
 
-/// The fee max proof.
+/// The percentage max proof.
 ///
-/// The proof certifies that the transfer fee Pedersen commitment encodes the maximum fee bound.
+/// The proof certifies that a Pedersen commitment encodes the maximum cap bound.
 #[allow(non_snake_case)]
 #[derive(Clone, Copy)]
 pub struct PercentageMaxProof {
@@ -492,7 +493,7 @@ impl ConditionallySelectable for PercentageMaxProof {
     }
 }
 
-/// The fee equality proof.
+/// The percentage equality proof.
 ///
 /// The proof certifies that the "real" delta value commitment and the "claimed" delta value
 /// commitment encode the same message.