{"id":25295630,"url":"https://github.com/lurk-lab/neptune","last_synced_at":"2025-12-12T16:31:40.520Z","repository":{"id":37104392,"uuid":"232188036","full_name":"argumentcomputer/neptune","owner":"argumentcomputer","description":"Rust Poseidon implementation (contact: @porcuquine)","archived":false,"fork":false,"pushed_at":"2024-12-04T21:37:26.000Z","size":11859,"stargazers_count":300,"open_issues_count":12,"forks_count":101,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-02-02T03:02:46.464Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/argumentcomputer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-06T21:23:39.000Z","updated_at":"2025-01-31T11:34:59.000Z","dependencies_parsed_at":"2023-09-27T01:59:34.815Z","dependency_job_id":"e5c25b72-0f3c-4159-86e3-40a768cd0a4a","html_url":"https://github.com/argumentcomputer/neptune","commit_stats":null,"previous_names":["filecoin-project/neptune","argumentcomputer/neptune","lurk-lab/neptune"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argumentcomputer%2Fneptune","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argumentcomputer%2Fneptune/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argumentcomputer%2Fneptune/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argumentcomputer%2Fneptune/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/argumentcomputer","download_url":"https://codeload.github.com/argumentcomputer/neptune/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238579786,"owners_count":19495552,"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":"2025-02-13T02:04:36.670Z","updated_at":"2025-10-28T01:32:07.129Z","avatar_url":"https://github.com/argumentcomputer.png","language":"Rust","funding_links":[],"categories":["Web 3.0","Rust"],"sub_categories":[],"readme":"# Neptune ![crates.io](https://img.shields.io/crates/v/neptune.svg) ![neptune](https://github.com/argumentcomputer/neptune/actions/workflows/rust.yml/badge.svg)[![dependency status](https://deps.rs/repo/github/argumentcomputer/neptune/status.svg)](https://deps.rs/repo/github/argumentcomputer/neptune)\n\n\n## About\nNeptune is a Rust implementation of the [Poseidon hash function](https://www.poseidon-hash.info/) tuned for\n[Filecoin](https://filecoin.io/).\n\nNeptune has been [audited by ADBK Consulting](poseidon-in-filecoin-final-report.pdf) and deemed fully compliant with the\npaper ([Starkad and Poseidon: New Hash Functions for Zero Knowledge Proof\nSystems](https://eprint.iacr.org/2019/458.pdf)).\n\nNeptune was initially specialized to the [BLS12-381 curve](https://electriccoin.co/blog/new-snark-curve/). Although the\nAPI allows for type specialization to other fields, the round numbers, constants, and s-box selection may not be\ncorrect. As long as the alternate field is a prime field of ~256 bits, the 128-bit security Neptune targets will apply.\nThere is a run-time assertion which will fail if constants are generated for a field whose elements do not have a\nrepresentation of exactly 32 byte. The [Pasta Curves](https://github.com/zcash/pasta_curves) meet these criteria and are\nexplicitly supported by Neptune.\n\nAt the time of the 1.0.0 release, Neptune on RTX 2080Ti GPU can build 8-ary Merkle trees for 4GiB of input in 16 seconds.\n\n## Implementation Specification\n\nFilecoin's Poseidon specification is published in the Filecoin specification document [here](https://spec.filecoin.io/#section-algorithms.crypto.poseidon). Additionally, Markdown and PDF versions are mirrored in this repo in the [`spec`](spec) directory.\n\n### Contributing to the Spec\n\n### PDF Rendering Instructions\n\nThe spec's PDF is rendered using [Typora](https://typora.io/). Download the spec's Markdown file [here](spec/poseidon_spec.md), open the file in Typora, make and save your changes, then export the file as a PDF.\n\n### Ensuring Spec Documents Stay in Sync\n\nWhen making changes to the spec documents in `neptune`, make sure that the spec's PDF file `poseidon_spec.pdf` is the PDF rendering of the Markdown spec `poseidon_spec.md`.\n\nIf you make changes to the spec in `neptune`, you must make those same changes to the Filecoin spec [here](https://github.com/filecoin-project/specs/blob/master/content/algorithms/crypto/poseidon.md), thus ensuring all three document's (one Markdown+Latex and one PDF in `neptune` and one Markdown+MathJax in [`filecoin-project/specs`](https://github.com/filecoin-project/specs/)) stay in sync.\n\n## Environment variables\n\n - `EC_GPU_FRAMEWORK=\u003ccuda | opencl\u003e` allows to select whether the CUDA or OpenCL implementation should be used. If not set, `cuda` will be used if available.\n\n - `EC_GPU_CUDA_NVCC_ARGS`\n\nBy default the CUDA kernel is compiled for several architectures, which may take a long time. `EC_GPU_CUDA_NVCC_ARGS` can be used to override those arguments. The input and output file will still be automatically set.\n\n    // Example for compiling the kernel for only the Turing architecture\n    EC_GPU_CUDA_NVCC_ARGS=\"--fatbin --gpu-architecture=sm_75 --generate-code=arch=compute_75,code=sm_75\"\n\n## Rust feature flags\n\nNeptune also supports batch hashing and tree building, which can be performed on a GPU. GPU batch hashing is implemented in pure CUDA/OpenCL. The pure CUDA/OpenCL batch hashing is provided by the internal `proteus` module. To use `proteus`, compile `neptune` with the `opencl` and/or `cuda` feature.\n\nThe `cuda` and `opencl` feature can be used independently or together. If both `cuda` and `opencl` are used, you can also select which implementation to use via the `NEPTUNE_GPU_FRAMEWORK` environment variable.\n\n### Arities\n\nThe CUDA/OpenCL kernel (enabled with the `cuda/opencl` feature) is generated with specific arities. Those arities need to be specified at compile-time via Rust feature flags. Available features are `arity2`, `arity4`, `arity8`, `arity11`, `arity16`, `arity24`, `arity36`. When the `strengthened` feature is enables, there will be an additional strengthened version available for each arity.\n\nWhen using the `cuda` feature, the kernel is generated at compile-time. The more arities are used, the longer is the compile time. Hence, by default there are no specific arities enabled. You need to set at least one yourself.\n\n### Fields\n\nThe CUDA/OpenCL kernel (enabled with the `cuda/opencl` feature) is generated for specific fields. Those fields need to be specified at compile-time via Rust feature flags. Available features are `bls` for BLS12-381 and `pasta` for the Pallas and Vesta curves' scalar fields.\n\n## Running the tests\n\nAs the compile-time of the kernel depends on how many arities are used, there are no arities enabled by default. In order to run the test, all arities need to explicitly be enabled. To run all tests on e.g. the CUDA implementation, run:\n\n    cargo test --no-default-features --features cuda,bls,pasta,arity2,arity4,arity8,arity11,arity16,arity24,arity36\n\n## Benchmarking Poseidon by Field and Preimage Length\n\nBenchmark Poseidon over the BLS12-381, Pallas, and Vesta scalar fields for preimages of length `2`, `4`, `8`, or `11` using:\n\n    cargo bench arity-\u003cpreimage len\u003e\n\nBenchmark Poseidon over a specific field (`bls`, `pallas`, or `vesta`) and preimage length using:\n\n    cargo bench arity-\u003cpreimage len\u003e/\u003cfield name\u003e\n\n## Sponge API\n\nNeptune implements the [Secure Sponge API for Field Elements](https://hackmd.io/bHgsH6mMStCVibM_wYvb2w) and serves as its reference implementation. The [`SpongeAPI` trait](https://github.com/argumentcomputer/neptune/blob/master/src/sponge/api.rs) defines the relevant API methods. See tests in source for simple examples of API usage [with circuits](https://github.com/argumentcomputer/neptune/blob/master/src/sponge/circuit.rs) and [without circuits](https://github.com/argumentcomputer/neptune/blob/master/src/sponge/vanilla.rs).\n\n## History\n\nNeptune was originally bootstrapped from [Dusk's reference implementation](https://github.com/dusk-network/dusk-poseidon-merkle).\n\n## Changes\n[CHANGELOG](CHANGELOG.md)\n\n## License\n\nMIT or Apache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flurk-lab%2Fneptune","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flurk-lab%2Fneptune","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flurk-lab%2Fneptune/lists"}