Skip to content

Commit 0e6d585

Browse files
LeonHibnikLeonHibnik
authored
Update README.md
1 parent 51fc21c commit 0e6d585

File tree

1 file changed

+2
-351
lines changed

1 file changed

+2
-351
lines changed

‎README.md

+2-351
Original file line numberDiff line numberDiff line change
@@ -1,353 +1,4 @@
1-
# ICICLE
1+
# ICICLE-JOLT
2+
This version of [ICICLE](https://github.com/ingonyama-zk/icicle) is designed to be used by Jolt and follows [Jolt](https://github.com/a16z/jolt) roadmap, for using ICICLE for any other purpose please follow the [dev documentation](https://dev.ingonyama.com/)
23

3-
<div align="center">
4-
ICICLE is a high-performance cryptographic acceleration library designed to optimize cryptographic computations across various hardware platforms, including CPUs, GPUs, and other accelerators.
5-
</div>
64

7-
<p align="center">
8-
<br>
9-
<img alt="ICICLE" width="300" height="300" src="McPaw.gif"/>
10-
</p>
11-
12-
<p align="center">
13-
<br>
14-
<br>
15-
<a href="https://discord.gg/EVVXTdt6DF">
16-
<img src="https://img.shields.io/discord/1063033227788423299?logo=discord&style=flat&labelColor=black&color=5765f2" alt="Chat with us on Discord">
17-
</a>
18-
<a href="https://www.linkedin.com/company/ingonyama">
19-
<img src="https://img.shields.io/badge/follow-blue?style=flat&logo=linkedin&labelColor=black" alt="Follow us on LinkedIn">
20-
</a>
21-
<a href="https://x.com/Ingo_zk">
22-
<img src="https://img.shields.io/badge/follow-darkgray?style=flat&logo=x&labelColor=black" alt="Follow us on Twitter">
23-
</a>
24-
<a href="https://github.com/ingonyama-zk/icicle/releases">
25-
<img src="https://img.shields.io/github/v/release/ingonyama-zk/icicle?style=flat&labelColor=black&color=lightblue" alt="GitHub Release">
26-
</a>
27-
</p>
28-
29-
30-
31-
32-
## Background
33-
34-
Zero Knowledge Proofs (ZKPs) are considered one of the greatest achievements of modern cryptography. Accordingly, ZKPs are expected to disrupt a number of industries and will usher in an era of trustless and privacy preserving services and infrastructure.
35-
36-
We believe that ICICLE will be a cornerstone in the acceleration of ZKPs:
37-
38-
- **Versatility**: Supports multiple hardware platforms, making it adaptable to various computational environments.
39-
- **Efficiency:** Designed to leverage the parallel nature of ZK computations, whether on GPUs, CPUs, or other accelerators.
40-
- **Scalability:** Provides an easy-to-use and scalable solution for developers, allowing them to optimize cryptographic operations with minimal effort.
41-
42-
## Getting Started
43-
44-
This guide will help you get started with ICICLE in C++, Rust, and Go.
45-
46-
> [!NOTE]
47-
> **Developers**: We highly recommend reading our [documentation](https://dev.ingonyama.com/) for a comprehensive explanation of ICICLE’s capabilities.
48-
49-
> [!TIP]
50-
> Try out ICICLE by running some [examples] available in C++, Rust, and Go bindings. Check out our install-and-use examples in [C++](https://github.com/ingonyama-zk/icicle/tree/main/examples/c%2B%2B/install-and-use-icicle), [Rust](https://github.com/ingonyama-zk/icicle/tree/main/examples/rust/install-and-use-icicle) and [Go](TODO)
51-
52-
### Prerequisites
53-
54-
- Any compatible hardware: ICICLE supports various hardware, including CPUs, Nvidia GPUs, and other accelerators.
55-
- [CMake](https://cmake.org/files/), Version 3.18 or above. Latest version recommended. Required only if building from source.
56-
- [CUDA Toolkit](https://developer.nvidia.com/cuda-downloads), Required only if using NVIDIA GPUs (version 12.0 or newer).
57-
58-
> [!NOTE]
59-
> For older GPUs that only support CUDA 11, ICICLE may still function, but official support is for CUDA 12 onwards.
60-
61-
62-
### Accessing Hardware
63-
64-
If you don't have access to an Nvidia GPU we have some options for you.
65-
66-
[Google Colab](https://colab.google/) offers a free [T4 GPU](https://www.nvidia.com/en-us/data-center/tesla-t4/) instance and ICICLE can be used with it, reference this guide for setting up your [Google Colab workplace][GOOGLE-COLAB-ICICLE].
67-
68-
If you require more compute and have an interesting research project, we have [bounty and grant programs][GRANT_PROGRAM].
69-
70-
## Building ICICLE from source
71-
72-
ICICLE provides build systems for C++, Rust, and Go. Each build system incorporates the core ICICLE library, which contains the essential cryptographic primitives. Refer to the [Getting started page](https://dev.ingonyama.com/icicle/build_from_source) for full details about building and using ICICLE.
73-
74-
> [!WARNING]
75-
> Ensure ICICLE libraries are installed correctly when building or installing a library/application that depends on ICICLE so that they can be located at runtime.
76-
77-
### Rust
78-
79-
In cargo.toml, specify the ICICLE libs to use:
80-
81-
```bash
82-
[dependencies]
83-
icicle-runtime = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
84-
icicle-core = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
85-
icicle-babybear = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
86-
# add other ICICLE crates here if need additional fields/curves
87-
```
88-
89-
You can specify `branch=branch-name`, `tag=tag-name`, or `rev=commit-id`.
90-
91-
Build the Rust project:
92-
93-
```bash
94-
cargo build --release
95-
```
96-
97-
### Go
98-
99-
There are two ways to build from source in Go:
100-
101-
1. Clone the repo, update your go.mod to point to the local clone, and build ICICLE within the clone
102-
103-
```sh
104-
git clone https://github.com/ingonyama-zk/icicle.git
105-
```
106-
107-
Add ICICLE v3 to your go.mod file:
108-
109-
```go
110-
require github.com/ingonyama-zk/icicle/v3 v3.0.0
111-
112-
replace github.com/ingonyama-zk/icicle/v3 => ../path/to/cloned/icicle
113-
```
114-
115-
Navigate to the cloned repo's golang bindings and build the library using the supplied [build script][ICICLE-GO-BUILD-SCRIPT]
116-
117-
```sh
118-
cd icicle/wrappers/golang
119-
chmod +x build.sh
120-
./build.sh -curve=bn254
121-
```
122-
123-
2. Update your go.mod to include ICICLE as a dependency, navigate to the dependency in your GOMODCACHE and build ICICLE there
124-
125-
```sh
126-
go get github.com/ingonyama-zk/icicle/v3
127-
cd $(go env GOMODCACHE)/github.com/ingonyama-zk/icicle/v3@<version>/wrappers/golang
128-
chmod +x build.sh
129-
./build.sh -curve=bn254
130-
```
131-
132-
> [!NOTE]
133-
> To specify the field, use the flag -field=<field>, where <field> can be one of the following: babybear, stark252, m31.
134-
> To specify a curve, use the flag -curve=<curve>, where <curve> can be one of the following: bn254, bls12_377, bls12_381, bw6_761, grumpkin.
135-
136-
Once ICICLE has been built, you can add specific packages when you need them in your application:
137-
138-
```go
139-
import (
140-
runtime "github.com/ingonyama-zk/icicle/v3/wrappers/golang/runtime"
141-
core "github.com/ingonyama-zk/icicle/v3/wrappers/golang/core"
142-
bn254 "github.com/ingonyama-zk/icicle/v3/wrappers/golang/curves/bn254"
143-
bn254MSM "github.com/ingonyama-zk/icicle/v3/wrappers/golang/curves/bn254/msm"
144-
)
145-
```
146-
147-
### C++
148-
149-
ICICLE can be built and tested in C++ using CMake. The build process is straightforward, but there are several flags you can use to customize the build for your needs.
150-
151-
**Clone the ICICLE repository:**
152-
153-
```bash
154-
git clone https://github.com/ingonyama-zk/icicle.git
155-
cd icicle
156-
```
157-
158-
**Configure the build:**
159-
160-
```bash
161-
mkdir -p build && rm -rf build/*
162-
cmake -S icicle -B build -DFIELD=babybear
163-
```
164-
165-
> [!NOTE]
166-
> To specify the field, use the flag -DFIELD=field, where field can be one of the following: babybear, stark252, m31.
167-
> To specify a curve, use the flag -DCURVE=curve, where curve can be one of the following: bn254, bls12_377, bls12_381, bw6_761, grumpkin.
168-
169-
**Build the project:**
170-
171-
```bash
172-
cmake --build build -j # -j is for multi-core compilation
173-
```
174-
175-
**Link your application (or library) to ICICLE:**
176-
177-
```cmake
178-
target_link_libraries(yourApp PRIVATE icicle_field_babybear icicle_device)
179-
```
180-
181-
**Install (optional):**
182-
183-
To install the libs, specify the install prefix `-DCMAKE_INSTALL_PREFIX=/install/dir/`. Then after building, use cmake to install the libraries:
184-
185-
```sh
186-
cmake -S icicle -B build -DFIELD=babybear -DCMAKE_INSTALL_PREFIX=/path/to/install/dir/
187-
cmake --build build -j # build
188-
cmake --install build # install icicle to /path/to/install/dir/
189-
```
190-
191-
**Run tests (optional):**
192-
193-
> [!CAUTION]
194-
> Most tests assume a CUDA backend exists and will fail otherwise, if a CUDA device is not found.
195-
196-
Add `-DBUILD_TESTS=ON` to the cmake command, build and execute tests:
197-
198-
```bash
199-
cmake -S icicle -B build -DFIELD=babybear -DBUILD_TESTS=ON
200-
cmake --build build -j
201-
cd build/tests
202-
ctest
203-
```
204-
205-
or choose the test-suite
206-
207-
```bash
208-
./build/tests/test_field_api # or another test suite
209-
# can specify tests using regex. For example for tests with ntt in the name:
210-
./build/tests/test_field_api --gtest_filter="*ntt*"
211-
```
212-
213-
**Build Flags:**
214-
215-
You can customize your ICICLE build with the following flags:
216-
217-
- `-DCPU_BACKEND=ON/OFF`: Enable or disable built-in CPU backend. `default=ON`.
218-
- `-DCMAKE_INSTALL_PREFIX=/install/dir`: Specify install directory. `default=/usr/local`.
219-
- `-DBUILD_TESTS=ON/OFF`: Enable or disable tests. `default=OFF`.
220-
- `-DBUILD_BENCHMARKS=ON/OFF`: Enable or disable benchmarks. `default=OFF`.
221-
222-
## Install CUDA backend
223-
224-
To install the CUDA backend
225-
226-
1. [Download the release binaries](https://github.com/ingonyama-zk/icicle/releases/).
227-
2. Install it, by extracting the binaries to `/opt/` or any other custom install path.
228-
3. In your application, load the cuda backend and select a CUDA device.
229-
4. All subsequent API will now use the selected device.
230-
231-
232-
Rust:
233-
234-
```rust
235-
use icicle_runtime::{runtime, Device};
236-
237-
runtime::load_backend_from_env_or_default().unwrap();
238-
// or load programmatically
239-
runtime::load_backend("/path/to/backend/installdir").unwrap();
240-
// Select CUDA device
241-
let device = Device::new("CUDA", 1 /*gpu-id*/);
242-
icicle_runtime::set_device(&device).unwrap();
243-
244-
// Any call will now execute on GPU-1
245-
```
246-
247-
Go:
248-
249-
```go
250-
import(
251-
"github.com/ingonyama-zk/icicle/v3/wrappers/golang/runtime"
252-
)
253-
254-
result := runtime.LoadBackendFromEnvOrDefault()
255-
// or load from custom install dir
256-
result := runtime.LoadBackend("/path/to/backend/installdir", true)
257-
// Select CUDA device
258-
device := runtime.CreateDevice("CUDA", 0) // or other
259-
result := runtime.SetDevice(device)
260-
261-
// Any call will now execute on GPU-0
262-
```
263-
C++:
264-
265-
```cpp
266-
#include "icicle/runtime.h"
267-
268-
// Load the installed backend
269-
eIcicleError result = icicle_load_backend_from_env_or_default();
270-
// or load it programmatically
271-
eIcicleError result = icicle_load_backend("/path/to/backend/installdir", true);
272-
273-
// Select CUDA device
274-
icicle::Device device = {"CUDA", 0 /*gpu-id*/};
275-
eIcicleError result = icicle_set_device(device);
276-
277-
// Any call will now execute on GPU-0
278-
```
279-
280-
Full details can be found in our [getting started docs](https://dev.ingonyama.com/icicle/introduction)
281-
282-
## Contributions
283-
284-
Join our [Discord Server][DISCORD] and find us on the ICICLE channel. We will be happy to work together to support your use case, and talk features, bugs and design.
285-
286-
### Development Contributions
287-
288-
If you are changing code, please make sure to change your [git hooks path][HOOKS_DOCS] to the repo's [hooks directory][HOOKS_PATH] by running the following command:
289-
290-
```sh
291-
git config core.hooksPath ./scripts/hooks
292-
```
293-
294-
In case `clang-format` is missing on your system, you can install it using the following command:
295-
296-
```sh
297-
sudo apt install clang-format
298-
```
299-
300-
You will also need to install [codespell](https://github.com/codespell-project/codespell?tab=readme-ov-file#installation) to check for typos.
301-
302-
This will ensure our custom hooks are run and will make it easier to follow our coding guidelines.
303-
304-
### Hall of Fame
305-
306-
- [Robik](https://github.com/robik75), for his ongoing support and mentorship
307-
- [liuxiao](https://github.com/liuxiaobleach), for being a top notch bug smasher
308-
- [gkigiermo](https://github.com/gkigiermo), for making it intuitive to use ICICLE in Google Colab
309-
- [nonam3e](https://github.com/nonam3e), for adding Grumpkin curve support into ICICLE
310-
- [alxiong](https://github.com/alxiong), for adding warmup for CudaStream
311-
- [cyl19970726](https://github.com/cyl19970726), for updating go install source in Dockerfile
312-
- [PatStiles](https://github.com/PatStiles), for adding Stark252 field
313-
314-
## Help & Support
315-
316-
For help and support talk to our devs in our discord channel [#ICICLE](https://discord.gg/EVVXTdt6DF) or contact us at <[email protected]>.
317-
318-
## License
319-
320-
ICICLE frontend is distributed under the terms of the MIT License.
321-
322-
> [!NOTE]
323-
> ICICLE backends, excluding the CPU backend, are distributed under a special license and are not covered by the MIT license.
324-
325-
See [LICENSE-MIT][LMIT] for details.
326-
327-
<!-- Begin Links -->
328-
[BLS12-381]: ./icicle/curves/
329-
[BLS12-377]: ./icicle/curves/
330-
[BN254]: ./icicle/curves/
331-
[BW6-671]: ./icicle/curves/
332-
[Grumpkin]: ./icicle/curves/
333-
[babybear]: ./icicle/fields/
334-
[stark252]: ./icicle/fields/
335-
[m31]: ./icicle/fields/
336-
[LMIT]: ./LICENSE
337-
[DISCORD]: https://discord.gg/Y4SkbDf2Ff
338-
[googletest]: https://github.com/google/googletest/
339-
[HOOKS_DOCS]: https://git-scm.com/docs/githooks
340-
[HOOKS_PATH]: ./scripts/hooks/
341-
[GOOGLE-COLAB-ICICLE]: https://dev.ingonyama.com/icicle/colab-instructions
342-
[GRANT_PROGRAM]: https://medium.com/@ingonyama/icicle-for-researchers-grants-challenges-9be1f040998e
343-
[ICICLE-CORE]: ./icicle/
344-
[ICICLE-RUST]: ./wrappers/rust/
345-
[ICICLE-GO]: ./wrappers/golang/
346-
[ICICLE-GO-BUILD-SCRIPT]: ./wrappers/golang/build.sh
347-
[ICICLE-CORE-README]: ./icicle/README.md
348-
[ICICLE-RUST-README]: ./wrappers/rust/README.md
349-
[ICICLE-GO-README]: ./wrappers/golang/README.md
350-
[documentation]: https://dev.ingonyama.com/icicle/overview
351-
[examples]: ./examples/
352-
353-
<!-- End Links -->

0 commit comments

Comments
 (0)