{"id":50896994,"url":"https://github.com/vanities/matador-miner","last_synced_at":"2026-06-16T01:01:59.333Z","repository":{"id":359564745,"uuid":"1245945620","full_name":"vanities/matador-miner","owner":"vanities","description":"Isolated, sandboxed Docker GPU miner for btxchain/btx (BTX): GPG-signed-release-only install, assumeutxo fast-start, CUDA MatMul PoW, self-custody wallet.","archived":false,"fork":false,"pushed_at":"2026-06-15T01:40:45.000Z","size":3961,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T02:22:36.349Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Cuda","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanities.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T18:05:11.000Z","updated_at":"2026-06-15T01:40:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vanities/matador-miner","commit_stats":null,"previous_names":["vanities/btx-miner","vanities/matador-miner"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vanities/matador-miner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanities%2Fmatador-miner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanities%2Fmatador-miner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanities%2Fmatador-miner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanities%2Fmatador-miner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanities","download_url":"https://codeload.github.com/vanities/matador-miner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanities%2Fmatador-miner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34386320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T01:00:45.981Z","updated_at":"2026-06-16T01:01:59.313Z","avatar_url":"https://github.com/vanities.png","language":"Cuda","funding_links":[],"categories":[],"sub_categories":[],"readme":"# matador-miner - a fast standalone miner for `btxchain/btx`\n\n![MATADOR - fearless BTX MatMul miner](docs/matador.png)\n\nA **standalone, decoupled** miner for the BTX MatMul proof-of-work: it pulls work from your\nown `btxd` (`getblocktemplate`), solves on the accelerator, and submits blocks - so updating\nthe miner never restarts your node. Built to be fast (our +22.9% pipeline-overlap is baked\nin) and to keep 100% of every solo block (no pool fee).\n\n**Backends**\n\n| Backend | Status |\n|---------|--------|\n| NVIDIA CUDA (single GPU, e.g. RTX 5090 / Blackwell `sm_120`) | working today |\n| NVIDIA multi-GPU | on the roadmap |\n| Apple Silicon (Metal) | on the roadmap (in progress) |\n\nThis repo also ships a sandboxed **Docker node + solo-miner** setup (`make solo`) that runs\na pinned BTX full node and mines with the CUDA backend, keeping the node, miner, and wallet\ndata isolated from the host - a turnkey way to run a node for the standalone miner to mine\nagainst, or to solo-mine end to end.\n\n\u003e **Upstream / official node:** [`github.com/btxchain/btx`](https://github.com/btxchain/btx). Pinned to **v0.32.11** (commit [`215170f2`](https://github.com/btxchain/btx/commit/215170f27f7d6889ce34aa7dbba2858ea07a468c)). This repo **compiles that exact commit from source** with the CUDA MatMul backend by choice - it guarantees native `sm_120` codegen for the 5090 and a byte-reproducible build. To run the GPG-signed prebuilt instead, set `BTX_INSTALL_MODE=release` + `RELEASE_TAG=v0.32.11` in `docker-compose.yml`.\n\u003e\n\u003e **Consensus timeline (upgrade before each height or you fork off the network):** block **125,000** shielded sunset + MatMul nonce-seed **v2**; **130,000** temporary empty-block subsidy penalty; **130,500** MatMul seed-derivation **v3** (binds each nonce's seed to the parent block's `parent_mtp`); **132,000** forward consensus (shielded-exit velocity cap, empty-block penalty ends). 0.32.11 covers all of these.\n\n## What this does\n\n- Compiles `btxd` + `btx-cli` and the CUDA MatMul backend from a pinned upstream commit (**0.32.11**), in the Docker build.\n- Runs that BTX full node in Docker (archival, `prune=0`, so shielded-state rebuilds never fail).\n- Creates/uses a local wallet under `./btx-data`.\n- Starts a supervised GPU **solo**-mining loop using BTX's MatMul proof-of-work.\n\n## Safety model (why this is the contained way to try it)\n\n- Runs entirely in a container; the node/miner cannot see your host filesystem.\n- **Source build:** compiles a single, pinned, immutable commit (0.32.11) from\n  [`github.com/btxchain/btx`](https://github.com/btxchain/btx). The signed\n  release key is integrity-only (self-published, no independent vouching), so\n  commit pinning is comparable trust - and a native `sm_120` compile is better\n  for the 5090. Acceptable **only** because everything runs sandboxed here with\n  no funds at stake; do not extend trust beyond this container. Set\n  `BTX_INSTALL_MODE=release` to run the signed prebuilt instead.\n- Mines to a wallet generated **inside your mounted `./btx-data`** so the wallet\n  state and keys persist outside the container.\n- Publishes no ports and does not require any external wallet service.\n\n## Prerequisites (on the Linux box with the GPU)\n\n- Docker + Docker Compose v2\n- Recent NVIDIA driver (Blackwell RTX 5090 needs a current R570+/R580+ driver)\n- `nvidia-container-toolkit` installed and configured:\n  `sudo nvidia-ctk runtime configure --runtime=docker \u0026\u0026 sudo systemctl restart docker`\n- Confirm the GPU is visible to Docker:\n  `docker run --rm --gpus all nvidia/cuda:12.8.0-runtime-ubuntu24.04 nvidia-smi`\n\n## Run\n\n```bash\n# copy this folder to the Linux box, then:\nmake solo        # build (first run) + solo-mine on 0.32.11\nmake help        # all targets: up/down/logs/status/balance/backup/restore/deploy/...\n```\n\nFirst build **compiles btxd + the CUDA backend from source** (a one-time\n~20-40 min step; the NVIDIA CUDA toolchain it needs is pulled into the Docker\nbuild, not your host). After that it syncs the chain (fast-start / assumeutxo\nkeeps this short - see [Fast-start](#fast-start--snapshot-0321), prints **your**\nmining address, and starts a supervised solo-mining loop. Rebuilds reuse Docker's\nlayer cache, so nothing recompiles unless you change `BTX_SOURCE_REF`.\n\n## Install the prebuilt miner (`matador-miner`)\n\nPrefer a single binary over the Docker stack? `matador-miner` is a **standalone solo GPU\nminer**: it pulls work from **your own `btxd`** via `getblocktemplate`, solves on the GPU\n(our +22.9% overlap is baked in), and submits with `submitblock`. It is **decoupled from\nthe node**, so updating the miner never restarts `btxd` (no shielded-state warmup, no lost\npropagation standing). Linux x86-64, NVIDIA Blackwell `sm_120` (RTX 5090).\n\n**One-line install** (downloads the latest release, verifies the sha256, installs to\n`/usr/local/bin`):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vanities/matador-miner/main/install.sh | bash\n```\n\nPin a version or change the install dir with env vars:\n`VERSION=v0.1.0 PREFIX=$HOME/.local/bin` before the pipe. Prefer to inspect first? Read\n[`install.sh`](install.sh), or do it by hand:\n\n```bash\napi=https://api.github.com/repos/vanities/matador-miner/releases/latest\nurl=$(curl -fsSL \"$api\" | grep -oE '\"browser_download_url\": *\"[^\"]+linux-x86_64\"' | cut -d'\"' -f4)\ncurl -fsSLO \"$url\" \u0026\u0026 curl -fsSLO \"$url.sha256\"          # binary + checksum\nsha256sum -c \"$(basename \"$url\").sha256\"                 # must print: OK\nchmod +x \"$(basename \"$url\")\" \u0026\u0026 sudo mv \"$(basename \"$url\")\" /usr/local/bin/matador-miner\nmatador-miner --help\n```\n\n**Run it** against a synced `btxd` (this repo's `make node`, or any `btxd` v0.32.11+ with\nRPC enabled):\n\n```bash\nmatador-miner \\\n  --chain main \\\n  --payoutaddress btx1...your-P2MR-address \\   # getnewaddress from a current btx wallet\n  --rpccookiefile ~/.btx/.cookie               # or --rpcuser/--rpcpassword\n# extras: --rpcconnect 127.0.0.1 --rpcport 19334 --maxtries N\n#         --dev-fee 1 (default; 0 disables)  --dev-address \u003caddr\u003e  LOG_LEVEL=debug\n```\n\n- **Solo + your keys only.** It submits to *your* `btxd` over **localhost RPC** and holds\n  **no wallet keys**; mined coins pay the `--payoutaddress` you provide.\n- **1% dev fee, time-based + transparent.** Like Claymore/PhoenixMiner/T-Rex, it points the\n  coinbase at the dev address for ~1% of wall-clock time (~36s/hr) and **logs every\n  entry/exit** of that window. Turn it off with `--dev-fee 0`.\n- Closed-source binary (AM2 LLC); **verify the sha256** before running. `LOG_LEVEL=debug`\n  for full per-stage solve timing, every template, every submit (accept/reject + reason).\n\n## Why solo\n\nYou run your own node + our CUDA solver, keep 100% of every block (no fee), saturate the\nGPU (~100% on a 5090), and get our +22.9% pipeline-overlap that a closed pool binary can't\ncarry. The trade-off is variance: solo is an all-or-nothing block lottery.\n\n## Operations (host-side helpers)\n\nOptional but recommended for an unattended rig. Run them detached on the Linux box:\n\n```bash\n# from your clone on the Linux box:\nmkdir -p ops-logs\nnohup bash scripts/empty-block-keeper.sh \u003e\u003e ops-logs/empty-block-keeper.log 2\u003e\u00261 \u003c/dev/null \u0026 disown\nnohup bash scripts/mining-watchdog.sh    \u003e\u003e ops-logs/mining-watchdog.log    2\u003e\u00261 \u003c/dev/null \u0026 disown\n```\n\n- **`scripts/empty-block-keeper.sh`** - between heights 130,000 and 132,000 a coinbase-only\n  block pays **half** the subsidy. The keeper holds a tiny self-spend in the mempool so your\n  blocks stay `nTx\u003e=2` (full subsidy). Self-exits at 132,000.\n- **`scripts/mining-watchdog.sh`** - samples the solve counter / tip / peers; on a stall it\n  alerts (`ops-logs/ALERT.txt`, optional push via `ALERT_CMD`) and auto-restarts the miner,\n  escalating to CRITICAL if a restart can't fix it (as a consensus stall wouldn't).\n- **`make deploy`** - minimal-downtime version bump: builds the new image while the miner\n  keeps mining, swaps on success, and times the warmup gap. See `docs/minimal-downtime-deploy.md`.\n\n## Monitor\n\n```bash\nmake status                                                                       # sync + difficulty + live solve rate\ndocker compose exec btx-miner btx-cli -datadir=/data getblockchaininfo            # sync state\ndocker compose exec btx-miner btx-cli -datadir=/data getmininginfo                # difficulty, chain_guard\ndocker compose exec btx-miner btx-cli -datadir=/data -rpcwallet=miner getbalance  # what you've mined\ncat ./btx-data/miner-address.txt                                                  # your reward address\n```\n\n## Fast-start / snapshot (0.32.11)\n\nThe entrypoint loads an assumeutxo snapshot to skip most of the initial sync. 0.32.11 added\nconsensus pins for shielded snapshots, so the bundled fast-start snapshot loads only with\n`allowunpinnedshieldedsnapshot=1` - the entrypoint sets this automatically (idempotent, so\nexisting datadirs pick it up on the next restart). `prune=0` means the node rebuilds the\nunshield-velocity state locally after loading, so forcing the load is safe.\n\n## Stop / clean up\n\n```bash\ndocker compose down        # stop\nrm -rf ./btx-data          # delete chain data + wallet (back it up first if you mined anything)\n```\n\n## Manual fallback (if the automated path hiccups)\n\nThe compiled binaries live at `/opt/btx/bin` (already on `PATH` in the image),\nso you can drive them by hand:\n\n```bash\ndocker compose run --rm --entrypoint bash btx-miner\n# inside the container:\nBTX_MATMUL_BACKEND=cuda btxd -datadir=/data -server=1 -daemon\nbtx-cli -datadir=/data createwallet miner\nbtx-cli -datadir=/data -rpcwallet=miner getnewaddress\n/opt/btx-src/contrib/mining/start-live-mining.sh \\\n  --datadir=/data --wallet=miner \\\n  --address-file=/data/miner-address.txt --should-mine-command=/bin/true\n```\n\nTo build a different commit, change `BTX_SOURCE_REF` in `docker-compose.yml`.\nTo run the signed precompiled release instead, set `BTX_INSTALL_MODE=release`\nand `RELEASE_TAG=v0.32.11`; the entrypoint then runs the upstream `faststart`\ninstaller (see `doc/linux-release-builds.md`).\n\n## Power use\n\nA 5090 mining full-tilt draws ~0.5 kW, roughly **$1-2/day** in electricity. For best\nnonces/watt rather than peak rate, `scripts/gpu-tune.service` locks the clock + caps power\n(~346 W at ~99% of the hashrate); install it per the comments in that file.\n\n## Credits / thanks\n\nThis repo is just packaging + tuning on top of other people's hard work. Thanks to:\n\n- **[`btxchain/btx`](https://github.com/btxchain/btx)** - the BTX node, the MatMul\n  proof-of-work, and the CUDA backend this builds and mines with. Everything here\n  compiles a pinned commit of it.\n- **[`dexbtx/minebtx`](https://github.com/dexbtx/minebtx)** (shib) - the minebtx\n  pool and `dexbtx-miner` stratum orchestrator; the protocol reference for our\n  v2/v3 seed + `parent_mtp` handling.\n\n## License\n\nProprietary - Copyright (c) 2026 AM2 LLC. All rights reserved. See [LICENSE](LICENSE).\nThird-party components (btxchain/btx and its Bitcoin Core lineage) remain under the\nMIT License. matador-miner release binaries ship under their own end-user terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanities%2Fmatador-miner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanities%2Fmatador-miner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanities%2Fmatador-miner/lists"}