Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


CUDA and OpenCL capable POW miner for Handshake.


Simply point the miner at an HS RPC server and you're off.

$ hs-miner --rpc-host localhost --rpc-port 13037 --rpc-pass my-password

CLI Usage

Another small utility is available for mining arbitrary headers. This is most useful for testing.

# Mine a single block
$ hs-mine [header-hex] [target] [backend] -n [nonce] -r [range]

API Usage

const miner = require('hs-miner');

const hdr = Buffer.alloc(256, 0x00);

console.log('Available backends: ', miner.getBackends());
console.log('Available devices: ', miner.getDevices());

if (miner.hasCUDA()) {
  console.log('Mining with cuda support!');

(async () => {
  const [nonce, extraNonce, match] = await miner.mineAsync(hdr, {
    backend: 'cuda',
    target: Buffer.alloc(32, 0xff),
    nonce: 123456,
    range: 2048,
    grids: 256,
    blocks: 8,
    threads: 2048

  console.log('Nonce: %d', nonce);
  console.log('Extra Nonce: %s', extraNonce);
  console.log('Match: %s', match);



  • miner.mine(hdr, options) - Mine a to-be-solved header (sync).
  • miner.mineAsync(hdr, options) - Mine a to-be-solved header (async).
  • miner.isRunning(device) - Test whether a device is currently running.
  • miner.stop(device) - Stop a running job.
  • miner.stopAll() - Stop all running jobs.
  • miner.verify(hdr, target?) - Verify a to-be-solved header (sync).
  • miner.blake2b(data, enc) - Hash a piece of data with blake2b.
  • miner.sha3(data, enc) - Hash a piece of data with sha3.
  • miner.hashHeader(data) - Hash miner serialized header.
  • miner.isCUDA(backend) - Test whether a backend is a CUDA backend.
  • miner.getNetwork() - Get network (compile time flag).
  • miner.getBackends() - Get available backends.
  • miner.hasCUDA() - Test whether CUDA support was built.
  • miner.hasOpenCL() - Test whether OpenCL support was built.
  • miner.hasDevice() - Test whether a device is available.
  • miner.getDeviceCount(type) - Get count of CUDA or OpenCL devices.
  • miner.getDevices(type) - Get CUDA or OpenCL devices. Returns an array of objects.


  • miner.toBits(target) - Convert a big endian target to a mantissa.
  • miner.toTarget(bits) - Convert mantissa to big endian target.
  • miner.toDouble(target) - Convert a big endian target to a double.
  • miner.toDifficulty(target) - Convert target/hash to a difficulty/share.
  • miner.toShare(hash) - Alias of toDifficulty.


  • miner.NETWORK - Network (compile time flag).
  • miner.BACKENDS - Available backends.
  • miner.HAS_CUDA - Whether CUDA support was built.
  • miner.BACKEND - Default backend.
  • miner.TARGET - Default target.
  • miner.HDR_SIZE - Handshake to-be-solved header size (256).
  • miner.EXTRA_NONCE_SIZE - Total size of extra nonce (24).
  • miner.EXTRA_NONCE_START - Start of extra nonce position (128).
  • miner.EXTRA_NONCE_END - End of extra nonce position (152).


  • backend - Name of the desired backend.
  • range - How many iterations before the miner stops looking.
  • nonce - 32 bit nonce to start mining from.
  • target - Big-endian target (32 bytes).
  • grids - Backend-specific, see below.
  • blocks - Backend-specific, see below.
  • threads - Backend-specific, see below.

Backends (so far)

  • CUDA - POW miner with CUDA (
  • OpenCL - POW miner with OpenCL (
  • CPU - Simple miner, mostly for testing (

Platform Support

The code has only been tested on Linux. Realistically, linux is the only thing that should matter for mining, but build support for other OSes is welcome via pull request.

Supports 64bit only right now.


  • Stratum support.


When using one of the CUDA backends, only one job per device is allowed at a time. This is done because the CUDA miners generally wipe out your GPU's memory anyway.

The grids, blocks and threads parameters are backend-specific:


  • grids: number of blocks per grid (default: 52428)
  • blocks: number of threads per block (default: 512)
  • threads: total number of threads (for maximum occupancy: threads = grids * blocks) (default: 26843136)


  • grids: n/a
  • blocks: work group size (default: 512)
  • threads: work items (default: 26843136)

For CUDA support, CUDA must be installed in either /opt/cuda or /usr/local/cuda when running the build scripts.

This can be modified with the CUDA_PREFIX environment variable:

$ CUDA_PREFIX=/path/to/cuda ./scripts/rebuild


NodeJS installation guide:

If you're on an OS without native NVIDIA packages, drivers can be installed from:

CUDA is available from NVIDIA's download page:

Debian & Ubuntu

$ sudo apt-get install linux-headers-$(uname -r)
$ sudo apt-get install build-essential

# Install latest NVIDIA drivers
$ sudo add-apt-repository ppa:graphics-drivers/ppa
$ sudo apt update
$ sudo apt install nvidia-390

# Install CUDA
# Pick out your installation:
$ wget
$ sudo dpkg -i cuda-repo-ubuntu1704_9.1.85-1_amd64.deb
$ sudo apt-key adv --fetch-keys
$ sudo apt-get update
$ sudo apt-get install cuda

# Install the latest node.js
$ curl -sL | sudo -E bash -
$ sudo apt-get install nodejs

# Install git & python
$ sudo apt-get install git python

$ npm install hs-miner

RHEL & Fedora

Follow this installation guide for nvidia drivers:

This also looks promising:

Install CUDA (RHEL)

# Pick out your installation:
$ wget
$ sudo rpm -i cuda-repo-rhel7-9.1.85-1.x86_64.rpm
$ sudo yum clean all
$ sudo yum install cuda

Install CUDA (Fedora)

# Pick out your installation:
$ wget
$ sudo rpm -i cuda-repo-fedora25-9.1.85-1.x86_64.rpm
$ sudo dnf clean all
$ sudo dnf install cuda

Install node.js & hs-miner (Both)

$ curl --silent --location | sudo bash -
$ sudo yum install nodejs gcc-c++ make git python2
$ npm install hs-miner

Arch Linux

$ sudo pacman -S nodejs npm git nvidia nvidia-utils nvidia-settings cuda python2
$ npm install hs-miner


$ brew install node git coreutils perl grep gnu-sed gawk python2
$ brew tap caskroom/drivers
$ brew cask install nvidia-cuda
$ npm install hs-miner




Pass an extra argument to the make commands to specify special behavior. Run make regtest extra=preprocess to output .cup files for the CUDA files. Or pass an environment variable EXTRA_ARG to one of the npm install-* scripts for the same behavior, such as $ EXTRA_ARG=preprocess npm run install.

Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work. </legalese>


  • Copyright (c) 2018, Christopher Jeffrey (MIT License).

See LICENSE for more info.