added docs

Author: olesHolem

README.md

@@ -5,34 +5,10 @@ It takes the zkos proof (in json format), and returns the snark proof going thro
 
 ![diagram](diagram.svg)
 
-You can use it as a library, or as a cli tool:
 
-```
-cargo run --bin wrapper --release -- prove --input testing_data/risc_proof --output-dir tmp.json
-```
+## Docs
 
-Also you should update generated files:
-```
-cargo run --bin wrapper_generator --release
-```
-
-## CRS file
-
-For production - please make sure to use the real CRS file:
-
-https://storage.googleapis.com/matterlabs-setup-keys-us/setup-keys/setup_2^24.key
-
-The tool also offers to use the 'fake' file - that works for local testing, but must NEVER be used for production cases.
-
-## Generating verification key
-
-
-```shell
-cargo run --bin wrapper_generator --release generate-vk --input-binary ../air_compiler/examples/hashed_fibonacci/app.bin --output-dir /tmp --trusted-setup-file crs/setup.key --universal-verifier
-```
-
-This will generate the verification key (and verification key hash) - that can be put into the solidity code.
-Or you can use era-boojum-verifier-cli tool to verify the proofs manually.
+See the [docs](./docs/README.md).
 
 ## Security
 

diagram.svg

@@ -0,0 +1,6 @@
+# Documentation
+
+This directory contains documentation and descriptions of the logic and design behind this repository:
+
+- [zkos-wrapper overview](./overview.md)
+- [Running end to end](./end_to_end.md)

docs/README.md

@@ -0,0 +1,29 @@
+# Running end to end wrapper
+
+Firstly, you should get these three files:
+- base.bin - file that contains your base program in binary format
+- risc_proof.json - file that contains the proof of the last airbender circuit (use airbender cli to generate it)
+- setup.key - file that contains the trusted setup for the final Snark (see [Crs](./overview.md##Crs) section)
+
+### Running full wrapper
+
+Now you can generate the final Snark proof and VK with the following command:
+```bash
+cargo run --bin wrapper --release -- prove --input-binary {path to base.bin} --input {path to risc_proof.json} --trusted-setup-file {path to setup.key} --output-dir {output directory}
+```
+
+### Generating final Snark VK
+
+With this command you can generate the final Snark VK:
+```bash
+cargo run --bin wrapper --release -- generate-vk --input-binary {path to base.bin} --trusted-setup-file {path to setup.key} --output-dir {output directory}
+```
+
+Generated VK can be put into the solidity code.
+Or you can use era-boojum-verifier-cli tool to verify the proofs manually.
+
+### Regenerating wrapper
+If you need to regenerate the wrapper, due to changes in the last airbender recursion circuit you can use the following command:
+```bash
+cargo run --bin wrapper_generator --release
+```

docs/end_to_end.md

@@ -0,0 +1,48 @@
+# ZKOS Wrapper - Overview
+
+## Why do we need this wrapper?
+
+In airbender we can proof an arbitrary number of RiscV cycles with multiple proofs and compress them into a single proof with recursion. But when it come to L1 verification it could be expensive. So our purpose is to wrap the last airbender proof into Snark.
+We already use [Snark wrapper](https://github.com/matter-labs/zksync-crypto/tree/main/crates/snark-wrapper) to wrap boojum Stark proofs into Snark. So we only need to implement airbender -> boojum wrapper. So in the end our full wrapping pipeline will look like this:
+![diagram](../diagram.svg)
+
+**Note:** we also use `Compression` step, which is just boojum -> boojum wrapper, to make proof smaller to fit it into `SnarkWrapper`.
+
+## ZKOS Wrapper parts
+
+This repository contains the following main components:
+- [wrapper](../wrapper/) - the main part with wrapper itself
+    - [wrapper-inner-verifier](../wrapper/src/wrapper_inner_verifier/) contains the inner `verify` function used for verification last airbender proof
+    - [wrapper-utils](../wrapper/src/wrapper_utils/) contains circuit representation of airbender structs and traits used for verification
+    - [transcript](../wrapper/src/transcript/) contains blake hash (for merkle trees and transcript) and transcript (for random challenges)
+    - [circuits](../wrapper/src/circuits/) contains defined circuits for all three parts of the pipeline: `risc_wrapper`, `compression` and `snark_wrapper`
+- [wrapper-generator](../wrapper_generator/) - generates code used in the inner `verify` function
+- [circuit-mersenne-field](../circuit-mersenne-field/) - circuit representation of Mersenne field used in the wrapper
+
+## Why do we need `wrapper-generator`?
+
+Usually, verification function takes VK (verification key) as an argument to specify what exact circuit we want to verify. However, in our case we are going to hardcode all the inner airbender circuit parameters into the wrapper itself. This is done for optimization purposes. So we use `wrapper-generator` to generate two files located in [wrapper-inner-verifier/imports/](../wrapper/src/wrapper_inner_verifier/imports/) folder:
+- `circuit_layout.rs` - contains the constants specifying geometry of airbender circuit
+- `circuit_quotient.rs` - contains the quotient part of verification
+
+These two files completely define the machine of the last airbender circuit. But we also need to verify that the correct code was run during the execution. For this purpose we have `final_state_constants.rs` file that contains two constants:
+- `FINAL_RISC_CIRCUIT_END_PARAMS` - the expected commitment of the program run on the last airbender circuit
+- `FINAL_RISC_CIRCUIT_AUX_REGISTERS_VALUES` - the expected commitment of all programs run on the previous layers (base program + recursion programs)
+
+**Note:** While `circuit_layout.rs` and `circuit_quotient.rs` are always generated by `wrapper_generator` and used during wrapping, `final_state_constants.rs` are not as necessary to update, as inner constants could be generated during proving/creating vk process.
+
+## Crs
+Crs (common reference string) is a trusted setup required for the final Snark (in the inner KZG commitment). You can download it with this command:
+```
+curl https://storage.googleapis.com/matterlabs-setup-keys-us/setup-keys/setup_2\^24.key --output setup.key
+```
+The tool also offers to use the 'fake' file - that works for local testing, but must NEVER be used for production cases.
+
+## Testing
+
+You can find the main tests for running all the pipeline in the [wrapper/tests/mod.rs](../wrapper/src/tests/mod.rs). These tests will use fibonachi as a base program and take the last airbender circuit proof as an input. In the end you will get all the intermediate proofs up to the final snark proof.
+
+## Running the wrapper
+You can find instructions for running the full pipeline here: [Running end to end](./end_to_end.md).
+
+### Happy wrapping :]