diff --git a/src/centralized_telescope/params.rs b/src/centralized_telescope/params.rs index 230bf3f1..80d3a57d 100644 --- a/src/centralized_telescope/params.rs +++ b/src/centralized_telescope/params.rs @@ -1,4 +1,4 @@ -//! Centralized Telescope's Params structure comprising the internal parameters +//! Centralized Telescope's `Params` structure comprising the internal parameters use std::f64::consts::LOG2_E; @@ -18,7 +18,25 @@ pub struct Params { } impl Params { - /// Setup algorithm taking a Params as input and returning Params parameters (u,d,q) + /// Returns a `Params` structure from user parameters + /// + /// # Arguments + /// + /// * `soundness_param` - the protocol soundness parameter, typically set at 128 + /// * `completeness_param` - the protocol completeness parameter, typically set at 128 + /// * `set_size` - the size of the prover set to lower bound + /// * `lower_bound` - the lower bound to prove + /// + /// # Returns + /// + /// A `Params` structure + /// + /// # Example + /// + /// ``` + /// use alba::centralized_telescope::params::Params; + /// let params = Params::new(128.0, 128.0, 1_000, 750); + /// ``` pub fn new( soundness_param: f64, completeness_param: f64, diff --git a/src/centralized_telescope/proof.rs b/src/centralized_telescope/proof.rs index eafb4ce2..8c266537 100644 --- a/src/centralized_telescope/proof.rs +++ b/src/centralized_telescope/proof.rs @@ -1,4 +1,4 @@ -//! Centralized Telescope Proof structure +//! Centralized Telescope's `Proof` structure #![doc = include_str!("../../docs/rustdoc/centralized_telescope/proof.md")] @@ -23,8 +23,18 @@ pub struct Proof { impl Proof { /// Centralized Telescope's proving algorithm, based on a DFS algorithm. - /// Calls up to params.max_retries times the prove_index function and + /// Calls up to `params.max_retries` times the prove_index function and /// returns a `Proof` if a suitable candidate tuple is found. + /// + /// # Arguments + /// + /// * `set_size` - the size of the prover set to lower bound + /// * `params` - the internal parameters to generate a proof from + /// * `prover_set` - the dataset to generate a proof from + /// + /// # Returns + /// + /// A `Proof` structure pub(super) fn new(set_size: u64, params: &Params, prover_set: &[Element]) -> Option { // Run prove_index up to max_retries times (0..params.max_retries).find_map(|retry_counter| { @@ -32,8 +42,19 @@ impl Proof { }) } - // Alba's verification algorithm, returns true if the proof is - /// successfully verified, following the DFS verification, false otherwise. + /// Centralized Telescope's verification algorithm, returns true if the + /// proof is successfully verified, following the DFS verification, false + /// otherwise. + /// + /// # Arguments + /// + /// * `self` - the proof to verify + /// * `set_size` - the size of the prover set to lower bound + /// * `params` - the internal parameters to generate a proof from + /// + /// # Returns + /// + /// A boolean, true if the proof verifies successfully otherwise false pub(super) fn verify(&self, set_size: u64, params: &Params) -> bool { if self.search_counter >= params.search_width || self.retry_counter >= params.max_retries @@ -68,8 +89,8 @@ impl Proof { } /// Indexed proving algorithm, returns the total number of DFS calls done - /// to find a proof and Some(proof) if found within params.dfs_bound calls - /// of DFS, otherwise None + /// to find a proof and `Some(proof)` if found within `params.dfs_bound` calls + /// of DFS, otherwise `None` fn prove_index( set_size: u64, params: &Params, @@ -118,7 +139,7 @@ impl Proof { /// Depth-First Search (DFS) algorithm which goes through all potential /// round candidates and returns the total number of recursive DFS calls /// done and, if not found under params.dfs_bound calls, None otherwise - /// Some(Proof), that is the first "round", i.e. the first proof candidate, + /// `Some(Proof)`, that is the first "round", i.e. the first proof candidate, /// Round{retry_counter, search_counter, x_1, ..., x_u)} such that: /// - ∀i ∈ [0, u-1], bin_hash(x_i+1) ∈ bins[round_hash(...round_hash(round_hash(v, t), x_1), ..., x_i)] /// - proof_hash(round_hash(... round_hash((round_hash(v, t), x_1), ..., x_u)) = true diff --git a/src/centralized_telescope/round.rs b/src/centralized_telescope/round.rs index ac7e4755..1e8ce657 100644 --- a/src/centralized_telescope/round.rs +++ b/src/centralized_telescope/round.rs @@ -1,4 +1,4 @@ -//! ALBA's Round structure and associated functions +//! Centralized Telescope's `Round` structure and associated functions #![doc = include_str!("../../docs/rustdoc/centralized_telescope/round.md")] diff --git a/src/centralized_telescope/telescope.rs b/src/centralized_telescope/telescope.rs index 2851906e..90eca48c 100644 --- a/src/centralized_telescope/telescope.rs +++ b/src/centralized_telescope/telescope.rs @@ -1,3 +1,4 @@ +//! Customer facing Centralized Telescope structure use super::params::Params; use super::proof::Proof; use crate::utils::types::Element; @@ -12,7 +13,25 @@ pub struct Telescope { } impl Telescope { - /// Initialize ALBA with `Params`. + /// Returns a `Telescope` structure from input parameters + /// + /// # Arguments + /// + /// * `soundness_param` - the protocol soundness parameter, typically set at 128 + /// * `completeness_param` - the protocol completeness parameter, typically set at 128 + /// * `set_size` - the size of the prover set to lower bound + /// * `lower_bound` - the lower bound to prove + /// + /// # Returns + /// + /// A `Telescope`` structure + /// + /// # Example + /// + /// ``` + /// use alba::centralized_telescope::Telescope; + /// let telescope = Telescope::create(128.0, 128.0, 1_000, 750); + /// ``` pub fn create( soundness_param: f64, completeness_param: f64, @@ -23,8 +42,26 @@ impl Telescope { Self { set_size, params } } - /// Initialize ALBA with `set_size` and unchecked `Setup`. - /// Use with caution, in tests or with trusted parameters. + /// Use with caution. Returns a `Telescope` structure from input and + /// internal parameters without checking the consistency between parameters + /// + /// # Arguments + /// + /// * `set_size` - the size of the prover set to lower bound + /// * `params` - some centralized Telescope internal parameters + /// + /// # Returns + /// + /// A `Telescope` structure + /// + /// # Example + /// + /// ``` + /// use alba::centralized_telescope::Telescope; + /// use alba::centralized_telescope::params::Params; + /// let params = Params {proof_size : 200, max_retries: 128, search_width: 10, valid_proof_probability: 0.001, dfs_bound: 40_000}; + /// let telescope = Telescope::setup_unsafe(1_000, ¶ms); + /// ``` pub fn setup_unsafe(set_size: u64, params: &Params) -> Self { Self { set_size, @@ -32,14 +69,57 @@ impl Telescope { } } - /// Alba's proving algorithm, based on a depth-first search algorithm. - /// Returns either a `Proof` or `None` if no proof is found. + /// Generates a Centralized Telescope proof. + /// + /// # Arguments + /// + /// * `self` - the current `Telescope` structure + /// * `prover_set` - an array of elements to generate an Alba proof on + /// + /// # Returns + /// + /// A `Proof` if found, `None` otherwise + /// + /// # Example + /// + /// ``` + /// use alba::centralized_telescope::Telescope; + /// let set_size = 200; + /// let telescope = Telescope::create(64.0, 64.0, set_size, 100); + /// let mut prover_set = Vec::new(); + /// for i in 0..set_size { + /// prover_set.push([(i % 256) as u8 ; 48]); + /// } + /// let proof = telescope.prove(&prover_set).unwrap(); + /// ``` pub fn prove(&self, prover_set: &[Element]) -> Option { Proof::new(self.set_size, &self.params, prover_set) } - /// Alba's verification algorithm. - /// Returns true if and only if the proof is successfully verified. + /// Verifies a Centralized Telescope proof. + /// + /// # Arguments + /// + /// * `self` - the current `Telescope` structure + /// * `proof` - a centralized Telescope proof + /// + /// # Returns + /// + /// True if the verification is successful, false otherwise + /// + /// # Example + /// + /// ``` + /// use alba::centralized_telescope::Telescope; + /// let set_size = 200; + /// let telescope = Telescope::create(64.0, 64.0, set_size, 100); + /// let mut prover_set = Vec::new(); + /// for i in 0..set_size { + /// prover_set.push([(i % 256) as u8 ; 48]); + /// } + /// let proof = telescope.prove(&prover_set).unwrap(); + /// assert!(telescope.verify(&proof)); + /// ``` pub fn verify(&self, proof: &Proof) -> bool { proof.verify(self.set_size, &self.params) }