Table of Contents
Poseidon_rs is an implementation in Rust of the Poseidon family of hash function.
It is being developed in the context of the EIP 5988 which proposes to introduce a new precompiled contract implementing Poseidon hash function over finite fields in order to provide an improved interoperability between the EVM and ZK & Validity rollups.
It is a work in progress, do not use in production.
- EIP 5988: https://eips.ethereum.org/EIPS/eip-5988
- EIP 5988 discussion: https://ethereum-magicians.org/t/eip-5988-add-poseidon-hash-function-precompile/11772
- Poseidon paper: https://eips.ethereum.org/assets/eip-5988/papers/poseidon_paper.pdf
- Reference implementation: https://extgit.iaik.tugraz.at/krypto/hadeshash/-/tree/master/code
This section describes how a hash of a message
Poseidon uses the sponge/squeeze technique to hash a message with an arbitrary size into a fixed-size output (see Fig1).
The sponge has a state
A sponge supports 2 operations: it can either absorb field elements or squeeze elements out.
To absorb a message of
To squeeze elements out, the sponge returns all or a part of its outer state and applies the Poseidon-permutation to its state.
To hash a message, we first absorb it entirely and then squeeze the required number of elements out.
The inner state is opaque: inputs don't directly modify it and it is never part of outputs. It is essential for security.
Our implementation hash messages of length a multiple of the rate only. Supporting variable-length messages would require a sponge-compliant padding rule.
A Poseidon permutation behaves like a random permutation. To achieve this, it applies many rounds of simpler permutations. Rounds come in 2 flavours: the more secure full rounds and the more efficient partial rounds (see Fig3).
A round function consists of 3 transformations that modify the state:
- Ark: the round constants are added to the state.
- S-box: a substitution box,
$Sbox(x)=x^α$ , is applied with α chosen such that$gcd(α,p-1)=1$ . - Mix: the state is mixed through a multiplication by a
$t×t$ MDS matrix.
In a full round function, S-boxes are applied to the full state while a partial round function contains a single S-box. Detailed overviews of both functions are given in Fig4 and Fig5.
Hash's security depends on the selection of adequate round constants and MDS matrix. In turn, these constants depend on the finite field, the number of rounds, the rate and the capacity. This makes the Poseidon hash function family flexible, but one has to manage the parameters in some way.
Several propositions were made to overcome this difficulty in the context of EIP-5988, among them those proposed by vbuterin :
- Add an extra global execution context variable which stores which state sizes and round counts have been used before, and the MDS and RC values for those state sizes using some standard algorithm. When using a new (state size, round count), generate new values and charge extra gas for this.
- Generate parameters in real time.
- Pass parameters in as inputs.
As a first step, we have chosen the first approach. Different sets of parameters including MDS matrix and the round constants are hardcoded in the library, but one could extend it with other sets of parameters.
Parameters either pertains to the sponge construct or the permutation:
- Sponge:
- The rate and the capacity.
- Permutation:
- The finite field, completely specified by its size.
- The number of full and partial rounds.
- The round constants and the MDS matrix.
The following set of parameters are included in the library thus far:
- Starkware: https://github.com/starkware-industries/poseidon
- Mina: https://github.com/o1-labs/proof-systems/blob/ebe59f35f5cb6bb33fc0ed3c4cb5040d8cd81247/book/src/specs/poseidon.md
- Install Rust
To build poseidon from source:
cargo build --releaseThe build generates 2 libraries located in target/release:
- libposeidon.rlib is the rust library file
- libposeidon.so is a shared-library wrapping the rust library with a C-interface
You can add predefined poseidon variants with the features flag, for example:
cargo build --release --features starkwareThe variants dependency tree is like so:
| starkware
|-- sw2
|-- sw3
|-- sw4
|-- sw8
| mina
|-- pallas
|-- vesta
This means that selecting feature starkware enables all four subvariants: sw2, sw3, sw4 and sw8.
By default, the library will compile as no_std. In fact, it compiles at the core layer, without even alloc. However, no_std is omitted if the feature std is enabled.
The library can include C-bindings for hash functions through the c_bind feature. In that case, one would want to build a staticlib to link it into another program, using for example:
cargo rustc --crate-type staticlib --release --features c_bind,starkwareTo test the rust library:
cargo testTests for the C-interface are also available through golang in the c-bind-tests folder. From that folder, one can run tests like so:
go test -vNote that golang must be installed on your system to run the go_tests.
Finally, we can also test that the library compiles with no_std compatibility in the ensure-no-std folder. From there, we can compile the test package like so:
cargo rustc --target thumbv7em-none-eabihfThe test passes if it compiles. Note that you can use another no_std target if you wish, and need to have it installed in your environment.
See the open issues for a list of proposed features (and known issues).
- Top Feature Requests (Add your votes using the 👍 reaction)
- Top Bugs (Add your votes using the 👍 reaction)
- Newest Bugs
Reach out to the maintainer at one of the following places:
- GitHub Discussions
- Contact options listed on this GitHub profile
If you want to say thank you or/and support active development of poseidon-rs:
- Add a GitHub Star to the project.
- Tweet about the poseidon-rs.
- Write interesting articles about the project on Dev.to, Medium or your personal blog.
Together, we can make poseidon-rs better!
First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.
Please read our contribution guidelines, and thank you for being involved!
For a full list of all authors and contributors, see the contributors page.
poseidon-rs follows good practices of security, but 100% security cannot be assured. poseidon-rs is provided "as is" without any warranty. Use at your own risk.
For more information and to report security issues, please refer to our security documentation.
This project is licensed under the MIT license.
See LICENSE for more information.
This implementation is inspired by earlier rust implementations. We would like to thank arnaudcube and neptune’s contributors.