Documentation - Intro

README.md

@@ -1,11 +1,91 @@
 # 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 efficiently prove knowledge by leveraging an *approximate lower bound*. 
+This approach introduces a controlled gap between the prover's actual knowledge and the threshold required for the verifier to be convinced. 
+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 SNARKs.
+Its main applications include large-scale decentralized signature schemes and 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 to meet the required threshold for a decision (such as reaching a quorum or winning a majority).
+Combining ALBA with zero-knowledge technology such as _zk-SNARKs_, we can efficiently keep individual votes private while 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]
+### 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 more than $n_f$ elements, where $n_f < n_p$. 
+ALBA generates a proof by choosing a subset of, potentially repeated, elements through a random walk satisfying some 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.
+
+ALBA also supports *weighted elements*, where each item has an integer weight. 
+In this case the prover demonstrates possession of elements with a total weight of at least $n_p$, while convincing 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, which then combines them into a single, compact proof for the verifier.
+
+ALBA can seamlessly handle both *weighted/unweighted* and *centralized/decentralized* configurations. 
+This flexibility is particularly valuable in applications like *proof-of-stake blockchains*, where weights represent stake amounts. 
+ALBA there ensures that  honest participants' stakes outweigh malicious contributions, providing robust security in distributed systems.
+The *decentralized construction* of ALBA 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's 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 supported, 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 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 shared elements 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:
+- Centralized unweighted Telescope Bounded (Section 3.2.2)
+- Decentralized unweighted Telescope Bounded (Sections 3.2.2, 4.2)
+- Centralized weighted Telescope Bounded (Sections 3.2.2, 5)
+- Decentralized weighted Telescope Bounded (Sections 3.2.2, 4.2, 5)
+- Centralized unweighted Simple Lottery (Section 4.1)
+- Decentralized unweighted Simple Lottery (Section 4.1)
+- Centralized weighted Simple Lottery (Sections 4.1, 5)
+- Decentralized weighted Simple Lottery (Sections 4.1, 5)
+
+
+### Disclaimer
 > 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 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
+
+### Library
+Compile the library by:
+```shell
+cargo build --release
+```
+
+### Tests and Benchmarks
+Run tests with `cargo test`. Run benchmarks with `cargo bench`. 
 
-👉 Checkout documentation on https://alba.cardano-scaling.org
+### Documentation
+Compile the documentation by:
+```shell
+RUSTDOCFLAGS="--html-in-header docs/assets/katex-header.html" cargo doc --no-deps --open
+```

docs/intro.md

@@ -1 +1,38 @@
-**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 condition, 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 all sequence 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 establishes a 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$), 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 actual set size ($|S_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 or 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**
+  - *Centralized Model*:
+    - A single prover generates a proof by selecting subsets of elements that satisfy certain conditions, outputting a compact certificate for the verifier.
+  - *Decentralized Model*:
+    - Multiple participants contribute their elements to an aggregator, who combines them into a single proof.
+    - This model is particularly efficient in scenarios requiring distributed collaboration, such as proof-of-stake blockchains or voting protocols.
+  - *Weighted and Unweighted Configurations*:
+    - In the unweighted setting, the proof involves demonstrating possession of a minimum number of elements.
+    - In the weighted setting, each element has an associated integer weight, and the prover demonstrates that the total weight meets or exceeds the required threshold.
+  - *Proof Construction Methods*:
+    - *Telescope*: Filters and narrows down subsets of elements through staged conditions, optimizing for speed and size.
+    - *Lottery*: Probabilistically selects elements in decentralized environments, supporting both weighted and unweighted setups.

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;