Skip to content

Commit b02ebf1

Browse files
yshekelyshekel
committed
Bump docs version
1 parent 604de04 commit b02ebf1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+7498
-0
lines changed

‎docs/versioned_docs/version-3.2.0/contributor-guide.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Contributor's Guide
2+
3+
We welcome all contributions with open arms. At Ingonyama we take a village approach, believing it takes many hands and minds to build a ecosystem.
4+
5+
## Contributing to ICICLE
6+
7+
- Make suggestions or report bugs via [GitHub issues](https://github.com/ingonyama-zk/icicle/issues)
8+
- Contribute to the ICICLE by opening a [pull request](https://github.com/ingonyama-zk/icicle/pulls).
9+
- Contribute to our [documentation](https://github.com/ingonyama-zk/icicle/tree/main/docs) and [examples](https://github.com/ingonyama-zk/icicle/tree/main/examples).
10+
- Ask questions on Discord
11+
12+
### Opening a pull request
13+
14+
When opening a [pull request](https://github.com/ingonyama-zk/icicle/pulls) please keep the following in mind.
15+
16+
- `Clear Purpose` - The pull request should solve a single issue and be clean of any unrelated changes.
17+
- `Clear description` - If the pull request is for a new feature describe what you built, why you added it and how its best that we test it. For bug fixes please describe the issue and the solution.
18+
- `Consistent style` - Rust and Golang code should be linted by the official linters (golang fmt and rust fmt) and maintain a proper style. For CUDA and C++ code we use [`clang-format`](https://github.com/ingonyama-zk/icicle/blob/main/.clang-format), [here](https://github.com/ingonyama-zk/icicle/blob/605c25f9d22135c54ac49683b710fe2ce06e2300/.github/workflows/main-format.yml#L46) you can see how we run it.
19+
- `Minimal Tests` - please add test which cover basic usage of your changes .
20+
21+
## Questions?
22+
23+
Find us on [Discord](https://discord.gg/6vYrE7waPj).

‎docs/versioned_docs/version-3.2.0/grants.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Ingonyama Grant programs
2+
3+
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.
4+
5+
## ICICLE ZK-GPU Ecosystem Grant
6+
7+
Ingonyama invites researchers and practitioners to collaborate in advancing ZK acceleration. We are allocating $100,000 for grants to support this initiative.
8+
9+
### Bounties & Grants
10+
11+
Eligibility for grants includes:
12+
13+
1. **Students**: Utilize ICICLE in your research.
14+
2. **Performance Improvement**: Enhance the performance of accelerated primitives in ICICLE.
15+
3. **Protocol Porting**: Migrate existing ZK protocols to ICICLE.
16+
4. **New Primitives**: Contribute new primitives to ICICLE.
17+
5. **Benchmarking**: Compare ZK benchmarks against ICICLE.
18+
19+
## Contact
20+
21+
For questions or submissions: [[email protected]](mailto:[email protected])
22+
23+
**Read the full article [here](https://www.ingonyama.com/blog/icicle-for-researchers-grants-challenges)**

‎docs/versioned_docs/version-3.2.0/icicle/arch_overview.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Architecture Overview
2+
3+
4+
ICICLE v3 is designed with flexibility and extensibility in mind, offering a robust framework that supports multiple compute backends and accommodates various cryptographic needs. This section provides an overview of ICICLE's architecture, highlighting its open and closed components, multi-device support, and extensibility.
5+
6+
### Frontend and CPU Backend
7+
8+
- **Frontend (FE):** The ICICLE frontend is open-source and designed to provide a unified API across different programming languages, including C++, Rust, and Go. This frontend abstracts the complexity of working with different backends, allowing developers to write backend-agnostic code that can be deployed across various platforms.
9+
- **CPU Backend:** ICICLE includes an open-source CPU backend that allows for development and testing on standard hardware. This backend is ideal for prototyping and for environments where specialized hardware is not available.
10+
11+
## CUDA Backend
12+
13+
- **CUDA Backend:** ICICLE also includes a high-performance CUDA backend that is closed-source. This backend is optimized for NVIDIA GPUs and provides significant acceleration for cryptographic operations.
14+
- **Installation and Licensing:** The CUDA backend needs to be downloaded and installed. Refer to the [installation guide](./install_cuda_backend.md) for detailed instructions.
15+
16+
## Multi-Device Support
17+
18+
- **Scalability:** ICICLE supports multi-device configurations, enabling the distribution of workloads across multiple GPUs or other hardware accelerators. This feature allows for scaling ZK proofs and other cryptographic operations across larger data centers or high-performance computing environments.
19+
20+
21+
## Build Your Own Backend
22+
23+
ICICLE is designed to be extensible, allowing developers to integrate new backends or customize existing ones to suit their specific needs. The architecture supports:
24+
25+
- **Custom Backends:** Developers can create their own backends to leverage different hardware or optimize for specific use cases. The process of building and integrating a custom backend is documented in the [Build Your Own Backend](./build_your_own_backend.md) section.
26+
- **Pluggable Components:** ICICLE's architecture allows for easy integration of additional cryptographic primitives or enhancements, ensuring that the framework can evolve with the latest advancements in cryptography and hardware acceleration.
27+

‎docs/versioned_docs/version-3.2.0/icicle/benchmarks.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Benchmarks
2+
3+
TODO

‎docs/versioned_docs/version-3.2.0/icicle/build_from_source.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
2+
# Build ICICLE from source
3+
4+
This guide will help you get started with building, testing, and installing ICICLE, whether you're using C++, Rust, or Go. It also covers installation of the CUDA backend and important build options.
5+
6+
## Building and Testing ICICLE frontend
7+
8+
### C++: Build, Test, and Install (Frontend)
9+
10+
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.
11+
12+
#### Build Commands
13+
14+
1. **Clone the ICICLE repository:**
15+
```bash
16+
git clone https://github.com/ingonyama-zk/icicle.git
17+
cd icicle
18+
```
19+
20+
2. **Configure the build:**
21+
```bash
22+
mkdir -p build && rm -rf build/*
23+
cmake -S icicle -B build -DFIELD=babybear
24+
```
25+
26+
:::info
27+
To specify the field, use the flag -DFIELD=field, where field can be one of the following: babybear, stark252, m31.
28+
29+
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.
30+
:::
31+
32+
:::tip
33+
If you have access to cuda backend repo, it can be built along ICICLE frontend by adding the following to the cmake command
34+
- `-DCUDA_BACKEND=local` # if you have it locally
35+
- `-DCUDA_BACKEND=<commit|branch>` # to pull CUDA backend, given you have access
36+
:::
37+
38+
3. **Build the project:**
39+
```bash
40+
cmake --build build -j
41+
```
42+
This is building the [libicicle_device](./libraries.md#icicle-device) and the [libicicle_field_babybear](./libraries.md#icicle-core) frontend lib that correspond to the field or curve.
43+
44+
4. **Link:**
45+
Link you application (or library) to ICICLE:
46+
```cmake
47+
target_link_libraries(yourApp PRIVATE icicle_field_babybear icicle_device)
48+
```
49+
50+
5. **Installation (optional):**
51+
To install the libs, specify the install prefix in the [cmake command](./build_from_source.md#build-commands)
52+
`-DCMAKE_INSTALL_PREFIX=/install/dir/`. Default install path on linux is `/usr/local` if not specified. For other systems it may differ. The cmake command will print it to the log
53+
```
54+
-- CMAKE_INSTALL_PREFIX=/install/dir/for/cmake/install
55+
```
56+
Then after building, use cmake to install the libraries:
57+
```
58+
cmake -S icicle -B build -DFIELD=babybear -DCMAKE_INSTALL_PREFIX=/path/to/install/dir/
59+
cmake --build build -j # build
60+
cmake --install build # install icicle to /path/to/install/dir/
61+
```
62+
63+
6. **Run tests (optional):**
64+
Add `-DBUILD_TESTS=ON` to the [cmake command](./build_from_source.md#build-commands) and build.
65+
Execute all tests
66+
```bash
67+
cmake -S icicle -B build -DFIELD=babybear -DBUILD_TESTS=ON
68+
cmake --build build -j
69+
cd build/tests
70+
ctest
71+
```
72+
or choose the test-suite
73+
```bash
74+
./build/tests/test_field_api # or another test suite
75+
# can specify tests using regex. For example for tests with ntt in the name:
76+
./build/tests/test_field_api --gtest_filter="*ntt*"
77+
```
78+
:::note
79+
Most tests assume a cuda backend exists and will fail otherwise if cannot find a CUDA device.
80+
:::
81+
82+
#### Build Flags
83+
84+
You can customize your ICICLE build with the following flags:
85+
86+
- `-DCPU_BACKEND=ON/OFF`: Enable or disable built-in CPU backend. `default=ON`.
87+
- `-DCMAKE_INSTALL_PREFIX=/install/dir`: Specify install directory. `default=/usr/local`.
88+
- `-DBUILD_TESTS=ON/OFF`: Enable or disable tests. `default=OFF`.
89+
- `-DBUILD_BENCHMARKS=ON/OFF`: Enable or disable benchmarks. `default=OFF`.
90+
91+
#### Features
92+
93+
By default, all [features](./libraries.md#supported-curves-and-operations) are enabled.
94+
This is since installed backends may implement and register all APIs. Missing APIs in the frontend would cause linkage to fail due to missing symbols. Therefore by default we include them in the frontend part too.
95+
96+
To disable features, add the following to the cmake command.
97+
- ntt: `-DNTT=OFF`
98+
- msm: `-DMSM=OFF`
99+
- g2 msm: `-DG2=OFF`
100+
- ecntt: `-DECNTT=OFF`
101+
- extension field: `-DEXT_FIELD=OFF`
102+
103+
:::tip
104+
Disabling features is useful when developing with a backend that is slow to compile (e.g. CUDA backend);
105+
:::
106+
107+
### Rust: Build, Test, and Install
108+
109+
To build and test ICICLE in Rust, follow these steps:
110+
111+
1. **Navigate to the Rust bindings directory:**
112+
```bash
113+
cd wrappers/rust # or go to a specific field/curve 'cd wrappers/rust/icicle-fields/icicle-babybear'
114+
```
115+
116+
2. **Build the Rust project:**
117+
```bash
118+
cargo build --release
119+
```
120+
By default, all [supported features are enabled](#features).
121+
Cargo features are used to disable features, rather than enable them, for the reason explained [here](#features):
122+
- `no_g2` to disable G2 MSM
123+
- `no_ecntt` to disable ECNTT
124+
125+
They can be disabled as follows:
126+
```bash
127+
cargo build --release --features=no_ecntt,no_g2
128+
```
129+
130+
:::note
131+
If you have access to cuda backend repo, it can be built along ICICLE frontend by using the following cargo features:
132+
- `cuda_backend` : if the cuda backend resides in `icicle/backend/cuda`
133+
- `pull_cuda_backend` : to pull main branch and build it
134+
:::
135+
136+
137+
3. **Run tests:**
138+
```bash
139+
cargo test # optional: --features=no_ecntt,no_g2,cuda_backend
140+
```
141+
:::note
142+
Most tests assume a CUDA backend is installed and fail otherwise.
143+
:::
144+
145+
4. **Install the library:**
146+
147+
By default, the libraries are installed to the `target/<buildmode>/deps/icicle` dir. If you want them installed elsewhere, define the env variable:
148+
```bash
149+
export ICICLE_INSTALL_DIR=/path/to/install/dir
150+
```
151+
152+
#### Use as cargo dependency
153+
In cargo.toml, specify the ICICLE libs to use:
154+
155+
```bash
156+
[dependencies]
157+
icicle-runtime = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
158+
icicle-core = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
159+
icicle-babybear = { git = "https://github.com/ingonyama-zk/icicle.git", branch="main" }
160+
# add other ICICLE crates here if need additional fields/curves
161+
```
162+
163+
Can specify `branch = <branch-name>` or `tag = <tag-name>` or `rev = <commit-id>`.
164+
165+
To disable features:
166+
```bash
167+
icicle-bls12-377 = { git = "https://github.com/ingonyama-zk/icicle.git", features = ["no_g2"] }
168+
```
169+
170+
As explained above, the libs will be built and installed to `target/<buildmode>/deps/icicle` so you can easily link to them. Alternatively you can set `ICICLE_INSTALL_DIR` env variable for a custom install directory.
171+
172+
:::warning
173+
Make sure to install icicle libs when installing a library/application that depends on icicle such that it is located at runtime.
174+
:::
175+
176+
### Go: Build, Test, and Install (TODO)
177+
178+
---
179+
**To install CUDA backend and license click [here](./install_cuda_backend.md#installation)**

‎docs/versioned_docs/version-3.2.0/icicle/build_your_own_backend.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Build Your Own Backend
2+
3+
TODO

0 commit comments

Comments
 (0)