{"id":13804198,"url":"https://github.com/keep-starknet-strange/poseidon-rs","last_synced_at":"2025-07-11T01:32:48.932Z","repository":{"id":68129593,"uuid":"577291647","full_name":"keep-starknet-strange/poseidon-rs","owner":"keep-starknet-strange","description":"Poseidon Rust library","archived":false,"fork":false,"pushed_at":"2023-03-13T09:56:29.000Z","size":1622,"stargazers_count":36,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-18T20:50:20.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keep-starknet-strange.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-12-12T12:17:23.000Z","updated_at":"2024-08-12T12:08:15.000Z","dependencies_parsed_at":"2024-01-21T20:13:12.930Z","dependency_job_id":null,"html_url":"https://github.com/keep-starknet-strange/poseidon-rs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-starknet-strange%2Fposeidon-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-starknet-strange%2Fposeidon-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-starknet-strange%2Fposeidon-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-starknet-strange%2Fposeidon-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keep-starknet-strange","download_url":"https://codeload.github.com/keep-starknet-strange/poseidon-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225669684,"owners_count":17505386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:00:43.551Z","updated_at":"2024-11-21T03:47:32.327Z","avatar_url":"https://github.com/keep-starknet-strange.png","language":"Rust","funding_links":[],"categories":["Additional developer resources"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003ePoseidon-rs\u003c/h1\u003e\n  \u003cimg src=\"docs/images/poseidon_rs_img.png\" height=\"200\"\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://github.com/keep-starknet-strange/poseidon-rs/issues/new?assignees=\u0026labels=bug\u0026template=01_BUG_REPORT.md\u0026title=bug%3A+\"\u003eReport a Bug\u003c/a\u003e\n  -\n  \u003ca href=\"https://github.com/keep-starknet-strange/poseidon-rs/issues/new?assignees=\u0026labels=enhancement\u0026template=02_FEATURE_REQUEST.md\u0026title=feat%3A+\"\u003eRequest a Feature\u003c/a\u003e\n  -\n  \u003ca href=\"https://github.com/keep-starknet-strange/poseidon-rs/discussions\"\u003eAsk a Question\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cbr /\u003e\n\n[![GitHub Workflow Status](https://github.com/keep-starknet-strange/poseidon-rs/actions/workflows/test.yml/badge.svg)](https://github.com/keep-starknet-strange/poseidon-rs/actions/workflows/test.yml)\n[![Project license](https://img.shields.io/github/license/keep-starknet-strange/poseidon-rs.svg?style=flat-square)](LICENSE)\n[![Pull Requests welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=flat-square)](https://github.com/keep-starknet-strange/poseidon-rs/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)\n\n\u003c/div\u003e\n\n![](docs/images/poseidon-rs.gif)\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [About](#about)\n- [Warning](#warning)\n- [Reference](#reference)\n- [Implementation Design](#implementation-design)\n  - [Poseidon Hash Function Overview](#poseidon-hash-function-overview)\n  - [Poseidon Permutation](#poseidon-permutation)\n  - [Round Function](#round-function)\n  - [Constants Selection](#constants-selection)  \n  - [Parameters](#parameters)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Build](#build)\n  - [Test](#test)\n- [Roadmap](#roadmap)\n- [Support](#support)\n- [Project assistance](#project-assistance)\n- [Contributing](#contributing)\n- [Authors \\\u0026 contributors](#authors--contributors)\n- [Security](#security)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n\u003c/details\u003e\n\n## About\n\n\u003e**Poseidon_rs** is an implementation in Rust of the Poseidon family of hash function.\n\nIt is being developed in the context of the [EIP 5988](https://eips.ethereum.org/EIPS/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 \u0026 Validity rollups.  \n\n## Warning\n\nIt is a work in progress, do not use in production.\n\n## Reference\n\n- EIP 5988: https://eips.ethereum.org/EIPS/eip-5988\n- EIP 5988 discussion: https://ethereum-magicians.org/t/eip-5988-add-poseidon-hash-function-precompile/11772\n- Poseidon paper: https://eips.ethereum.org/assets/eip-5988/papers/poseidon_paper.pdf\n- Reference implementation: https://extgit.iaik.tugraz.at/krypto/hadeshash/-/tree/master/code\n\n## Implementation Design\n\n### Poseidon Hash Function Overview\n\nThis section describes how a hash of a message $M$ is computed using Poseidon.\n\nPoseidon uses the sponge/squeeze technique to hash a message with an arbitrary size into a fixed-size output (see [Fig1](#figure-1-global-overview-of-a-poseidon-hash)).\n\nThe sponge has a state $S = (S_{1}, …, S_{t})$ made of $t$ field elements, initialized to zero. The state is divided into the outer state and the inner state, made of $r$ (rate) and $c$ (capacity) elements respectively.\n\n\u003cdiv align=\"center\"\u003e\n \n  #### **Figure 1. Global overview of a Poseidon hash**\n  \u003cimg src=\"docs/images/rm-poseidon-fig-1.svg\"\u003e\n\u003c/div\u003e\n\nA sponge supports 2 operations: it can either absorb field elements or squeeze elements out.\n\nTo absorb a message of $r$ elements, the sponge adds the message to its outer state and applies the poseidon-permutation, leaving the sponge in a new state (see [Fig2](#figure-2-absorption)). More elements can be absorbed at will.\n\nTo squeeze elements out, the sponge returns all or a part of its outer state and applies the Poseidon-permutation to its state.\n\nTo hash a message, we first absorb it entirely and then squeeze the required number of elements out.\n\n\u003eThe inner state is opaque: inputs don't directly modify it and it is never part of outputs. It is essential for security.\n\n\u003cdiv align=\"center\"\u003e\n\n  #### **Figure 2. Absorption**\n  \u003cimg src=\"docs/images/rm-poseidon-fig-2.svg\"\u003e\n\u003c/div\u003e\n\n\n\u003eOur implementation hash messages of length a multiple of the rate only. Supporting variable-length messages would require a sponge-compliant padding rule. \n\n\n### Poseidon Permutation \n\nA 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](#figure-3-poseidon-permutation)).\n\n\u003cdiv align=\"center\"\u003e\n\n  #### **Figure 3. Poseidon permutation**\n  \u003cimg src=\"docs/images/rm-poseidon-fig-3.svg\"\u003e\n\u003c/div\u003e\n\n### Round Function\n\nA round function consists of 3 transformations that modify the state:\n- Ark: the round constants are added to the state.\n- S-box: a substitution box, $Sbox(x)=x^α$, is applied with α chosen such that $gcd⁡(α,p-1)=1$.\n- Mix: the state is mixed through a multiplication by a $t×t$ [MDS matrix](https://en.wikipedia.org/wiki/MDS_matrix).\n\nIn 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](#figure-5-partial-round-overview) and [Fig5](#figure-5-partial-round-overview).\n\n\u003cdiv align=\"center\"\u003e\n\n  #### **Figure 4. Full round overview**\n  \u003cimg src=\"docs/images/rm-poseidon-fig-4.svg\"\u003e\n\n  #### **Figure 5. Partial round overview**\n  \u003cimg src=\"docs/images/rm-poseidon-fig-5.svg\"\u003e\n\n\u003c/div\u003e\n\n### Constants Selection\n\nHash'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.\n\nSeveral propositions were made to overcome this difficulty in the context of EIP-5988, [among them those proposed by vbuterin](https://ethereum-magicians.org/t/eip-5988-add-poseidon-hash-function-precompile/11772) :\n\n\u003e 1. 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.\n\u003e 2. Generate parameters in real time.\n\u003e 3. Pass parameters in as inputs.\n\nAs 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.\n\n### Parameters \n\nParameters either pertains to the sponge construct or the permutation:\n\n- Sponge:\n    - The rate and the capacity. \n- Permutation:\n    - The finite field, completely specified by its size. \n    - The number of full and partial rounds. \n    - The round constants and the MDS matrix. \n\nThe following set of parameters are included in the library thus far: \n\n- Starkware: https://github.com/starkware-industries/poseidon \n- Mina: https://github.com/o1-labs/proof-systems/blob/ebe59f35f5cb6bb33fc0ed3c4cb5040d8cd81247/book/src/specs/poseidon.md \n\n## Getting Started\n\n### Prerequisites\n\n- Install [Rust](https://www.rust-lang.org/tools/install)\n\n### Build\n\nTo build poseidon from source:\n\n```bash\ncargo build --release\n```\n\nThe build generates 2 libraries located in `target/release`:\n  1. libposeidon.rlib is the rust library file\n  1. libposeidon.so is a shared-library wrapping the rust library with a C-interface\n\n\n#### Variants\nYou can add predefined poseidon variants with the features flag, for example:\n\n```bash\ncargo build --release --features starkware\n```\n\nThe variants dependency tree is like so:\n\n\t| starkware\n\t|-- sw2\n\t|-- sw3\n\t|-- sw4\n\t|-- sw8\n\t| mina\n\t|-- pallas\n\t|-- vesta\n\nThis means that selecting feature starkware enables all four subvariants: sw2, sw3, sw4 and sw8.\n\n#### std feature\nBy default, the library will compile as no_std. In fact, it compiles at the core layer, without even alloc.\nHowever, no_std is omitted if the feature std is enabled.\n\n#### c_bind feature\nThe library can include C-bindings for hash functions through the c_bind feature.\nIn that case, one would want to build a staticlib to link it into another program, using for example:\n\n```bash\ncargo rustc --crate-type staticlib --release --features c_bind,starkware\n```\n\n### Tests\n\nTo test the rust library:\n```bash\ncargo test\n```\n\nTests for the C-interface are also available through golang in the c-bind-tests folder.\nFrom that folder, one can run tests like so:\n\n```bash \ngo test -v\n```\nNote that golang must be installed on your system to run the go_tests.\n\nFinally, we can also test that the library compiles with no_std compatibility in the ensure-no-std folder.\nFrom there, we can compile the test package like so:\n\n```bash\ncargo rustc --target thumbv7em-none-eabihf\n```\n\nThe test passes if it compiles.\nNote that you can use another no_std target if you wish, and need to have it installed in your environment.\n\n\n## Roadmap\n\nSee the [open issues](https://github.com/keep-starknet-strange/poseidon-rs/issues) for\na list of proposed features (and known issues).\n\n- [Top Feature Requests](https://github.com/keep-starknet-strange/poseidon-rs/issues?q=label%3Aenhancement+is%3Aopen+sort%3Areactions-%2B1-desc)\n  (Add your votes using the 👍 reaction)\n- [Top Bugs](https://github.com/keep-starknet-strange/poseidon-rs/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Areactions-%2B1-desc)\n  (Add your votes using the 👍 reaction)\n- [Newest Bugs](https://github.com/keep-starknet-strange/poseidon-rs/issues?q=is%3Aopen+is%3Aissue+label%3Abug)\n\n## Support\n\nReach out to the maintainer at one of the following places:\n\n- [GitHub Discussions](https://github.com/keep-starknet-strange/poseidon-rs/discussions)\n- Contact options listed on\n  [this GitHub profile](https://github.com/starknet-exploration)\n\n## Project assistance\n\nIf you want to say **thank you** or/and support active development of poseidon-rs:\n\n- Add a [GitHub Star](https://github.com/keep-starknet-strange/poseidon-rs) to the\n  project.\n- Tweet about the poseidon-rs.\n- Write interesting articles about the project on [Dev.to](https://dev.to/),\n  [Medium](https://medium.com/) or your personal blog.\n\nTogether, we can make poseidon-rs **better**!\n\n## Contributing\n\nFirst off, thanks for taking the time to contribute! Contributions are what make\nthe open-source community such an amazing place to learn, inspire, and create.\nAny contributions you make will benefit everybody else and are **greatly\nappreciated**.\n\nPlease read [our contribution guidelines](docs/CONTRIBUTING.md), and thank you\nfor being involved!\n\n## Authors \u0026 contributors\n\nFor a full list of all authors and contributors, see\n[the contributors page](https://github.com/keep-starknet-strange/poseidon-rs/contributors).\n\n## Security\n\nposeidon-rs follows good practices of security, but 100% security cannot be assured.\nposeidon-rs is provided **\"as is\"** without any **warranty**. Use at your own risk.\n\n_For more information and to report security issues, please refer to our\n[security documentation](docs/SECURITY.md)._\n\n## License\n\nThis project is licensed under the **MIT license**.\n\nSee [LICENSE](LICENSE) for more information.\n\n## Acknowledgements\n\nThis implementation is inspired by earlier rust implementations. We would like to thank [arnaudcube](https://github.com/arnaucube) and [neptune](https://github.com/filecoin-project/neptune)’s contributors. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeep-starknet-strange%2Fposeidon-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeep-starknet-strange%2Fposeidon-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeep-starknet-strange%2Fposeidon-rs/lists"}