SoloMiner

What is this?

SoloMiner is a little hobby project I built to try solo mining Bitcoin from my MacBook. It sits in your menu bar, connects to a mining pool over Stratum v1, and throws SHA-256d hashes at the network.

Will you actually find a block? Almost certainly not. The odds are something like 1 in a quadrillion per block with consumer hardware. But its fun to try, and if you somehow do hit one, the entire block reward is yours.

I mainly built this to learn about how Bitcoin mining works under the hood. Figured I'd share it incase anyone else wants to mess around with it.

Features

Menu Bar App

Lives in your menu bar. No dock icon, doesn't get in the way. Click to open a popover dashboard with live stats.

Metal GPU Mining

SHA-256d compute shader runs on your Apple GPU. Gets around ~69 MH/s on an M2 Pro. Not great, not terrible.

Terminal UI

Full curses-based TUI with the same features as the GUI. Run with --tui flag. Works over SSH too.

Auto Everything

Auto-reconnects on disconnect, auto-tunes difficulty based on your hashrate, auto-saves stats to disk.

Built-in Pools

Ships with 5 solo mining pools preconfigured. Or add your own. Has a ping button to check latency.

CLI Mode

Headless mining from the command line. Good for running in tmux on a mac mini or whatever.

Getting Started

You need a Mac running macOS 12 or later and Python 3.10+. Apple Silicon recommended but Intel works too (slower).

        # clone it

        git clone https://github.com/CooperWaNg-py/SoloMiner.git

        cd SoloMiner

        # install deps

        pip3 install -r requirements.txt

        # run the gui

        python3 main.py

        # or the terminal ui

        python3 main.py --tui

        # or just the cli

        python3 cli.py --address bc1qYOUR_ADDRESS_HERE

Then go to Settings, enter your Bitcoin address, pick a pool, and hit Start. That's pretty much it.

How It Works

If you're curious about what's happening under the hood:

Connect to pool

SoloMiner connects to a Bitcoin mining pool using the Stratum v1 protocol. The pool sends block templates (jobs) containing the data you need to hash.

Hash on GPU

Each job is an 80-byte block header. The Metal compute shader tries millions of different nonce values, computing SHA256(SHA256(header)) for each one. About 4 million per batch.

Submit shares

When a hash meets the pool's difficulty target, it's submitted as a "share". The engine auto-tunes difficulty to target roughly 1 share every 20 seconds.

Hope for the best

If a hash also meets the actual Bitcoin network difficulty (astronomically harder), you've found a block. You win the block reward. This basically never happens with consumer GPUs.

Building the .app

If you want a standalone .app you can put in your Applications folder:

        # install pyinstaller

        pip3 install pyinstaller

        # build it (uses the included spec file)

        pyinstaller SoloMiner.spec

        # the app ends up in dist/

        open dist/SoloMiner.app

There's also a setup.py for py2app if you prefer that. Check the README for more details. Fair warning - PyObjC bundling can be finicky depending on your Python version.

Automated builds run every 4 commits and get posted to the Releases page.

Heads up: macOS will block the app from opening since it's not signed. Go to System Settings > Privacy & Security, scroll down, and click "Open Anyway".

FAQ (sorta)

Will I actually mine a Bitcoin block?

Realistically no. Current Bitcoin network hashrate is around 800 EH/s. Your M2 does maybe 70 MH/s. That's like entering a foot race against a fighter jet. But the lottery ticket is free to play.

Does this work on Windows / Linux?

No, it's macOS only. It uses Apple Metal for GPU compute and PyObjC/AppKit for the UI. Those are Mac-only frameworks. If you're on Linux you probably want cgminer or something like that.

Is this safe to use?

The code is open source, you can read every line. It only connects to the pool you configure, only sends mining shares, and stores config locally at ~/Library/Application Support/SoloMiner.

Why does it use so much GPU?

Because it's mining lol. That's literally what mining is - doing as many hashes as possible as fast as possible. If you want it to chill a bit, switch to "Eco Mode" in the performance settings.

Why solo mining instead of a regular pool?

Regular pool mining with consumer hardware earns you like fractions of a penny per day after electricity. Not worth it. Solo mining earns you nothing 99.9999% of the time but has that tiny chance of everything.