update poseidon2 docs

docs/README.md

@@ -1,39 +1,97 @@
-# 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
 
 ```
-$ npm start
+npm install
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+## 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
 
-### Build
+In order to create a new version, run the following:
 
+```sh
+npm run docusaurus docs:version <version to create>
 ```
-$ npm run build
+
+For example:
+
+Assuming the next version is 5.6.0, we would run the following:
+
+```sh
+npm run docusaurus docs:version 5.6.0
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+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
 
-### Deployment
+1. Remove the version from versions.json.
 
-Using SSH:
+[
+  "3.2.0",
+  "3.1.0",
+  "3.0.0",
+  "2.8.0",
+- "1.10.1"
+]
+
+
+2. Delete the versioned docs directory for that version. Example: versioned_docs/version-1.10.1.
+3. Delete the versioned sidebars file. Example: versioned_sidebars/version-1.10.1-sidebars.json.
+
+## Local development
+
+To render the site, run the following
 
 ```
-$ USE_SSH=true npm run deploy
+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

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
 

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