Update docs (#892)

* update tables * fix errors * add more on pairings * fix rendering * fix * fix * fixes * fix parentheses * render * fix * add and reorg references
lambdaclass · Aug 24, 2024 · c4fa1f2 · c4fa1f2
1 parent f552f63
commit c4fa1f2
Show file tree

Hide file tree

Showing 12 changed files with 110 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
 # lambdaworks
+
 > From the heights of these towers of fields, forty centuries of mathematics look down on us. 
 
 This library provides efficient implementation of cryptographic primitives used to build proving systems. Along with it, many backends for proving systems are shipped, and compatibility with different frontends is supported.
@@ -32,6 +33,7 @@ So, we decided to build our library, focusing on performance, with clear documen
 - [Groth 16](https://github.com/lambdaclass/lambdaworks/tree/main/provers/groth16)
 
 ### Crypto
+
 - [Elliptic curves](https://github.com/lambdaclass/lambdaworks/tree/main/math/src/elliptic_curve)
 - [Multiscalar multiplication](https://github.com/lambdaclass/lambdaworks/tree/main/math/src/msm)
 - [Hashes](https://github.com/lambdaclass/lambdaworks/tree/main/crypto/src/hash)
@@ -41,12 +43,15 @@ Most of math and crypto crates supports no-std without allocation with `no-defau
 Both Math and Crypto support wasm with target `wasm32-unknown-unknown`. To see an example of how to use this to deploy a verifier in a browser, check the Cairo Prover wasm-pack verifier.
 
 ## Examples - mini apps
+
 - [Merkle Tree CLI](https://github.com/lambdaclass/lambdaworks/tree/main/examples/merkle-tree-cli)
 - [Proving Miden](https://github.com/lambdaclass/lambdaworks/tree/main/examples/prove-miden)
 - [Shamir's secret sharing](https://github.com/lambdaclass/lambdaworks/tree/main/examples/shamir_secret_sharing)
 - [BabySNARK](https://github.com/lambdaclass/lambdaworks/tree/main/examples/baby-snark)
+- [Pinocchio](https://github.com/lambdaclass/lambdaworks/tree/main/examples/pinocchio)
 
 ## Exercises and Challenges
+
 - [lambdaworks exercises and challenges](https://github.com/lambdaclass/lambdaworks_exercises/tree/main)
 - [Roadmap for Sparkling Water Bootcamp](https://github.com/lambdaclass/sparkling_water_bootcamp/blob/main/README.md)
 
@@ -85,9 +90,9 @@ List of symbols:
 | **Elliptic Curves** | **Lambdaworks** | **Arkworks**          | **Halo2**          | **gnark**          | **Constantine**    |
 | BLS12-381           | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | BLS12-377           | 🏗️                 | :heavy_check_mark: | :x:                | :heavy_check_mark: | :heavy_check_mark: |
-| BN-254              | 🏗️                 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| Pallas              | :heavy_check_mark: | :heavy_check_mark: | :x:                | :x:                | :heavy_check_mark: |
-| Vesta               | :heavy_check_mark: | :heavy_check_mark: | :x:                | :x:                | :heavy_check_mark: |
+| BN-254              | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| Pallas              | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x:                | :heavy_check_mark: |
+| Vesta               | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x:                | :heavy_check_mark: |
 | Bandersnatch        | 🏗️                 | :heavy_check_mark: | :x:                | :heavy_check_mark:  | :heavy_check_mark: |
 | **STARKs**       | **Lambdaworks**     | **Arkworks** | **Halo2** | **gnark** | **Constantine** |
 | STARK Prover     | :heavy_check_mark:  | :x:          | :x:       | :x:       | :x:             |
@@ -158,26 +163,34 @@ To serve the documentation locally, first install both [mdbook](https://rust-lan
 make docs
 ```
 
-## 📚 References
+## 📚 References and acknowledgements
 
-The following links, repos and projects have been important in the development of this library and we want to thank and acknowledge them. 
+The following links, repos, companies and projects have been important in the development of this library and we want to thank and acknowledge them. 
 
 - [Starkware](https://starkware.co/)
+- [Polygon](https://polygon.technology/)
+- [Mina](https://minaprotocol.com/)
+- [zcash](https://z.cash/)
+- [Matter Labs](https://matter-labs.io/)
+- [o1Labs](https://www.o1labs.org/)
+- [zkSync](https://zksync.io/)
+- [Aleo](https://aleo.org/)
+- [Risc0](https://github.com/risc0/risc0)
+- [Aztec](https://github.com/AztecProtocol)
+- [Ingonyama](https://www.ingonyama.com/)
+- [Neptune](https://github.com/Neptune-Crypto)
 - [Winterfell](https://github.com/facebook/winterfell)
 - [Anatomy of a Stark](https://aszepieniec.github.io/stark-anatomy/overview)
 - [Giza](https://github.com/maxgillett/giza)
 - [Ministark](https://github.com/andrewmilson/ministark)
 - [Sandstorm](https://github.com/andrewmilson/sandstorm)
 - [STARK-101](https://starkware.co/stark-101/)
 - [starknet-rs](https://github.com/xJonathanLEI/starknet-rs/)
-- [Risc0](https://github.com/risc0/risc0)
-- [Neptune](https://github.com/Neptune-Crypto)
 - [Summary on FRI low degree test](https://eprint.iacr.org/2022/1216)
 - [STARKs paper](https://eprint.iacr.org/2018/046)
 - [DEEP FRI](https://eprint.iacr.org/2019/336)
 - [BrainSTARK](https://aszepieniec.github.io/stark-brainfuck/)
 - [Plonky2](https://github.com/mir-protocol/plonky2)
-- [Aztec](https://github.com/AztecProtocol)
 - [Arkworks](https://github.com/arkworks-rs)
 - [Thank goodness it's FRIday](https://vitalik.ca/general/2017/11/22/starks_part_2.html)
 - [Diving DEEP FRI](https://blog.lambdaclass.com/diving-deep-fri/)
@@ -190,3 +203,4 @@ The following links, repos and projects have been important in the development o
 - [CAIRO whitepaper](https://eprint.iacr.org/2021/1063.pdf)
 - [Gnark](https://github.com/Consensys/gnark)
 - [Constantine](https://github.com/mratsim/constantine)
+- [Plonky3](https://github.com/Plonky3/Plonky3)
diff --git a/bootcamp/README.md b/bootcamp/README.md
@@ -7,6 +7,7 @@ Public repository for exercises, challenges and all the needs of the Sparkling W
 This first week will be focused on the development of one of the building blocks of Cryptography: Finite Fields. 
 
 ### Recommended material:
+
 - [An introduction to mathematical cryptography](https://books.google.com.ar/books/about/An_Introduction_to_Mathematical_Cryptogr.html?id=BHuTQgAACAAJ&source=kp_book_description&redir_esc=y) - Chapter 1.
 - [Finite Fields](https://www.youtube.com/watch?v=MAhmV_omOwA&list=PLFX2cij7c2PynTNWDBzmzaD6ij170ILbQ&index=8)
 - [Constructing finite fields](https://www.youtube.com/watch?v=JPiXFn9WA5Y&list=PLFX2cij7c2PynTNWDBzmzaD6ij170ILbQ&index=6)
@@ -15,12 +16,14 @@ This first week will be focused on the development of one of the building blocks
 - [Mersenne primes](https://eprint.iacr.org/2023/824.pdf)
 
 ### Challenges:
+
 - [Implement Montgomery backend for 32 bit fields](https://github.com/lambdaclass/lambdaworks/issues/538).
 - [Implement efficient Mersenne prime backend](https://github.com/lambdaclass/lambdaworks/issues/540).
 - [Implement efficient backend for pseudo-Mersenne primes](https://github.com/lambdaclass/lambdaworks/issues/393).
 - Compare specific field implementations with ordinary Montgomery arithmetic.
 
 ### Cryptography content:
+
 - [Serious Cryptography](https://books.google.com.ar/books/about/Serious_Cryptography.html?id=1D-QEAAAQBAJ&source=kp_book_description&redir_esc=y), Chapters 9 & 10.
 
 ### Exercises

diff --git a/crypto/README.md b/crypto/README.md
@@ -3,7 +3,6 @@
 [Latest Version]: https://img.shields.io/crates/v/lambdaworks-crypto.svg
 [crates.io]: https://crates.io/crates/lambdaworks-crypto
 
-
 ## Usage
 
 Add this to your `Cargo.toml`

diff --git a/docs/src/plonk/SUMMARY.md b/docs/src/plonk/SUMMARY.md
@@ -3,5 +3,4 @@
 - [Recap](./recap.md)
 - [Protocol](./protocol.md)
 - [Implementation](./implementation.md)
-- [Circuit API](./constraint_system.md)
-
+- [Circuit API](./constraint_system.md)
diff --git a/docs/src/plonk/constraint_system.md b/docs/src/plonk/constraint_system.md
@@ -1,4 +1,5 @@
 # Circuit API
+
 In this section, we'll discuss how to build your own constraint system to prove the execution of a particular program.
 
 ## Simple Example
@@ -99,5 +100,4 @@ fn main() {
 }
 ```
 
-You can keep composing these functions in order to create more complex systems.
-
+You can keep composing these functions in order to create more complex systems.
diff --git a/docs/src/plonk/implementation.md b/docs/src/plonk/implementation.md
@@ -1,12 +1,15 @@
 # Implementation
+
 In this section we discuss the implementation details of the PLONK algorithm. We use the notation and terminology of the [protocol](./protocol.md) and [recap](./recap.md) sections. 
 
-At the moment our API supports the backend of PLONK. That is, all the setup, prove and verify algorithms. We temporarily rely on external sources for the definition of a circuit and the creation of the $Q$ and $V$ matrices, as well as the execution of it to obtain the trace matrix $T$. We mainly use gnark temporarily for that purpose.
+At the moment our API supports the backend of PLONK, that is, all the setup, prove and verify algorithms. We temporarily rely on external sources for the definition of a circuit and the creation of the $Q$ and $V$ matrices, as well as the execution of it to obtain the trace matrix $T$. We mainly use gnark temporarily for that purpose.
+
+To generate proofs and validate them, we need to feed the algorithms with precomputed values of the $Q$, $V$ and $T$ matrices, and the primitive root of unity $\omega$.
 
-So to generate proofs and validate them, we need to feed the algorithms with precomputed values of the $Q$, $V$ and $T$ matrices, and the primitive root of unity $\omega$.
+Let's see our API on a test circuit that provides all these values. The program in this case is the one that takes an input $x$, a private input $e$ and computes $y = xe + 5$. As in the toy example of the recap, the output of the program is added to the public inputs and the circuit actually asserts that the output is the claimed value. So more precisely, the prover will generate a proof for the statement `ASSERT(x*e+5==y)`, where both $x,y$ are public inputs.
 
-Let us see our API on a test circuit that provides all these values. The program in this case is the one that takes an input $x$, a private input $e$ and computes $y = xe +5$. As in the toy example of the recap, the output of the program is added to the public inputs and the circuit actually asserts that the output is the claimed value. So more precisely, the prover will generate a proof for the statement `ASSERT(x*e+5==y)`, where both $x,y$ are public inputs.
 # Usage
+
 Here is the happy path.
 
 ```rust
@@ -90,16 +93,21 @@ pub struct Witness<F: IsField> {
     pub c: Vec<FieldElement<F>>,
 }
 ```
+
 Next the commitment scheme KZG (Kate-Zaverucha-Goldberg) is instantiated.
+
 ```rust
 let srs = test_srs(common_preprocessed_input.n);
 let kzg = KZG::new(srs);
 ```
 The `setup` function performs the setup phase. It only needs the common preprocessed input and the commitment scheme.
+
 ```rust
 let verifying_key = setup(&common_preprocessed_input, &kzg);
 ```
-It outputs an instance of the struct `VerificationKey`.
+
+It outputs an instance of the struct `VerificationKey`:
+
 ```rust
 pub struct VerificationKey<G1Point> {
     pub qm_1: G1Point,
@@ -113,6 +121,7 @@ pub struct VerificationKey<G1Point> {
     pub s3_1: G1Point,
 }
 ```
+
 It stores the commitments of the eight polynomials of the common preprocessed input. The suffix `_1` means it is a commitment. It comes from the notation $[f]_1$, where $f$ is a polynomial.
 
 Then a prover is instantiated
@@ -133,6 +142,7 @@ where
     phantom: PhantomData<F>,
 }
 ```
+
 It stores an instance of a commitment scheme and a random field element generator needed for blinding polynomials.
 
 Then the public input is defined. As we mentioned in the recap, the public input contains the output of the program.
@@ -149,7 +159,9 @@ let proof = prover.prove(
     &verifying_key,
 );
 ```
+
 The output is an instance of the struct `Proof`.
+
 ```rust
 pub struct Proof<F: IsField, CS: IsCommitmentScheme<F>> {
     // Round 1.
@@ -222,6 +234,7 @@ assert!(verifier.verify(
 ```
 
 ## Padding
+
 All the matrices $Q, V, T, PI$ are padded with dummy rows so that their length is a power of two. To be able to interpolate their columns, we need a primitive root of unity $\omega$ of that order. Given the particular field used in our implementation, that means that the maximum possible size for a circuit is $2^{32}$.
 
 The entries of the dummy rows are filled in with zeroes in the $Q$, $V$ and $PI$ matrices. The $T$ matrix needs to be consistent with the $V$ matrix. Therefore it is filled with the value of the variable with index $0$.
@@ -233,6 +246,7 @@ Some other rows in the $V$ matrix have also dummy values. These are the rows cor
 The implementation pretty much follows the rounds as are described in the [protocol](./protocol.md) section. There are a few details that are worth mentioning.
 
 ## Commitment Scheme
+
 The commitment scheme we use is the [Kate-Zaverucha-Goldberg](https://www.iacr.org/archive/asiacrypt2010/6477178/6477178.pdf) scheme with the `BLS 12 381` curve and the ate pairing. It can be found in the `commitments` module of the `lambdaworks_crypto` package.
 
 The order $r$ of the cyclic subgroup is
@@ -271,12 +285,14 @@ The internal state of the hasher at the end of this exercise is `message_4 || Ha
 The underlying hasher function we use is `h=sha3`.
 
 ### Field elements
+
 The result of every challenge is a $256$-bit string, which is interpreted as an integer in big-endian order. A field element is constructed out of it by taking modulo the field order. The prime field used in this implementation has a $255$-bit order. Therefore some field elements are more probable to occur than others because they have more representatives as 256-bit integers.
 
 ### Strong Fiat-Shamir
+
 The first messages added to the transcript are all commitments of the polynomials of the common preprocessed input and the values of the public inputs. This prevents a known vulnerability called "weak Fiat-Shamir".
 Check out the following resources to learn more about it.
 
 - [What can go wrong (zkdocs)](https://www.zkdocs.com/docs/zkdocs/protocol-primitives/fiat-shamir/#what-can-go-wrong)
 - [How not to Prove Yourself: Pitfalls of the Fiat-Shamir Heuristic and Applications to Helios](https://eprint.iacr.org/2016/771.pdf)
-- [Weak Fiat-Shamir Attacks on Modern Proof Systems](https://eprint.iacr.org/2023/691)
+- [Weak Fiat-Shamir Attacks on Modern Proof Systems](https://eprint.iacr.org/2023/691)
diff --git a/docs/src/plonk/plonk.md b/docs/src/plonk/plonk.md
@@ -8,5 +8,4 @@ We have written this document with the aim of making it accessible to both novic
 
 - [Recap](./recap.md)
 - [Protocol](./protocol.md)
-- [Implementation](./implementation.md)
-
+- [Implementation](./implementation.md)