47 releases (28 stable)
|7.2.0||Aug 9, 2022|
|7.0.0||Jul 21, 2022|
|6.2.0||Jun 10, 2022|
|6.0.0||Mar 23, 2022|
|0.5.3||Mar 24, 2020|
#63 in Cryptography
4,081 downloads per month
Used in 28 crates (11 directly)
Neptune has been audited by ADBK Consulting and deemed fully compliant with the paper (Starkad and Poseidon: New Hash Functions for Zero Knowledge Proof Systems).
Neptune was initially specialized to the BLS12-381 curve. Although the API allows for type specialization to other fields, the round numbers, constants, and s-box selection may not be correct. As long as the alternate field is a prime field of ~256 bits, the 128-bit security Neptune targets will apply. There is a run-time assertion which will fail if constants are generated for a field whose elements do not have a representation of exactly 32 byte. The Pasta Curves meet these criteria and are explicitly supported by Neptune.
At 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.
Contributing to the Spec
PDF Rendering Instructions
Ensuring Spec Documents Stay in Sync
When 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
If you make changes to the spec in
neptune, you must make those same changes to the Filecoin spec here, thus ensuring all three document's (one Markdown+Latex and one PDF in
neptune and one Markdown+MathJax in
filecoin-project/specs) stay in sync.
NEPTUNE_DEFAULT_GPU=<unique-id>allows you to select the default GPU that tree-builder is going to run on given its unique ID.
(The unique ID is the UUID or the hexadecimal Bus-ID that can be found through
lspci and etc.)
NEPTUNE_GPU_FRAMEWORK=<cuda | opencl>allows to select whether the CUDA or OpenCL implementation should be used. If not set,
cudawill be used if available.
By default the CUDA kernel is compiled for several architectures, which may take a long time.
BELLMAN_CUDA_NVCC_ARGS can be used to override those arguments. The input and output file will still be automatically set.
// Example for compiling the kernel for only the Turing architecture NEPTUNE_CUDA_NVCC_ARGS="--fatbin --gpu-architecture=sm_75 --generate-code=arch=compute_75,code=sm_75"
Rust feature flags
Neptune 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
neptune with the
opencl feature can be used independently or together. If both
opencl are used, you can also select which implementation to use via the
NEPTUNE_GPU_FRAMEWORK environment variable.
The 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
arity36. When the
strengthened feature is enables, there will be an additional strengthened version available for each arity.
When 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.
The 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.
Running the tests
As 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:
cargo test --no-default-features --features cuda,bls,pasta,arity2,arity4,arity8,arity11,arity16,arity24,arity36
Benchmarking Poseidon by Field and Preimage Length
Benchmark Poseidon over the BLS12-381, Pallas, and Vesta scalar fields for preimages of length
cargo bench arity-<preimage len>
Benchmark Poseidon over a specific field (
vesta) and preimage length using:
cargo bench arity-<preimage len>/<field name>
Neptune implements the Secure Sponge API for Field Elements and serves as its reference implementation. The
SpongeAPI trait defines the relevant API methods. See tests in source for simple examples of API usage with circuits and without circuits.
Neptune was originally bootstrapped from Dusk's reference implementation.
MIT or Apache 2.0