Merge pull request #27 from ingonyama-zk/icicle-provers

document how to use icicle <> gnark with a circuit

.prettierignore

@@ -0,0 +1,17 @@
+.docusaurus/
+node_modules/
+yarn.lock
+.DS_Store
+
+# tex build artifacts
+.aux
+.bbl
+.bcf
+.blg
+.fdb_latexmk
+.fls
+.log
+.out
+.xml
+.gz
+.toc

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "proseWrap": "preserve",
+  "endOfLine": "lf"
+}

docs/contributor-guide.md

@@ -21,4 +21,3 @@ When opening a [pull request](https://github.com/ingonyama-zk/icicle/pulls) plea
 ## Questions?
 
 Find us on [Discord](https://discord.gg/6vYrE7waPj).
-

docs/icicle/colab-instructions.md

@@ -7,11 +7,11 @@ As Colab is able to interact with shell commands, a user can also install a fram
 
 First thing to do in a notebook is to set the runtime type to a T4 GPU.
 
-* in the upper corner click on the dropdown menu and select "change runtime type"
+- in the upper corner click on the dropdown menu and select "change runtime type"
 
 ![Change runtime](../../static/img/colab_change_runtime.png)
 
-* In the window select "T4 GPU" and press Save
+- In the window select "T4 GPU" and press Save
 
 ![T4 GPU](../../static/img/t4_gpu.png)
 
@@ -60,7 +60,7 @@ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 cmake version 3.27.9
 
 CMake suite maintained and supported by Kitware (kitware.com/cmake).
-Wed Jan 17 13:10:18 2024       
+Wed Jan 17 13:10:18 2024
 +---------------------------------------------------------------------------------------+
 | NVIDIA-SMI 535.104.05             Driver Version: 535.104.05   CUDA Version: 12.2     |
 |-----------------------------------------+----------------------+----------------------+
@@ -72,7 +72,7 @@ Wed Jan 17 13:10:18 2024
 | N/A   39C    P8               9W /  70W |      0MiB / 15360MiB |      0%      Default |
 |                                         |                      |                  N/A |
 +-----------------------------------------+----------------------+----------------------+
-                                                                                         
+
 +---------------------------------------------------------------------------------------+
 | Processes:                                                                            |
 |  GPU   GI   CI        PID   Type   Process name                            GPU Memory |

docs/icicle/integrations.md

@@ -1,8 +1,8 @@
-# Integrations
+# ICICLE integrated provers
 
 ICICLE has been used by companies like [Celer Network](https://github.com/celer-network), [Gnark](https://github.com/Consensys/gnark) and others to accelerate their ZK proving pipeline.
 
-Many of these integrations have been a collaboration between Ingonyama and the integrating company. We have learned a lot about designing GPU based ZK provers.  
+Many of these integrations have been a collaboration between Ingonyama and the integrating company. We have learned a lot about designing GPU based ZK provers.
 
 If you're interested in understanding these integrations better or learning how you can use ICICLE to accelerate your existing ZK proving pipeline this is the place for you.
 
@@ -12,7 +12,7 @@ Lets illustrate an ICICLE integration, so you can understand the core API and de
 
 ![ICICLE architecture](../../static/img/architecture-high-level.png)
 
-Engineers usually use a cryptography library to implement their ZK protocols. These libraries implement efficient primitives which are used as building blocks for the protocol; ICICLE is such a library. The difference is that ICICLE is designed from the start to run on GPUs; the Rust and Golang APIs abstract away all low level CUDA details. Our goal was to allow developers with no GPU experience to quickly get started with ICICLE. 
+Engineers usually use a cryptography library to implement their ZK protocols. These libraries implement efficient primitives which are used as building blocks for the protocol; ICICLE is such a library. The difference is that ICICLE is designed from the start to run on GPUs; the Rust and Golang APIs abstract away all low level CUDA details. Our goal was to allow developers with no GPU experience to quickly get started with ICICLE.
 
 A developer may use ICICLE with two main approaches in mind.
 
@@ -23,28 +23,70 @@ The first approach for GPU-accelerating your Prover with ICICLE is quick to impl
 
 A full GPU replacement means performing the entire ZK proof on the GPU. This approach will reduce latency to a minimum and requires you to change the way you implement the protocol to be more GPU friendly. This approach will take full advantage of GPU acceleration. Redesigning your prover this way may take more engineering effort but we promise you that its worth it!
 
-## Using ICICLE integrations
+## Using ICICLE integrated provers
 
 Here we cover how a developer can run existing circuits on ICICLE integrated provers.
 
 ### Gnark
 
 [Gnark](https://github.com/Consensys/gnark) officially supports GPU proving with ICICLE. Currently only Groth16 on curve `BN254` is supported. This means that if you are currently using Gnark to write your circuits you can enjoy GPU acceleration without making many changes.
 
-To use GPUs, add the `icicle` buildtag to your build/run commands, e.g. `go run -tags=icicle main.go.`
+:::info
 
-You must also switch to the ICICLE backend, WithIcicleAcceleration backend ProverOption:
+Currently ICICLE has been merged to Gnark [master branch](https://github.com/Consensys/gnark), however the [latest release](https://github.com/Consensys/gnark/releases/tag/v0.9.1) is from October 2023.
+
+:::
+
+Make sure your golang circuit project has `gnark` as a dependency and that you are using the master branch for now.
+
+```
+go get 	github.com/consensys/gnark@master
+```
+
+You should see two indirect dependencies added.
+
+```
+...
+	github.com/ingonyama-zk/icicle v0.1.0 // indirect
+	github.com/ingonyama-zk/iciclegnark v0.1.1 // indirect
+...
+```
+
+:::info
+As you may notice we are using ICICLE v0.1 here since golang bindings are only support in ICICLE v0.1 for the time being.
+:::
+
+To switch over to ICICLE proving, make sure to change the backend you are using, below is an example of how this should be done.
 
 ```
 // toggle on
 proofIci, err := groth16.Prove(ccs, pk, secretWitness, backend.WithIcicleAcceleration())
-    
+
 // toggle off
 proof, err := groth16.Prove(ccs, pk, secretWitness)
 ```
 
-You can reference the [Gnark docs](https://github.com/Consensys/gnark?tab=readme-ov-file#gpu-support) for further information.
+Now that you have enabled `WithIcicleAcceleration` backend simple change the way your run your circuits to:
+
+```
+go run -tags=icicle main.go
+```
+
+Your logs should look something like this if everything went as expected.
 
+```
+13:12:05 INF compiling circuit
+13:12:05 INF parsed circuit inputs nbPublic=1 nbSecret=1
+13:12:05 INF building constraint builder nbConstraints=3
+13:12:05 DBG precomputing proving key in GPU acceleration=icicle backend=groth16 curve=bn254 nbConstraints=3
+13:12:05 DBG constraint system solver done nbConstraints=3 took=0.070259
+13:12:05 DBG prover done acceleration=icicle backend=groth16 curve=bn254 nbConstraints=3 took=80.356684
+13:12:05 DBG verifier done backend=groth16 curve=bn254 took=1.843888
+```
+
+`acceleration=icicle` indicates that the prover is running in acceleration mode with ICICLE.
+
+You can reference the [Gnark docs](https://github.com/Consensys/gnark?tab=readme-ov-file#gpu-support) for further information.
 
 ### Halo2
 

docs/icicle/rust-bindings.md

@@ -25,12 +25,10 @@ If you wish to point to a specific ICICLE branch add `branch = "<name_of_branch>
 
 When you build your project ICICLE will be built as part of the build command.
 
-
 # How do the rust bindings work?
 
 The rust bindings are just rust wrappers for ICICLE Core static libraries which can be compiled. We integrate the compilation of the static libraries into rusts toolchain to make usage seamless and easy. This is achieved by [extending rusts build command](https://github.com/ingonyama-zk/icicle/blob/main/wrappers/rust/icicle-curves/icicle-bn254/build.rs).
 
-
 ```rust
 use cmake::Config;
 use std::env::var;

docs/icicle/supporting-additional-curves.md

@@ -6,7 +6,6 @@ Supporting additional curves is still a work in progress and is bound to change
 
 :::
 
-
 We understand the need for ZK developers to use different curves, some common some more exotic. For this reason we designed ICICLE to allow developers to add any curve they desire.
 
 ## ICICLE Core
@@ -45,21 +44,23 @@ In order to support a new curves in the binding libraries you first must support
 
 Create a new folder named `icicle-<curve_name>` under the [rust wrappers folder](https://github.com/ingonyama-zk/icicle/tree/main/wrappers/rust/icicle-curves). Your new directory should look like this.
 
-
-* icicle-<curve_name>/
-  * src/
-    * ntt/
-        * mod.rs
-    * msm/
-        * mod.rs
-    * curve.rs
-    * lib.rs
-  * Cargo.toml
-  * build.rs
+```
+└── rust
+    ├── icicle-curves
+        ├── icicle-<curve_name>
+    │   │   ├── Cargo.toml
+    │   │   ├── build.rs
+    │   │   └── src/
+    │   │       ├── curve.rs
+    │   │       ├── lib.rs
+    │   │       ├── msm/
+    │   │       │   └── mod.rs
+    │   │       └── ntt/
+    │   │           └── mod.rs
+```
 
 Lets look at [`ntt/mod.rs`](https://github.com/ingonyama-zk/icicle/blob/main/wrappers/rust/icicle-curves/icicle-bn254/src/ntt/mod.rs) for example.
 
-
 ```
 ...
 

docs/introduction.md

@@ -1,16 +1,17 @@
 ---
 slug: /
 displayed_sidebar: GettingStartedSidebar
-title: ""
+title: ''
 ---
+
 # Welcome to Ingonyama's Developer Documentation
 
 Ingonyama is a next-generation semiconductor company, focusing on Zero-Knowledge Proof hardware acceleration. We build accelerators for advanced cryptography, unlocking real-time applications. Our focus is on democratizing access to compute intensive cryptography and making it accessible for developers to build on top of.
 
 Currently our flagship products are:
 
 - **ICICLE**:
-[ICICLE](https://github.com/ingonyama-zk/icicle) is a fully featured GPU accelerated cryptography library for building ZK provers. ICICLE allows you to accelerate your ZK existing protocols in a matter of hours or implement your protocol from scratch on GPU.
+  [ICICLE](https://github.com/ingonyama-zk/icicle) is a fully featured GPU accelerated cryptography library for building ZK provers. ICICLE allows you to accelerate your ZK existing protocols in a matter of hours or implement your protocol from scratch on GPU.
 
 ---
 

package.json

@@ -13,7 +13,8 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "dev": "docusaurus start"
+    "dev": "docusaurus start",
+    "format": "prettier --write '**/*.md'"
   },
   "dependencies": {
     "@docusaurus/core": "2.0.0-beta.18",
@@ -40,5 +41,8 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "devDependencies": {
+    "prettier": "^3.2.4"
   }
 }

sidebars.js

@@ -21,7 +21,7 @@ module.exports = {
         },
         {
           type: "doc",
-          label: "Official Integrations",
+          label: "ICICLE Provers",
           id: "icicle/integrations"
         },
         {