Documentation - Intro (#62)

## Content

This PR aims to provide
- Introduction section of the documentation
- A page including the variable mapping
- README update

## Pre-submit checklist

- Branch
    - [X] Commit sequence broadly makes sense
    - [X] Key commits have useful messages
- PR
    - [X] No clippy warnings in the CI
    - [X] Self-reviewed the diff
    - [X] Useful pull request description
    - [X] Reviewer requested
- Documentation
    - [X] Update README file (if relevant)
    - [X] Update documentation website (if relevant)

## Comments
Run the following command to compile the documentation:
```shell
cargo doc --no-deps --open
```
Note that you might need to run `cargo clean` before compiling to see
the changes.

## Issue(s)
Closes #60

---------

Co-authored-by: Raphael <[email protected]>
Co-authored-by: Tolik Zinovyev <[email protected]>

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustdocflags = "--html-in-header docs/assets/katex-header.html"

Cargo.toml

@@ -43,6 +43,3 @@ module_name_repetitions = "allow"
 must_use_candidate = "allow"
 semicolon_if_nothing_returned = "deny"
 similar_names = "allow"
-
-[package.metadata.docs.rs]
-rustdoc-args = [ "--html-in-header", "./docs/assets/katex-header.html" ]

README.md

@@ -1,11 +1,87 @@
 # ALBA
+This is a 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, 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 is a cryptographic primitive that enables a prover to convince a verifier that their dataset includes at least a minimum number of elements meeting a specific condition, called a predicate, without revealing the entire dataset.
+The core idea of ALBA is to introduce a controlled gap between the prover's actual knowledge and the threshold the verifier wants to confirm. 
+This gap not only gives ALBA its name (_Approximate Lower Bound Argument_) but also enables highly efficient algorithms for generating compact proofs.
+ALBA proofs are particularly small and efficient in scenarios with significant discrepancy between the dataset size and the threshold to prove, or involving weight oracles, and are generated significantly faster than traditional general purpose SNARKs.
+Its main applications include voting and certifying digital signatures in large-scale decentralized networks as well as other blockchain scenarios where it improves communication efficiency among multiple provers sharing a common witness.
 
-> **Approximate Lower Bound Arguments**,  _Pyrros Chaidos, Prof Aggelos Kiayias, Leonid Reyzin, Anatoliy Zinovyev_, May 2024, Eurocrypt'24
+For example, in a decentralized voting system, participants (voters) submit votes that support different options or candidates.
+To validate the results without revealing all individual votes, an ALBA protocol could be used to prove a majority was reached.
+Each vote can be considered an _element_ that meets a certain predicate (e.g., a valid vote for a specific 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 (such as reaching a quorum or winning a majority).
+Combining ALBA with zero-knowledge technology, such as _zk-SNARKs_, can efficiently keep individual votes private while potentially reducing the proof size even more.
+Beyond voting, ALBA's versatility makes it suitable for various use cases requiring efficient, scalable proof systems that balance privacy, speed, and resource efficiency.
 
-> [!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
+### ALBA in a Nutshell
+ALBA's core construction, the _centralized telescope_, operates as follows:  
+The prover holds a set of $n_p$ elements (e.g. signatures, data points, or weighted items) that satisfy a predicate. 
+The verifier needs to be convinced that the prover knows strictly more than $n_f$ elements, where $n_f < n_p$. 
+ALBA generates a proof by choosing a subset of, potentially repeated, elements. These elements are selected through a random walk satisfying random oracle checks at each step, outputting a tuple significantly smaller than $n_f$.
+The larger the ratio $n_p / n_f$, the smaller the proof size, making ALBA practical for scenarios involving large datasets and low thresholds.
 
-👉 Checkout documentation on https://alba.cardano-scaling.org
+ALBA furthermore supports *weighted elements*, where each item has an integer weight. 
+In this case, the prover has in possession elements with a total weight of at least $n_p$ and convinces the verifier that the total weight exceeds $n_f$.
+In *decentralized settings*, ALBA adapts to distributed data environments. 
+Multiple participants play a lottery and send their elements to an aggregator accordingly to its result. The aggregator then combines them into a single, compact proof for the verifier.
+
+ALBA can seamlessly handle both *un/weighted* and *de/centralized* configurations at the same time. 
+This flexibility is particularly valuable in applications like *proof-of-stake blockchains*, where weights represent stake amounts. 
+ALBA there can be used to ensure that honest participants' stakes outweigh malicious contributions, providing robust security in distributed systems.
+The *decentralized construction* of ALBA also stands out for its flexibility, offering tradeoffs between proof size and communication complexity. 
+This feature allows protocol designers to optimize ALBA for various decentralized applications.
+
+### Why Use ALBA?
+ALBA is an ideal choice for applications that require:
+- *Fast proof generation and verification*, such as in blockchain systems or multisignature schemes.
+- *Efficient decentralized collaboration*, enabling multiple participants to jointly prove knowledge.
+- *Flexibility in tradeoffs*, balancing proof size and communication overhead.
+Whether it is for multisignatures, proof-of-stake systems, or secure voting protocols, ALBA provides a robust, scalable, and efficient solution for proving knowledge across diverse use cases.
+
+## Implementation
+The library implements ALBA schemes based on two core constructions: *Telescope* and *Lottery*. 
+These constructions form the foundation for the various configurations, including centralized and decentralized setups as well as unweighted and weighted scenarios.
+
+The *Telescope* construction allows the prover to build a sequence of elements that satisfy staged hash-based conditions.
+This process efficiently filters relevant elements, narrowing down the data to subsets that meet the required criteria.
+By introducing bounded repetitions and constraints such as pre-hashing on the prover's search, the construction ensures scalability and efficiency for large datasets.
+
+The *Lottery* construction offers a decentralized approach where participants probabilistically decide whether to share their elements with an aggregator. 
+The aggregator collects enough elements and concatenates them to generate a proof. 
+This method is inherently decentralized and can also handle weighted scenarios by incorporating element weights into the lottery process.
+
+Using these constructions, the library supports eight ALBA schemes, covering a wide range of configurations:
+- _Telescope bounded_ (Section 3.2.2), whether centralized or not (Section 4.2), unweighted or not (Section 5),
+- _Lottery_ (Section 4.1), whether centralized or not, unweighted or not (Section 5).
+
+## ⚠️ Disclaimer
+This code is NOT fit for production, it has not been optimized, thoroughly tested, nor audited.
+Its one and only purpose is to help people who are more familiar with code than equations to prototype larger protocols using ALBA.
+
+## 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
+Compile the library by:
+```shell
+cargo build --release
+```
+
+Run tests with: 
+```shell
+cargo test
+```
+
+Run benchmarks with: 
+```shell
+cargo bench
+```
+
+Compile the documentation by:
+```shell
+cargo doc --no-deps --open
+```

docs/intro.md

@@ -1 +1,42 @@
-**Telescope ALBA** documentation.
+- Assume that a prover has a large collection of data. They want to convince a verifier that their set contains at least a minimum number of elements satisfying a specific predicate, known as a predicate. This remains true even if the prover only shares a portion of their data.
+- A trivial solution to this problem would be for the prover to provide the entire dataset or the minimum number of distinct elements to the verifier. However, this approach is inefficient due to the large size of the data and communication costs.
+- The Approximate Lower Bound Argument (ALBA) protocol is a new cryptographic primitive that solves this problem efficiently.
+- ALBA is designed to prove knowledge efficiently by leveraging an *approximate lower bound*.
+  - This approach exploits the gap between the prover's actual knowledge and the threshold needed to convince the verifier.
+  - The gap enables compact proofs and efficient verification.
+- ALBA supports both centralized and decentralized setups, as well as weighted and unweighted datasets, making it useful for applications such as blockchain protocols, voting systems, and multisignature schemes.
+
+## Overview
+- **The Protocol**
+  - The protocol addresses the challenge of succinctly proving knowledge of a large set of verifiable evidence.
+  - The prover convinces the verifier by revealing only a subset of this evidence, achieving efficiency in both proof size and communication.
+  - Given a large set $S_p$ that satisfies a predicate $R$ such that $|S_p| \geq n_p$, the prover aims to convince the verifier that the set contains more than $n_f$ elements, where $n_f$ is a threshold strictly smaller than $n_p$.
+    - This establishes an _approximate_ lower bound because the prover's proof guarantees the presence of more than $n_f$ elements, but the actual set size $|S_p|$ is typically greater. The term "approximate" reflects that the bound is loose rather than tight.
+    - $n_p$ might be smaller than $|S_p|$ for various practical reasons:
+      - *Uncertainty about* $|S_p|$: In scenarios like probabilistic lotteries, not all elements of the set are sent, and the actual number depends on the lottery draw.
+      - *Timeliness*: The prover may want to generate a proof as soon as possible without waiting to collect all elements in the dataset. Even with $n < n_p$ (and $n > n_f$) elements, there is a chance of successfully generating a proof. 
+  - ALBA achieves efficiency by leveraging the gap between the provable lower bound ($n_f$) and the prover set size ($n_p$). This gap enables compact proofs and rapid verification without compromising security. The larger the ratio $n_p / n_f$, 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 and interactive protocols.
+    - Previous methods were largely theoretical and less efficient for practical, large-scale applications.
+- **Design goals**
+  - *Efficiency*: Ensure fast proof generation and verification with minimal computational and communication overhead.
+  - *Scalability*: Handle large datasets with low thresholds, suitable for high-throughput applications like blockchains.
+  - *Flexibility*: Support a range of configurations, including weighted/unweighted and centralized/decentralized setups.
+  - *Practical Usability*: Provide developers with an implementation that bridges theoretical concepts and real-world use cases.
+- **Setup and interaction models**
+  - *Interaction models*
+    - *Centralized model*: In the centralized setup, a single prover is responsible for generating a proof. The prover selects subsets of elements from their dataset that satisfy specific conditions and outputs a compact certificate for the verifier. This approach is ideal for scenarios where a single entity holds all the necessary data.
+    - *Decentralized model*: In decentralized environments, multiple participants (provers) collaborate to create a proof. Each participant contributes elements to an aggregator, who combines these contributions into a single proof. This model is particularly suited for distributed systems like proof-of-stake blockchains or secure voting protocols, where data is naturally spread across multiple parties.
+  - *Weighted and unweighted configurations*
+    - *Unweighted configuration*: Provers demonstrate possession of a minimum number of elements that satisfy the required conditions.
+    - *Weighted configuration*: Each element has an integer weight. The prover demonstrates that the total weight of their elements meets or exceeds a specific threshold.
+  - *Proof construction methods*: The ALBA protocol supports two main constructions for generating proofs, both of which can be used in centralized or decentralized, weighted or unweighted setups:
+    - *Telescope construction*
+      - Filters and narrows down subsets of elements through staged, hash-based conditions.
+      - Provides a configurable tradeoff between communication complexity and proof size, allowing flexibility in applications.
+      - Especially useful when optimizing for smaller proof sizes is a priority.
+    - *Lottery construction*
+      - Probabilistically selects elements for inclusion in the proof.
+      - Optimized for the best communication complexity, though at the cost of larger proof sizes compared to the telescope method.
+      - Ideal for decentralized settings requiring minimal communication overhead.

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;