stacks-miner

stacks-miner is a control plane for Stacks mining. One command to install, configure, and supervise a Stacks miner with Bitcoin Core, stacks-node, and stacks-signer.

stacks-miner does not generate or manage wallets. You bring your own Bitcoin and Stacks keys from wallets you already control.

Note: Bitcoin testnet3 is broken for stacks-node SPV. Use --network mainnet for production or --network regtest for local testing.

What You Need

1. A Bitcoin wallet — Sparrow or Electrum. Create a wallet, write down the recovery phrase, and fund it with at least 0.01 BTC.
2. A Stacks wallet — Leather or Xverse. Create a wallet and back up the recovery phrase.
3. A Linux server — 16 GB RAM, 800 GB disk, 4+ CPU cores. Hetzner dedicated servers work well (~$40/month).

Exporting Your Private Keys

You'll need to export one private key from each wallet and save them to files on your server:

Bitcoin key (from Sparrow):

1. Open your wallet in Sparrow
2. Go to Settings → Keystore → click the eye icon to show the master private key
3. Copy the WIF key (starts with L, K, or 5)
4. Save it: echo 'YOUR_WIF_KEY' > ~/.btc-mining-key && chmod 600 ~/.btc-mining-key

Stacks key (from Leather):

1. Open Leather → Settings → Secret Key → copy your 24-word seed phrase
2. Use the Stacks CLI to derive the hex key: npx @stacks/cli make_keychain -m "your 24 word phrase here"
3. Copy the privateKey field from the JSON output (64-character hex string)
4. Save it: echo 'YOUR_HEX_KEY' > ~/.stx-mining-key && chmod 600 ~/.stx-mining-key

Security: Never paste private keys into chat, email, or any shared channel. Save them directly to files on the server.

Setup with Claude Code (Recommended)

If you have Claude Code installed, it knows how to set up stacks-miner end-to-end. Just tell it:

"Set up a Stacks miner on mainnet"

Claude will walk you through each step interactively — wallet setup, key export, server provisioning, installation, and monitoring. It will ask questions at each decision point rather than dumping everything at once.

To give Claude access to the stacks-miner skill, clone this repo on the machine where you're running Claude Code:

git clone https://github.com/huth-stacks/stacks-miner.git
cd stacks-miner

Then start Claude Code in that directory and ask it to set up your miner.

Quick Start (Manual)

# On your Linux server, build the binary:
git clone https://github.com/huth-stacks/stacks-miner.git
cd stacks-miner
cargo build --release
sudo cp target/release/stacks-miner /usr/local/bin/

# One-command install (downloads Bitcoin Core + stacks-core, deploys systemd services):
sudo stacks-miner install --network mainnet \
  --bitcoin-key-file ~/.btc-mining-key \
  --stacks-key-file ~/.stx-mining-key \
  -y

This takes ~90 minutes (mostly loading the Bitcoin UTXO snapshot). When done, it prints your funding address and next steps.

Step-by-Step Setup

If you prefer to run each step individually:

# 1. Initialize with your wallet keys
stacks-miner init --network mainnet \
  --bitcoin-key-file ~/.btc-mining-key \
  --stacks-key-file ~/.stx-mining-key \
  --bitcoin-rpc-url http://127.0.0.1:8332 \
  --bitcoin-rpc-username btcuser \
  --bitcoin-rpc-password btcpass

# 2. Confirm your wallets are backed up externally
stacks-miner backup --network mainnet --confirm

# 3. Check funding address and balance
stacks-miner fund --network mainnet

# 4. Verify everything is healthy
stacks-miner doctor --network mainnet

# 5. Start mining (foreground supervisor)
stacks-miner start --network mainnet

# 6. Check status
stacks-miner status --network mainnet --json

Commands

stacks-miner install    One-command server provisioning (requires root)
stacks-miner init       Initialize with your wallet keys
stacks-miner backup     Confirm your wallets are backed up
stacks-miner fund       Show funding address, balance, and mining runway
stacks-miner doctor     Health checks with remediation guidance
stacks-miner status     Readiness state and sync progress
stacks-miner start      Self-healing supervisor (foreground process)
stacks-miner upgrade    Update stacks-node and stacks-signer binaries

Run stacks-miner <command> --help for full options on any command.

Mining Costs

At the default burn rate of 20,000 sats/block (~144 blocks/day):

Duration	BTC needed
24 hours	~0.003 BTC
1 week	~0.02 BTC
1 month	~0.09 BTC

Adjust with --burn-fee-cap during init. Higher burn = higher chance of winning blocks.

Server Requirements

Resource	Mainnet	Regtest (testing)
RAM	16 GB	4 GB
Disk	800 GB	5 GB
CPU	4+ cores	2 cores
Bitcoin sync	~90 min (with UTXO snapshot)	Instant

Building from Source

Requires Rust (install with curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh).

cargo build --release                # Build the binary
make build-linux                     # Static musl binary (no GLIBC deps)
cargo test                           # Run tests

Documentation

• SKILL.md — complete operator guide
• runbooks/ — operational playbooks for testnet and mainnet
• docs/strategy.md — design rationale