You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
3
+
The developer docs for ICICLE is a static website built using [Docusaurus](https://docusaurus.io/).
4
4
5
-
### Installation
5
+
##Requirements
6
6
7
-
```
8
-
$ npm i
9
-
```
7
+
Docusaurus is written in Typescript and distributed as npm packages. npm is a prerequisite as is node.js
8
+
9
+
If node.js or npm aren't installed, its suggested to use [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) to [install both](https://github.com/nvm-sh/nvm?tab=readme-ov-file#usage) at the same time.
10
10
11
-
### Local Development
11
+
##Install
12
12
13
+
```sh
14
+
npm install
13
15
```
14
-
$ npm start
16
+
17
+
## Versioning
18
+
19
+
ICICLE docs are versioned, keeping the latest set of docs for previous major versions and the latest 4 sets of docs for the current major version.
20
+
21
+
The [docs](./docs/) directory holds the next version's docs
22
+
All **released** versions are under the [versioned_docs](./versioned_docs/) directory.
23
+
24
+
### Releasing new versions
25
+
26
+
In order to create a new version, run the following:
27
+
28
+
```sh
29
+
npm run docusaurus docs:version <version to create>
15
30
```
16
31
17
-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
32
+
For example:
18
33
19
-
### Build
34
+
Assuming the next version is 5.6.0, we would run the following:
20
35
36
+
```sh
37
+
npm run docusaurus docs:version 5.6.0
21
38
```
22
-
$ npm run build
39
+
40
+
This command will:
41
+
42
+
1. Add a new version for the specified `<version to create>` in the [versions file](./versions.json)
43
+
2. Create a directory under [versioned_docs](./versioned_docs/) with the name `version-<version to create>` and copies everything in the [docs](./docs/) directory there.
44
+
3. Create a file under [versioned_sidebars](./versioned_sidebars/) with the name `version-<version to create>-sidebars.json` and copies the current [sidebar.ts](./sidebars.ts) file there after converting it to a json object.
45
+
46
+
### Removing old versions
47
+
48
+
- Remove the version from versions.json.
49
+
50
+
```json
51
+
[
52
+
"3.2.0",
53
+
"3.1.0",
54
+
"3.0.0",
55
+
"2.8.0",
56
+
- "1.10.1"
57
+
]
23
58
```
24
59
25
-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
60
+
- Delete the versioned docs directory for that version. Example: versioned_docs/version-1.10.1.
61
+
- Delete the versioned sidebars file. Example: versioned_sidebars/version-1.10.1-sidebars.json.
62
+
63
+
## Static assets
26
64
27
-
### Deployment
65
+
Static assets like images should be placed in the top level [static](./static/) directory **regardless** of which version it will be used in.
28
66
29
-
Using SSH:
67
+
Docusaurus adds all of the files in the directories listed as `staticDirectories` in the config to the root of the build output so they can be accessed directly from the root path.
30
68
69
+
Read more on this [here](https://docusaurus.io/docs/static-assets)
70
+
71
+
### Adding a new static directory
72
+
73
+
To update where Docusaurus looks for static directories, add the directory name to the `statidDirectories` list in the config:
Since the static assets are at the root of the build output, static assets can be linked to directly from the root, maintaining the directory hierarchy they have in the static directory.
90
+
91
+
For example:
92
+
93
+
If an image is located at `static/images/poseidon.png`, it should be linked to as `/images/poseidon.png`
94
+
95
+
## Local development
96
+
97
+
To render the site, run the following
98
+
99
+
```sh
100
+
npm start
33
101
```
34
102
35
-
Not using SSH:
103
+
This command starts a local development server and opens up a browser window on port 3000. Most changes are reflected live (hot reloaded) without having to restart the server.
36
104
105
+
By default, the next version's docs are not rendered. In order to view any changes in the next version's docs, update the following in the [config file](./docusaurus.config.ts):
106
+
107
+
```ts
108
+
const ingoPreset = {
109
+
docs: {
110
+
.
111
+
.
112
+
includeCurrentVersion: false, // Update this to true to render the next verion's docs
113
+
.
114
+
.
115
+
.
116
+
117
+
},
118
+
.
119
+
.
120
+
.
121
+
} satisfiesPreset.Options
37
122
```
38
-
$ GIT_USER=<Your GitHub username> npm run deploy
123
+
124
+
### Updating docs in old versions
125
+
126
+
In order to update docs for old versions, the files under the specific version's [versioned_docs](./versioned_docs/) directory must be updated.
127
+
128
+
### Updating docs across versions
129
+
130
+
If docs need updating across multiple versions, including future versions, they need to be updated in each previous version's [versioned_docs](./versioned_docs/) and the next version's docs under the [docs](./docs/) directory
131
+
132
+
## Adding or removing docs from rendering
133
+
134
+
Each version has its own sidebar.json file located in the [versioned_sidebars](./versioned_sidebars/) directory.
135
+
136
+
The next version's sidebar is found in [sidebar.ts](./sidebars.ts).
137
+
138
+
You can add or remove a doc from there to change the sidebar and include or prevent docs from rendering.
139
+
140
+
## Troubleshooting
141
+
142
+
### Latex isn't rendering correctly
143
+
144
+
Latex formula must have the `$$` on a separate line:
Engineers usually use a cryptographic 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.
Copy file name to clipboardexpand all lines: docs/docs/icicle/primitives/hash.md
+26-16
Original file line number
Diff line number
Diff line change
@@ -18,13 +18,13 @@ For scenarios where large datasets need to be hashed efficiently, ICICLE support
18
18
19
19
ICICLE supports the following hash functions:
20
20
21
-
1.**Keccak-256**
22
-
2.**Keccak-512**
23
-
3.**SHA3-256**
24
-
4.**SHA3-512**
25
-
5.**Blake2s**
26
-
6.**Poseidon**
27
-
7.**Poseidon2**
21
+
1.**Keccak-256**
22
+
2.**Keccak-512**
23
+
3.**SHA3-256**
24
+
4.**SHA3-512**
25
+
5.**Blake2s**
26
+
6.**Poseidon**
27
+
7.**Poseidon2**
28
28
29
29
:::info
30
30
Additional hash functions might be added in the future. Stay tuned!
@@ -40,25 +40,36 @@ Keccak can take input messages of any length and produce a fixed-size hash. It u
40
40
41
41
[Blake2s](https://www.rfc-editor.org/rfc/rfc7693.txt) is an optimized cryptographic hash function that provides high performance while ensuring strong security. Blake2s is ideal for hashing small data (such as field elements), especially when speed is crucial. It produces a 256-bit (32-byte) output and is often used in cryptographic protocols.
42
42
43
-
44
43
### Poseidon
45
44
46
45
[Poseidon](https://eprint.iacr.org/2019/458) is a cryptographic hash function designed specifically for field elements. It is highly optimized for zero-knowledge proofs (ZKPs) and is commonly used in ZK-SNARK systems. Poseidon’s main strength lies in its arithmetization-friendly design, meaning it can be efficiently expressed as arithmetic constraints within a ZK-SNARK circuit.
47
46
48
47
Traditional hash functions, such as SHA-2, are difficult to represent within ZK circuits because they involve complex bitwise operations that don’t translate efficiently into arithmetic operations. Poseidon, however, is specifically designed to minimize the number of constraints required in these circuits, making it significantly more efficient for use in ZK-SNARKs and other cryptographic protocols that require hashing over field elements.
49
48
50
-
Currently the Poseidon implementation is the Optimized Poseidon(https://hackmd.io/@jake/poseidon-spec#Optimized-Poseidon). Optimized Poseidon significantly decreases the calculation time of the hash.
49
+
Currently the Poseidon implementation is the [Optimized Poseidon](https://hackmd.io/@jake/poseidon-spec#Optimized-Poseidon). Optimized Poseidon significantly decreases the calculation time of the hash.
51
50
52
51
The optional `domain_tag` pointer parameter enables domain separation, allowing isolation of hash outputs across different contexts or applications.
53
52
54
-
55
53
### Poseidon2
56
54
57
55
[Poseidon2](https://eprint.iacr.org/2023/323.pdf) is a cryptographic hash function designed specifically for field elements.
58
56
It is an improved version of the original [Poseidon](https://eprint.iacr.org/2019/458) hash, offering better performance on modern hardware. Poseidon2 is optimized for use with elliptic curve cryptography and finite fields, making it ideal for decentralized systems like blockchain. Its main advantage is balancing strong security with efficient computation, which is crucial for applications that require fast, reliable hashing.
59
57
60
58
The optional `domain_tag` pointer parameter enables domain separation, allowing isolation of hash outputs across different contexts or applications.
61
59
60
+
:::info
61
+
62
+
The supported values of state size ***t*** as defined in [eprint 2023/323](https://eprint.iacr.org/2023/323.pdf) are 2, 3, 4, 8, 12, 16, 20 and 24. Note that ***t*** sizes 8, 12, 16, 20 and 24 are supported only for small fields (babybear and m31).
63
+
64
+
:::
65
+
66
+
:::info
67
+
68
+
The S box power alpha, number of full rounds and partial rounds, rounds constants, MDS matrix, and partial matrix for each field and ***t*** can be found in this [folder](https://github.com/ingonyama-zk/icicle/tree/9b1506cda9eab30fc6a8d0a338e2cfab877402f7/icicle/include/icicle/hash/poseidon2_constants/constants).
69
+
70
+
:::
71
+
72
+
In the current version the padding is not supported and should be performed by the user.
62
73
63
74
## Using Hash API
64
75
@@ -84,21 +95,20 @@ auto poseidon = Poseidon::create<scalar_t>(t);
84
95
// The domain tag acts as the first input to the hash function, with the remaining t-1 inputs following it.
85
96
scalar_t domain_tag = scalar_t::zero(); // Example using zero; this can be set to any valid field element.
86
97
auto poseidon_with_domain_tag = Poseidon::create<scalar_t>(t, &domain_tag);
87
-
// This version of the hasher with a domain tag expects t-1 additional inputs for hashing.
88
98
// Poseidon2 requires specifying the field-type and t parameter (supported 2, 3, 4, 8, 12, 16, 20, 24) as defined by
89
-
// the Poseidon2 paper. For large fields (field width >= 254) the supported values of t are 2, 3, 4.
99
+
// the Poseidon2 paper. For large fields (field width >= 252) the supported values of t are 2, 3, 4.
90
100
auto poseidon2 = Poseidon2::create<scalar_t>(t);
91
101
// Optionally, Poseidon2 can accept a domain-tag, which is a field element used to separate applications or contexts.
92
102
// The domain tag acts as the first input to the hash function, with the remaining t-1 inputs following it.
93
103
scalar_t domain_tag = scalar_t::zero(); // Example using zero; this can be set to any valid field element.
94
104
auto poseidon2_with_domain_tag = Poseidon2::create<scalar_t>(t, &domain_tag);
95
-
// This version of the hasher with a domain tag expects t-1 additional inputs for hashing.
105
+
// This version of the hasher with a domain tag expects t-1 inputs per hasher.
96
106
```
97
107
98
108
### 2. Hashing Data
99
109
100
110
Once you have a hasher object, you can hash any input data by passing the input, its size, a configuration, and an output buffer:
Currently the poseidon sponge function (sponge function description could be found in Sec 2.1 of https://eprint.iacr.org/2019/458.pdf) isn't implemented.
173
+
Currently the poseidon sponge mode (sponge function description could be found in Sec 2.1 of [eprint 2019/458](https://eprint.iacr.org/2019/458.pdf)) isn't implemented.
164
174
165
175
### 5. Poseidon2 sponge function
166
176
167
-
Currently the poseidon2 sponge function (sponge function description could be found in Sec 2.1 of https://eprint.iacr.org/2019/458.pdf ) isn't implemented.
177
+
Currently the poseidon2 is implemented in compression mode, the sponge mode discussed in [eprint 2023/323](https://eprint.iacr.org/2023/323.pdf) is not implemented.
0 commit comments