Update Readme (#987)

jotabulacios · nicole-graus · ColoCarletti · web-flow · commit d9385675aa91 · 2025-04-04T17:10:25.000Z
* update kzg Readme

* KZG: make sure example is ok

* Add Readme for Merkle Tree

* Add Readme for Circle

* fix circle docs

* fix circle readme

* fix typo, remove unused test and fix markdown style

* changes in circle readme

* fix circle readme

* fix clippy

* fix clippy spaces

---------

Co-authored-by: Nicole &lt;nicole.graus@lambdaclass.com&gt;
Co-authored-by: Joaquin Carletti &lt;joaquin.carletti@lambdaclass.com&gt;
Co-authored-by: Diego K &lt;43053772+diegokingston@users.noreply.github.com&gt;
diff --git a/crates/crypto/src/commitments/README.md b/crates/crypto/src/commitments/README.md
@@ -60,10 +60,136 @@ $e( P - y g_1 , - g_2 ) \times e( Q , [\tau]_2 - z g_2 ) \equiv 1 \pmod{r}$
 
 This is more efficient, since we can compute the pairing using two Miller loops but just one final exponentiation.
 
+
+## Implementation
+
+The implementation in this codebase includes:
+
+- `StructuredReferenceString`: Stores the powers of a secret value in both G1 and G2 groups
+- `KateZaveruchaGoldberg`: The main implementation of the KZG commitment scheme
+- Support for both single and batch openings/verifications
+
+## API Usage
+
+KZG commitments can be used to commit to polynomials and later prove evaluations at specific points. Here's how to use the KZG implementation in lambdaworks:
+
+### Creating a KZG Instance
+
+First, you need to load or create a Structured Reference String (SRS) and initialize the KZG instance:
+
+```rust
+use lambdaworks_crypto::commitments::kzg::{KateZaveruchaGoldberg, StructuredReferenceString};
+use lambdaworks_crypto::commitments::traits::IsCommitmentScheme;
+use lambdaworks_math::elliptic_curve::short_weierstrass::curves::bls12_381::{
+    curve::BLS12381Curve,
+    default_types::{FrElement, FrField},
+    pairing::BLS12381AtePairing,
+    twist::BLS12381TwistCurve,
+};
+use lambdaworks_math::elliptic_curve::short_weierstrass::point::ShortWeierstrassProjectivePoint;
+
+// Load SRS from a file
+let srs_file = "path/to/srs.bin";
+let srs = StructuredReferenceString::from_file(srs_file).unwrap();
+
+// Create a KZG instance
+let kzg = KateZaveruchaGoldberg::<FrField, BLS12381AtePairing>::new(srs);
+```
+
+### Committing to a Polynomial
+
+To commit to a polynomial, you first create the polynomial and then use the `commit` method:
+
+```rust
+use lambdaworks_math::field::element::FieldElement;
+use lambdaworks_math::polynomial::Polynomial;
+
+// Create a polynomial p(x) = x + 1
+let p = Polynomial::<FrElement>::new(&[FieldElement::one(), FieldElement::one()]);
+
+// Commit to the polynomial
+let commitment = kzg.commit(&p);
+```
+
+### Generating and Verifying Proofs
+
+To prove that a polynomial evaluates to a specific value at a specific point:
+
+```rust
+// Choose a point to evaluate the polynomial
+let x = -FieldElement::one();
+
+// Compute the evaluation
+let y = p.evaluate(&x);  // Should be 0 for p(x) = x + 1 when x = -1
+
+// Generate a proof for this evaluation
+let proof = kzg.open(&x, &y, &p);
+
+// Verify the proof
+let is_valid = kzg.verify(&x, &y, &commitment, &proof);
+assert!(is_valid, "Proof verification failed");
+```
+
+### Batch Operations
+
+KZG supports batch operations for more efficient verification of multiple polynomial evaluations:
+
+```rust
+// Create polynomials
+let p0 = Polynomial::<FrElement>::new(&[FieldElement::from(9000)]);  // Constant polynomial
+let p1 = Polynomial::<FrElement>::new(&[
+    FieldElement::from(1),
+    FieldElement::from(2),
+    -FieldElement::from(1),
+]);  // p(x) = 1 + 2x - x²
+
+// Commit to the polynomials
+let p0_commitment = kzg.commit(&p0);
+let p1_commitment = kzg.commit(&p1);
+
+// Choose a point to evaluate the polynomials
+let x = FieldElement::from(3);
+
+// Compute the evaluations
+let y0 = p0.evaluate(&x);  // 9000
+let y1 = p1.evaluate(&x);  // 1 + 2*3 - 3² = 1 + 6 - 9 = -2
+
+// Generate a random field element for the batch proof
+let upsilon = &FieldElement::from(1);  // In practice, use a random value
+
+// Generate batch proof
+let proof = kzg.open_batch(&x, &[y0.clone(), y1.clone()], &[p0, p1], upsilon);
+
+// Verify batch proof
+let is_valid = kzg.verify_batch(
+    &x,
+    &[y0, y1],
+    &[p0_commitment, p1_commitment],
+    &proof,
+    upsilon
+);
+assert!(is_valid, "Batch proof verification failed");
+```
+
+### Serialization and Deserialization
+
+The SRS can be serialized and deserialized for storage and transmission:
+
+```rust
+// Serialize the SRS
+let bytes = srs.as_bytes();
+
+// Deserialize the SRS
+let deserialized_srs = StructuredReferenceString::<
+    ShortWeierstrassProjectivePoint<BLS12381Curve>,
+    ShortWeierstrassProjectivePoint<BLS12381TwistCurve>,
+>::deserialize(&bytes).unwrap();
+```
+
 ## References
 
 - [Constantine](https://github.com/mratsim/constantine/blob/master/constantine/commitments/kzg.nim)
 - [EIP-4844](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md)
 - [KZG proof verification](https://github.com/ethereum/consensus-specs/blob/v1.4.0-beta.1/specs/deneb/polynomial-commitments.md#verify_kzg_proof_batch)
 - [Multiproofs KZG](https://dankradfeist.de/ethereum/2021/06/18/pcs-multiproofs.html)
-- [Fast amortized KZG proofs](https://eprint.iacr.org/2023/033)
+- [Fast amortized KZG proofs](https://eprint.iacr.org/2023/033)
diff --git a/crates/crypto/src/commitments/kzg.rs b/crates/crypto/src/commitments/kzg.rs
@@ -376,15 +376,15 @@ mod tests {
 
         let x = FieldElement::from(3);
 
-        let p0 = Polynomial::<FrElement>::new(&[FieldElement::from(9000)]);
+        let p0 = Polynomial::<FrElement>::new(&[FieldElement::from(9000)]); // Constant polynomial
         let p0_commitment: <BLS12381AtePairing as IsPairing>::G1Point = kzg.commit(&p0);
         let y0 = FieldElement::from(9000);
 
         let p1 = Polynomial::<FrElement>::new(&[
             FieldElement::from(1),
             FieldElement::from(2),
             -FieldElement::from(1),
-        ]);
+        ]); // p(x) = 1 + 2x - x²
         let p1_commitment: <BLS12381AtePairing as IsPairing>::G1Point = kzg.commit(&p1);
         let y1 = p1.evaluate(&x);
 
diff --git a/crates/crypto/src/merkle_tree/README.md b/crates/crypto/src/merkle_tree/README.md
@@ -0,0 +1,231 @@
+# Merkle Trees
+
+A Merkle tree is a binary tree data structure where each leaf node contains the hash of a data block, and each non-leaf node contains the hash of its two child nodes. This structure allows for efficient and secure verification of content in large data structures.
+
+## What is a Merkle Tree?
+
+Merkle trees provide a way to efficiently verify the integrity of data. Here's how they work:
+
+1. **Leaf Nodes**: Start by hashing each piece of data (e.g., files, transactions) to create the leaf nodes
+2. **Internal Nodes**: Each internal node is created by hashing the concatenation of its two child nodes
+3. **Root Hash**: The hash at the top of the tree (root) represents a cryptographic summary of all the data
+
+For example, with 8 files (f₁, f₂, ..., f₈):
+- First, hash each file: h₁ = H(f₁), h₂ = H(f₂), ..., h₈ = H(f₈)
+- Then hash pairs: h₁₂ = H(h₁, h₂), h₃₄ = H(h₃, h₄), etc.
+- Continue until you reach the root: h₁₋₈ = H(h₁₋₄, h₅₋₈)
+
+The power of Merkle trees comes from their ability to generate compact proofs. A **Merkle proof** for a specific piece of data consists of the minimal set of hashes needed to recompute the root hash. This allows verification that a piece of data belongs to the original set without needing all the data.
+
+## Overview
+
+The Merkle tree implementation in Lambdaworks provides:
+
+- A generic `MerkleTree` structure that can work with different hash functions and data types
+- Support for generating and verifying inclusion proofs
+- Multiple backend implementations for different use cases
+- Serialization and deserialization of proofs
+- Optional parallel processing for improved performance
+
+## Implementation
+
+The implementation in this codebase includes:
+
+- `MerkleTree`: The main Merkle tree data structure
+- `Proof`: Represents a Merkle proof for verifying inclusion of data
+- `IsMerkleTreeBackend`: A trait for implementing different backend strategies
+- Several backend implementations:
+  - `FieldElementBackend`: For hashing field elements using various hash functions
+  - `FieldElementVectorBackend`: For hashing vectors of field elements
+  - `BatchPoseidonTree`: For batch hashing with Poseidon
+
+## API Usage
+
+### Creating a Merkle Tree
+
+Here's a basic example of creating a Merkle tree with field elements:
+
+```rust
+use lambdaworks_crypto::merkle_tree::{
+    merkle::MerkleTree,
+    backends::field_element::FieldElementBackend,
+};
+use lambdaworks_math::field::{
+    element::FieldElement,
+    fields::fft_friendly::stark_252_prime_field::Stark252PrimeField,
+};
+use sha3::Keccak256;
+
+// Define the types we'll use
+type F = Stark252PrimeField;
+type FE = FieldElement<F>;
+
+// Create some data
+let values: Vec<FE> = (1..6).map(FE::from).collect();
+
+// Build the Merkle tree using Keccak256 as the hash function
+let merkle_tree = MerkleTree::<FieldElementBackend<F, Keccak256, 32>>::build(&values).unwrap();
+```
+
+### Using BatchPoseidonTree for Efficient Hashing
+
+The `BatchPoseidonTree` backend is specifically designed for efficient batch hashing using the Poseidon hash function, which is particularly useful in zero-knowledge proof systems. This backend provides optimized performance for vectors of field elements.
+
+```rust
+use lambdaworks_crypto::merkle_tree::{
+    merkle::MerkleTree,
+    backends::field_element_vector::BatchPoseidonTree,
+};
+use lambdaworks_crypto::hash::poseidon::starknet::PoseidonCairoStark252;
+use lambdaworks_math::field::{
+    element::FieldElement,
+    fields::fft_friendly::stark_252_prime_field::Stark252PrimeField,
+};
+
+// Define the types we'll use
+type F = Stark252PrimeField;
+type FE = FieldElement<F>;
+
+// Create some data (vectors of field elements)
+let values: Vec<Vec<FE>> = vec![
+    vec![FE::from(1), FE::from(2)],
+    vec![FE::from(3), FE::from(4)],
+    vec![FE::from(5), FE::from(6)],
+    vec![FE::from(7), FE::from(8)],
+];
+
+// Build the Merkle tree using Poseidon hash function
+let merkle_tree = MerkleTree::<BatchPoseidonTree<PoseidonCairoStark252>>::build(&values).unwrap();
+
+// Generate a proof for a specific element
+let proof = merkle_tree.get_proof_by_pos(1).unwrap();
+
+// Verify the proof
+let is_valid = proof.verify::<BatchPoseidonTree<PoseidonCairoStark252>>(
+    &merkle_tree.root,
+    1,
+    &values[1]
+);
+
+assert!(is_valid, "Proof verification failed");
+```
+
+Key features of `BatchPoseidonTree`:
+
+1. **Optimized for ZK Systems**: Poseidon is designed to be efficient in zero-knowledge proof systems, making this backend ideal for ZK applications.
+
+2. **Batch Hashing**: The `hash_many` function efficiently processes multiple field elements at once.
+
+3. **Field Element Compatibility**: Works with vectors of field elements, which is common in cryptographic protocols.
+
+4. **Performance**: Poseidon offers better performance than traditional hash functions when working with field elements in ZK contexts.
+
+### Generating Proofs
+
+To generate a proof for a specific leaf:
+
+```rust
+// Generate a proof for the first element (index 0)
+let proof = merkle_tree.get_proof_by_pos(0).unwrap();
+```
+
+### Verifying Proofs
+
+To verify that a value is included in the tree:
+
+```rust
+// Verify the proof
+let is_valid = proof.verify::<FieldElementBackend<F, Keccak256, 32>>(
+    &merkle_tree.root,  // The Merkle root
+    0,                  // The position of the leaf
+    &values[0]          // The value to verify
+);
+
+assert!(is_valid, "Proof verification failed");
+```
+
+### Working with Vectors of Field Elements
+
+If you need to hash vectors of field elements:
+
+```rust
+use lambdaworks_crypto::merkle_tree::{
+    merkle::MerkleTree,
+    backends::field_element_vector::FieldElementVectorBackend,
+};
+use lambdaworks_math::field::{
+    element::FieldElement,
+    fields::fft_friendly::stark_252_prime_field::Stark252PrimeField,
+};
+use sha3::Keccak256;
+
+// Define the types we'll use
+type F = Stark252PrimeField;
+type FE = FieldElement<F>;
+
+// Create some data (vectors of field elements)
+let values: Vec<Vec<FE>> = vec![
+    vec![FE::from(1), FE::from(2)],
+    vec![FE::from(3), FE::from(4)],
+    vec![FE::from(5), FE::from(6)],
+];
+
+// Build the Merkle tree
+let merkle_tree = MerkleTree::<FieldElementVectorBackend<F, Keccak256, 32>>::build(&values).unwrap();
+
+// Generate a proof
+let proof = merkle_tree.get_proof_by_pos(0).unwrap();
+
+// Verify the proof
+let is_valid = proof.verify::<FieldElementVectorBackend<F, Keccak256, 32>>(
+    &merkle_tree.root,
+    0,
+    &values[0]
+);
+
+assert!(is_valid, "Proof verification failed");
+```
+
+## Serialization and Deserialization
+
+Proofs can be serialized and deserialized for storage or transmission. Note that serialization requires the `alloc` feature to be enabled:
+
+```rust
+// This requires the 'alloc' feature to be enabled
+use lambdaworks_crypto::merkle_tree::{
+    merkle::MerkleTree,
+    proof::Proof,
+    // For testing, you might use a simpler backend like TestBackend
+};
+use lambdaworks_math::traits::{Deserializable, Serializable};
+
+// Serialize the proof
+let serialized_proof = proof.serialize();
+
+// Deserialize the proof
+let deserialized_proof = Proof::deserialize(&serialized_proof).unwrap();
+
+// Verify the deserialized proof
+let is_valid = deserialized_proof.verify(
+    &merkle_tree.root,
+    0,
+    &values[0]
+);
+
+assert!(is_valid, "Deserialized proof verification failed");
+```
+
+Note: The serialization example assumes that the type used for the Merkle tree nodes implements both `Serializable` and `Deserializable` traits.
+
+## Performance Considerations
+
+- The Merkle tree implementation automatically pads the input data to the next power of 2, which is required for a balanced binary tree
+- For large datasets, enable the `parallel` feature to use parallel processing for improved performance
+- Choose an appropriate backend based on your security and performance requirements:
+  - Standard cryptographic hash functions (SHA-3, Keccak) provide strong security guarantees
+
+
+## References
+
+- [Merkle Tree - Wikipedia](https://en.wikipedia.org/wiki/Merkle_tree)
+- [What is a Merkle Tree?](https://decentralizedthoughts.github.io/2020-12-22-what-is-a-merkle-tree/) - A comprehensive explanation of Merkle trees, proofs, and applications
diff --git a/crates/math/src/circle/README.md b/crates/math/src/circle/README.md
