Merge pull request #264 from dusk-network/change_gadget

Make `composer` be the first param in gadgets

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Switch parameter for gadgets: `composer` should always be the first parameter
+
 ## [0.38.0] - 2024-04-24
 
 ### Changed

README.md

@@ -17,9 +17,7 @@ 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.
 
-## Examples
-
-### Hash
+## Example
 
 ```rust
 use rand::rngs::StdRng;
@@ -52,41 +50,6 @@ let merkle_hash = Hash::digest(Domain::Merkle4, &input[..4]);
 assert_ne!(merkle_hash, Hash::digest(Domain::Other, &input[..4]));
 ```
 
-### Encryption
-
-```rust
-#![cfg(feature = "encryption")]
-
-use dusk_bls12_381::BlsScalar;
-use dusk_jubjub::{JubJubScalar, GENERATOR_EXTENDED, dhke};
-use dusk_poseidon::{decrypt, encrypt, Error};
-use ff::Field;
-use rand::rngs::StdRng;
-use rand::SeedableRng;
-
-// generate the keys and nonce needed for the encryption
-let mut rng = StdRng::seed_from_u64(0x42424242);
-let alice_secret = JubJubScalar::random(&mut rng);
-let alice_public = GENERATOR_EXTENDED * &alice_secret;
-let bob_secret = JubJubScalar::random(&mut rng);
-let bob_public = GENERATOR_EXTENDED * &bob_secret;
-let nonce = BlsScalar::random(&mut rng);
-
-// Alice encrypts a message of 3 BlsScalar using Diffie-Hellman key exchange
-// with Bob's public key
-let message = vec![BlsScalar::from(10), BlsScalar::from(20), BlsScalar::from(30)];
-let shared_secret = dhke(&alice_secret, &bob_public);
-let cipher = encrypt(&message, &shared_secret, &nonce)
-    .expect("Encryption should pass");
-
-// Bob decrypts the cipher using Diffie-Hellman key exchange with Alice's public key
-let shared_secret = dhke(&bob_secret, &alice_public);
-let decrypted_message = decrypt(&cipher, &shared_secret, &nonce)
-    .expect("Decryption should pass");
-
-assert_eq!(decrypted_message, message);
-```
-
 ## Benchmarks
 
 There are benchmarks for hashing, encrypting and decrypting in their native form, operating on `Scalar`, and for a zero-knowledge circuit proof generation and verification.

benches/hash.rs

@@ -39,7 +39,7 @@ impl Circuit for SpongeCircuit {
             });
 
         let output_witness =
-            HashGadget::digest(Domain::Merkle4, composer, &w_message);
+            HashGadget::digest(composer, Domain::Merkle4, &w_message);
         composer.assert_equal_constant(output_witness[0], 0, Some(self.output));
 
         Ok(())

src/encryption.rs

@@ -4,6 +4,44 @@
 //
 // Copyright (c) DUSK NETWORK. All rights reserved.
 
+//! Encryption using the poseidon hash function:
+//!
+//! ## Example
+//!
+//! ```rust
+//! #![cfg(feature = "encryption")]
+//!
+//! use dusk_bls12_381::BlsScalar;
+//! use dusk_jubjub::{JubJubScalar, GENERATOR_EXTENDED, dhke};
+//! use dusk_poseidon::{decrypt, encrypt, Error};
+//! use ff::Field;
+//! use rand::rngs::StdRng;
+//! use rand::SeedableRng;
+//!
+//! // generate the keys and nonce needed for the encryption
+//! let mut rng = StdRng::seed_from_u64(0x42424242);
+//! let alice_secret = JubJubScalar::random(&mut rng);
+//! let alice_public = GENERATOR_EXTENDED * &alice_secret;
+//! let bob_secret = JubJubScalar::random(&mut rng);
+//! let bob_public = GENERATOR_EXTENDED * &bob_secret;
+//! let nonce = BlsScalar::random(&mut rng);
+//!
+//! // Alice encrypts a message of 3 BlsScalar using Diffie-Hellman key exchange
+//! // with Bob's public key
+//! let message = vec![BlsScalar::from(10), BlsScalar::from(20), BlsScalar::from(30)];
+//! let shared_secret = dhke(&alice_secret, &bob_public);
+//! let cipher = encrypt(&message, &shared_secret, &nonce)
+//!     .expect("Encryption should pass");
+//!
+//! // Bob decrypts the cipher using Diffie-Hellman key exchange with Alice's
+//! // public key
+//! let shared_secret = dhke(&bob_secret, &alice_public);
+//! let decrypted_message = decrypt(&cipher, &shared_secret, &nonce)
+//!     .expect("Decryption should pass");
+//!
+//! assert_eq!(decrypted_message, message);
+//! ```
+
 #[cfg(feature = "zk")]
 pub(crate) mod gadget;
 

src/hash/gadget.rs

@@ -104,8 +104,8 @@ impl<'a> HashGadget<'a> {
     /// given domain and input, e.g. using [`Domain::Merkle4`] with an input
     /// anything other than 4 Scalar.
     pub fn digest(
-        domain: Domain,
         composer: &mut Composer,
+        domain: Domain,
         input: &'a [Witness],
     ) -> Vec<Witness> {
         let mut hash = Self::new(domain);
@@ -120,8 +120,8 @@ impl<'a> HashGadget<'a> {
     /// given domain and input, e.g. using [`Domain::Merkle4`] with an input
     /// anything other than 4 Scalar.
     pub fn digest_truncated(
-        domain: Domain,
         composer: &mut Composer,
+        domain: Domain,
         input: &'a [Witness],
     ) -> Vec<Witness> {
         let mut hash = Self::new(domain);

tests/hash.rs

@@ -93,7 +93,7 @@ impl<const L: usize> Circuit for TestCircuit<L> {
 
         // check that the gadget result is as expected
         let gadget_output =
-            HashGadget::digest(Domain::Other, composer, &input_witnesses);
+            HashGadget::digest(composer, Domain::Other, &input_witnesses);
         composer.assert_equal_constant(gadget_output[0], 0, Some(self.output));
 
         Ok(())
@@ -173,8 +173,8 @@ impl<const L: usize> Circuit for TestTruncatedCircuit<L> {
         let mut hash = HashGadget::new(Domain::Other);
         hash.update(&input_witnesses);
         let gadget_output = HashGadget::digest_truncated(
-            Domain::Other,
             composer,
+            Domain::Other,
             &input_witnesses,
         );
         composer.assert_equal_constant(