ingonyama-zk · ImmanuelSegol · Jan 1, 2024 · Dec 29, 2023 · Dec 29, 2023 · Dec 29, 2023
diff --git a/docs/blaze/bindings.md b/docs/blaze/bindings.md
diff --git a/docs/blaze/gpu-development-guide.md b/docs/blaze/gpu-development-guide.md
diff --git a/docs/blaze/introduction.md b/docs/blaze/introduction.md
diff --git a/docs/blaze/overview.md b/docs/blaze/overview.md
diff --git a/docs/grants.md b/docs/grants.md
@@ -0,0 +1,7 @@
+# Ingonyama Grant programs
+
+Ingonyama understands the importance of supporting and fostering a vibrant community of researchers and builders to advance ZK. To encourage progress, we are not only developing in the open but also sharing resources with researchers and builders through various programs.
+
+## ICICLE for Researchers: Grants & Challenges
+
+https://www.ingonyama.com/blog/icicle-for-researchers-grants-challenges
diff --git a/docs/icicle/bindings.md b/docs/icicle/bindings.md
diff --git a/docs/icicle/generating-curves.md b/docs/icicle/generating-curves.md
diff --git a/docs/icicle/golang-bindings.md b/docs/icicle/golang-bindings.md
@@ -0,0 +1,87 @@
+# Golang bindings
+
+Golang bindings allow you to use ICICLE as a Golang library.
+
+The `curves` directory contains implementations for every supported curve. Each curve is its own package and includes all the required primitives and methods. There is no need to import all curves into your project, only the ones your project requires.
+
+`goicicle.go` contains wrappers for CUDA memory allocation methods.
+
+`templates` contains scripts to generate new packages for new curves, so if you ever want to add support for a new curve you can generate it based off these templates.
+
+## Using ICICLE Golang bindings in your project
+
+Too add ICICLE to your `go.mod` file. 
+
+```
+go get github.com/ingonyama-zk/icicle/goicicle
+```
+
+If you want to specify a specific branch
+
+```
+go get github.com/ingonyama-zk/icicle/goicicle@<branch_name>
+```
+
+For a specific commit
+
+```
+go get github.com/ingonyama-zk/icicle/goicicle@<commit_id>
+```
+
+While this will add the ICICLE library to your project you sill need to build the static library, using our [make file](https://github.com/ingonyama-zk/icicle/blob/main/goicicle/Makefile).
+
+```
+make libbn254.so
+```
+
+The current supported options are `libbn254.so`, `libbls12_381.so`, `libbls12_377.so`, `libbw6_671.so` and all to compile all curves. The resulting .so files are the compiled shared libraries for each curve.
+
+
+Once the static library has been built
+
+```
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH/<path_to_shared_libs>
+```
+
+Now you should be able to run your ICICLE program as usual.
+
+# How do the Golang bindings work?
+
+The shared libraries produced from the CUDA code compilation are used to bind Golang to ICICLE's CUDA code.
+
+1. These shared libraries (`libbn254.so`, `libbls12_381.so`, `libbls12_377.so`, `libbw6_671.so`) can be imported in your Go project to leverage the GPU accelerated functionalities provided by ICICLE.
+
+2. In your Go project, you can use `cgo` to link these shared libraries. Here's a basic example on how you can use `cgo` to link these libraries:
+
+```go
+/*
+#cgo LDFLAGS: -L/path/to/shared/libs -lbn254 -lbls12_381 -lbls12_377 -lbw6_671
+#include "icicle.h" // make sure you use the correct header file(s)
+*/
+import "C"
+
+func main() {
+    // Now you can call the C functions from the ICICLE libraries.
+    // Note that C function calls are prefixed with 'C.' in Go code.
+}
+```
+
+Replace `/path/to/shared/libs` with the actual path where the shared libraries are located on your system.
+
+## Common issues
+
+### Cannot find static library
+
+In some cases you may encounter the following error, despite exporting the correct `LD_LIBRARY_PATH`.
+
+```
+/usr/local/go/pkg/tool/linux_amd64/link: running gcc failed: exit status 1
+/usr/bin/ld: cannot find -lbn254: No such file or directory
+/usr/bin/ld: cannot find -lbn254: No such file or directory
+/usr/bin/ld: cannot find -lbn254: No such file or directory
+/usr/bin/ld: cannot find -lbn254: No such file or directory
+/usr/bin/ld: cannot find -lbn254: No such file or directory
+collect2: error: ld returned 1 exit status
+```
+
+This is normally fixed by exporting the path to the static library location in the following way: `export CGO_LDFLAGS="-L/<path_to_shared_lib>/"`
diff --git a/docs/icicle/gpu-development-guide.md b/docs/icicle/gpu-development-guide.md
diff --git a/docs/icicle/integrations.md b/docs/icicle/integrations.md
@@ -0,0 +1,55 @@
+# Integrations
+
+ICICLE has been used by companies like [Celer Network](https://github.com/celer-network), [Gnark](https://github.com/Consensys/gnark), [EZKL](https://blog.ezkl.xyz/post/acceleration/) 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.  
+
+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.
+
+## A primer to building your own integrations
+
+Lets illustrate an ICICLE integration, so you can understand the core API and design overview of ICICLE.
+
+![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. 
+
+A developer may use ICICLE with two main approaches in mind.
+
+1. Drop in replacement approach.
+2. Full GPU replacement approach.
+
+The first approach for GPU-accelerating your Prover with ICICLE is quick to implement, but it has limitations, such as reduced memory optimization and limited protocol tuning for GPUs. It's a solid starting point, but those committed to fully leveraging GPU acceleration should consider a more comprehensive approach.
+
+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
+
+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.`
+
+You must also switch to the ICICLE backend, WithIcicleAcceleration backend ProverOption:
+
+```
+// 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.
+
+
+### Halo2
+
+EZKL [Halo2](https://github.com/zkonduit/halo2) fork integrated with ICICLE for GPU acceleration. This means that you can run your existing Halo2 circuits with GPU acceleration just by activating a feature flag.
+
+To enable GPU acceleration just enable `icicle_gpu` [feature flag](https://github.com/zkonduit/halo2/blob/3d7b5e61b3052680ccb279e05bdcc21dd8a8fedf/halo2_proofs/Cargo.toml#L102).
+
+This feature flag will seamlessly toggle on GPU acceleration for you. You can have a look at [EZKL](https://github.com/zkonduit/ezkl) to see how their team utilized GPU acceleration.