chore: comments (#193)

crates/mpz-ole-core/src/ideal.rs

@@ -51,7 +51,7 @@ impl<F> Default for ReceiverState<F> {
     }
 }
 
-/// Ideal COT functionality.
+/// Ideal ROLE functionality.
 #[derive(Debug, Clone)]
 pub struct IdealROLE<F> {
     inner: Arc<Mutex<Inner<F>>>,
@@ -89,7 +89,7 @@ where
         }
     }
 
-    /// Transfers correlated OTs.
+    /// Performs ROLEs.
     pub fn transfer(
         &mut self,
         count: usize,

crates/mpz-ole-core/src/lib.rs

@@ -9,10 +9,8 @@
 //! - The functionality computes `y = ab + x` and returns `y` to the receiver.
 //!
 //! It's often easier to frame OLE as producing an additive sharing of a
-//! product.
-//!
-//! Where the sender knows `(a, x)` and the receiver knows `(b, y)` such that
-//! `ab = x + y`. This representation is used in [`OLEShare`].
+//! product, where the sender knows `(a, x)` and the receiver knows `(b, y)` such
+//! that `ab = x + y`. This representation is used in [`OLEShare`].
 
 #![deny(missing_docs, unreachable_pub, unused_must_use)]
 #![deny(unsafe_code)]
@@ -39,7 +37,7 @@ use serde::{Deserialize, Serialize};
 
 /// An OLE identifier.
 ///
-/// Multiple OLEs may be batched together under the same transfer ID.
+/// Multiple OLEs may be batched together under the same ID.
 #[derive(
     Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
 )]

crates/mpz-ole-core/src/receiver.rs

@@ -1,4 +1,4 @@
-//! Receiver implementation.
+//! ROLE receiver.
 
 use std::collections::VecDeque;
 
@@ -21,6 +21,7 @@ struct Queued<F> {
 pub struct Receiver<T, F> {
     id: OLEId,
     alloc: usize,
+    /// The total count of ROLEs in the `queue`.
     pending: usize,
     queue: VecDeque<Queued<F>>,
     rot: T,
@@ -121,6 +122,7 @@ where
             });
         }
 
+        // Store the rest of the ROLEs which were not queued.
         self.role.extend_from_slice(&shares[i..]);
         self.alloc = 0;
         self.pending = 0;

crates/mpz-ole-core/src/sender.rs

@@ -23,6 +23,7 @@ struct Queued<F> {
 pub struct Sender<T, F> {
     id: OLEId,
     alloc: usize,
+    /// The total count of ROLEs in the `queue`.
     pending: usize,
     queue: VecDeque<Queued<F>>,
     rot: T,
@@ -112,6 +113,7 @@ where
             });
         }
 
+        // Store the rest of the ROLEs which were not queued.
         self.role.extend_from_slice(&shares[i..]);
         self.alloc = 0;
         self.pending = 0;

crates/mpz-share-conversion-core/src/a2m.rs

@@ -6,8 +6,8 @@
 //! share of A. So both parties start with `x` and `y` and want to end up with
 //! `a` and `b`, where `A = x + y = a * b`.
 //!
-//! This module implements the A2M protocol from <https://eprint.iacr.org/2023/964>, page 40,
-//! figure 16, 4.
+//! This module implements the A2M protocol from
+//! - [ref1]: <https://eprint.iacr.org/2023/964>, page 40, figure 16, 4.
 
 use mpz_fields::Field;
 use mpz_ole_core::{OLEShare, Offset};
@@ -23,8 +23,11 @@ pub(crate) struct A2MMasked<F>(F);
 /// their input.
 #[derive(Debug)]
 pub(crate) struct A2MSenderDerand<F> {
+    /// An additive share. h_P in ref1.
     input: F,
+    /// A ROLE output which will be adjusted.
     add: F,
+    /// A ROLE input. (h̃_P)⁻¹ in ref1.
     mul: F,
 }
 
@@ -53,8 +56,11 @@ where
 /// A2M Sender sends masked share to the receiver.
 #[derive(Debug)]
 pub(crate) struct A2MSenderAdjust<F> {
+    /// An additive share. h_P in ref1.
     input: F,
+    /// An OLEe output. s_P in ref1.
     add: F,
+    /// An OLEe input. (h̃_P)⁻¹ in ref1.
     mul: F,
 }
 
@@ -78,8 +84,11 @@ where
 /// We start with a ROLE and derandomize the receiver's input.
 #[derive(Debug)]
 pub(crate) struct A2MReceiverDerand<F> {
+    /// An additive share. h_V in ref1.
     input: F,
+    /// A ROLE output. s_V in ref1.
     add: F,
+    /// A ROLE input.
     mul: F,
 }
 
@@ -97,8 +106,10 @@ where
 
     /// Sends the offset to the sender.
     pub(crate) fn offset(self) -> (A2MReceiverAdjust<F>, Offset<F>) {
+        // Adjust OLEe input to be equal to h_V (in ref1).
         let offset = self.input - self.mul;
 
+        // The sender makes no adjustment to the receiver's OLEe output.
         (A2MReceiverAdjust { add: self.add }, Offset(offset))
     }
 }
@@ -113,7 +124,7 @@ impl<F> A2MReceiverAdjust<F>
 where
     F: Field,
 {
-    /// Receives the masked share, returning the multiplicative share.
+    /// Receives the masked share (`d` in ref1), returning the multiplicative share.
     pub(crate) fn receive(self, masked: A2MMasked<F>) -> F {
         self.add + masked.0
     }

crates/mpz-share-conversion-core/src/receiver.rs

@@ -1,7 +1,5 @@
 //! Share conversion receiver.
 
-//! Share conversion sender.
-
 use std::{collections::VecDeque, marker::PhantomData};
 
 use mpz_common::future::{new_output, MaybeDone, Sender as OutputSender};

crates/mpz-share-conversion/src/lib.rs

@@ -1,5 +1,6 @@
 //! This crate provides additive-to-multiplicative (A2M) and
-//! multiplicative-to-additive (M2A) share conversion protocols.
+//! multiplicative-to-additive (M2A) share conversion protocols,
+//! both with semi-honest security.
 
 #![deny(missing_docs, unreachable_pub, unused_must_use)]
 #![deny(unsafe_code)]