A C library implementing the POST API setup method for general-purpose CPUs and for CUDA and Vulkan compute processors.

Windows 10/11, macOS or Linux. One or more of the following:

• A GPU and drivers with CUDA support (minimum compute compatibility 5.0, maximum compute compatibility 9), such as a modern Nvidia GPU and Nvidia drivers version R525 or newer.
• A GPU and drivers with Vulkan 1.3 support such as a modern AMD, Apple M1 processor, and Intel GPUs.
• A x86-64 cpu such as AMD or Intel CPUs.
• A ARM 64 bit cpu such as Apple Silicon or Ampere Altra
• Both discrete and on-board GPUs are supported as long as they support the minimum CUDA or Vulkan runtime version.

We currently provide release binaries and build instructions for Windows, Mac and Ubuntu 22.04 but the library can be built on other Linux distros for usage on these systems.

• 16 KiB per CUDA core for CUDA
• 4 MiB per compute unit for Vulkan

• 2080 MiB

On Linux platforms with Hybrid Nvidia GPU setup please use Nvidia driver R525 or newer. Older ones are known to have compatibility issues. Non hybrid cards are confirmed to be working with R520 and older versions.

• For building CUDA support: NVIDIA Cuda Toolkit 11, an NVIDIA GPU with CUDA support, and an Nvdia driver version R525 or newer.
  • If building on Linux you should refer to the distribution preferred method installation if available
• For building Vulkan support: Vulkan SDK 1.3 and a GPU with Vulkan 1.3 runtime support.

• Windows 10/11.
• Microsoft Visual Studio 2022
• You may also need to install specific versions of the Windows SDK when prompted when attempting to build the library for the first time.

• Ubuntu 22.04
• Cmake, GCC 11

• Cmake, GCC 11

• Xcode
• Xcode Command Line Dev Tools
• Cmake, GCC 11

1. Install latest version of Xcode with the command line dev tools.
2. Download the Vulkan 1.3 sdk installer for macOS from https://vulkan.lunarg.com/sdk/home#mac
3. Install Vulkan SDK with the Vulkan installer.
4. Change directory to the folder where the SDK is installed (default $ cd $HOME/VulkanSDK/1.3.xxx) and run the install script with $ sudo ./install_vulkan.py
5. Add the Vulkan env vars to your .bash_profile file with the root location set to the sdk directory on your hard-drive. For example, if Vulkan sdk 1.2.154 is installed then the env vars should be set like this:

export VULKAN_SDK_VERSION="1.3.xxx"                   # Replace xxx with actual version
export VULKAN_ROOT_LOCATION="$HOME/VulkanSDK/1.3.xxx" # adapt to install location on your machine
export VULKAN_SDK="$VULKAN_ROOT_LOCATION/macOS"
export VK_ICD_FILENAMES="$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json"
export VK_LAYER_PATH="$VULKAN_SDK/share/vulkan/explicit_layers.d"
export PATH="/usr/local/opt/python/libexec/bin:$VULKAN_SDK/bin:$PATH"
export DYLD_LIBRARY_PATH="$DYLD_LIBRARY_PATH:$VULKAN_SDK/lib/"

Default build configuration:

SPACEMESHCUDA   "Build with CUDA support"   default: ON
SPACEMESHVULKAN "Build with Vulkan support" default: ON

SPACEMESHCUDA   "Build with CUDA support"   default: OFF
SPACEMESHVULKAN "Build with Vulkan support" default: ON

To build the library with full support for both CUDA and Vulkan on Windows or on Linux use a system with an Nvidia GPU and drivers. Otherwise, turn off CUDA support and build for Vulkan only. Building on macOS only supports Vulkan.

1. Open project folder into Visual Studio 2022: File -> Open -> Folder.
2. Set x64-Release Project Settings.
3. Build: CMake -> Rebuild All.
4. Run test: CMake -> Debug from Build Folder -> gpu-setup-test.exe

If using VULKAN, make sure to clone the zlib submodule:

git submodule update --init

Configure your build using the default configuration:

cmake -B build

To disable CUDA use:

cmake -B build -DSPACEMESHCUDA=OFF

To disable VULKAN use:

cmake -B build -DSPACEMESHVULKAN=OFF

Build the project:

cmake --build build

Run the tests:

./build/test/gpu-setup-test -t
./build/test/gpu-setup-test -u
./build/test/gpu-setup-test -b

1. Since the test app is not notarized, you may need to enable it via spctl --add /path/to/gpu-setup-test or by right-click-open it and click open.
2. Set execute permissions if not already set, e.g., chmod a x gpu-setup-test
3. Add the test app's path to the dynamic lib search path, e.g., export DYLD_LIBRARY_PATH=.

