Skip to content

About

Pickaxe Miner is a native Rust high-performance GPU miner

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Pickaxe Miner

Pickaxe Miner

Rust miner for Bitcoin Cash and CashTokens: GPU token mining, BCH ASIC mining, and pool or farm operation from one terminal application. A browser WebGPU miner is also available for PHOTON.

Download the latest release · Guides · Development and releases

This README describes the current branch. For a downloaded build, its release notes describe the features included in that package.

What to mine

Asset or mode Hardware Networks Getting started
PHOTON Native GPUs; browser WebGPU Mainnet and Chipnet Direct token rewards; no funded fee pot. Quick start, protocol
ELECTRIC Native GPUs using CUDA or the portable engine Mainnet and Chipnet Fund its fee pot using the setup's QR code, then mine. ELECTRIC guide
PHOTON + ELECTRIC hash split Native GPUs Mainnet and Chipnet Choose each token's share of the GPUs in one session. Hash split
Bitcoin Cash (BCH) ASICs over Stratum V1 or V2 Mainnet and Chipnet Solo mining, upstream pools or managed P2Pool. ASIC guide, P2Pool

PHOTON uses its live v3.2 covenant; the retired v0 contract is no longer mined. ELECTRIC continues to use its existing v1 covenant. The author's ELECTRIC v2 is a reference for future tokens, not a migration of the current token.

ELECTRIC's fee pot pays the transaction fee and the BCH attached to each token reward. That attached BCH arrives with the tokens at the reward recipient. Pickaxe calculates fees from transaction size and the node/server's reported rate. Setup shows its funding QR, balance and recovery-key location. The owner-pot dashboard also offers Max/send controls; see the pot guide.

Upcoming ASIC tokens

SAFA production mining is upcoming. The production ASIC-token registries are currently empty. The merge-mining format v2 and Chipnet test hooks are implemented, including tSAFA from an explicit deployment file; tSAFA is not offered in the normal token selector. See BCH merge-mining, tSAFA on Chipnet and ASIC-exclusive token proposals for their separate status and remaining deployment checks.

Chain connections

PHOTON and ELECTRIC can discover state and submit claims through your BCH node or through Electrum/Fulcrum. A configured node is tried first; the ordinary mode can fall back to public Fulcrum servers. --source node requires the node to work. Native discovery needs no transaction index and supports a pruned node that retains the blocks being followed.

BCH solo mining and embedded P2Pool require your own BCH node. When joining a public pool or public P2Pool with its jobs, the upstream supplies the templates. Using your own templates at a compatible SV2 pool requires your node and Job Declaration. Fulcrum supplies indexed token state, not BCH block templates. See template sources.

Donations

PHOTON and ELECTRIC each default to a 4% mining-work donation, adjustable per token in Advanced settings, including 0%. At the default, 96% of completed candidate hashes mine for your wallet; each win pays its selected recipient directly. The donation is based on work, not guaranteed rewards, so short sessions can have different outcomes because wins are random.

The BCH ASIC server has its own 1.5% donation by default: 0.5% of mining work and 1% of each block reward. Set it anywhere from 0% to 100%, in 0.5% steps, with stratum-v2 serve --donation <percent> or in the dashboard's Advanced settings (a); changes are saved. Shown percentages are rounded up to two decimals. Other assets keep their own donation policies. Actual rewards depend on which work wins.

ASICs and pools

The ASIC server's workers page shows each device's own report, and Enter opens the highlighted row's Device panel, online or offline, with confirmed controls (restart, pause, resume, blink its light to find it, Avalon work levels) for most makes, through asic-rs. With --upstream, it sends SV1 devices to a remote Stratum V2 pool instead of your own node, with backup pools in order; there the pool builds the blocks, so the donation is that share of mining work at the pool. See docs/stratum-v2.md.

For pool operators

Run a public BCH pool with Pickaxe: SV1 and SV2 miners connect with their own payout address, and the blocks they find pay them directly in the coinbase, so the pool holds no one's money. You choose your fee and where it comes from (the coinbase, mining work, or both) and the address it goes to, including a multisig; miners can see every fee in the coinbase. stratum-v2 serve --public --pool-fee 2 --pool-fee-address <address>; see docs/pool.md. Run a pool also starts a GPU pool, where each rig mines for its own address and your fee is a share of mining time. Press i on the dashboard for Connection info: the addresses (and, for rigs, the command) miners copy, for your network and, with Tailscale, from anywhere.

