Documentation - Intro

README.md

@@ -1,11 +1,34 @@
 # ALBA
+This is the Rust library of _Approximate Lower Bound Arguments_ proposed in the [paper](https://iohk.io/en/research/library/papers/approximate-lower-bound-arguments/), May 2024, Eurocrypt'24 by _Pyrros Chaidos, Prof Aggelos Kiayias, Leonid Reyzin, Anatoliy Zinovyev_.
 
-Implementation of _Approximate Lower Bound Arguments_ from the [paper](https://iohk.io/en/research/library/papers/approximate-lower-bound-arguments/) published by IOG Research:
+### Introduction
+ALBA enables a prover who has a large collection of data to convince a verifier that their set includes at least a minimum number of items that meet a specific condition, called a predicate, even though the prover only reveals a subset of the data. By approximating a lower bound on the prover's knowledge, ALBA makes use of a controlled gap between the size of prover's actual knowledge and the threshold of the verifier checks they know. This design results in highly efficient proofs, achieving nearly optimal proof sizes in both non-interactive and distributed environments. ALBA's primary applications include large-scale decentralized signature schemes. It is particularly well-suited for decentralized or blockchain scenarios, where it enhances communication efficiency among multiple provers sharing witness.
 
-> **Approximate Lower Bound Arguments**,  _Pyrros Chaidos, Prof Aggelos Kiayias, Leonid Reyzin, Anatoliy Zinovyev_, May 2024, Eurocrypt'24
+In a decentralized voting system, participants (voters) submit votes that support different options or candidates. To validate the results without revealing individual votes, an ALBA protocol could be used. Each voter's choice can be considered an _element_ that meets a certain predicate (e.g., a valid vote for a candidate). Instead of tallying every vote publicly, ALBA allows an aggregator (like an election authority) to generate a compact proof showing that a sufficient number of valid votes has been cast for each candidate to meet the required threshold for a decision (such as reaching a quorum or winning a majority). This approach keeps individual votes private while enabling quick, efficient validation of the voting outcome, making it particularly useful for secure, private, and scalable voting systems where privacy and efficiency are critical.
+
+The paper introduces various ALBA protocol constructions tailored to different needs. The basic construction enables a prover to show possession of a large set by creating a proof sequence of elements that meet staged hash-based conditions, efficiently excluding small sets. _Pre-hashing_ improves this by precomputing hashes to group elements into _bins_, reducing computation and enhancing performance, especially with large sets. For smaller sets, the generalized Telescope scheme allows multiple attempts to form a proof, adjusting parameters to maintain efficiency across sizes. Decentralized versions of ALBA include the _Simple Lottery Construction_, where each party holding an element decides to share it based on a random _lottery_ mechanism, with an aggregator forming the proof from a target number of shared elements. The _Decentralized Telescope_ adapts the Telescope scheme for multiple parties, who individually apply it and share qualifying elements with an aggregator. Finally, the weighted extension supports elements with integer weights, allowing the prover to meet a total weight threshold, making ALBA versatile for contexts where elements have varying significance.
+
+The library covers the following constructions of the ALBA protocol:
+1. Centralized Telescope
+2. Simple Lottery Construction
+3. Decentralized Telescope
+4. Wighted-Decentralized Telescope
+
+### Disclaimer
 
-> [!IMPORTANT]
 > This code is NOT fit for production, it's not been optimised, thoroughly tested, nor audited by competent cryptographers.
-> Its one and only purpose is to help people who are more familiar with code than equations to have a better understanding of ALBAs
+> Its one and only purpose is to help people who are more familiar with code than equations to have a better understanding of ALBAs.
+
+### Documentation
+👉 We deliver comprehensive [documentation][crate::docs] aimed at connecting theory with practical implementation.
+
+👉 Checkout website on this [link](https://alba.cardano-scaling.org).
+
+### Compiling the library
+Compile the library:
+```shell
+cargo build --release
+```
 
-👉 Checkout documentation on https://alba.cardano-scaling.org
+### Tests and Benchmarks
+Run tests with `cargo test`. Run benchmarks with `cargo bench`. 

docs/intro.md

@@ -1 +1,26 @@
-**Telescope ALBA** documentation.
+- Assume that, a prover, who has a large collection of data, wants to convince a verifier that their set contains at least a minimum number of items that satisfy a specific condition, known as a predicate, even if the prover only shares a portion of it.
+- The Approximate Lower Bound Argument (ALBA) protocol is a new cryptographic primitive that solves this problem efficiently.
+- The protocol makes use of a small gap between the size of what the prover actually has and the threshold the verifier knows they have.
+- . This gap makes ALBA very efficient, as it reduces the data the prover needs to share, enabling compact and efficient proofs.
+- ALBA also supports weighted items, where each item has an assigned importance or weight. This allows the prover to demonstrate that the total weight of their set meets a required threshold, rather than simply the count of items.
+- ALBA supports scalable and efficient proof mechanisms in decentralized systems, i.e., voting schemes.
+
+## Overview
+- **The protocol**
+    - The protocol addresses the problem of succinctly proving knowledge of a large set of verifiable evidence.
+    - The prover convinces the verifier by revealing only a subset of this evidence, thus achieving efficiency in both time and communication.
+    - Given a large set $S_p$ that satisfies a predicate $R$ such that $|S_p| \geq n_p$, the prover wants to convince the verifier that the set contains at least $n_f$ elements, where $n_f$ is a threshold strictly smaller than $n_p$.
+        - This creates an _approximate_ lower bound, as the verifier is convinced that $S_p$ meets or exceeds a threshold, though the actual size might be greater.
+    - ALBA achieves efficiency by making use of the gap between the provable lower bound and the actual size, enabling rapid verification without compromising security. The greater the gap, the smaller the proof, and the faster its generation.
+- **Historical context**
+    - The concept builds on classic approaches in proof systems, where similar challenges in communication complexity were addressed by using probabilistic techniques or interactive protocols.
+    - Previous methods were largely theoretical and less efficient for practical, large-scale applications.
+- **Design goals**
+    - ALBA aims to minimize both proof size and computational load, making it feasible for high-throughput settings like blockchain networks.
+    - The protocol is versatile and adaptable, supporting non-interactive proofs in both the random oracle and common reference string model as well as allowing multi-prover scenario in decentralized environments.
+        - This makes it of special interest for multi-party environment, such as a blockchain where many parties collectively validate transactions.
+- **Setup and interaction models**
+    - Non-interactive Model:
+        - ALBA provides a non-interactive proof of knowledge in the random oracle model (_NIROPK_), where the verifier can extract knowledge directly from observing queries.
+    - Decentralized Model:
+        - ALBA is also adapted for decentralized, multi-prover settings, where several entities hold parts of $S_p$ and communicate over a network to jointly prove possession of evidence, achieving efficiency in both communication and computation.

docs/varmap.md

@@ -0,0 +1,27 @@
+Variable name mapping.
+
+In the [paper](https://iohk.io/en/research/library/papers/approximate-lower-bound-arguments/), numerous variables are represented by various letters. To enhance the simplicity and readability of our code, we have opted for descriptive names. A mapping between the variable names used in the paper and those in the code is provided for reference.
+
+
+| Paper              | Code                                                                                             |
+|--------------------|--------------------------------------------------------------------------------------------------|
+| $\lambda_{sec}$    | [`soundness_param`][crate::centralized_telescope::params::Params::soundness_param]               |
+| $\lambda_{rel}$    | [`completeness_param`][crate::centralized_telescope::params::Params::completeness_param]         |
+| $S_p$              | `prover_set`                                                                                     |
+| $n_p$              | [`set_size`][crate::centralized_telescope::params::Params::set_size]                             |
+| $n_f$              | [`lower_bound`][crate::centralized_telescope::params::Params::lower_bound]                       |
+| $u$                | [`proof_size`][crate::centralized_telescope::setup::Setup::proof_size]                           |
+| $r$                | [`max_retries`][crate::centralized_telescope::setup::Setup::max_retries]                         |
+| $d$                | [`search_width`][crate::centralized_telescope::setup::Setup::search_width]                       |
+| $q$                | [`valid_proof_probability`][crate::centralized_telescope::setup::Setup::valid_proof_probability] |
+| $b$                | [`dfs_bound`][crate::centralized_telescope::setup::Setup::dfs_bound]                             |
+| $v$                | `retry_counter`                                                                                  |
+| $t$                | `search_counter`                                                                                 |
+| $H_0$              | `bin_hash`                                                                                       |
+| $H_1$              | `round_hash`                                                                                     |
+| $H_2$              | `proof_hash`                                                                                     |
+| $s_i$              | `Element`                                                                                        |
+| $s_1, \ldots, s_u$ | `element_sequence`                                                                               |
+| $p$                | [`lottery_probability`][crate::simple_lottery::setup::Setup::lottery_probability]                |
+| $limit$            | `step`                                                                                           |
+

src/docs.rs

@@ -1,3 +1,6 @@
-//! Telescope-ALBA documentation
+//! Approximate Lower Bound Arguments (_ALBA_) documentation.
 
 #![doc = include_str!("../docs/intro.md")]
+
+#[doc = include_str!("../docs/varmap.md")]
+pub mod variables {}

src/lib.rs

@@ -1,8 +1,6 @@
 // #![deny(missing_docs)]
 #![doc = include_str!("../README.md")]
 
-//! An implementation of Approximate Lower Bound Arguments
-//! (ALBA, <https://eprint.iacr.org/2023/1655.pdf>).
 mod utils;
 
 pub mod centralized_telescope;