neptune-triton is a Futhark implementation of the Poseidon hash function, targeting OpenCL for execution on GPU.

This repository contains two packages: neptune-triton-generator and neptune-triton. The former is a code generator, and the latter is the resulting Rust library.

The generated neptune-triton library is implemented over the Bls12-381 curve. neptune-triton's security levels (partial round numbers) are hard coded to match those provided by neptune, but the actual round constants used must be provided at runtime. When neptune-triton is used by neptune to provide support for batched hashes (arities 2, 8, and 11).

Code generation is performed by genfut. First OpenCL code is generated by invoking the Futhark compiler, then Rust bindings are generated using bindgen. Finally, a Rust library wrapping the generated bindings is created. The resulting Rust library is neptune-triton.

In general, users should not need to generate code. This already been performed by the library maintainer, and the resulting generated code is consumed as-is by downstream dependencies. However, for development purposes, or to verify the provenance of the generated Rust code, neptune-triton can be generated by running neptune-triton-generator's default codegen binary.

NOTE: the following will also generate OpenCL code using Futhark, so you will need to have installed the Futhark compiler first. Instructions for installing the correct version of Futhark can be found below.

From repository root:

% cd library
% cargo run

This will generate Futhark artifacts for an OpenCL implemented in library/neptune-triton/lib/, Rust bindings, and a Rust library wrapping OpenCL code in …/neptune-triton/.

You can verify that the existing neptune-triton library indeed represents the result of invoking genfut by observing that regenerating the code does not result in a diff to the repository version. For more detail, see the next section and the procedure described there.

Because Futhark output is deterministic by design, you can easily verify that the OpenCL artifacts are indeed those generated by compiling poseidon.fut with Futhark. Because Futhark does not provide facilities for I/O and only emits purely functional and (with small exceptions for profiling and deubgging) side-effect free programs. From the preceding link:

Calling an entry point, or interacting with Futhark values through the functions listed above, has no system-wide side effects, such as writing to the file system, launching processes, or performing network connections. Defects in the program or Futhark compiler itself can with high probability result only in the consumption of CPU or GPU resources, or a process crash.

To verify that OpenCL artifacts are those generated by Futhark, first check the Futhark version which was used by inspecting the contents of library/neptune-triton/futhark-version.txt. Next, install the reported Futhark version. Note that a specific Git commit hash is reported, and this commit must be used when building and installing Futhark if you wish to verify the correctness of the generated code.

For example, if futhark-version.txt contains the folowing, then neptune-triton was compiled using commit 965e8eb of Futhark:

Futhark 0.16.0
git: 965e8eb (Fri Jul 3 14:53:26 2020 +0200)
Copyright (C) DIKU, University of Copenhagen, released under the ISC license.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Once Futhark is installed installed, verify the installation by comparing the version information from your Futhark version and that in futhark-version.txt.

% futhark --version

The text should be identical.

Assuming your Futhark version text exactly matches that included in the neptune-triton source you wish to verify, you can regenerate lib/a.c, lib/a.h as follows:

From repository root:

% cd library
% futhark opencl --library -o neptune-triton/lib/a poseidon.fut

If you have recompiled poseidon.fut from a checkout of the project's Git repository, you should observe:

• The timestamps of neptune-triton/lib/a.c, neptune-triton/lib/a.h, and neptune-triton/lib/a.fut have been udpated to reflect this recompilation.
• The content of the files is unchanged, and git status shows that your branch is up do date, if it was before:

On branch master
Your branch is up to date with 'origin/master.

nothing to commit, working tree clean

If this is not the case, first ensure you do have a clean checkout as above, then try again. Compiling with the correct Futhark version should produce new output (observable by timestamp) but no change of content ('nothing to commit, working treen clean').

From the second paragraph of 4.8 General Guarantees (also linked above):

Using the #[unsafe] attribute with in-place updates can result in writes to arbitrary memory locations. A malicious program can likely exploit this to obtain arbitrary code execution, just as with any insecure C program. If you must run untrusted code, consider using the --safe command line option to instruct the compiler to disable #[unsafe].

You may inspect (or grep) poseidon.fut to verify that #[unsafe] is not used. To observe this differently, you can compile with the --safe option and witness that the output still remains unchanged (as above).

From repository root:

% cd library
% futhark opencl --safe --library -o neptune-triton/lib/a poseidon.fut

The Filecoin Project is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)