How to start

Run pickaxe for the setup, or use the command line.

To In the setup (pickaxe) On the command line Guide
Mine PHOTON on your GPUs GPU mining pickaxe mine --address <yours> Quick start
Mine ELECTRIC on your GPUs GPU mining, ELECTRIC; fund its fee pot pickaxe electric mine --address <yours> docs/electric-token.md
Split your GPUs between both tokens GPU mining, Hash split pickaxe split --share photon=80 --share electric=20 --address <yours> docs/hash-split.md
Mine with GPUs on many machines GPU mining; rigs: Join a GPU pool or farm coordinator --rigs-listen 0.0.0.0:3340, rigs --coordinator HOST:3340 --coordinator-key KEY docs/farm.md
Join someone's GPU pool GPU mining, Join a GPU pool or farm pickaxe mine --coordinator HOST:3340 --coordinator-key KEY --address <yours> docs/farm.md
Mine on HiveOS, mmpOS or RaveOS – the release's custom-miner package for your system docs/farm-os.md
Run a GPU pool Run a pool, GPU pool pickaxe mine --rigs-listen 0.0.0.0:3340 --rigs-only --rigs-public --rigs-fee 2 --address <yours> docs/pool.md
Mine BCH solo with your ASICs ASIC mining, Solo pickaxe stratum-v2 serve (your BCH node) docs/stratum-v2.md
Point your ASICs at a pool ASIC mining, Join a pool pickaxe stratum-v2 serve --sv1-listen 0.0.0.0:3333 --upstream stratum2+tcp://HOST:PORT/KEY docs/stratum-v2.md
Run a BCH pool for others Run a pool, ASIC pool pickaxe stratum-v2 serve --public --pool-fee 2 --pool-tag /MyPool/ docs/pool.md
Mine at a pool with your own node's templates ASIC mining, Join a pool; Advanced: Job Declaration pickaxe stratum-v2 serve --sv1-listen 0.0.0.0:3333 --upstream stratum2+tcp://HOST:PORT/KEY --job-declaration docs/job-declaration.md
Serve your node's templates to SV2 pools and P2Pool ASIC mining, Solo; Advanced: Serve templates pickaxe stratum-v2 serve --tp-listen 0.0.0.0:8442 docs/stratum-v2.md

A server or coordinator shows where devices and rigs connect on its dashboard (i or I, Connection info), ready to copy, for your network and, with Tailscale, from anywhere. Choose your node or pool connection for BCH, and your node or Fulcrum connection for GPU tokens, as described under Chain connections.

Supported platforms

Windows x86_64, Linux x86_64 and Apple Silicon macOS, plus a browser miner (WebAssembly on browser WebGPU).

Linux and Windows ARM64 (for example Raspberry Pi 5, Ampere servers and Snapdragon laptops) build and pass the tests on GitHub's ARM64 runners; each CI run uploads the ARM64 binaries. They mine through the portable engine (Vulkan, or DirectX 12 on Windows).

GPU Engine
NVIDIA GeForce RTX 50 series (sm_120) CUDA
AMD Radeon RX 6000, 7000 and 9000 (gfx1030-gfx1034, gfx1100-gfx1102, gfx1200-gfx1201) Native HIP T2
AMD integrated (Ryzen) and other AMD GPUs Portable engine on Vulkan
Intel GPUs Portable engine on Vulkan, or on DirectX 12 when the Vulkan driver fails
Other NVIDIA GPUs Portable engine on Vulkan, chosen automatically (the CUDA kernels target sm_120 only)
Apple Silicon (M1 and later) Portable engine on Metal
GPUs no other engine finds: older integrated GPUs without Vulkan or DirectX 12, ARM GPUs (Mali, Adreno) with only an OpenCL driver OpenCL engine, used only when no other engine finds a GPU, or with --backend opencl
Browser miner: browsers with WebGPU enabled (Chrome, Edge, Firefox, Safari on supported systems) PHOTON on the portable engine in WebAssembly

