Struct Poseidon2 

pub struct Poseidon2();

Implementation of the Poseidon2 hash function with 256-bit output.

The implementation follows the original specification and its accompanying reference implementation.

The parameters used to instantiate the function are:

• Field: 64-bit prime field with modulus 2^64 - 2^32 + 1.
• State width: 12 field elements.
• Capacity size: 4 field elements.
• S-Box degree: 7.
• Rounds: There are 2 different types of rounds, called internal and external, and are structured as follows:

• Initial External rounds (IE): add_constants → apply_sbox → apply_matmul_external.
• Internal rounds: add_constants → apply_sbox → apply_matmul_internal, where the constant addition and sbox application apply only to the first entry of the state.
• Terminal External rounds (TE): add_constants → apply_sbox → apply_matmul_external.
• An additional apply_matmul_external is inserted at the beginning in order to protect against some recent attacks.

The above parameters target a 128-bit security level. The digest consists of four field elements and it can be serialized into 32 bytes (256 bits).

Hash output consistency

Functions hash_elements(), merge(), and merge_with_int() are internally consistent. That is, computing a hash for the same set of elements using these functions will always produce the same result. For example, merging two digests using merge() will produce the same result as hashing 8 elements which make up these digests using hash_elements() function.

However, hash() function is not consistent with functions mentioned above. For example, if we take two field elements, serialize them to bytes and hash them using hash(), the result will differ from the result obtained by hashing these elements directly using hash_elements() function. The reason for this difference is that hash() function needs to be able to handle arbitrary binary strings, which may or may not encode valid field elements - and thus, deserialization procedure used by this function is different from the procedure used to deserialize valid field elements.

Thus, if the underlying data consists of valid field elements, it might make more sense to deserialize them into field elements and then hash them using hash_elements() function rather than hashing the serialized bytes using hash() function.

Domain separation

merge_in_domain() hashes two digests into one digest with some domain identifier and the current implementation sets the second capacity element to the value of this domain identifier. Using a similar argument to the one formulated for domain separation in Appendix C of the specifications, one sees that doing so degrades only pre-image resistance, from its initial bound of c.log_2(p), by as much as the log_2 of the size of the domain identifier space. Since pre-image resistance becomes the bottleneck for the security bound of the sponge in overwrite-mode only when it is lower than 2^128, we see that the target 128-bit security level is maintained as long as the size of the domain identifier space, including for padding, is less than 2^128.

Hashing of empty input

The current implementation hashes empty input to the zero digest [0, 0, 0, 0]. This has the benefit of requiring no calls to the Poseidon2 permutation when hashing empty input.

Implementations

impl Poseidon2

pub const COLLISION_RESISTANCE: u32 = 128

Target collision resistance level in bits.

pub const NUM_EXTERNAL_ROUNDS_HALF: usize = NUM_EXTERNAL_ROUNDS_HALF

Number of initial or terminal external rounds.

pub const NUM_INTERNAL_ROUNDS: usize = NUM_INTERNAL_ROUNDS

Number of internal rounds.

pub const STATE_WIDTH: usize = STATE_WIDTH

Sponge state is set to 12 field elements or 768 bytes; 8 elements are reserved for the rate and the remaining 4 elements are reserved for the capacity.

pub const RATE_RANGE: Range<usize> = RATE_RANGE

The rate portion of the state is located in elements 0 through 7 (inclusive).

pub const RATE0_RANGE: Range<usize> = RATE0_RANGE

The first 4-element word of the rate portion.

pub const RATE1_RANGE: Range<usize> = RATE1_RANGE

The second 4-element word of the rate portion.

pub const CAPACITY_RANGE: Range<usize> = CAPACITY_RANGE

The capacity portion of the state is located in elements 8, 9, 10, and 11.

pub const DIGEST_RANGE: Range<usize> = DIGEST_RANGE

The output of the hash function can be read from state elements 0, 1, 2, and 3 (the first word of the state).

pub const MAT_DIAG: [Felt; 12] = MAT_DIAG

Matrix used for computing the linear layers of internal rounds.

pub const ARK_EXT_INITIAL: [[Felt; 12]; 4] = ARK_EXT_INITIAL

Round constants added to the hasher state.

pub const ARK_EXT_TERMINAL: [[Felt; 12]; 4] = ARK_EXT_TERMINAL

pub const ARK_INT: [Felt; 22] = ARK_INT

pub fn hash(bytes: &[u8]) -> Word

Returns a hash of the provided sequence of bytes.

pub fn apply_permutation(state: &mut [Felt; 12])

Applies the Poseidon2 permutation to the provided state in-place.

pub fn hash_elements<E>(elements: &[E]) -> Word

where E: BasedVectorSpace<Felt>,

Returns a hash of the provided field elements.

pub fn merge(values: &[Word; 2]) -> Word

Returns a hash of two digests. This method is intended for use in construction of Merkle trees and verification of Merkle paths.

pub fn merge_many(values: &[Word]) -> Word

Returns a hash of multiple digests.

pub fn merge_with_int(seed: Word, value: u64) -> Word

Returns a hash of a digest and a u64 value.

pub fn merge_in_domain(values: &[Word; 2], domain: Felt) -> Word

Returns a hash of two digests and a domain identifier.

pub fn apply_matmul_external(state: &mut [Felt; 12])

Applies the M_E (external) linear layer to the state in-place.

This basically takes any 4 x 4 MDS matrix M and computes the matrix-vector product with the matrix defined by [[2M, M, ..., M], [M, 2M, ..., M], ..., [M, M, ..., 2M]].

Given the structure of the above matrix, we can compute the product of the state with matrix [M, M, ..., M] and compute the final result using a few addition.

pub fn matmul_internal(state: &mut [Felt; 12], mat_diag: [Felt; 12])

Applies the M_I (internal) linear layer to the state in-place.

The matrix is given by its diagonal entries with the remaining entries set equal to 1. Hence, given the sum of the state entries, the matrix-vector product is computed using a multiply-and-add per state entry.

pub fn add_rc(state: &mut [Felt; 12], ark: &[Felt; 12])

Adds the round constants to the state in-place.

pub fn apply_sbox(state: &mut [Felt; 12])

Applies the S-box (x^7) to each element of the state in-place.

Trait Implementations

impl Clone for Poseidon2

fn clone(&self) -> Poseidon2

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Poseidon2

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for Poseidon2

fn eq(&self, other: &Poseidon2) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Poseidon2

impl Eq for Poseidon2

impl StructuralPartialEq for Poseidon2