Integrate new SAFE framework

This commit includes a big refactor of the code including the
introduction of a `Hash` struct for hashing different input.

Resolves #202 #248

.github/workflows/dusk_ci.yml

@@ -26,12 +26,6 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo bench --features=cipher,zk --no-run
 
-  check_merkle:
-    name: Check merkle compiles without zk
-    uses: dusk-network/.github/.github/workflows/run-tests.yml@main
-    with:
-      test_flags: --features=merkle --no-run
-
   check_cipher:
     name: Check cipher compiles without zk
     uses: dusk-network/.github/.github/workflows/run-tests.yml@main
@@ -42,4 +36,4 @@ jobs:
     name: Tests all
     uses: dusk-network/.github/.github/workflows/run-tests.yml@main
     with:
-      test_flags: --features=zk,cipher,merkle,rkyv-impl,size_32
+      test_flags: --features=zk,cipher,rkyv-impl,size_32

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `Hash` struct [#202]
+
+### Changed
+
+- Refactor code with the introduction of SAFE framework [#248]
+
+### Removed
+
+- Remove `perm_uses` module as it is obsolete with the introduction of SAFE [#248]
+- Remove `merkle` feature with the introduction of SAFE [#248]
+
 ## [0.35.0] - 2024-02-28
 
 ### Changed
@@ -28,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add the code for the hades permutation to crate [#240]
 - Add internal `permute` and `permute_gadget` functions to `hades` module [#243]
+- Add SAFE dependency [#248]
 
 ## [0.34.0] - 2024-01-24
 
@@ -451,13 +465,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Variants of sponge for `Scalar` & `Gadget(Variable/LC)`.
 
 <!-- ISSUES -->
+[#248]: https://github.com/dusk-network/poseidon252/issues/248
 [#246]: https://github.com/dusk-network/poseidon252/issues/246
 [#243]: https://github.com/dusk-network/poseidon252/issues/243
 [#240]: https://github.com/dusk-network/poseidon252/issues/240
 [#215]: https://github.com/dusk-network/poseidon252/issues/215
 [#212]: https://github.com/dusk-network/poseidon252/issues/212
 [#206]: https://github.com/dusk-network/poseidon252/issues/206
 [#203]: https://github.com/dusk-network/poseidon252/issues/203
+[#202]: https://github.com/dusk-network/poseidon252/issues/202
 [#200]: https://github.com/dusk-network/poseidon252/issues/200
 [#198]: https://github.com/dusk-network/poseidon252/issues/198
 [#197]: https://github.com/dusk-network/Poseidon252/issues/197

Cargo.toml

@@ -14,19 +14,20 @@ dusk-bls12_381 = { version = "0.13", default-features = false }
 dusk-jubjub = { version = "0.14", default-features = false }
 dusk-bytes = "0.1"
 dusk-plonk = { version = "0.19", default-features = false, features = ["alloc"], optional = true }
+dusk-safe = "0.1"
 rkyv = { version = "0.7", optional = true, default-features = false }
 bytecheck = { version = "0.6", optional = true, default-features = false }
 
 [dev-dependencies]
 criterion = "0.3"
 rand = { version = "0.8", default-features = false, features = ["getrandom", "std_rng"] }
 ff = { version = "0.13", default-features = false }
+once_cell = "1"
 
 [features]
 zk = [
     "dusk-plonk",
 ]
-merkle = []
 cipher = []
 size_16 = ["rkyv/size_16"]
 size_32 = ["rkyv/size_32"]
@@ -58,7 +59,7 @@ incremental = false
 codegen-units = 1
 
 [[bench]]
-name = "sponge"
+name = "hash"
 harness = false
 required-features = ["zk"]
 

README.md

@@ -6,62 +6,60 @@
 
 Reference implementation for the Poseidon Hashing algorithm.
 
-#### Reference
-
+Reference:
 [Starkad and Poseidon: New Hash Functions for Zero Knowledge Proof Systems](https://eprint.iacr.org/2019/458.pdf)
 
-This repository has been created so there's a unique library that holds the tools & functions
-required to perform Poseidon Hashes.
+This repository has been created so there's a unique library that holds the tools & functions required to perform Poseidon Hashes on field elements of the bls12-381 elliptic curve.
 
-These hashes heavily rely on the Hades design for its inner permutation.
+The hash uses the Hades design for its inner permutation and the [SAFE](https://eprint.iacr.org/2023/522.pdf) framework for contstructing the sponge.
 
-**The library provides the two hashing techniques of Poseidon:**
+The library provides the two hashing techniques of Poseidon:
+- The 'normal' hashing functionalities operating on `BlsScalar`.
+- The 'gadget' hashing functionalities that build a circuit which outputs the hash.
 
-## Sponge Hash
+## Example
 
-The `Sponge` technique in Poseidon allows to hash an unlimited amount of data
-into a single `Scalar`.
-The sponge hash technique requires a padding to be applied before the data can
-be hashed.
+```rust
+use rand::rngs::StdRng;
+use rand::SeedableRng;
 
-This is done to avoid hash collisions as stated in the paper of the Poseidon Hash
-algorithm. See: <https://eprint.iacr.org/2019/458.pdf>.
-The inputs of the `sponge_hash` are always `Scalar` or need to be capable of being represented
-as it.
+use dusk_poseidon::{Domain, Hash};
+use dusk_bls12_381::BlsScalar;
+use ff::Field;
 
-The module provides two sponge hash implementations:
+// generate random input
+let mut rng = StdRng::seed_from_u64(0xbeef);
+let mut input = [BlsScalar::zero(); 42];
+for scalar in input.iter_mut() {
+    *scalar = BlsScalar::random(&mut rng);
+}
 
-- Sponge hash using `Scalar` as backend. Which hashes the inputted `Scalar`s and returns a single
-  `Scalar`.
+// digest the input all at once
+let hash = Hash::digest(Domain::Other, &input);
 
-- Sponge hash gadget using `dusk_plonk::Witness` as a backend. This technique is used/required
-  when you want to proof pre-images of unconstrained data inside Zero-Knowledge PLONK circuits.
+// update the input gradually
+let mut hasher = Hash::new(Domain::Other);
+hasher.update(&input[..3]);
+hasher.update(&input[3..]);
+assert_eq!(hash, hasher.finalize());
 
-## Documentation
+// create a hash used for merkle tree hashing with arity = 4
+let merkle_hash = Hash::digest(Domain::Merkle4, &input[..4]);
 
-This crate contains info about all the functions that the library provides as well as the
-documentation regarding the data structures that it exports. To check it, please feel free to go to
-the [documentation page](https://dusk-network.github.io/Poseidon252/poseidon252/index.html)
+// which is different when another domain is used
+assert_ne!(merkle_hash, Hash::digest(Domain::Other, &input[..4]));
+```
 
 ## Benchmarks
 
 There are benchmarks for `sponge` and `cipher` in their native form, operating on `Scalar`, and as a zero-knowledge gadget, using `Witness`.
 
 To run all benchmarks on your machine, run
 ```shell
-cargo bench
+cargo bench --features=zk,cipher
 ```
 in the repository.
 
-To run a specific benchmark, run
-```shell
-cargo bench --bench <name>
-```
-where you replace `<name>` with the benchmark name. For example to run the benchmarks for the poseidon cipher encription from the file 'benches/cipher_encrypt.rs', you would need to run
-```shell
-cargo bench --benches cipher_encrypt
-```
-
 ## Licensing
 
 This code is licensed under Mozilla Public License Version 2.0 (MPL-2.0). Please see [LICENSE](https://github.com/dusk-network/plonk/blob/master/LICENSE) for further info.

src/cipher.rs

@@ -24,7 +24,7 @@
 //! use core::ops::Mul;
 //! use dusk_bls12_381::BlsScalar;
 //! use dusk_jubjub::{dhke, JubJubExtended, JubJubScalar, GENERATOR};
-//! use dusk_poseidon::cipher::PoseidonCipher;
+//! use dusk_poseidon::PoseidonCipher;
 //! use rand::rngs::OsRng;
 //! use ff::Field;
 //!
@@ -89,17 +89,15 @@
 use dusk_bls12_381::BlsScalar;
 use dusk_bytes::{DeserializableSlice, Error as BytesError, Serializable};
 use dusk_jubjub::JubJubAffine;
+use dusk_safe::Safe;
 
-use crate::hades::{permute, WIDTH};
+use crate::hades::{ScalarPermutation, WIDTH};
 
 #[cfg(feature = "rkyv-impl")]
 use bytecheck::CheckBytes;
 #[cfg(feature = "rkyv-impl")]
 use rkyv::{Archive, Deserialize, Serialize};
 
-#[cfg(feature = "zk")]
-pub use zk::{decrypt, encrypt};
-
 const MESSAGE_CAPACITY: usize = 2;
 const CIPHER_SIZE: usize = MESSAGE_CAPACITY + 1;
 const CIPHER_BYTES_SIZE: usize = CIPHER_SIZE * BlsScalar::SIZE;
@@ -202,7 +200,7 @@ impl PoseidonCipher {
         let mut cipher = [zero; CIPHER_SIZE];
         let mut state = PoseidonCipher::initial_state(secret, *nonce);
 
-        permute(&mut state);
+        ScalarPermutation::new().permute(&mut state);
 
         (0..MESSAGE_CAPACITY).for_each(|i| {
             state[i + 1] += if i < message.len() {
@@ -214,7 +212,7 @@ impl PoseidonCipher {
             cipher[i] = state[i + 1];
         });
 
-        permute(&mut state);
+        ScalarPermutation::new().permute(&mut state);
         cipher[MESSAGE_CAPACITY] = state[1];
 
         PoseidonCipher::new(cipher)
@@ -232,14 +230,14 @@ impl PoseidonCipher {
         let mut message = [zero; MESSAGE_CAPACITY];
         let mut state = PoseidonCipher::initial_state(secret, *nonce);
 
-        permute(&mut state);
+        ScalarPermutation::new().permute(&mut state);
 
         (0..MESSAGE_CAPACITY).for_each(|i| {
             message[i] = self.cipher[i] - state[i + 1];
             state[i + 1] = self.cipher[i];
         });
 
-        permute(&mut state);
+        ScalarPermutation::new().permute(&mut state);
 
         if self.cipher[MESSAGE_CAPACITY] != state[1] {
             return None;
@@ -250,11 +248,12 @@ impl PoseidonCipher {
 }
 
 #[cfg(feature = "zk")]
-mod zk {
+pub mod zk {
     use super::PoseidonCipher;
-    use crate::hades::{permute_gadget, WIDTH};
+    use crate::hades::{GadgetPermutaiton, WIDTH};
 
     use dusk_plonk::prelude::*;
+    use dusk_safe::Safe;
 
     impl PoseidonCipher {
         /// Returns the initial state of the encryption within a composer
@@ -298,7 +297,7 @@ mod zk {
         let mut state =
             PoseidonCipher::initial_state_circuit(composer, ks0, ks1, nonce);
 
-        permute_gadget(composer, &mut state);
+        GadgetPermutaiton::new(composer).permute(&mut state);
 
         (0..PoseidonCipher::capacity()).for_each(|i| {
             let x = if i < message.len() {
@@ -315,7 +314,7 @@ mod zk {
             cipher[i] = state[i + 1];
         });
 
-        permute_gadget(composer, &mut state);
+        GadgetPermutaiton::new(composer).permute(&mut state);
         cipher[PoseidonCipher::capacity()] = state[1];
 
         cipher
@@ -338,7 +337,7 @@ mod zk {
         let mut state =
             PoseidonCipher::initial_state_circuit(composer, ks0, ks1, nonce);
 
-        permute_gadget(composer, &mut state);
+        GadgetPermutaiton::new(composer).permute(&mut state);
 
         (0..PoseidonCipher::capacity()).for_each(|i| {
             let constraint = Constraint::new()
@@ -352,7 +351,7 @@ mod zk {
             state[i + 1] = cipher[i];
         });
 
-        permute_gadget(composer, &mut state);
+        GadgetPermutaiton::new(composer).permute(&mut state);
 
         composer.assert_equal(cipher[PoseidonCipher::capacity()], state[1]);
 

src/error.rs

@@ -0,0 +1,31 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) DUSK NETWORK. All rights reserved.
+
+use dusk_safe::Error as SafeError;
+
+/// Defines all possible error variants for SAFE
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Error {
+    /// A call to during the lifetime of the [`safe::Sponge`] that doesn't fit
+    /// the io-pattern.
+    IOPatternViolation,
+
+    /// An invalid io-pattern.
+    InvalidIOPattern,
+
+    /// The input doesn't yield enough input elements.
+    TooFewInputElements,
+}
+
+impl From<SafeError> for Error {
+    fn from(safe_error: SafeError) -> Self {
+        match safe_error {
+            SafeError::IOPatternViolation => Self::IOPatternViolation,
+            SafeError::InvalidIOPattern => Self::InvalidIOPattern,
+            SafeError::TooFewInputElements => Self::TooFewInputElements,
+        }
+    }
+}