PHOTON supports the engines above. ELECTRIC currently supports CUDA and the portable engine; use --backend wgpu on systems without CUDA.

The engine is selected automatically, and one miner mines on every discrete GPU of the machine, each on its best engine (several GPUs). An integrated GPU mines automatically only when no discrete GPU is present. devices lists every GPU with its engine. HIP runs C++ kernels by default; PICKAXE_HIP_KERNELS=rust selects the kernels built from the shared Rust engine. Which kernels each GPU runs, how they are built and how to switch: GPU code map. All documentation: docs.

Quick start: mainnet TUI

From the extracted download folder, run the command for your platform:

Platform Command
Windows PowerShell .\pickaxe.exe
Linux ./pickaxe
Apple Silicon Mac ./pickaxe

Double-clicking the executable opens the same setup. The interactive setup opens with Mainnet selected. Enter your payout address and choose Start mining. Saved profiles keep your settings for next time. To start PHOTON directly in the mining TUI, use pickaxe mine --address "YOUR_MAINNET_PAYOUT_ADDRESS", replacing the placeholder with your valid payout CashAddr. Choose ELECTRIC, Hash split or ASIC mining in setup for the other modes. Servers are selected automatically for GPU tokens; BCH setup asks for the node or pool its mode needs.

PHOTON, ELECTRIC and hash-split sessions share a dashboard with per-token rates, wins and work, plus shared GPU utilization, temperature and power. Select a token for its own details. G shows charts (hidden initially), A opens Advanced settings, F opens ELECTRIC's pot details, and B safely returns to profiles after pending claims or sends are settled. See dashboard controls.

Portable engine in the TUI

The portable engine mines on any GPU above that has no native engine:

Where Command
Windows .\pickaxe.exe mine --network mainnet --backend wgpu
Linux ./pickaxe mine --network mainnet --backend wgpu
Windows on DirectX 12 Put Microsoft's dxcompiler.dll and dxil.dll next to pickaxe.exe (details), run $env:PICKAXE_WGPU_API = 'dx12', then the Windows command

Automatic selection already picks the portable engine for every GPU without a native engine; --backend wgpu forces it.

Several GPUs

One miner drives all of a machine's GPUs: they mine the same job for your address with separate work, so they never compete for the same reward. By default every discrete GPU mines:

Mine on Add to the mine command
Every discrete GPU nothing (default)
Every GPU, integrated included --include-integrated
Chosen GPUs --device 0,2, with the numbers devices prints

In setup, Enter on the GPU row lists the GPUs with a checkbox each, and a profile remembers the choice. The dashboard shows each GPU's rate and temperature. A GPU that fails restarts by itself while the others keep mining.

Several machines

Your other machines can mine as rigs of one coordinator, so they never compete for the same reward either. The coordinator is your normal miner with one more option: only it talks to the chain and claims, and every rig signs with its own key. The link is encrypted, and a rig trusts only the coordinator whose key it was given.

Machine Command
The coordinator your usual mine command plus --rigs-listen 0.0.0.0:3340; add --rigs-only for a coordinator that uses no GPU, on any computer
Each rig pickaxe mine --coordinator <coordinator address>:3340 --coordinator-key <key>, optionally --rig-name <name>

The coordinator prints its key when it starts and shows it on the dashboard with the rigs connected, their GPUs, rate and winners. Rigs need no address, server or node of their own and report their status as text lines; without the coordinator they pause. Repeat --coordinator and --coordinator-key (in the same order) to give a rig backup coordinators, tried in order. Press I on the coordinator's dashboard for the exact command each rig runs, for your network and, with Tailscale, from anywhere. For farms (rigs as services, ports, rigs in other places, the live test) see docs/farm.md; with --rigs-public a coordinator runs a public GPU pool, where each rig mines for its own --address and the operator's fee is a share of mining time.

Browser miner

The PHOTON browser miner uses the portable engine compiled to WebAssembly. Choose a browser with WebGPU enabled on your system. In the extracted browser download, run this command (Python required), then open http://127.0.0.1:8080, choose Mainnet or Chipnet, enter your payout address and press Start mining:

