# Poseidon
[](https://badge.fury.io/py/poseidon-hash)
This repository contains a reference implementations for the original version of Poseidon [1] and the instantiation as a hash
function tuned for Filecoin [2].
Moreover, scripts to calculate the round numbers, the round constants, and the MDS matrices are also included.
## Theoretical introduction
The set of parameters (`t`, `M`, `p`, `alpha`) fully specify a unique instance of Poseidon
All other Poseidon parameters and constants are derived from these parameters.
The optimized Poseidon hash function is instantiated in the same way as the un-optimized algorithm, however the optimized
Poseidon algorithm requires the additional pre-computation of round constants, pre-sparse matrix and sparse matrices.
We implemented the pre-computation steps according to [2].
The hash function takes as input a list of elements from a certain field `F` and outputs o single field
element.
In addition, for this implementation the `input_rate` (size of input) parameter is required, which can take any value
from `1` to `t`. A longer input size is possible and it is a work in progress.
## Usage: generate new instance with pre-generated parameters
To create a new hash instance, you can use ready-made functions in [parameters.py](poseidon/parameters.py) that have all
the necessary parameters,
or you can set your own parameters that have already been generated.
For matrices and round constants, use the hex representation.
```python
import poseidon
def main():
poseidon_simple, t = poseidon.parameters.case_simple()
input_vec = [x for x in range(0, t)]
print("Input: ", input_vec)
poseidon_digest = poseidon_simple.run_hash(input_vec)
print("Output: ", hex(int(poseidon_digest)))
security_level = 128
input_rate = 3
t_opt = 4
full_round = 8
partial_round = 56
alpha = 5
poseidon_pre_generated = poseidon.OptimizedPoseidon(poseidon.HashType.CONSTINPUTLEN, poseidon.parameters.prime_255,
security_level, alpha, input_rate, t_opt,
full_round=full_round, partial_round=partial_round,
rc_list=poseidon.parameters.round_constants_neptune,
mds_matrix=poseidon.parameters.matrix_neptune)
input_vec_2 = [x for x in range(0, t_opt - 1)]
print("Input: ", input_vec_2)
poseidon_output = poseidon_pre_generated.run_hash(input_vec_2)
print("Output: ", hex(int(poseidon_output)))
if __name__ == "__main__":
main()
```
## Usage: generate new instance without pre-generated parameters
The number of rounds, roound constants and matrices are optional parameters;
if they are not specified, they will be generated automatically.
For the same required input parameters the same optional parameters will always be generated.
```python
import poseidon
def main():
security_level = 128
input_rate = 3
t = 4
alpha = 5
poseidon_new = poseidon.Poseidon(poseidon.parameters.prime_255, security_level, alpha, input_rate, t)
input_vec = [x for x in range(0, t)]
print("Input: ", input_vec)
poseidon_output = poseidon_new.run_hash(input_vec)
print("Output: ", hex(int(poseidon_output)))
if __name__ == "__main__":
main()
```
## Running tests
Test vectors and parameters for non-optimised implementation are taken from [3].
Parameter generation for the optimized Poseidon is checked using test vectors that are taken (in some cases generated) from
the implementation of [2].
Running all tests
```commandline
python3 -m pytest tests/
```
Running tests by file
```commandline
python3 -m pytest tests/test_hash.py
```
Running a specific test. After `::` you must enter the name of the specific test in the corresponding file
```commandline
python3 -m pytest tests/test_hash.py::test_not_optimized_poseidon
```
## License
The code is released under the MIT license. See [LICENSE](LICENSE) for more information.
## Contact
Feel free to [reach out](mailto:hi@ingonyama.com)!
[1] *Poseidon: A New Hash Function for Zero-Knowledge Proof Systems. Cryptology ePrint Archive, Report 2019/458.
https://eprint.iacr.org/2019/458. Accepted at USENIX'21.*
[2] *Neptune specification https://github.com/filecoin-project/neptune/tree/master/spec*
[3] *Reference Implementations for Various Versions of Starkad and
Poseidon https://extgit.iaik.tugraz.at/krypto/hadeshash*
# CHANGELOG
## Version 0.1.3 05/05/2023
1. Fixed bug with type mismatch when calculating gcd.
2. Corrected the order of matrix and vector multiplication within the code, not in the tests.
## Version 0.1.2 04/07/2023
1. Bug with matrix multiplication fixed.
## Version 0.1.0 07/18/2022
1. First major release of the code, includes implementation of hash function and its optimization.
2. Add generator of round constants, round numbers and MDS matrix with correspond tests.
Raw data
{
"_id": null,
"home_page": "https://github.com/ingonyama-zk/poseidon-hash",
"name": "poseidon-hash",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Hash Function,Cryptography",
"author": "Ingonyama",
"author_email": "ekaterina@ingonyama.com",
"download_url": "https://files.pythonhosted.org/packages/e2/81/4b85be2ae5f94daa81edfd1bf2513eecbf3a59a4f5e2ce17d2b263d607ec/poseidon-hash-0.1.3.tar.gz",
"platform": null,
"description": "# Poseidon\n\n[](https://badge.fury.io/py/poseidon-hash)\n\nThis repository contains a reference implementations for the original version of Poseidon [1] and the instantiation as a hash\nfunction tuned for Filecoin [2].\nMoreover, scripts to calculate the round numbers, the round constants, and the MDS matrices are also included.\n\n\n## Theoretical introduction\n\nThe set of parameters (`t`, `M`, `p`, `alpha`) fully specify a unique instance of Poseidon\nAll other Poseidon parameters and constants are derived from these parameters.\n\nThe optimized Poseidon hash function is instantiated in the same way as the un-optimized algorithm, however the optimized\nPoseidon algorithm requires the additional pre-computation of round constants, pre-sparse matrix and sparse matrices.\nWe implemented the pre-computation steps according to [2].\n\nThe hash function takes as input a list of elements from a certain field `F` and outputs o single field\nelement.\nIn addition, for this implementation the `input_rate` (size of input) parameter is required, which can take any value\nfrom `1` to `t`. A longer input size is possible and it is a work in progress.\n\n\n## Usage: generate new instance with pre-generated parameters\n\nTo create a new hash instance, you can use ready-made functions in [parameters.py](poseidon/parameters.py) that have all\nthe necessary parameters,\nor you can set your own parameters that have already been generated.\n\nFor matrices and round constants, use the hex representation.\n\n```python\nimport poseidon\n\ndef main():\n poseidon_simple, t = poseidon.parameters.case_simple()\n\n input_vec = [x for x in range(0, t)]\n print(\"Input: \", input_vec)\n poseidon_digest = poseidon_simple.run_hash(input_vec)\n print(\"Output: \", hex(int(poseidon_digest)))\n\n security_level = 128\n input_rate = 3\n t_opt = 4\n full_round = 8\n partial_round = 56\n alpha = 5\n poseidon_pre_generated = poseidon.OptimizedPoseidon(poseidon.HashType.CONSTINPUTLEN, poseidon.parameters.prime_255, \n security_level, alpha, input_rate, t_opt,\n full_round=full_round, partial_round=partial_round,\n rc_list=poseidon.parameters.round_constants_neptune, \n mds_matrix=poseidon.parameters.matrix_neptune)\n\n input_vec_2 = [x for x in range(0, t_opt - 1)]\n print(\"Input: \", input_vec_2)\n poseidon_output = poseidon_pre_generated.run_hash(input_vec_2)\n print(\"Output: \", hex(int(poseidon_output)))\n\n\nif __name__ == \"__main__\":\n main()\n```\n\n## Usage: generate new instance without pre-generated parameters\n\nThe number of rounds, roound constants and matrices are optional parameters;\nif they are not specified, they will be generated automatically.\nFor the same required input parameters the same optional parameters will always be generated.\n\n```python\nimport poseidon\n\ndef main():\n security_level = 128\n input_rate = 3\n t = 4\n alpha = 5\n poseidon_new = poseidon.Poseidon(poseidon.parameters.prime_255, security_level, alpha, input_rate, t)\n\n input_vec = [x for x in range(0, t)]\n print(\"Input: \", input_vec)\n poseidon_output = poseidon_new.run_hash(input_vec)\n print(\"Output: \", hex(int(poseidon_output)))\n\n\nif __name__ == \"__main__\":\n main()\n```\n\n## Running tests\n\nTest vectors and parameters for non-optimised implementation are taken from [3].\n\nParameter generation for the optimized Poseidon is checked using test vectors that are taken (in some cases generated) from\nthe implementation of [2].\n\nRunning all tests\n\n```commandline\npython3 -m pytest tests/ \n```\n\nRunning tests by file\n\n```commandline\npython3 -m pytest tests/test_hash.py \n```\n\nRunning a specific test. After `::` you must enter the name of the specific test in the corresponding file\n\n```commandline\npython3 -m pytest tests/test_hash.py::test_not_optimized_poseidon\n```\n\n## License\n\nThe code is released under the MIT license. See [LICENSE](LICENSE) for more information.\n\n## Contact\n\nFeel free to [reach out](mailto:hi@ingonyama.com)! \n\n\n[1] *Poseidon: A New Hash Function for Zero-Knowledge Proof Systems. Cryptology ePrint Archive, Report 2019/458.\nhttps://eprint.iacr.org/2019/458. Accepted at USENIX'21.*\n\n[2] *Neptune specification https://github.com/filecoin-project/neptune/tree/master/spec*\n\n[3] *Reference Implementations for Various Versions of Starkad and\nPoseidon https://extgit.iaik.tugraz.at/krypto/hadeshash*\n \n\n\n# CHANGELOG\n\n## Version 0.1.3 05/05/2023\n1. Fixed bug with type mismatch when calculating gcd.\n2. Corrected the order of matrix and vector multiplication within the code, not in the tests.\n\n## Version 0.1.2 04/07/2023\n1. Bug with matrix multiplication fixed.\n\n## Version 0.1.0 07/18/2022\n1. First major release of the code, includes implementation of hash function and its optimization.\n2. Add generator of round constants, round numbers and MDS matrix with correspond tests.\n",
"bugtrack_url": null,
"license": "",
"summary": "Reference implementation in Python of Poseidon and optimized Poseidon (Neptune) hash functions",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/ingonyama-zk/poseidon-hash"
},
"split_keywords": [
"hash function",
"cryptography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc3ea977683d668e333ce9d4500d7e535bb8b4b2c43116e9571a5d04abd606a5",
"md5": "e0fd468e6226964250d7fd11b35d6daa",
"sha256": "9ef555ca7c2f78eb0e19a41c50fd6b52759dc72bb76982f00f9a3ee0a032436f"
},
"downloads": -1,
"filename": "poseidon_hash-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0fd468e6226964250d7fd11b35d6daa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 92973,
"upload_time": "2023-05-05T09:33:06",
"upload_time_iso_8601": "2023-05-05T09:33:06.637346Z",
"url": "https://files.pythonhosted.org/packages/cc/3e/a977683d668e333ce9d4500d7e535bb8b4b2c43116e9571a5d04abd606a5/poseidon_hash-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e2814b85be2ae5f94daa81edfd1bf2513eecbf3a59a4f5e2ce17d2b263d607ec",
"md5": "307c463a2cbd015127869cfe8efac46b",
"sha256": "d7251bab3cb998bc0bbfbc2ef5bba79b9ee9747cc9cbcdf6e20b380d16418958"
},
"downloads": -1,
"filename": "poseidon-hash-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "307c463a2cbd015127869cfe8efac46b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6012509,
"upload_time": "2023-05-05T09:33:41",
"upload_time_iso_8601": "2023-05-05T09:33:41.194758Z",
"url": "https://files.pythonhosted.org/packages/e2/81/4b85be2ae5f94daa81edfd1bf2513eecbf3a59a4f5e2ce17d2b263d607ec/poseidon-hash-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-05 09:33:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ingonyama-zk",
"github_project": "poseidon-hash",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "poseidon-hash"
}
JSON
