update poseidon2 docs (#681)

Signed-off-by: Jeremy Felder <[email protected]> Co-authored-by: danny-shterman <[email protected]> Co-authored-by: Jeremy Felder <[email protected]>
ingonyama-zk · Dec 13, 2024 · 55167b5 · 55167b5
1 parent bef4371
commit 55167b5
Show file tree

Hide file tree

Showing 17 changed files with 1,509 additions and 186 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -1,39 +1,155 @@
-# Website
+# ICICLE Developer Docs
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+The developer docs for ICICLE is a static website built using [Docusaurus](https://docusaurus.io/).
 
-### Installation
+## Requirements
 
-```
-$ npm i
-```
+Docusaurus is written in Typescript and distributed as npm packages. npm is a prerequisite as is node.js
+
+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.
 
-### Local Development
+## Install
 
+```sh
+npm install
 ```
-$ npm start
+
+## Versioning
+
+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.
+
+The [docs](./docs/) directory holds the next version's docs
+All **released** versions are under the [versioned_docs](./versioned_docs/) directory.
+
+### Releasing new versions
+
+In order to create a new version, run the following:
+
+```sh
+npm run docusaurus docs:version <version to create>
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+For example:
 
-### Build
+Assuming the next version is 5.6.0, we would run the following:
 
+```sh
+npm run docusaurus docs:version 5.6.0
 ```
-$ npm run build
+
+This command will:
+
+1. Add a new version for the specified `<version to create>` in the [versions file](./versions.json)
+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.
+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.
+
+### Removing old versions
+
+- Remove the version from versions.json.
+
+```json
+  [
+    "3.2.0",
+    "3.1.0",
+    "3.0.0",
+    "2.8.0",
+  - "1.10.1"
+  ]
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+- Delete the versioned docs directory for that version. Example: versioned_docs/version-1.10.1.
+- Delete the versioned sidebars file. Example: versioned_sidebars/version-1.10.1-sidebars.json.
+
+## Static assets
 
-### Deployment
+Static assets like images should be placed in the top level [static](./static/) directory **regardless** of which version it will be used in.
 
-Using SSH:
+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.
 
+Read more on this [here](https://docusaurus.io/docs/static-assets)
+
+### Adding a new static directory
+
+To update where Docusaurus looks for static directories, add the directory name to the `statidDirectories` list in the config:
+
+```ts
+const config: Config = {
+  .
+  .
+  .
+  staticDirectories: ['static'/*, "another static dir" */],
+  .
+  .
+  .
+}
 ```
-$ USE_SSH=true npm run deploy
+
+### Linking to static assets in docs
+
+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.
+
+For example:
+
+If an image is located at `static/images/poseidon.png`, it should be linked to as `/images/poseidon.png`
+
+## Local development
+
+To render the site, run the following
+
+```sh
+npm start
 ```
 
-Not using SSH:
+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.
 
+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):
+
+```ts
+const ingoPreset = {
+  docs: {
+    .
+    .
+    includeCurrentVersion: false, // Update this to true to render the next verion's docs
+    .
+    .
+    .
+
+  },
+  .
+  .
+  .
+} satisfies Preset.Options
 ```
-$ GIT_USER=<Your GitHub username> npm run deploy
+
+### Updating docs in old versions
+
+In order to update docs for old versions, the files under the specific version's [versioned_docs](./versioned_docs/) directory must be updated.
+
+### Updating docs across versions
+
+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
+
+## Adding or removing docs from rendering
+
+Each version has its own sidebar.json file located in the [versioned_sidebars](./versioned_sidebars/) directory.
+
+The next version's sidebar is found in [sidebar.ts](./sidebars.ts).
+
+You can add or remove a doc from there to change the sidebar and include or prevent docs from rendering.
+
+## Troubleshooting
+
+### Latex isn't rendering correctly
+
+Latex formula must have the `$$` on a separate line:
+
+```mdx
+$$
+M_{4} = \begin{pmatrix}
+5 & 7 & 1 & 3 \\
+4& 6 & 1 & 1 \\
+1 & 3 & 5 & 7\\
+1 & 1 & 4 & 6\\
+\end{pmatrix}
+$$
 ```
diff --git a/docs/docs/icicle/colab-instructions.md b/docs/docs/icicle/colab-instructions.md
@@ -9,11 +9,11 @@ First thing to do in a notebook is to set the runtime type to a T4 GPU.
 
 - in the upper corner click on the dropdown menu and select "change runtime type"
 
-![Change runtime](./static/img/colab_change_runtime.png)
+![Change runtime](/img/colab_change_runtime.png)
 
 - In the window select "T4 GPU" and press Save
 
-![T4 GPU](./static/img/t4_gpu.png)
+![T4 GPU](/img/t4_gpu.png)
 
 Installing Rust is rather simple, just execute the following command:
 

diff --git a/docs/docs/icicle/integrations.md b/docs/docs/icicle/integrations.md
@@ -10,7 +10,7 @@ If you're interested in understanding these integrations better or learning how
 
 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)
+![ICICLE architecture](/img/architecture-high-level.png)
 
 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.
 

diff --git a/docs/docs/icicle/libraries.md b/docs/docs/icicle/libraries.md
@@ -33,6 +33,7 @@ Each library has a corresponding crate. See [programmers guide](./programmers_gu
 | [Vector operations](./primitives/vec_ops) |                      ✅                       |                           ✅                           |                           ✅                           |                      ✅                      |    ✅     |
 | [Polynomials](./polynomials/overview)     |                      ✅                       |                           ✅                           |                           ✅                           |                      ✅                      |    ❌     |
 | [Poseidon](primitives/hash#poseidon)      |                      ✅                       |                           ✅                           |                           ✅                           |                      ✅                      |    ✅     |
+| [Poseidon2](primitives/hash#poseidon2)    |                      ✅                       |                           ✅                           |                           ✅                           |                      ✅                      |    ✅     |
 
 #### Supported fields and operations
 
@@ -43,6 +44,7 @@ Each library has a corresponding crate. See [programmers guide](./programmers_gu
 | [NTT](primitives/ntt)                     |                        ✅                         |                                                 ✅                                                  |   ❌   |
 | Extension Field                           |                        ✅                         |                                                 ❌                                                  |   ✅   |
 | [Poseidon](primitives/hash#poseidon)      |                        ✅                         |                                                 ✅                                                  |   ✅   |
+| [Poseidon2](primitives/hash#poseidon2)    |                        ✅                         |                                                 ✅                                                  |   ✅   |
 
 ### Misc
 

diff --git a/docs/docs/icicle/primitives/hash.md b/docs/docs/icicle/primitives/hash.md
@@ -18,13 +18,13 @@ For scenarios where large datasets need to be hashed efficiently, ICICLE support
 
 ICICLE supports the following hash functions:
 
-1.  **Keccak-256**
-2.	**Keccak-512**
-3.	**SHA3-256**
-4.	**SHA3-512**
-5.	**Blake2s**
-6.	**Poseidon**
-7.	**Poseidon2**
+1. **Keccak-256**
+2. **Keccak-512**
+3. **SHA3-256**
+4. **SHA3-512**
+5. **Blake2s**
+6. **Poseidon**
+7. **Poseidon2**
 
 :::info
 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
 
 [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.
 
-
 ### Poseidon
 
 [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.
 
 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.
 
-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.
+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.
 
 The optional `domain_tag` pointer parameter enables domain separation, allowing isolation of hash outputs across different contexts or applications.
 
-
 ### Poseidon2
 
 [Poseidon2](https://eprint.iacr.org/2023/323.pdf) is a cryptographic hash function designed specifically for field elements.
 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.
 
 The optional `domain_tag` pointer parameter enables domain separation, allowing isolation of hash outputs across different contexts or applications.
 
+:::info
+
+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).
+
+:::
+
+:::info
+
+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).
+
+:::
+
+In the current version the padding is not supported and should be performed by the user.
 
 ## Using Hash API
 
@@ -84,21 +95,20 @@ auto poseidon = Poseidon::create<scalar_t>(t);
 // The domain tag acts as the first input to the hash function, with the remaining t-1 inputs following it.
 scalar_t domain_tag = scalar_t::zero(); // Example using zero; this can be set to any valid field element.
 auto poseidon_with_domain_tag = Poseidon::create<scalar_t>(t, &domain_tag);
-// This version of the hasher with a domain tag expects t-1 additional inputs for hashing.
 // Poseidon2 requires specifying the field-type and t parameter (supported 2, 3, 4, 8, 12, 16, 20, 24) as defined by
-// the Poseidon2 paper. For large fields (field width >= 254) the supported values of t are 2, 3, 4.
+// the Poseidon2 paper. For large fields (field width >= 252) the supported values of t are 2, 3, 4.
 auto poseidon2 = Poseidon2::create<scalar_t>(t); 
 // Optionally, Poseidon2 can accept a domain-tag, which is a field element used to separate applications or contexts.
 // The domain tag acts as the first input to the hash function, with the remaining t-1 inputs following it.
 scalar_t domain_tag = scalar_t::zero(); // Example using zero; this can be set to any valid field element.
 auto poseidon2_with_domain_tag = Poseidon2::create<scalar_t>(t, &domain_tag);
-// This version of the hasher with a domain tag expects t-1 additional inputs for hashing.
+// This version of the hasher with a domain tag expects t-1 inputs per hasher.
 ```
 
 ### 2. Hashing Data
 
 Once you have a hasher object, you can hash any input data by passing the input, its size, a configuration, and an output buffer:
-   
+
 ```cpp
 /**
  * @brief Perform a hash operation.
@@ -160,11 +170,11 @@ eIcicleErr err = keccak256.hash(input.data(), input.size() / config.batch, confi
 
 ### 4. Poseidon sponge function
 
-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.
+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.
 
 ### 5. Poseidon2 sponge function
 
-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.
+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.
 
 ### Supported Bindings