Add introduction & usage subsections and polish

- update README.md (landing)
- add introduction/folding-and-sonobe.md subsection
- add usage/decider-verify subsection

src/README.md

@@ -4,12 +4,15 @@ Experimental folding schemes library implemented in a joint effort by [0xPARC](h
 
 <img align="left" style="width:30%;min-width:250px;margin:20px;" src="imgs/sonobe.png">
 
-<br>
-<b>Sonobe</b> is a modular library to fold circuit instances in an Incremental Verifiable computation (IVC) style, which allows to generate a zkSNARK proof of the circuit foldings that can be verified in Ethereum's EVM.
-<br><br>
+<b>Sonobe</b> is a modular library to fold circuit instances in an Incremental Verifiable computation (IVC) style. It features multiple folding schemes and decider setups, allowing users to pick the scheme which best fit their needs. <b>Sonobe</b> also provides a way for developers to generate an EVM-verifiable zkSNARK proof of correct folding.
+
+Sonobe is conceived as an exploratory effort with the aim to push forward the practical side of folding schemes and advancing towards onchain (EVM) verification.
+
 <i>"The <a href="https://en.wikipedia.org/wiki/Sonobe">Sonobe module</a> is one of the many units used to build modular origami. The popularity of Sonobe modular origami models derives from the simplicity of folding the modules, the sturdy and easy assembly, and the flexibility of the system."</i>
 
-<br><br>
+
+> **Warning**: experimental code, do not use in production.<br>
+> The code has not been audited. Several optimizations are also pending. Our focus so far has been on implementing the Nova + CycleFold proving system and achieving onchain (EVM) verification.
 
 
 ## Schemes implemented

src/SUMMARY.md

@@ -1,11 +1,13 @@
 # sonobe docs
-[Introduction](README.md)
+- [Introduction](README.md)
+	- [Folding Schemes and Sonobe](folding-and-sonobe.md)
 
 - [Usage](usage/overview.md)
 	- [Frontend](usage/frontend.md)
 	- [Fold](usage/fold.md)
 	- [Decider prove](usage/decider-prove.md)
-	- [Solidity verifier](usage/solidity-verifier.md)
+	- [Decider verify](usage/decider-verify.md)
+		- [Solidity verifier](usage/solidity-verifier.md)
 	- [Modularity](usage/modularity.md)
 - [Design](design/design.md)
 	- [Nova+CycleFold circuit](design/novacyclefold-circuit.md)

src/design/design.md

@@ -3,4 +3,4 @@
 #### Notation
 We work on a cycle of curves composed by $E_1$ and $E_2$, where $E_1.F_r = E_2.F_q$ and $E_1.F_q=E_2.F_r$.
 We will use $F_r$ to refer to $E_1.F_r=E_2.F_q$, and $F_q$ to refer to $E_1.F_q=E_2.F_r$.
-The main circuit constraint field is $F_r$, and $C_{EC}$ circuit constraint field is $F_q$.
+The main circuit constraint field is $F_r$, and $C_{EC}$ circuit constraint field is $F_q$ (in some cases we use also $C^*$, both notations come from papers).

src/folding-and-sonobe.md

@@ -0,0 +1,36 @@
+# Folding schemes and Sonobe
+
+## Folding schemes overview
+
+Folding schemes are a family of SNARKs for iterative computations, allowing to prove that a function $F$ applied $n$ times to an initial input $z_0$ results in $z_n$.
+
+<img src="imgs/folding-main-idea-diagram.png" style="width:70%;" />
+
+Where $w_i$ are the external witnesses used at each iterative step.
+
+In other words, it allows to prove efficiently that $z_n = F(...~F(F(F(F(z_0, w_0), w_1), w_2), ...), w_{n-1})$.
+
+<br>
+
+The next 3 videos provide a good overview on the folding shcmes ideas:
+- In [this presentation](https://www.youtube.com/watch?v=Jj19k2AXH2k) (5 min) Abhiram Kothapalli explains the main idea of Nova folding scheme.
+- In [this presentation](https://youtu.be/IzLTpKWt-yg?t=6367) (20 min) Carlos Pérez overviews the features of folding schemes and what can be build with them.
+- In [this presentation](https://www.youtube.com/watch?v=SwonTtOQzAk) (1h) Justin Drake explains the folding schemes and Nova concepts.
+
+
+## Sonobe overview
+
+Sonobe is a folding schemes modular library to fold R1CS instances in an Incremental Verifiable computation (IVC) style. It also provides the tools required to generate a zkSNARK out of an IVC proof and to verify it on Ethereum's EVM.
+
+The development flow using Sonobe looks like:
+
+1. Define a circuit to be folded
+2. Set which folding scheme to be used (eg. Nova)
+3. Set a final decider to generate the final proof (eg. Spartan over Pasta curves)
+4. Generate the the decider verifier
+
+![](imgs/sonobe-lib-pipeline.png)
+
+The folding scheme and decider used can be swapped respectively with a few lines of code (eg. switching from a Decider that uses two Spartan proofs over a cycle of curves, to a Decider that uses a single Groth16 proof over the BN254 to be verified in an Ethereum smart contract).
+
+Complete examples can be found at [sonobe/folding-schemes/examples](https://github.com/privacy-scaling-explorations/sonobe/tree/main/folding-schemes/examples)

src/usage/decider-prove.md

@@ -38,19 +38,12 @@ let circuit = DeciderEthCircuit::<
 >::from_nova::<CubicFCircuit<Fr>>(nova.clone());
 let mut rng = rand::rngs::OsRng;
 
-let start = Instant::now();
 let (pk, vk) =
     Groth16::<Bn254>::circuit_specific_setup(circuit.clone(), &mut rng).unwrap();
-println!("Groth16 setup, {:?}", start.elapsed());
 
 // decider proof generation
 let decider_pp = (poseidon_config.clone(), g16_pk, kzg_pk);
 let proof = DECIDER::prove(decider_pp, rng, nova.clone()).unwrap();
-
-// decider proof verification
-let decider_vp = (poseidon_config, g16_vk, kzg_vk);
-let verified = DECIDER::verify(decider_vp, nova.i, nova.z_0, nova.z_i, &nova.U_i, &nova.u_i, proof).unwrap();
-assert!(verified);
 ```
 
 As mentioned above, complete examples can be found at [sonobe/folding-schemes/examples](https://github.com/privacy-scaling-explorations/sonobe/tree/main/folding-schemes/examples)

src/usage/decider-verify.md

@@ -0,0 +1,26 @@
+# Decider verify
+We can now verify the Decider proof
+
+```rust
+// this is the same that we defined for the prover
+type DECIDER = Decider<
+    Projective,
+    GVar,
+    Projective2,
+    GVar2,
+    CubicFCircuit<Fr>,
+    KZG<'static, Bn254>,
+    Pedersen<Projective2>,
+    Groth16<Bn254>,
+    NOVA,
+>;
+
+let decider_vp = (g16_vk, kzg_vk);
+let verified = DECIDER::verify(
+    decider_vp, nova.i, nova.z_0, nova.z_i, &nova.U_i, &nova.u_i, proof,
+)
+.unwrap();
+assert!(verified);
+```
+
+In the Ethereum Decider case, we can generate a Solidity smart contract that verifies the proofs onchain. More details in the [next section](solidity-verifier.md).

src/usage/overview.md

@@ -1,20 +1,6 @@
 # Usage
-
-## Folding schemes overview
-(wip)
-<!-- [introductory text here (TODO)] -->
-
-<img src="../imgs/folding-main-idea-diagram.png" style="width:70%;" />
-
-[...] [this presentation](https://youtu.be/IzLTpKWt-yg?t=6367), where [Carlos Pérez](https://twitter.com/CPerezz19) overviews the features of folding schemes and what can be build with them.
-
-
-## Sonobe overview
-<!-- TODO explain the idea of sonobe, being a modular library to use different folding schemes -->
-Suppose that the user inputs a circuit that follows the IVC structure, chooses which Folding Scheme to use (eg. Nova), and which Decider (eg. Spartan over Pasta curve).
-
-Later the user can for example change with few code changes the Folding Scheme being used (eg. switch to ProtoGalaxy) and also the Decider (eg. Groth16 over bn254), so the final proof can be verified in an Ethereum smart contract.
-
-![](../imgs/sonobe-lib-pipeline.png)
-
-Complete examples can be found at [sonobe/folding-schemes/examples](https://github.com/privacy-scaling-explorations/sonobe/tree/main/folding-schemes/examples)
+This section showcases how to use the Sonobe library to:
+- Define a circuit to be folded using the Frontend
+- Fold the circuit using one of the folding schemes
+- Generate a final Decider proof
+- Verify the Decider proof, and in Ethereum case, generate a Solidity verifier 

src/usage/solidity-verifier.md

@@ -1,6 +1,6 @@
 # Solidity verifier
 
-Having used the `DeciderEth` (see [Onchain Decider](#Onchain-Decider) section), we can now verify it in Ethereum's EVM.
+Having used the `Decider` from `decider_eth.rs`, we can now verify it in Ethereum's EVM.
 
 First we need to generate the Solidity contracts that verify the Decider proofs. Use the [solidity-verifiers-cli](cli) tool
 ```