misc comments pr83

garble/mpz-garble/src/lib.rs

@@ -335,7 +335,8 @@ pub trait Execute {
     ) -> Result<(), ExecutionError>;
 }
 
-/// This trait provides methods for proving the output of a circuit.
+/// This trait provides methods for the evaluator to prove the authenticity of the evaluated garbled
+/// circuit's output.
 #[async_trait]
 pub trait Prove {
     /// Executes the provided circuit as the prover, assigning to the provided output values.
@@ -346,11 +347,11 @@ pub trait Prove {
         outputs: &[ValueRef],
     ) -> Result<(), ProveError>;
 
-    /// Proves the provided values.
+    /// Proves the authenticity of the provided output values.
     async fn prove(&mut self, values: &[ValueRef]) -> Result<(), ProveError>;
 }
 
-/// This trait provides methods for verifying the output of a circuit.
+/// This trait provides methods for the garbler to verify the authenticity of the evaluator's output.
 #[async_trait]
 pub trait Verify {
     /// Executes the provided circuit as the verifier, assigning to the provided output values.
@@ -361,30 +362,30 @@ pub trait Verify {
         outputs: &[ValueRef],
     ) -> Result<(), VerifyError>;
 
-    /// Verifies the provided values against the expected values.
+    /// Verifies the provided output values against the expected values.
     async fn verify(
         &mut self,
         values: &[ValueRef],
         expected_values: &[Value],
     ) -> Result<(), VerifyError>;
 }
 
-/// This trait provides methods for decoding values.
+/// This trait provides methods for decoding output values.
 #[async_trait]
 pub trait Decode {
-    /// Decodes the provided values, returning the plaintext values to all parties.
+    /// Decodes the provided output values, returning the plaintext values to all parties.
     async fn decode(&mut self, values: &[ValueRef]) -> Result<Vec<Value>, DecodeError>;
 }
 
-/// This trait provides methods for decoding values with different privacy configurations.
+/// This trait provides methods for decoding output values with different privacy configurations.
 #[async_trait]
 pub trait DecodePrivate {
-    /// Decodes the provided values, returning the plaintext values to only this party.
+    /// Decodes the provided output values, returning the plaintext values to only this party.
     async fn decode_private(&mut self, values: &[ValueRef]) -> Result<Vec<Value>, DecodeError>;
 
-    /// Decodes the provided values, returning the plaintext values to the other party(s).
+    /// Decodes the provided output values, returning the plaintext values to the other party(s).
     async fn decode_blind(&mut self, values: &[ValueRef]) -> Result<(), DecodeError>;
 
-    /// Decodes the provided values, returning additive shares of plaintext values to all parties.
+    /// Decodes the provided output values, returning additive shares of plaintext values to all parties.
     async fn decode_shared(&mut self, values: &[ValueRef]) -> Result<Vec<Value>, DecodeError>;
 }

garble/mpz-garble/src/protocol/deap/mod.rs

@@ -225,23 +225,18 @@ impl DEAP {
         Ok(())
     }
 
-    /// Proves the output of a circuit to the other party.
+    /// Executes the provided circuit as the prover, assigning to the provided output values.
     ///
     /// # Notes
     ///
     /// This function can only be called by the leader.
     ///
-    /// This function does _not_ prove the output right away,
-    /// instead the proof is committed to and decommitted later during
-    /// the call to [`finalize`](Self::finalize).
-    ///
     /// # Arguments
     ///
     /// * `id` - The ID of the circuit.
     /// * `circ` - The circuit to execute.
     /// * `inputs` - The inputs to the circuit.
     /// * `outputs` - The outputs to the circuit.
-    /// * `sink` - The sink to send messages to.
     /// * `stream` - The stream to receive messages from.
     /// * `ot_recv` - The OT receiver.
     #[allow(clippy::too_many_arguments)]
@@ -332,7 +327,7 @@ impl DEAP {
         Ok(())
     }
 
-    /// Sends a commitment to the provided values, proving them to the follower upon finalization.
+    /// Sends a commitment to the provided output values, deferring the actual proving until finalization.
     pub async fn defer_prove<S: Sink<GarbleMessage, Error = std::io::Error> + Unpin>(
         &self,
         id: &str,
@@ -354,7 +349,7 @@ impl DEAP {
         Ok(())
     }
 
-    /// Receives a commitment to the provided values, and stores it until finalization.
+    /// Receives a commitment to the provided output values, and stores it until finalization.
     ///
     /// # Notes
     ///
@@ -364,7 +359,7 @@ impl DEAP {
     ///
     /// * `id` - The ID of the operation
     /// * `values` - The values to receive a commitment to
-    /// * `expected_values` - The expected values which will be verified against the commitment
+    /// * `expected_values` - The expected plaintext values which will be verified against the commitment
     /// * `stream` - The stream to receive messages from
     pub async fn defer_verify<S: Stream<Item = Result<GarbleMessage, std::io::Error>> + Unpin>(
         &self,
@@ -375,6 +370,7 @@ impl DEAP {
     ) -> Result<(), DEAPError> {
         let encoded_values = self.gen.get_encodings(values)?;
 
+        // Encode the expected plaintext values.
         let expected_values = expected_values
             .iter()
             .zip(encoded_values)

garble/mpz-garble/src/protocol/deap/vm.rs

@@ -309,6 +309,8 @@ where
             .await
     }
 
+    // Note: we do _not_ prove the output right away, instead the proof is committed to
+    // and decommitted later when the DEAP instance is finalized.
     async fn prove(&mut self, values: &[ValueRef]) -> Result<(), ProveError> {
         self.deap()
             .defer_prove(
@@ -346,6 +348,8 @@ where
             .await
     }
 
+    // Note: we do _not_ verify the output right away, instead a commitment from the prover is stored
+    // and verified later when the DEAP instance is finalized.
     async fn verify(
         &mut self,
         values: &[ValueRef],