python -m http.server 8080 --bind 127.0.0.1 --directory web

Browser intensity defaults to 50% and changes in Advanced apply after the current batch. Pause native GPU mining before using the browser miner. Keep the tab open while mining. Names: wgpu is the Rust GPU library inside Pickaxe (the --backend wgpu option), and WebGPU is the browser API (names, portable builds).

Install

Download the archive for your operating system and architecture from the latest release. Use the release's SHA256SUMS.txt to verify the download, then extract the archive and open a terminal in its extracted folder. Keep the executable and its bundled GPU files together.

Linux:

./pickaxe

Windows PowerShell:

.\pickaxe.exe

Headless, from the same directory:

./pickaxe mine --no-tui
.\pickaxe.exe mine --no-tui

Setup and profiles

Without --no-tui, the miner opens a short setup:

  1. Profiles: your saved profiles. Enter on one opens its settings with Start selected, so a second Enter mines. R renames and D deletes (with a confirmation).
  2. What to do: GPU mining, ASIC mining, or run a pool for other miners.
  3. Network: Mainnet or Chipnet.
  4. Token: the GPU tokens for that network (with ELECTRIC and a Hash split between them, docs/hash-split.md), or for ASIC, "BCH + merge-mined CashTokens" or "ASIC-exclusive CashTokens (SAFA, ...)". Choosing BCH starts the BCH ASIC server, which builds blocks from your own BCH node (see docs/stratum-v2.md); the BCH node list finds Bitcoin Cash Node on the same computer, which needs no password. ASIC-exclusive tokens come later.
  5. Settings + Start: GPU, payout address, intensity, Fulcrum servers, BCH node and profile name on one page. GPU mining adds a Token row to change the token and a Mining row: solo, or join a GPU pool or farm with its coordinator's address and key (its Connection info shows them), as a rig; a farm's rigs can run HiveOS, mmpOS, RaveOS, SimpleMining OS and the like. ASIC mining adds a Mining row: solo on your node, or join a pool: a normal SV2 pool's address and key, or P2Pool, either a P2Pool node to join or your own P2Pool node that Pickaxe runs with your BCH node (docs/p2pool.md). With ELECTRIC chosen, alone or in a hash split, the settings show its fee pot with a QR code to fund it and its balance as it comes in. Running a pool asks what miners will mine: an ASIC pool asks for the pool type, your node, the pool fee, where it comes from (coinbase, mining work or both) and its address, then starts a public pool; a GPU pool asks for the pool type, the token's servers, the fee (a share of each rig's mining time) and its address, then coordinates the pool's rigs (docs/pool.md). The Pool row of Join a pool takes the pool's address or its one-line stratum2+tcp://HOST:PORT/KEY, which fills the key.

Fulcrum servers and nodes you add are saved once per network in config.sources.json, next to config.profiles.json, and shared by every profile on that network. Servers you add that are not built in are tried first; built-in servers, including ones you also saved, are ranked by health. Servers and nodes saved inside older profiles move there automatically. Press S while mining to change the address or intensity, or to use another server for the session; A opens Advanced settings.

Mainnet and Chipnet

Choose the network in setup or pass --network mainnet or --network chipnet. Mainnet is the default. Saved sources are separate for each network.

From an extracted native package, PHOTON test mining starts with:

./pickaxe --network chipnet mine --address 'bchtest:YOUR_TOKEN_AWARE_P2PKH_ADDRESS'

For ELECTRIC, use the same network selection with electric mine, and fund the Chipnet pot shown by setup. BCH ASIC mining also uses the network selected in setup; its node or upstream pool must serve that network. See the ELECTRIC and ASIC guides.

Replace the placeholder with your valid payout CashAddr. Mainnet requires bitcoincash: and Chipnet requires bchtest:; mismatched addresses are rejected, never converted. Chipnet and other BCH test networks share the address prefix, so the prefix alone cannot distinguish those networks.

Diagnostic logging

Optional file logging is disabled by default. Set PICKAXE_TUI_LOG before starting the interactive TUI to append timestamped events and status snapshots (about every 10 seconds) to a local file. Choose a writable location; its parent directory must already exist. This option does not apply to --no-tui mode.

Windows PowerShell, from the extracted release directory:

$env:PICKAXE_TUI_LOG = "$PWD\pickaxe-diagnostic.log"
.\pickaxe.exe mine

To disable logging for the next launch in that PowerShell session:

Remove-Item Env:PICKAXE_TUI_LOG -ErrorAction SilentlyContinue
.\pickaxe.exe mine

Linux, from the extracted release directory:

PICKAXE_TUI_LOG="$PWD/pickaxe-diagnostic.log" ./pickaxe mine

That Linux command enables logging for that invocation only. If the variable was exported in your shell, remove it before the next launch:

unset PICKAXE_TUI_LOG
./pickaxe mine

Stop the existing miner before relaunching. Changing the variable in a shell does not change a running miner, and a launcher script that sets it will enable logging again. There is no live logging toggle; /logs only displays runtime events in the TUI.

Log files are appended to without automatic rotation or a size limit. After an investigation, stop the miner before archiving or deleting the log, and disable logging for subsequent runs.

Build

Rust is the default CUDA mining backend. Build its GPU kernels with the pinned nightly compiler, then build the executable with stable Rust.

Linux:

rustup toolchain install nightly-2026-04-02 --profile minimal --component rust-src,llvm-tools-preview,llvm-bitcode-linker
bash tools/build-rust-kernels.sh sm_120
cargo build --release --locked

Windows PowerShell 7:

rustup toolchain install nightly-2026-04-02 --profile minimal --component rust-src,llvm-tools-preview,llvm-bitcode-linker
./tools/build-rust-kernels.ps1 -Architecture sm_120
cargo build --release --locked

The legacy CUDA C++ backend remains available with cargo build --release --locked --no-default-features --features tail-grind. Use a separate output directory when comparing the two builds.

The source-build binary is target/release/pickaxe_miner (pickaxe_miner.exe on Windows); release archives name it pickaxe or pickaxe.exe. Run --version to see the version of your build. Keep the supplied cuda/build directory beside the executable. Release archives include the required GPU files.

The release CUDA files target NVIDIA sm_120. AMD HIP retains its existing backend. Other NVIDIA architectures require compatible CUDA files and separate validation.

Interactive TUI:

cargo run --release -- mine

Headless:

cargo run --release -- mine --no-tui

List GPUs:

cargo run --release -- devices

Benchmark:

cargo run --release -- benchmark

Limitations

  • GPU token mining needs a GPU; there is no CPU mining fallback. An ASIC server or rigs-only coordinator can run on a host without a mining GPU.
  • CUDA performance was measured on the local NVIDIA GPU; HIP artifacts are build-verified, without a physical AMD performance claim.

Features

  • High-performance native GPU mining
  • Every GPU of a machine in one miner, with per-GPU status
  • PHOTON and ELECTRIC GPU mining on Mainnet and Chipnet
  • Hash split between GPU tokens in one session
  • ELECTRIC funding QR, signed fee-pot claims and owner-controlled recovery
  • BCH ASIC mining over SV1/SV2, managed P2Pool and pool Job Declaration
  • Automatic winner verification and submission
  • Runtime intensity control from 10% to 100%
  • Safe live payout-address switching
  • Fulcrum/Electrum connectivity
  • Native BCH node validation and transaction broadcast
  • Interactive Ratatui interface
  • Headless and JSON operation
  • Persistent, bounded GPU memory architecture
  • Stale-job and generation protection
  • Device discovery and benchmark tools

The reference/ directory contains PHOTON and ELECTRIC material used for implementation and correctness testing, including future-contract references. Its shared-t2/ and shared-stages/ folders hold the portable engine's WGSL, generated from rust-engine/ by tools/shared-gpu-proof/sync_filter.py and never edited by hand.

Development

dev is the alpha/testing branch; master is stable. Changes move through reviewed PRs. See development and release steps and Rust security checks.

License

Pickaxe Miner is licensed under the GNU Affero General Public License, version 3.0 only (AGPL-3.0-only). Third-party components and reference materials retain their respective licenses.

About

Pickaxe Miner is a native Rust high-performance GPU miner

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages