feat: Poseidon2 hash function (#673)

- Lacks support for sponge hash
- Lacks support for t>4 cases for large fields (>4B)

Co-authored-by: danny-shterman <[email protected]>
Co-authored-by: Leon Hibnik <[email protected]>
Co-authored-by: LeonHibnik <[email protected]>
Co-authored-by: Yuval Shekel <[email protected]>

Author: 4 people

docs/docs/icicle/golang-bindings/hash.md

@@ -16,7 +16,7 @@ Using the Hash package requires `go` version 1.22
 
 The ICICLE library provides Golang bindings for hashing using a variety of cryptographic hash functions. These hash functions are optimized for both general-purpose data and cryptographic operations such as multi-scalar multiplication, commitment generation, and Merkle tree construction.
 
-This guide will show you how to use the ICICLE hashing API in Golang with examples for common hash algorithms, such as Keccak-256, Keccak-512, SHA3-256, SHA3-512, Blake2s, and Poseidon.
+This guide will show you how to use the ICICLE hashing API in Golang with examples for common hash algorithms, such as Keccak-256, Keccak-512, SHA3-256, SHA3-512, Blake2s, Poseidon.
 
 ## Importing Hash Functions
 

docs/docs/icicle/primitives/hash.md

@@ -4,7 +4,7 @@
 
 ICICLE’s hashing system is designed to be flexible, efficient, and optimized for both general-purpose and cryptographic operations. Hash functions are essential in operations such as generating commitments, constructing Merkle trees, executing the Sumcheck protocol, and more.
 
-ICICLE provides an easy-to-use interface for hashing on both CPU and GPU, with transparent backend selection. You can choose between several hash algorithms such as Keccak-256, Keccak-512, SHA3-256, SHA3-512, Blake2s, Poseidon and more, which are optimized for processing both general data and cryptographic field elements or elliptic curve points.
+ICICLE provides an easy-to-use interface for hashing on both CPU and GPU, with transparent backend selection. You can choose between several hash algorithms such as Keccak-256, Keccak-512, SHA3-256, SHA3-512, Blake2s, Poseidon, Poseidon2 and more, which are optimized for processing both general data and cryptographic field elements or elliptic curve points.
 
 ## Hashing Logic
 
@@ -24,6 +24,7 @@ ICICLE supports the following hash functions:
 4.	**SHA3-512**
 5.	**Blake2s**
 6.	**Poseidon**
+7.	**Poseidon2**
 
 :::info
 Additional hash functions might be added in the future. Stay tuned!
@@ -50,6 +51,15 @@ Currently the Poseidon implementation is the Optimized Poseidon (https://hackmd.
 
 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.
+
+
 ## Using Hash API
 
 ### 1. Creating a Hasher Object
@@ -60,6 +70,7 @@ First, you need to create a hasher object for the specific hash function you wan
 #include "icicle/hash/keccak.h"
 #include "icicle/hash/blake2s.h"
 #include "icicle/hash/poseidon.h"
+#include "icicle/hash/poseidon2.h"
 
 // Create hasher instances for different algorithms
 auto keccak256 = Keccak256::create();
@@ -74,6 +85,14 @@ auto poseidon = Poseidon::create<scalar_t>(t);
 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.
+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.
 ```
 
 ### 2. Hashing Data
@@ -139,9 +158,13 @@ auto output = std::make_unique<std::byte[]>(32 * config.batch); // Allocate outp
 eIcicleErr err = keccak256.hash(input.data(), input.size() / config.batch, config, output.get());
 ```
 
-### 4. Posidon sponge function
+### 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.
+
+### 5. Poseidon2 sponge function
 
-Currently the poseidon sponge function (Sec 2.1 of https://eprint.iacr.org/2019/458.pdf ) isn't implemented.
+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.
 
 ### Supported Bindings
 

docs/docs/icicle/primitives/poseidon.md

@@ -62,9 +62,9 @@ So for Poseidon of arity 2 and input of size 1024 * 2, we would expect 1024 elem
 
 Poseidon is extremely customizable and using different constants will produce different hashes, security levels and performance results.
 
-We support pre-calculated and optimized constants for each of the [supported curves](../libraries#supported-curves-and-operations).The constants can be found [here](https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/hash/poseidon_constants) and are labeled clearly per curve `<curve_name>_poseidon.h`.
+We support pre-calculated and optimized constants for each of the [supported curves](../libraries#supported-curves-and-operations).The constants can be found [here](https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/poseidon/constants) and are labeled clearly per curve `<curve_name>_poseidon.h`.
 
-If you wish to generate your own constants you can use our python script which can be found [here](https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/hash/poseidon_constants/generate_parameters.py).
+If you wish to generate your own constants you can use our python script which can be found [here](https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/poseidon/constants/generate_parameters.py).
 
 Prerequisites:
 

docs/docs/icicle/primitives/poseidon2.md

@@ -88,3 +88,4 @@ Bn254TreeBuilder::build_merkle_tree(
 )
 .unwrap();
 ```
+

icicle/CMakeLists.txt

@@ -69,6 +69,7 @@ option(G2 "Build G2 MSM" ON)
 option(EXT_FIELD "Build extension field" ON)
 option(HASH "Build hashes and tree builders" ON)
 option(POSEIDON "Build poseidon hash" ON)
+option(POSEIDON2 "Build poseidon2 hash" ON)
 option(SANITIZE "Enable memory address sanitizer" OFF)
 
 # address sanitizer
@@ -179,4 +180,5 @@ endif()
 
 if (BUILD_TESTS)
   add_subdirectory(tests)
-endif()
+endif()
+

icicle/backend/cpu/CMakeLists.txt

@@ -15,6 +15,9 @@ if (FIELD)
     if (POSEIDON)
         target_sources(icicle_field PRIVATE src/hash/cpu_poseidon.cpp)
     endif()
+    if (POSEIDON2)
+        target_sources(icicle_field PRIVATE src/hash/cpu_poseidon2.cpp)
+    endif()
     target_include_directories(icicle_field PRIVATE include)
 endif() # FIELD
 

icicle/backend/cpu/src/hash/cpu_poseidon.cpp

@@ -4,28 +4,28 @@
 #include <vector>
 
 #if FIELD_ID == BN254
-  #include "icicle/hash/poseidon_constants/bn254_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/bn254_poseidon.h"
 using namespace poseidon_constants_bn254;
 #elif FIELD_ID == BLS12_381
-  #include "icicle/hash/poseidon_constants/bls12_381_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/bls12_381_poseidon.h"
 using namespace poseidon_constants_bls12_381;
 #elif FIELD_ID == BLS12_377
-  #include "icicle/hash/poseidon_constants/bls12_377_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/bls12_377_poseidon.h"
 using namespace poseidon_constants_bls12_377;
 #elif FIELD_ID == BW6_761
-  #include "icicle/hash/poseidon_constants/bw6_761_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/bw6_761_poseidon.h"
 using namespace poseidon_constants_bw6_761;
 #elif FIELD_ID == GRUMPKIN
-  #include "icicle/hash/poseidon_constants/grumpkin_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/grumpkin_poseidon.h"
 using namespace poseidon_constants_grumpkin;
 #elif FIELD_ID == M31
-  #include "icicle/hash/poseidon_constants/m31_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/m31_poseidon.h"
 using namespace poseidon_constants_m31;
 #elif FIELD_ID == BABY_BEAR
-  #include "icicle/hash/poseidon_constants/babybear_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/babybear_poseidon.h"
 using namespace poseidon_constants_babybear;
 #elif FIELD_ID == STARK_252
-  #include "icicle/hash/poseidon_constants/stark252_poseidon.h"
+  #include "icicle/hash/poseidon_constants/constants/stark252_poseidon.h"
 using namespace poseidon_constants_stark252;
 #endif
 
@@ -292,4 +292,4 @@ namespace icicle {
 
   REGISTER_CREATE_POSEIDON_BACKEND("CPU", create_cpu_poseidon_hash_backend);
 
-} // namespace icicle
+} // namespace icicle