docs: misc comments for MPCOT and Ferret-core

privacy-scaling-explorations · May 10, 2024 · cb37e16 · cb37e16
1 parent cfa42a5
commit cb37e16
Show file tree

Hide file tree

Showing 10 changed files with 43 additions and 41 deletions.
diff --git a/mpz-core/src/lpn.rs b/mpz-core/src/lpn.rs
@@ -112,10 +112,10 @@ impl<const D: usize> LpnEncoder<D> {
     }
 }
 
-/// Lpn paramters
+/// LPN parameters.
 #[derive(Copy, Clone, Debug)]
 pub struct LpnParameters {
-    /// The length of output vecotrs.
+    /// The length of output vectors.
     pub n: usize,
     /// The length of the secret vector
     pub k: usize,
@@ -156,9 +156,7 @@ impl LpnParameters {
 
 #[cfg(test)]
 mod tests {
-    use crate::lpn::LpnEncoder;
-    use crate::prp::Prp;
-    use crate::Block;
+    use crate::{lpn::LpnEncoder, prp::Prp, Block};
 
     impl<const D: usize> LpnEncoder<D> {
         #[allow(dead_code)]
@@ -202,9 +200,7 @@ mod tests {
 
     #[test]
     fn lpn_test() {
-        use crate::lpn::LpnEncoder;
-        use crate::prg::Prg;
-        use crate::Block;
+        use crate::{lpn::LpnEncoder, prg::Prg, Block};
 
         let k = 20;
         let n = 200;

diff --git a/ot/mpz-ot-core/src/ferret/cuckoo.rs b/ot/mpz-ot-core/src/ferret/cuckoo.rs
@@ -142,7 +142,7 @@ pub(crate) fn hash_to_index(hash: &AesEncryptor, range: usize, value: u32) -> us
     (res as usize) % range
 }
 
-// Finds the position of the item in each Bucket.
+// Finds the position of the `item` in the given `bucket`.
 #[inline(always)]
 pub(crate) fn find_pos(bucket: &[Item], item: &Item) -> Result<usize, BucketError> {
     let pos = bucket.iter().position(|&x| *item == x);

diff --git a/ot/mpz-ot-core/src/ferret/mod.rs b/ot/mpz-ot-core/src/ferret/mod.rs
@@ -13,7 +13,7 @@ pub mod spcot;
 /// Computational security parameter
 pub const CSP: usize = 128;
 
-/// Number of hashes in Cuckoo hash.
+/// Number of hash functions in Cuckoo hash.
 pub const CUCKOO_HASH_NUM: usize = 3;
 
 /// Trial numbers in Cuckoo hash insertion.

diff --git a/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs b/ot/mpz-ot-core/src/ferret/mpcot/receiver.rs
@@ -50,7 +50,10 @@ impl Receiver {
 
 impl Receiver<state::PreExtension> {
     /// Performs the hash procedure in MPCOT extension.
-    /// Outputs the length of each bucket plus 1.
+    ///
+    /// For each bucket outputs a tuple:
+    /// - the base 2 logarithm (rounded up) of the length of the bucket
+    /// - the position of an index in the bucket
     ///
     /// See Step 1 to Step 4 in Figure 7.
     ///
@@ -71,7 +74,7 @@ impl Receiver<state::PreExtension> {
         }
         let cuckoo = CuckooHash::new(self.state.hashes.clone());
 
-        // Inserts all the alpha's.
+        // Inserts all the alphas.
         let table = cuckoo.insert(alphas)?;
 
         let m = table.len();
@@ -201,7 +204,7 @@ pub mod state {
     ///
     /// In this state the receiver performs pre extension in MPCOT (potentially multiple times).
     pub struct PreExtension {
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
         /// The hashes to generate Cuckoo hash table.
         pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>,
@@ -214,7 +217,7 @@ pub mod state {
     ///
     /// In this state the receiver performs MPCOT extension (potentially multiple times).
     pub struct Extension {
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
         /// Current length of Cuckoo hash table, will possibly be changed in each extension.
         pub(super) m: usize,

diff --git a/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs b/ot/mpz-ot-core/src/ferret/mpcot/receiver_regular.rs
@@ -1,4 +1,5 @@
 //! MPCOT receiver for regular indices. Regular indices means the indices are evenly distributed.
+//! See "Optimization for regular indices" in §5.
 
 use mpz_core::Block;
 
@@ -26,8 +27,11 @@ impl Receiver {
     }
 }
 impl Receiver<state::PreExtension> {
-    /// Performs the prepare procedure in MPCOT extension.
-    /// Outputs the indices for SPCOT.
+    /// Performs the preparation procedure in MPCOT extension.
+    ///
+    /// For each call to be made to SPCOT outputs a tuple:
+    /// - the base 2 logarithm (rounded up) of the length of the choice-bit vector
+    /// - the index of the point in the vector
     ///
     /// # Arguments.
     ///
@@ -46,7 +50,7 @@ impl Receiver<state::PreExtension> {
             ));
         }
 
-        // The range of each interval.
+        // The size of each interval.
         let k = (n + t - 1) / t;
 
         let queries_length = if n % t == 0 {
@@ -163,7 +167,7 @@ pub mod state {
     ///
     /// In this state the receiver performs pre extension in MPCOT (potentially multiple times).
     pub struct PreExtension {
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
     }
 
@@ -175,7 +179,7 @@ pub mod state {
     ///
     /// In this state the receiver performs MPCOT extension (potentially multiple times).
     pub struct Extension {
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         #[allow(dead_code)]
         pub(super) counter: usize,
         /// The total number of indices in the current extension.

diff --git a/ot/mpz-ot-core/src/ferret/mpcot/sender.rs b/ot/mpz-ot-core/src/ferret/mpcot/sender.rs
@@ -187,7 +187,7 @@ pub mod state {
     pub struct PreExtension {
         /// Sender's global secret.
         pub(super) delta: Block,
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
         /// The hashes to generate Cuckoo hash table.
         pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>,
@@ -202,18 +202,18 @@ pub mod state {
     pub struct Extension {
         /// Sender's global secret.
         pub(super) delta: Block,
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
 
         /// Current length of Cuckoo hash table, will possibly be changed in each extension.
         pub(super) m: usize,
         /// The total number of indices in the current extension.
         pub(super) n: u32,
-        /// The hashes to generate Cuckoo hash table.
+        /// The hash functions to generate Cuckoo hash table.
         pub(super) hashes: Arc<[AesEncryptor; CUCKOO_HASH_NUM]>,
-        /// The buckets contains all the hash values.
+        /// The buckets containing all the hash values.
         pub(super) buckets: Vec<Vec<Item>>,
-        /// The padded buckets length (power of 2).
+        /// The padded length of each bucket (power of 2).
         pub(super) buckets_length: Vec<usize>,
     }
 

diff --git a/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs b/ot/mpz-ot-core/src/ferret/mpcot/sender_regular.rs
@@ -1,4 +1,5 @@
 //! MPCOT sender for regular indices. Regular indices means the indices are evenly distributed.
+//! See "Optimization for regular indices" in §5.
 
 use mpz_core::Block;
 
@@ -31,7 +32,7 @@ impl Sender {
 }
 
 impl Sender<state::PreExtension> {
-    /// Performs the prepare procedure in MPCOT extension.
+    /// Performs the preparation procedure in MPCOT extension.
     /// Outputs the information for SPCOT.
     ///
     /// # Arguments.
@@ -49,7 +50,7 @@ impl Sender<state::PreExtension> {
             ));
         }
 
-        // The range of each interval.
+        // The size of each interval.
         let k = (n + t - 1) / t;
 
         let queries_length = if n % t == 0 {
@@ -69,7 +70,7 @@ impl Sender<state::PreExtension> {
         let mut queries_depth = Vec::with_capacity(queries_length.len());
 
         for len in queries_length.iter() {
-            // pad `len`` to power of 2.
+            // pad `len` to power of 2.
             let power = len
                 .checked_next_power_of_two()
                 .expect("len should be less than usize::MAX / 2 - 1")
@@ -156,7 +157,7 @@ pub mod state {
     pub struct PreExtension {
         /// Sender's global secret.
         pub(super) delta: Block,
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
     }
 
@@ -169,7 +170,7 @@ pub mod state {
     pub struct Extension {
         /// Sender's global secret.
         pub(super) delta: Block,
-        /// Current MPCOT counter
+        /// Current MPCOT extension counter.
         pub(super) counter: usize,
         /// The total number of indices in the current extension.
         pub(super) n: u32,

diff --git a/ot/mpz-ot-core/src/ferret/receiver.rs b/ot/mpz-ot-core/src/ferret/receiver.rs
@@ -67,12 +67,8 @@ impl Receiver {
 }
 
 impl Receiver<state::Extension> {
-    /// The prepare precedure of extension, sample error vectors and outputs information for MPCOT.
+    /// The preparation procedure of extension. Samples error vectors and outputs information for MPCOT.
     /// See step 3 and 4.
-    ///
-    /// # Arguments.
-    ///
-    /// * `lpn_type` - The type of LPN parameters.
     pub fn get_mpcot_query(&mut self) -> (Vec<u32>, usize, usize) {
         match self.state.lpn_type {
             LpnType::Uniform => {
@@ -97,7 +93,7 @@ impl Receiver<state::Extension> {
     }
 
     /// Performs the Ferret extension.
-    /// Outputs exactly l = n - t COTs.
+    /// Outputs exactly l = n - k COTs.
     ///
     /// See step 5 and 6.
     ///
@@ -162,9 +158,9 @@ pub mod state {
 
     /// The receiver's state after the setup phase.
     ///
-    /// In this state the sender performs Ferret extension (potentially multiple times).
+    /// In this state the receiver performs Ferret extension (potentially multiple times).
     pub struct Extension {
-        /// Current Ferret counter.
+        /// Current Ferret extension counter.
         pub(super) counter: usize,
 
         /// Lpn parameters.

diff --git a/ot/mpz-ot-core/src/ferret/sender.rs b/ot/mpz-ot-core/src/ferret/sender.rs
@@ -71,7 +71,7 @@ impl Sender<state::Extension> {
     }
 
     /// Performs the Ferret extension.
-    /// Outputs exactly l = n-t COTs.
+    /// Outputs exactly l = n-k COTs.
     ///
     /// See step 5 and 6.
     ///
@@ -128,7 +128,7 @@ pub mod state {
         /// Sender's global secret.
         #[allow(dead_code)]
         pub(super) delta: Block,
-        /// Current Ferret counter.
+        /// Current Ferret extension counter.
         pub(super) counter: usize,
 
         /// Lpn type.

diff --git a/ot/mpz-ot-core/src/ideal/ideal_spcot.rs b/ot/mpz-ot-core/src/ideal/ideal_spcot.rs
@@ -48,9 +48,11 @@ impl IdealSpcot {
 
     /// Performs the batch extension of SPCOT.
     ///
-    /// # Argument
+    /// # Arguments
     ///
-    /// * `pos` - The positions in each extension.
+    /// * `pos` - For each extension contains a tuple:
+    ///           - the length of the choice-bit vector
+    ///           - the index of the point in the vector
     pub fn extend(&mut self, pos: &[(usize, u32)]) -> (SpcotMsgForSender, SpcotMsgForReceiver) {
         let mut v = vec![];
         let mut w = vec![];