Docs/lib usability

docs/co-circom-cli/co-circom.md → docs/co-circom/cli/cli.md

@@ -1,6 +1,10 @@
-# co-circom CLI
+# coCircom Command-Line Interface
 
-```txt
+This section expands on using the coCircom CLI to perform witness extension and proof generation in MPC including preparation steps thereof. As mentioned earlier, coCircom is best used alongside circom and snarkjs for generating intermediate artifacts.
+
+The [interactive workshop at ZK12](https://www.youtube.com/watch?v=w2HJxrDE01k) demonstrates the usage and workflow of the coCircom CLI (some background in the beginning, using the coCircom CLI starts around [28:58](https://youtu.be/w2HJxrDE01k?si=QcHRR-V8tXX6FPmw&t=1738)), as well as the coNoir CLI later on in the video.
+
+```text
 Usage: co-circom <COMMAND>
 
 Commands:
@@ -17,3 +21,5 @@ Options:
   -h, --help     Print help
   -V, --version  Print version
 ```
+
+The subsections go into detail for each of `co-circom`'s commands.

docs/co-circom-cli/generate-proof.md → docs/co-circom/cli/generate-proof.md

@@ -8,12 +8,11 @@ The aim of the `generate-proof` command is to run proof generation in MPC using
 co-circom generate-proof --witness test_vectors/poseidon/witness.wtns.0.shared --zkey test_vectors/poseidon/poseidon.zkey --protocol REP3 --config configs/party1.toml --out proof.json --public-input public_input.json
 ```
 
-The above command takes a witness share `test_vectors/poseidon/witness.wtns.0.shared`, a traditional circom `.zkey` file and a [networking config](./config.md) and produces a circom-compatible proof `proof.json`, with a circom-compatible public input file `public_input.json`.
+The above command takes a witness share `test_vectors/poseidon/witness.wtns.0.shared`, a traditional circom `.zkey` file and a [networking config](../../network-config.md) and produces a circom-compatible proof `proof.json`, with a circom-compatible public input file `public_input.json`.
 
 ## Reference
 
 ```txt
-$ co-circom generate-proof --help
 Evaluates the prover algorithm for the specified circuit and witness share in MPC
 
 Usage: co-circom generate-proof [OPTIONS] <PROOF_SYSTEM>
@@ -25,6 +24,7 @@ Options:
       --config <CONFIG>              The path to the config file
       --witness <WITNESS>            The path to the witness share file
       --zkey <ZKEY>                  The path to the proving key (.zkey) file, generated by snarkjs setup phase
+      --check-zkey                   Perform checks on the zkey elements (can take a long time)
       --protocol <PROTOCOL>          The MPC protocol to be used [possible values: REP3, SHAMIR]
       --curve <CURVE>                The pairing friendly curve to be used [possible values: BN254, BLS12-381]
       --out <OUT>                    The output file where the final proof is written to. If not passed, this party will not write the proof to a file

docs/co-circom/cli/generate-witness.md

@@ -0,0 +1,29 @@
+# generate-witness
+
+The aim of the `generate-witness` command is to generate a secret-shared witness file in MPC using secret shares of the input.
+
+## Example
+
+```bash
+co-circom generate-witness --input test_vectors/poseidon/input.json.0.shared --circuit test_vectors/poseidon/circuit.circom --protocol REP3 --curve BN254 --config configs/party1.toml --out test_vectors/poseidon/witness.wtns.0.shared --config test_vectors/poseidon/config.toml
+```
+
+The above command takes a shared input file `input.json.0.shared` for the circuit `circuit.circom` with the [network config](../../network-config.md) and outputs the witness share to `test_vectors/poseidon/witness.wtns.0.shared`.
+
+## Reference
+
+```txt
+Evaluates the extended witness generation for the specified circuit and input share in MPC
+
+Usage: co-circom generate-witness [OPTIONS]
+
+Options:
+      --config <CONFIG>          The path to the config file
+      --input <INPUT>            The path to the input share file
+      --circuit <CIRCUIT>        The path to the circuit file
+      --protocol <PROTOCOL>      The MPC protocol to be used [possible values: REP3, SHAMIR]
+      --curve <CURVE>            The pairing friendly curve to be used [possible values: BN254, BLS12-381]
+      --out <OUT>                The output file where the final witness share is written to
+  -O <SIMPLIFICATION_LEVEL>      The simplification level passed to the circom compiler (0-2) [default: 1]
+  -h, --help                     Print help (see more with '--help')
+```

docs/co-circom-cli/merge-input-shares.md → docs/co-circom/cli/merge-input-shares.md

@@ -15,7 +15,6 @@ The above command takes the two input shares `input0.json.0.shared` and `input1.
 ## Reference
 
 ```txt
-co-circom merge-input-shares --help
 Merge multiple shared inputs received from multiple parties into a single one
 
 Usage: co-circom merge-input-shares [OPTIONS]

docs/co-circom-cli/split-input.md → docs/co-circom/cli/split-input.md

@@ -15,17 +15,16 @@ These shares can be handed to the 3 different MPC parties for the witness genera
 ## Reference
 
 ```txt
-$ co-circom split-input --help
 Splits a JSON input file into secret shares for use in MPC
 
 Usage: co-circom split-input [OPTIONS]
 
 Options:
-      --config <CONFIG>              The path to the config file
-      --input <INPUT>                The path to the input JSON file
-      --circuit <CIRCUIT>            The path to the circuit file
-      --protocol <PROTOCOL>          The MPC protocol to be used [possible values: REP3, SHAMIR]
-      --curve <CURVE>                The pairing friendly curve to be used [possible values: BN254, BLS12-381]
-      --out-dir <OUT_DIR>            The path to the (existing) output directory
-  -h, --help                         Print help (see more with '--help')
+      --config <CONFIG>      The path to the config file
+      --input <INPUT>        The path to the input JSON file
+      --circuit <CIRCUIT>    The path to the circuit file
+      --protocol <PROTOCOL>  The MPC protocol to be used [possible values: REP3, SHAMIR]
+      --curve <CURVE>        The pairing friendly curve to be used [possible values: BN254, BLS12-381]
+      --out-dir <OUT_DIR>    The path to the (existing) output directory
+  -h, --help                 Print help (see more with '--help')
 ```

docs/co-circom-cli/split-witness.md → docs/co-circom/cli/split-witness.md

@@ -15,15 +15,14 @@ These shares can be handed to the 3 different MPC parties for the proof generati
 ## Reference
 
 ```txt
-$ co-circom split-witness --help
 Splits an existing witness file generated by circom into secret shares for use in MPC
 
 Usage: co-circom split-witness [OPTIONS]
 
 Options:
       --config <CONFIG>            The path to the config file
-      --witness <WITNESS>          The path to the input witness file generated by circom
-      --r1cs <R1CS>                The path to the r1cs file, generated by circom compiler
+      --witness <WITNESS>          The path to the input witness file generated by Circom
+      --r1cs <R1CS>                The path to the r1cs file, generated by Circom compiler
       --protocol <PROTOCOL>        The MPC protocol to be used [possible values: REP3, SHAMIR]
       --curve <CURVE>              The pairing friendly curve to be used [possible values: BN254, BLS12-381]
       --out-dir <OUT_DIR>          The path to the (existing) output directory

docs/co-circom-cli/translate-witness.md → docs/co-circom/cli/translate-witness.md

@@ -8,12 +8,11 @@ The aim of the `translate-witness` command is to take a witness file `witness.wt
 co-circom translate-witness --witness test_vectors/poseidon/witness.wtns --src-protocol REP3 --target-protocol SHAMIR --curve BN254 --config configs/party1.toml --out test_vectors/poseidon/shamir_witness.wtns
 ```
 
