diff --git a/docs/blaze/bindings.md b/docs/blaze/bindings.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/blaze/gpu-development-guide.md b/docs/blaze/gpu-development-guide.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/blaze/introduction.md b/docs/blaze/introduction.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/blaze/overview.md b/docs/blaze/overview.md deleted file mode 100644 index 92d1099..0000000 --- a/docs/blaze/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Blaze Overview - -WIP diff --git a/docs/grants.md b/docs/grants.md new file mode 100644 index 0000000..ee74c2c --- /dev/null +++ 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 deleted file mode 100644 index e69de29..0000000 diff --git a/docs/icicle/generating-curves.md b/docs/icicle/generating-curves.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/icicle/golang-bindings.md b/docs/icicle/golang-bindings.md new file mode 100644 index 0000000..c19a929 --- /dev/null +++ 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@ +``` + +For a specific commit + +``` +go get github.com/ingonyama-zk/icicle/goicicle@ +``` + +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 static libraries for each curve. + + +Once the static library has been built + +``` +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH/ +``` + +Now you should be able to run your ICICLE program as usual. + +# How do the Golang bindings work? + +The static libraries produced from the CUDA code compilation are used to bind Golang to ICICLE's CUDA code. + +1. These static 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 static 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 static 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//"` diff --git a/docs/icicle/gpu-development-guide.md b/docs/icicle/gpu-development-guide.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/icicle/integrations.md b/docs/icicle/integrations.md new file mode 100644 index 0000000..abacdde --- /dev/null +++ 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. diff --git a/docs/icicle/introduction.md b/docs/icicle/introduction.md index d1cd071..daa7e07 100644 --- a/docs/icicle/introduction.md +++ b/docs/icicle/introduction.md @@ -1,8 +1,16 @@ # Getting started with ICICLE +This guide is oriented towards developers who want to start writing code with the ICICLE libraries. If you just want to run your existing ZK circuits on GPU refer to [this guide](./integrations.md#using-icicle-integrations) please. + ## ICICLE repository overview -The ICICLE repository has three main sections, each section is independent from the other. +![ICICLE API overview](../../static/img/apilevels.png) + +The diagram above displays the general architecture of ICICLE and the API layers that exist. The CUDA API, which we also call ICICLE Core, is the lowest level and is comprised of CUDA kernels which implement all primitives such as MSM as well as C++ wrappers which expose these methods for different curves. + +ICICLE Core compiles into a static library. This library can be used with our official Golang and Rust wrappers or you can implement a wrapper for it in any language. + +Based on this dependency architecture, the ICICLE repository has three main sections, each of which is independent from the other. - ICICLE core - ICICLE Rust bindings @@ -12,14 +20,14 @@ The ICICLE repository has three main sections, each section is independent from [ICICLE core](https://github.com/ingonyama-zk/icicle/tree/main/icicle) contains all the low level CUDA code implementing primitives such as [points](https://github.com/ingonyama-zk/icicle/tree/main/icicle/primitives) and [MSM](https://github.com/ingonyama-zk/icicle/tree/main/icicle/appUtils/msm). There also exists higher level C++ wrappers to expose the low level CUDA primitives ([example](https://github.com/ingonyama-zk/icicle/blob/main/icicle/curves/bn254/msm.cu)). -ICICLE Core would typically be compiled into a shared library and used in a third party language such as Rust, Golang or Python. +ICICLE Core would typically be compiled into a static library and used in a third party language such as Rust, Golang or Python. ### ICICLE Rust and Golang bindings -- [ICICLE Rust bindings](https://github.com/ingonyama-zk/icicle/tree/main/src) +- [ICICLE Rust bindings](https://github.com/ingonyama-zk/icicle/tree/main/wrappers/rust) - [ICICLE Golang bindings](https://github.com/ingonyama-zk/icicle/tree/main/goicicle) -These are autogenerated bindings which allow you to easily use ICICLE in a Rust or Golang project. Setting up Golang bindings requires a bit of extra steps compared to the Rust bindings which utilize the `cargo build` tool. +These bindings allow you to easily use ICICLE in a Rust or Golang project. Setting up Golang bindings requires a bit of extra steps compared to the Rust bindings which utilize the `cargo build` tool. ## Running ICICLE @@ -34,12 +42,17 @@ This guide assumes that you have a Linux or Windows machine with a Nvidia GPU in - Any Nvidia GPU - Linux or Windows operating system. +#### Optional Prerequisites -If you don't wish to install these prerequisites you can follow this tutorial from within our [ZK-Container](https://github.com/ingonyama-zk/icicle/blob/main/Dockerfile) (docker container). To learn more about using ZK-Containers read this. +- Docker, latest version. +- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html) + + +If you don't wish to install these prerequisites you can follow this tutorial using a [ZK-Container](https://github.com/ingonyama-zk/icicle/blob/main/Dockerfile) (docker container). To learn more about using ZK-Containers [read this](../zk-containers.md). ### Setting up ICICLE and running tests -The objective of this chapter is to make sure you can run the ICICLE Rust and Golang tests, achieving this will make sure you know how to setup ICICLE and run a ICICLE program. For the sake of simplicity we will be using the ICICLE docker container as our environment, you of course may install the prerequisites on your machine and follow the same commands in your terminal. +The objective of this guide is to make sure you can run the ICICLE Core, Rust and Golang tests. Achieving this will ensure you know how to setup ICICLE and run a ICICLE program. For simplicity, we will be using the ICICLE docker container as our environment, however, you may install the prerequisites on your machine and follow the same commands in your terminal. #### Setting up our environment @@ -69,7 +82,217 @@ If you accidentally close your terminal and want to reconnect just call: docker exec -it icicle_container bash ``` +Lets make sure that we have the correct CUDA version before proceeding + +``` +nvcc --version +``` + +You should see something like this + +``` +nvcc: NVIDIA (R) Cuda compiler driver +Copyright (c) 2005-2023 NVIDIA Corporation +Built on Tue_Aug_15_22:02:13_PDT_2023 +Cuda compilation tools, release 12.2, V12.2.140 +Build cuda_12.2.r12.2/compiler.33191640_0 +``` + +Make sure the release version is at least 12.0. #### ICICLE Core + +ICICLE Core is found under [`/icicle`](https://github.com/ingonyama-zk/icicle/tree/main/icicle). To build and run the tests first: + +``` +cd icicle +``` + +We are going to compile ICICLE for a specific curve + +``` +mkdir -p build +cmake -S . -B build -DCURVE=bn254 -DBUILD_TESTS=ON +cmake --build build +``` + +`-DBUILD_TESTS=ON` compiles the tests, without this flag `ctest` wont work. +`-DCURVE=bn254` tells the compiler which curve to build. You can find a list of supported curves [here](https://github.com/ingonyama-zk/icicle/tree/main/icicle/curves). + +The output in `build` folder should include the static libraries for the compiled curve. + + +:::info +Make sure to only use `-DBUILD_TESTS=ON` for running test as the archive output will only be available when `-DBUILD_TESTS=ON` is not supplied. +::: + +To run the test + +``` +cd build +ctest +``` + #### ICICLE Rust -#### ICICLE Golang \ No newline at end of file + +The rust bindings work by first compiling the CUDA static libraries as seen [here](https://github.com/ingonyama-zk/icicle/blob/main/wrappers/rust/icicle-curves/icicle-bn254/build.rs). The compilation of CUDA and the Rust library is all handled by the rust build toolchain. + +Similar to ICICLE Core here we also have to compile per curve. + +Lets compile curve `bn254` + +``` +cd wrappers/rust/icicle-curves/icicle-bn254 +``` + +Now lets build our library + +``` +cargo build --release +``` + +This may take a couple of minutes since we are compiling both the CUDA and Rust code. + +To run the tests + +``` +cargo test -- --test-threads=1 +``` + +`--test-threads=1` is needed because currently some tests might interfere with one another inside the GPU. + +We also include some benchmarks + +``` +cargo bench +``` + +#### ICICLE Golang + +The Golang bindings are a bit more of a manual process. We start by compiling a static library for a curve we want to use in this case `bn254`. + +``` +cd goicicle +``` + +Now lets build our static library + +``` +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 static libraries for each curve. + +`make clean` will remove compiled static libraries. + +Before using the static libraries we need to make our OS aware of them + +``` +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH/ +``` + +:::tip + +On some systems, despite exporting `LD_LIBRARY_PATH`, the system still won't be able to locate our static libraries. In this case, try the following steps. + +``` +export CGO_LDFLAGS="-L//" +``` +::: + +To run test for a specific curve + +``` +go test ./goicicle/curves/bn254 -count=1 +``` + +### Running ICICLE examples + +ICICLE examples can be found [here](https://github.com/ingonyama-zk/icicle-examples) these examples cover some simple use cases using C++, rust and golang. + +In each example directory, ZK-container files are located in a subdirectory `.devcontainer`. + +* example-name/ + * .devcontainer/ + * Dockerfile + * devcontainer.json + + +Lets run one of our C++ examples, in this case the [MSM example](https://github.com/ingonyama-zk/icicle-examples/blob/main/c%2B%2B/msm/example.cu). + +Clone the repository + +``` +git clone https://github.com/ingonyama-zk/icicle-examples.git +cd icicle-examples +``` + +Enter the test directory + +``` +cd c++/msm +``` + +Now lets build our docker file and run the test inside it. Make sure you have installed the [optional prerequisites](#optional-prerequisites). + +``` +docker build -t icicle-example-msm -f .devcontainer/Dockerfile . +``` + +Lets start and enter the container + +``` +docker run -it --rm --gpus all -v .:/icicle-example icicle-example-msm +``` + +to run the example + +``` +rm -rf build +mkdir -p build +cmake -S . -B build +cmake --build build +./build/example +``` + +You can now experiment with our other examples, perhaps try to run a rust or golang example next. + +## Writing new bindings for ICICLE + +Since ICICLE Core is written in CUDA / C++ its really simple to generate static libraries. These static libraries can be installed on any system and called by higher level languages such as Golang or Python. + +static libraries can be loaded into memory once and used by multiple programs, reducing memory usage and potentially improving performance. They also allow you to separate functionality into distinct modules so your static library may need to compile only specific features that you want to use. + +Lets review the Golang bindings since its a pretty verbose example (compared to rust which hides it pretty well) of using static libraries. Golang has a library named `CGO` which can be used to link static 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. + + out := (*C.BN254_projective_t)(unsafe.Pointer(p)) + in := (*C.BN254_affine_t)(unsafe.Pointer(affine)) + + C.projective_from_affine_bn254(out, in) +} +``` + +The comments on the first line tell `CGO` which libraries to import as well as which header files to include. You can then call methods which are part of the static library and defined in the header file, `C.projective_from_affine_bn254` is an example. + +If you wish to create your own bindings for a language of your choice we suggest you start by investigating how you can call static libraries. + +### ICICLE Adapters + +One of the core ideas behind ICICLE is that developers can gradually accelerate their provers. Many protocols are written using other cryptographic libraries and completely replacing them may be complex and time consuming. + +Therefore we offer adapters for various popular libraries, these adapters allow us to convert points and scalars between different formats defined by various libraries. Here is a list: + +Golang adapters: +- [Gnark crypto adapter](https://github.com/ingonyama-zk/iciclegnark) diff --git a/docs/icicle/overview.md b/docs/icicle/overview.md index 64d68d0..0267dbc 100644 --- a/docs/icicle/overview.md +++ b/docs/icicle/overview.md @@ -1,41 +1,50 @@ -# ICICLE Overview +# What is ICICLE? -ICICLE is a GPU Library for cryptographic acceleration, currently focused primarily on Zero Knowledge Proof acceleration. ICICLE offers developers GPU accelerated cryptographic primitives such as EC operations, MSM, NTT, and Poseidon hash. +ICICLE is a cryptography library for ZK using GPUs. ICICLE implements blazing fast cryptographic primitives such as EC operations, MSM, NTT, Poseidon hash and more on GPU. -ICICLE allows developers with minimal GPU experience to effortlessly accelerate there ZK application, from our experiments even the most naive implementation may yield 10X improvement in proving times. +ICICLE allows developers with minimal GPU experience to effortlessly accelerate there ZK application; from our experiments, even the most naive implementation may yield 10X improvement in proving times. +ICICLE has been used by many leading ZK companies such as [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. -![ICICLE API overview](../../static/img/iciclestructure.png) +Dont have a GPU? [read this](#dont-have-access-to-a-gpu) +## How can you use ICICLE? -The diagram above displays the general architecture of ICICLE and the API layers that exists. At the lowest level we have CUDA kernels which implement all primitives such as MSM for example. Our C++ wrapper is compiled into a shared library this library can be used with our official Golang and Rust wrappers or you can implement a wrapper for it in any language of your desire. +ICICLE can be used in the same way you would use any other cryptography library. However, over the past couple of months developing and integrating ICICLE into many systems we found a couple use case catagories. +### ICICLE for circuit developers -To get started with ICICLE quickly follow this guide, getting started with ICICLE. If you want to learn more about CUDA or GPUs please refer to our GPU development guide. +If you are a circuit developer and are experiencing bottlenecks while running your circuits, an ICICLE integrated prover may be the solution. -## Why are we excited about GPUs? +ICICLE has been integrated into a number of popular ZK provers including [Gnark prover](https://github.com/Consensys/gnark) and [Halo2](https://github.com/zkonduit/halo2). This means that you can enjoy GPU acceleration for your existing circuits immediately without writing a single line of code by simply switching on the GPU prover flag! -- GPUs are a perfect match for ZK compute - around 97% of ZK protocol runtime is parallel by nature. -- GPUs are simple for developers to use and scale compared to other hardware platforms. -- GPUs are extremely competitive in terms of power / performance and price (3x cheaper). -- GPUs are popular and readily available. +### Integrating into existing ZK provers -For a more in-depth understanding on this topic we suggest you read [our article on the subject](https://www.ingonyama.com/blog/revisiting-paradigm-hardware-acceleration-for-zero-knowledge-proofs). +From our collaboration with [EZKL](https://blog.ezkl.xyz/post/acceleration/) we have learned that its possible to accelerate a specific part of your prover to solve for a specific bottleneck. -## ICICLE integration overview +ICICLE can be used to accelerate specific parts of your prover without completely rewriting your ZK prover. -Lets illustrate an ICICLE integration, so you can understand the core API and design overview of ICICLE. +### Developing your own ZK provers +If you are planning on developing your ZK prover from scratch ICICLE can be used to develop an extremely optimized and scalable ZK prover. One of the advantages GPUs provide is scaling your ZK prover across many machines in a data center. -![ICICLE architecture](../../static/img/architecture-highlight.png) +### Developing proof of concepts -Engineers usually use a cryptography library such as Arkworks 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 quickly get started with ICICLE. +ICICLE is also ideal for developing small prototypes. ICICLE has Golang and Rust bindings so you can easily develop a library implementing a specific primitive using ICICLE. An example would be develop a KZG commitment library using ICICLE. -A developer may use ICICLE with two main approaches in mind. -1. Drop in replacement approach. -2. Full GPU replacement approach. +## Dont have access to a GPU? -The first approach is best suited for teams aiming to quickly implement a GPU version of their Prover. This method predominantly involves substituting the core methods with ICICLE's methods. While this approach can yield significant performance gains it has many draw backs, implementing memory optimizations is limited and optimizing the protocol itself to be more suited for GPU is also limited. This approach is a great way to begin using ICICLE, however for someone who is looking to seriously adopt GPU acceleration we would recommend a more rigorous approach. +We understand that not all developers have access to a GPU and we don't want this to limit anyone from developing with ICICLE. Here are some ways we can help you gain access to GPUs. -A complete GPU replacement means preforming 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! +#### Grants + +At Ingonyama we are interested in accelerating the progress of ZK and cryptography. If are an engineer, developer or an academic researcher we invite you to checkout [our grant program](https://www.ingonyama.com/blog/icicle-for-researchers-grants-challenges). We will give you access to GPUs and even pay you to do your dream research! + +#### Google Colab + +This is a great way to get started with ICICLE instantly. Google Colab offers free GPU access the down side being that the GPU doesn't have a lot of RAM but it should be enough for experimenting and even prototyping with ICICLE. + +For an extensive guide on how to setup Google Colab with ICICLE refer to [this article](https://github.com/gkigiermo/rust-cuda-colab). + +If none of these options are appropriate for you reach out to us on [telegram](https://t.me/RealElan) we will do our best to help you. diff --git a/docs/icicle/rust-bindings.md b/docs/icicle/rust-bindings.md new file mode 100644 index 0000000..07352f6 --- /dev/null +++ b/docs/icicle/rust-bindings.md @@ -0,0 +1,56 @@ +# Rust bindings + +Rust bindings allow you to use ICICLE as a rust library. + +`icicle-core` defines all interfaces, macros and common methods. + +`icicle-cuda-runtime` defines DeviceContext which can be used to manage a specific GPU as well as wrapping common CUDA methods. + +`icicle-curves` implements all interfaces and macros from icicle-core for each curve. For example icicle-bn254 implements curve bn254. Each curve has its own build script which will build the CUDA libraries for that curve as part of the rust-toolchain build. + +## Using ICICLE Rust bindings in your project + +Simply add the following to your `Cargo.toml`. + +``` +# GPU Icicle integration +icicle = { git = "https://github.com/ingonyama-zk/icicle.git" } +``` + +If you wish to point to a specific ICICLE branch add `branch = ""` to the ICICLE dependency. +For a specific commit add `rev = ""`. + +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; + +fn main() { + println!("cargo:rerun-if-env-changed=CXXFLAGS"); + println!("cargo:rerun-if-changed=../../../../icicle"); + + let cargo_dir = var("CARGO_MANIFEST_DIR").unwrap(); + let profile = var("PROFILE").unwrap(); + + let out_dir = Config::new("../../../../icicle") + .define("BUILD_TESTS", "OFF") //TODO: feature + .define("CURVE", "bn254") + .define("CMAKE_BUILD_TYPE", "Release") + .build_target("icicle") + .build(); + + println!("cargo:rustc-link-search={}/build", out_dir.display()); + + println!("cargo:rustc-link-lib=ingo_bn254"); + println!("cargo:rustc-link-lib=stdc++"); + // println!("cargo:rustc-link-search=native=/usr/local/cuda/lib64"); + println!("cargo:rustc-link-lib=cudart"); +} +``` diff --git a/docs/icicle/supporting-additional-curves.md b/docs/icicle/supporting-additional-curves.md new file mode 100644 index 0000000..9989e2b --- /dev/null +++ b/docs/icicle/supporting-additional-curves.md @@ -0,0 +1,90 @@ +# Supporting Additional Curves + +:::note + +Supporting additional curves is still a work in progress and is bound to change in the future. Currently, the process is very manual but plan to automate the majority of it in future releases. + +::: + + +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 + +ICICLE core is very generic by design so all algorithms and primitives are designed to work based of configuration files [selected during compile](https://github.com/ingonyama-zk/icicle/blob/main/icicle/curves/curve_config.cuh) time. This is why we compile ICICLE Core per curve. + +To add support a new curve you must create a new file under [`icicle/curves`](https://github.com/ingonyama-zk/icicle/tree/main/icicle/curves). The file should be named `_params.cuh`. + +We also require some changes to [`curve_config.cuh`](https://github.com/ingonyama-zk/icicle/blob/main/icicle/curves/curve_config.cuh#L16-L29), we need to add a new curve id. + +``` +... + +#define BN254 1 +#define BLS12_381 2 +#define BLS12_377 3 +#define BW6_761 4 +#define 5 + +... +``` + +Make sure to modify the [rest of the file](https://github.com/ingonyama-zk/icicle/blob/4beda3a900eda961f39af3a496f8184c52bf3b41/icicle/curves/curve_config.cuh#L16-L29) accordingly. + +Finally we must modify the [`make` file](https://github.com/ingonyama-zk/icicle/blob/main/icicle/CMakeLists.txt#L64) to make sure we can compile our new curve. + +``` +set(SUPPORTED_CURVES bn254;bls12_381;bls12_377;bw6_761;) +``` + +## Bindings + +In order to support a new curves in the binding libraries you first must support it in ICICLE core. + +### Rust + +Create a new folder named `icicle-` 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-/ + * src/ + * ntt/ + * mod.rs + * msm/ + * mod.rs + * curve.rs + * lib.rs + * Cargo.toml + * build.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. + + +``` +... + +extern "C" { + #[link_name = "bn254NTTCuda"] + fn ntt_cuda<'a>( + input: *const ScalarField, + size: usize, + is_inverse: bool, + config: &NTTConfig<'a, ScalarField>, + output: *mut ScalarField, + ) -> CudaError; + + #[link_name = "bn254DefaultNTTConfig"] + fn default_ntt_config() -> NTTConfig<'static, ScalarField>; + + #[link_name = "bn254InitializeDomain"] + fn initialize_ntt_domain(primitive_root: ScalarField, ctx: &DeviceContext) -> CudaError; +} + +... +``` + +Here you would need to replace `bn254NTTCuda` with `NTTCuda`. Most of these changes are pretty straight forward. One thing you should pay attention to is limb sizes as these change for different curves. For example `BN254` [has limb size of 8](https://github.com/ingonyama-zk/icicle/blob/4beda3a900eda961f39af3a496f8184c52bf3b41/wrappers/rust/icicle-curves/icicle-bn254/src/curve.rs#L15) but for your curve this may be different. + +### Golang + +TODO: based on jeremies changes \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md index 0a00903..4967389 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -2,33 +2,39 @@ slug: / displayed_sidebar: GettingStartedSidebar --- -# Introduction +# Welcome to Ingonyamas 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**: 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. -- **[Blaze]**: -Blaze is a Rust library for ZK acceleration on Xilinx FPGAs. It make it easier then ever for developres to interact with FPGAs and for FPGA designers to give developers access to their hardware. +- **Blaze**: +Blaze is a Rust library for ZK acceleration on Xilinx FPGAs. It makes it easier than ever for developers to interact with FPGAs and for FPGA designers to give developers access to their hardware. --- ## Our current take on hardware acceleration -At Ingonyama we belive that GPUs are emerging as an essential infrastructure component for enabling ZK acceleartion. This is due to their mass avalbilty, industry proven scalability, competitive preformace to power ratio and the ease at which developers can intergarte GPUs into their software stack. For a complete review of this topic we suggest you read [this article](https://www.ingonyama.com/blog/revisiting-paradigm-hardware-acceleration-for-zero-knowledge-proofs) by our CEO. +We believe GPUs are as important for ZK as for AI. -We belive GPUs are as important for ZK as to AI. +- GPUs are a perfect match for ZK compute - around 97% of ZK protocol runtime is parallel by nature. +- GPUs are simple for developers to use and scale compared to other hardware platforms. +- GPUs are extremely competitive in terms of power / performance and price (3x cheaper). +- GPUs are popular and readily available. -However despite our current focus on GPUs we are still hard at work developing a ZPU (ZK Processing Unit), with the goal of offering a programable hardware platform for ZK. To read more about ZPUs we suggest you read this [article](https://medium.com/@ingonyama/zpu-the-zero-knowledge-processing-unit-f886a48e00e0). +For a more in-depth understanding on this topic we suggest you read [our article on the subject](https://www.ingonyama.com/blog/revisiting-paradigm-hardware-acceleration-for-zero-knowledge-proofs). + +Despite our current focus on GPUs we are still hard at work developing a ZPU (ZK Processing Unit), with the goal of offering a programmable hardware platform for ZK. To read more about ZPUs we suggest you read this [article](https://medium.com/@ingonyama/zpu-the-zero-knowledge-processing-unit-f886a48e00e0). ## ICICLE -ICICLE is is a fully featured GPU accelerated cryptography library, the cryptographic primitives such as EC operations, MSM, NTT and more implemented in CUDA. +ICICLE is a cryptography library for ZK using GPUs. +ICICLE implements blazing fast cryptographic primitives such as EC operations, MSM, NTT, Poseidon hash and more on GPU. -ICICLE is designed to be easy to use, developers don't have to touch a single line of CUDA code. Our Rust and Golang ICICLE bindings allow your team to transition from CPU to GPU with minimal re-engineering. ICICLE you wont only enjoy faster prover runtime on GPU but scalability as well, now that your proving pipeline supports GPU its possible to use ICICLE's multi GPU support to scale your prover across any number of GPUs. +ICICLE is designed to be easy to use, developers don't have to touch a single line of CUDA code. Our Rust and Golang bindings allow your team to transition from CPU to GPU with minimal changes. Learn more about ICICLE and GPUs [here][ICICLE-OVERVIEW]. @@ -36,15 +42,13 @@ Learn more about ICICLE and GPUs [here][ICICLE-OVERVIEW]. Blaze is a Rust library for ZK acceleration on Xilinx FPGAs. Blaze can be used by both FPGA developer and software engineers looking to integrate FPGAs into their software. -Software engineers will enjoy Blazes abstractions allowing them to interact with FPGA drivers at a high level without having to implement low level read/write operations, we also allow developers to programmatically load binary's to an FPGA and much more. FPGA developers can benefit by building their accelerators based on our shell named [Wrapshell](https://github.com/Quarky93/warpshell). Wrapshell offers common features, such as the PCIe subsystem (DMA), AXI Firewalls, and infrastructure to reconfigure the user-partition at runtime as well as many more features which simplify and speed up the development of FPGA-based accelerators. Wrapshell with Blaze allow you to deliver easy to integrate custom PCIe-based FPGA accelerator. - -Learn more about Blaze and FPGAs [here][BLAZE-OVERVIEW]. +Software engineers will enjoy Blazes abstractions allowing them to interact with FPGA drivers at a high level without having to implement low level read/write operations, we also allow developers to programmatically load binaries to an FPGA and much more. FPGA developers can benefit by building their accelerators based on our shell named [Warpshell](https://github.com/Quarky93/warpshell). Warpshell offers common features, such as the PCIe subsystem (DMA), AXI Firewalls, and infrastructure to reconfigure the user-partition at runtime as well as many more features which simplify and speed up the development of FPGA-based accelerators. Warpshell with Blaze allows you to deliver easy to integrate custom PCIe-based FPGA accelerator. ## Get in Touch -If you have any questions, ideas, or are thinking of building something in this space join our discssion on [Discord]. Most of our work is open source, you can explore our code on [github](https://github.com/ingonyama-zk) or perhaps read some of [our research papers](https://github.com/ingonyama-zk/papers). +If you have any questions, ideas, or are thinking of building something in this space join the discussion on [Discord]. You can explore our code on [github](https://github.com/ingonyama-zk) or read some of [our research papers](https://github.com/ingonyama-zk/papers). -Follow us on [Twitter](https://x.com/Ingo_zk) and [YouTube](https://www.youtube.com/@ingo_ZK), and sign up for our [mailing list](https://wkf.ms/3LKCbdj) to get our latest announcements. +Follow us on [Twitter](https://x.com/Ingo_zk) and [YouTube](https://www.youtube.com/@ingo_ZK) and sign up for our [mailing list](https://wkf.ms/3LKCbdj) to get our latest announcements. [ICICLE-OVERVIEW]: ./icicle/overview.md [BLAZE-OVERVIEW]: ./blaze/overview.md diff --git a/docs/zk-containers.md b/docs/zk-containers.md new file mode 100644 index 0000000..2cc2fe8 --- /dev/null +++ b/docs/zk-containers.md @@ -0,0 +1,11 @@ +# ZK Containers + +We found that developing ZK provers with ICICLE gives developers the ability to scale ZK provers across many machines and many GPUs. To make this possible we developed the ZK Container. + +A ZK Container is an standardized, optimized and secure docker container that we configured with ICICLE applications in mind. A developer using ZK Containers can deploy an ICICLE application on a single machine or on a thousand GPU machines in a data center with minimal concerns regarding compatibility. + +ZK Containers have been used by Ingonyama clients to achieve scalability across large data centers. +We suggest you read our [article](https://medium.com/@ingonyama/product-announcement-zk-containers-0e2a1f2d0a2b) regarding ZK Containers to understand the benefits of using them. + + +![ZK Containers inside a ZK data center](../static/img/architecture-zkcontainer.png) diff --git a/sidebars.js b/sidebars.js index 991120b..3bf126d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -19,45 +19,37 @@ module.exports = { label: "Getting started", id: "icicle/introduction" }, + { + type: "doc", + label: "Official Integrations", + id: "icicle/integrations" + }, { type: "doc", label: "Golang bindings", - id: "icicle/bindings", + id: "icicle/golang-bindings", }, { type: "doc", label: "Rust bindings", - id: "icicle/bindings", + id: "icicle/rust-bindings", }, { type: "doc", - label: "A guide to GPU development", - id: "icicle/gpu-development-guide", + label: "Supporting additional curves", + id: "icicle/supporting-additional-curves", }, ] }, { type: "doc", - label: "Blaze", - id: 'blaze/overview', + label: "ZK Containers", + id: "zk-containers", }, { - type: "category", - label: "Moon Math Club", - collapsed: false, - items: [ - { - type: "doc", - label: "MSM Tutorial", - id: "blaze/introduction" - }, - { - type: "doc", - label: "FFT Tutorial", - id: "blaze/introduction" - }, - - ] + type: "doc", + label: "Ingonyama Grant program", + id: "grants", }, { type: "category", diff --git a/static/img/apilevels.png b/static/img/apilevels.png new file mode 100644 index 0000000..8cf079b Binary files /dev/null and b/static/img/apilevels.png differ diff --git a/static/img/architecture-high-level.png b/static/img/architecture-high-level.png new file mode 100644 index 0000000..737e53b Binary files /dev/null and b/static/img/architecture-high-level.png differ diff --git a/static/img/architecture-highlight.png b/static/img/architecture-highlight.png deleted file mode 100644 index ac05cc5..0000000 Binary files a/static/img/architecture-highlight.png and /dev/null differ diff --git a/static/img/architecture-overview.png b/static/img/architecture-overview.png new file mode 100644 index 0000000..4c82bc1 Binary files /dev/null and b/static/img/architecture-overview.png differ diff --git a/static/img/architecture-zkcontainer.png b/static/img/architecture-zkcontainer.png new file mode 100644 index 0000000..c3e0383 Binary files /dev/null and b/static/img/architecture-zkcontainer.png differ diff --git a/static/img/architecture.png b/static/img/architecture.png deleted file mode 100644 index b57b343..0000000 Binary files a/static/img/architecture.png and /dev/null differ diff --git a/static/img/iciclestructure.png b/static/img/iciclestructure.png deleted file mode 100644 index 93d05bd..0000000 Binary files a/static/img/iciclestructure.png and /dev/null differ