1. Set execute permissions if not already set, e.g., chmod a x gpu-setup-test
2. Add the test app's path to the dynamic lib search path, e.g., export LD_LIBRARY_PATH=.

Run from the console to print usage:

$ gpu-setup-test
Usage:
--list               or -l                 print available providers
--benchmark          or -b                 run benchmark
--core               or -c                 test the core library use case
--test               or -t                 run basic test
--test-vector-check                        run a CPU test and compare with test-vector
--test-pow           or -tp                test pow computation
--test-leafs-pow     or -tlp               test pow computation while computing leafs
--unit-tests         or -u                 run unit tests
--integration-tests  or -i                 run integration tests
--label-size         or -s <1-256>         set label size [1-256]
--labels-count       or -n <1-32M>         set labels count [up to 32M]
--reference-provider or -r <id>            the result of this provider will be used as a reference [default - CPU]
--print              or -p                 print detailed data comparison report for incorrect results
--pow-diff           or -d <0-256>         count of leading zero bits in target D value [default - 16]
--srand-seed         or -ss <unsigned int> set srand seed value for POW test: 0 - use zero id/seed [default], -1 - use random value
--solution-idx       or -si <unsigned int> set solution index for POW test: index will be compared to be the found solution for Pow [default - unset]

By default, the library does not detect supported Vulkan GPUs if CUDA GPUs are detected. This behavior can be changed using two environment variables:

SPACEMESH_DUAL_ENABLED
 empty or 0 - default behavior
 1 - detect Vulkan GPUs even if CUDA GPUs are detected

SPACEMESH_PROVIDERS_DISABLED
 empty - default behavior
 "cuda" - do not detect CUDA GPUs
 "vulkan" - do not detect Vulkan GPUs

The library supports multiple compute providers at runtime. For best performance, use the following providers based on your OS and GPU:

Compute leaves and/or pow solution:

int scryptPositions(
   uint32_t provider_id,      // POST compute provider ID
   const uint8_t *id,         // 32 bytes
   uint64_t start_position,   // e.g. 0
   uint64_t end_position,     // e.g. 49,999
   uint32_t hash_len_bits,    // (1...256) for each hash output, the number of prefix bits (not bytes) to copy into the buffer
   const uint8_t *salt,       // 32 bytes
   uint32_t options,          // compute leafs and/or compute pow
   uint8_t *out,              // memory buffer large enough to include hash_len_bits * number of requested hashes
   uint32_t N,                // scrypt N
   uint32_t R,                // scrypt r
   uint32_t P,                // scrypt p
   uint8_t *D,                // Target D for the POW computation. 256 bits.
   uint64_t *idx_solution,    // index of output where output < D if POW compute was on. MAX_UINT64 otherwise.
   uint64_t *hashes_computed, // The number of hashes computed, should be equal to the number of requested hashes.
   uint64_t *hashes_per_sec   // Performance
);

The api currently only supports the following N, P, R scrypt params.

• Supported N values: 1 - 28835
• Supported R values: 1
• Supported P values: 1

Gets the system's GPU capabilities. E.g. CUDA and/or NVIDIA or NONE:

int stats();

Stops all GPU work and don’t fill the passed-in buffer with any more results:

int stop(
 uint32_t ms_timeout   // timeout in milliseconds
);

Returns non-zero if stop in progress:

SPACEMESHAPI int spacemesh_api_stop_inprogress();

Returns POS compute providers info:

SPACEMESHAPI int spacemesh_api_get_providers(
 PostComputeProvider *providers, // out providers info buffer, if NULL - returns count of available providers
 int max_providers// buffer size
);

1. Download release artifacts from a github release in this repo for your platform or build the artifacts from source code.
2. Copy all artifacts to your project resources directory. The files should be included in your app's runtime resources.
3. Use api.h to link the library from your code.

Integration test of the basic library use case in a Spacemesh full node to generate proof of space and find a pow solution:

/build/test/.gpu-setup-test -c -n 100663296 -d 20

Disclaimer: these are community submitted benchmarks which haven't been verified. Your milage may vary. The library is also likely to have bugs, is in alpha quality and the gpu-post algorithm is likely to change before the release of the Spacemesh 0.2 testnet.

gpu-setup-test -b -n 2000000

Scrypt Benchmarks (n=512, r=1, p=1) 1 byte per leaf, batch size leaves per API call.

The library performance on a GPU depends on the GPU's CUDA and Vulkan performance. The following benchmarks are available from geekbench:

• Geekbench Cuda Benchmarks
• Geekbench Vulkan Benchmarks