-The above command takes the witness file `test_vectors/poseidon/witness.wtns` which was generated with the source MPC protocol `REP3` and translates it to the witness file `test_vectors/poseidon/shamir_witness.wtns` which is suitable for the target MPC protocol `SHAMIR`. The translation process requires network interaction, thus a [networking config](./config.md) is required as well.
+The above command takes the witness file `test_vectors/poseidon/witness.wtns` which was generated with the source MPC protocol `REP3` and translates it to the witness file `test_vectors/poseidon/shamir_witness.wtns` which is suitable for the target MPC protocol `SHAMIR`. The translation process requires network interaction, thus a [networking config](../../network-config.md) is required as well.
 
 ## Reference
 
 ```txt
-$ co-circom translate-witness --help
 Translates the witness generated with one MPC protocol to a witness for a different one
 
 Usage: co-circom translate-witness [OPTIONS]

docs/co-circom/co-circom.md

@@ -0,0 +1,7 @@
+# coCircom
+
+coCircom enables us perform [circom](../resources/circom)'s witness extension and proof generation with MPC. circom and coCircom and their artifacts may be used interchangeably, e.g. a proof generated by coCircom verifies using circom and vice-versa. coCircom also relies on artifacts generated by circom, e.g. the R1CS file, the zkey, and the vkey.
+
+To get started with the coCircom workflow, we require some circuit alongside an input. Based on these files we can create a proof according the workflow depicted below. For more details the Circom setup have a look at the circom docs [extending the witness](https://docs.circom.io/getting-started/computing-the-witness/) and [generating a proof](https://docs.circom.io/getting-started/proving-circuits/). 
+
+<img src={require("./figures/co-circom-workflow.png").default} alt="overview drawing"/>

docs/co-circom/lib/example.md

@@ -0,0 +1,41 @@
+# Example
+
+The following is a incomplete example of how to use the `co-circom` lib crate.
+For complete and working example see [here](https://github.com/TaceoLabs/co-snarks/tree/main/co-circom/co-circom/examples).
+
+```rust
+// connect to network
+let network_config = NetworkConfig::new(/* ... */);
+let mut net = Rep3MpcNet::new(network_config)?;
+
+// parse circuit file & put through our compiler
+let circuit =
+    CoCircomCompiler::<Bn254>::parse(dir.join("circuit.circom"), CompilerConfig::default())?;
+
+// split inputs
+let mut input = Input::new();
+input.insert("a".to_string(), Value::String("2".to_string()));
+input.insert("b".to_string(), Value::String("3".to_string()));
+let [share0, share1, share2] = co_circom::split_input::<Bn254>(input, circuit.public_inputs())?;
+
+// parse zkey, without performing extra checks (only advised for zkeys knwon to be valid)
+let zkey = Arc::new(Groth16ZKey::<Bn254>::from_reader(
+    std::fs::read(dir.join("multiplier2.zkey"))?.as_slice(),
+    CheckElement::No,
+)?);
+
+// generate witness
+let (witness, net) =
+    co_circom::generate_witness_rep3::<Bn254>(circuit, share0, net, VMConfig::default())?;
+let public_inputs = witness.public_inputs_for_verify();
+
+// generate proof
+let (proof, _) = Rep3CoGroth16::prove(net, zkey, witness)?;
+
+// verify proof
+let vk = Groth16JsonVerificationKey::<Bn254>::from_reader(
+    std::fs::read(dir.join("verification_key.json"))?.as_slice(),
+)?;
+Groth16::verify(&vk, &proof, &public_inputs)?;
+```
+

docs/co-circom/lib/lib.md

@@ -0,0 +1,7 @@
+# coCircom Rust Library
+
+The coCircom Rust library provides the same set of features as the [CLI](../cli/cli.md) variant of coCircom, where the [CLI](../cli/cli.md) essentially exposes the library functions to the user on the command line.
+
+The library is meant to support you in developing your own application that makes use of coCircom's functionality. The next pages will guide you through setting up and including coCircom in your project.
+
+To view the more detailed docs, clone the repo and run `cargo doc --open --no-deps -p co-circom` to generate the rustdoc.