{"id":31618035,"url":"https://github.com/yash-xoxo/btc","last_synced_at":"2025-10-06T13:45:10.538Z","repository":{"id":317861380,"uuid":"1069133364","full_name":"Yash-xoxo/BTC","owner":"Yash-xoxo","description":"High performance, open source CPU/GPU Miner Docker Image for some mininer algoritms with AES, AVX, AVX2, SHA, AVX512 and VAES.","archived":false,"fork":false,"pushed_at":"2025-10-03T13:43:33.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T15:15:25.947Z","etag":null,"topics":["docker-compose","flask-api","html5"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yash-xoxo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-10-03T13:05:02.000Z","updated_at":"2025-10-03T13:43:36.000Z","dependencies_parsed_at":"2025-10-06T09:32:37.923Z","dependency_job_id":null,"html_url":"https://github.com/Yash-xoxo/BTC","commit_stats":null,"previous_names":["yash-xoxo/btc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Yash-xoxo/BTC","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yash-xoxo%2FBTC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yash-xoxo%2FBTC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yash-xoxo%2FBTC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yash-xoxo%2FBTC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yash-xoxo","download_url":"https://codeload.github.com/Yash-xoxo/BTC/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yash-xoxo%2FBTC/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621844,"owners_count":26017253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"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":["docker-compose","flask-api","html5"],"created_at":"2025-10-06T13:45:05.438Z","updated_at":"2025-10-06T13:45:10.530Z","avatar_url":"https://github.com/Yash-xoxo.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⛏ Bitcoin Lottery Miner Dashboard\n\nA **multi-rig monitoring stack** for Bitcoin solo mining with cpuminer-opt. This project runs multiple CPU miners and a live dashboard to track hashrate, shares, uptime, and lottery odds.\n\n---\n\n## 📖 Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Why Docker?](#-why-docker)\n- [Why Python?](#-why-python)\n- [Architecture](#architecture)\n- [Project Structure](#-project-structure)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Monitoring](#monitoring)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nBitcoin Lottery Miner Dashboard is a containerized monitoring solution for solo Bitcoin mining. It orchestrates multiple cpuminer-opt instances and provides a real-time web dashboard to track mining performance, statistics, and theoretical lottery odds of finding a block.\n\n**⚠️ Important:** Solo mining Bitcoin with CPU has **extremely low probability** of success. This project is primarily for **educational purposes** and learning about mining infrastructure.\n\n---\n\n## Features\n\n✅ **Multi-Rig Support** – Monitor multiple miners from a single dashboard  \n✅ **Real-Time Stats** – Live hashrate, shares submitted, uptime tracking  \n✅ **Lottery Odds Calculator** – Displays theoretical probability of finding a block  \n✅ **Dockerized** – Complete isolation, portability, and reproducibility  \n✅ **Easy Scaling** – Add more miners by editing `docker-compose.yml`  \n✅ **REST API** – JSON endpoint for programmatic access to miner stats  \n✅ **Lightweight** – Built on Flask + Gunicorn, minimal resource overhead  \n\n---\n\n## 🐳 Why Docker? \n\n`docker pull cniweb/cpuminer-opt:latest`\n\n- **Isolation** – Miners and dashboard run in separate containers, no pollution of your host system\n- **Portability** – Same configuration works on Linux, macOS, and Windows (with Docker Desktop)\n- **Easy Scaling** – Add more miners without managing dependencies manually\n- **Reproducibility** – Pinned versions ensure consistent behavior across environments\n- **Simple Deployment** – One command to start the entire stack\n\n---\n\n## 🐍 Why Python?\n\nThe dashboard backend is written in **Python (Flask)** because:\n\n- **Flask** is lightweight and perfect for serving APIs + simple HTML dashboards\n- Python's built-in libraries (`socket`, `json`, `time`) make polling miner stats trivial\n- **Easy to extend** – Add alerts, database logging, or advanced visualizations later\n- **Wide compatibility** – Works on any platform with Python 3.11+\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│           User Browser (Port 5000)          │\n└─────────────────┬───────────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────────┐\n│    Flask Dashboard (Gunicorn on :8080)      │\n│  - Polls miner APIs every few seconds       │\n│  - Calculates hashrate \u0026 lottery odds       │\n│  - Serves web UI + REST API                 │\n└──────────┬──────────────────────┬───────────┘\n           │                      │\n           ▼                      ▼\n┌──────────────────┐   ┌──────────────────┐\n│  Miner 1 (4048)  │   │  Miner 2 (4049)  │\n│  cpuminer-opt    │   │  cpuminer-opt    │\n│  → solo.ckpool   │   │  → solo.ckpool   │\n└──────────────────┘   └──────────────────┘\n```\n\n\n**How It Works:**\n\n1. **Miners** (`cniweb/cpuminer-opt`) run SHA256d hashing against Bitcoin via `solo.ckpool.org`. Each miner exposes an API on TCP (ports 4048, 4049)\n2. **Dashboard backend** (`dashboard/app.py`) is a Flask app that opens a socket to each miner, requests `summary`, parses JSON, and stores samples in memory\n3. **Frontend** (`dashboard/templates/index.html`) is a styled HTML dashboard that polls `/api/miners` every few seconds and updates stats live\n4. **Dockerfile** builds a minimal Python + Flask image with Gunicorn\n5. **Docker Compose** spins up miners and dashboard together, wiring their networks automatically\n\n\n---\n\n## 📂 Project Structure\n\n```\nBTC/\n├─ docker-compose.yml      # Orchestrates miners + dashboard\n└─ dashboard/\n    ├─ app.py              # Flask backend, polls miners via socket\n    ├─ requirements.txt    # Python dependencies (Flask, gunicorn)\n    ├─ Dockerfile          # Build instructions for dashboard image\n    └─ templates/\n        └─ index.html      # Frontend UI (HTML/CSS/JS)\n```\n\n---\n\n## Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/Yash-xoxo/BTC.git\ncd BTC\n```\n\nOr manually create the project structure as shown in [Project Structure](#-project-structure).\n\n### 2. Configure Your Bitcoin Wallet\n\nEdit `docker-compose.yml` and replace the placeholder address:\n\n```yaml\ncommand: \u003e\n  cpuminer\n  -a sha256d\n  -o stratum+tcp://solo.ckpool.org:3333\n  -u bc1YourRealBTCWalletAddress.LotteryMiner1  # ← CHANGE THIS\n  --api-bind 0.0.0.0:4048\n  -t 2\n```\n\n**⚠️ Critical:** Use a **real Bitcoin wallet address** or the pool will reject your shares.\n\n### 3. Build and Start Containers\n\n```bash\ndocker compose up -d --build\n```\n\nThis will:\n- Build the dashboard Docker image\n- Pull the cpuminer-opt image\n- Start 2 miner containers + 1 dashboard container\n\n### 4. Verify Containers Are Running\n\nCheck they're running:\n\n```bash\ndocker ps\n```\n\nYou should see:\n- `btc-miner1-1` (port 4048)\n- `btc-miner2-1` (port 4049)\n- `btc-dashboard-1` (port 5000 → 8080 inside)\n\n### 5. Check Logs\n\n**For miner logs:**\n\n```bash\ndocker logs -f btc-miner1-1\n```\n\nLook for:\n\n```\nAPI listening to 0.0.0.0:4048\naccepted: 1/1 (100.00%), ...\n```\n\n**For dashboard logs:**\n\n```bash\ndocker logs -f btc-dashboard-1\n```\n\nLook for:\n\n```\n[INFO] Listening at: http://0.0.0.0:8080\n```\n\n---\n\n\n## Configuration\n\n## 📈 Scaling\n\nTo add more miners:\n\n### 1. Add Miner to Docker Compose\n\nCopy one of the `miner` blocks in `docker-compose.yml` and modify:\n\n```yaml\n  miner3:\n    image: cniweb/cpuminer-opt:latest\n    container_name: miner3\n    command:\n      - \"cpuminer\"\n      - \"-a\"\n      - \"sha256d\"\n      - \"-o\"\n      - \"stratum+tcp://solo.ckpool.org:3333\"\n      - \"-u\"\n      - \"bc1YourRealBTCWallet.LotteryMiner3\"  # Change worker name\n      - \"-p\"\n      - \"x\"\n      - \"-t\"\n      - \"4\"\n      - \"--api-bind=0.0.0.0:4050\"  # New port\n    ports:\n      - \"4050:4050\"  # Map new port\n    restart: unless-stopped\n```\n\n### 2. Update Dashboard Configuration\n\nAdd the new miner to the `MINERS` environment variable in the `dashboard` service:\n\n```yaml\ndashboard:\n  build: ./dashboard\n  ports:\n    - \"5000:8080\"\n  environment:\n    - MINERS=miner1:4048,miner2:4049,miner3:4050  # Add miner3\n  depends_on:\n    - miner1\n    - miner2\n    - miner3  # Add dependency\n```\n\n### 3. Rebuild and Restart\n\n```bash\ndocker compose down\ndocker compose up -d --build\n```\n\nThe new miner will automatically appear on the dashboard!\n\n```\n\n### Adjusting CPU Threads\n\nChange the `-t` parameter in `docker-compose.yml`:\n\n```yaml\ncommand: \u003e\n  cpuminer\n  ...\n  -t 4  # Use 4 CPU threads instead of 2\n```\n\n---\n\n## Usage\n\n### Accessing the Dashboard\n\nOpen your browser and navigate to:\n\n```\nhttp://localhost:5000\n```\n\nYou'll see:\n- **Hashrate** for each miner\n- **Shares Submitted** (accepted/rejected)\n- **Uptime**\n- **Lottery Odds** (probability of finding a block)\n\n### REST API Endpoint\n\nGet miner stats as JSON:\n\n```bash\ncurl http://localhost:5000/api/miners\n```\n\nExample response:\n\n```json\n{\n  \"miners\": [\n    {\n      \"name\": \"Miner 1\",\n      \"status\": \"online\",\n      \"hashrate\": 1250000,\n      \"shares\": {\"accepted\": 42, \"rejected\": 0},\n      \"uptime\": 3600\n    },\n    {\n      \"name\": \"Miner 2\",\n      \"status\": \"online\",\n      \"hashrate\": 1180000,\n      \"shares\": {\"accepted\": 39, \"rejected\": 1},\n      \"uptime\": 3600\n    }\n  ],\n  \"total_hashrate\": 2430000,\n  \"network_difficulty\": 85000000000000,\n  \"lottery_odds\": \"1 in 35000000000\"\n}\n```\n\n---\n\n## Monitoring\n\n### Start Everything\n\n```bash\ndocker compose up -d --build\n```\n\n### Stop Everything\n\n```bash\ndocker compose down\n```\n\n### Restart Just Dashboard\n\nAfter making code changes:\n\n```bash\ndocker compose build dashboard\ndocker compose up -d dashboard\n```\n\n### View Logs\n\n**Dashboard logs:**\n\n```bash\ndocker logs -f btc-dashboard-1\n```\n\n**Miner logs:**\n\n```bash\ndocker logs -f btc-miner1-1\ndocker logs -f btc-miner2-1\n```\n\n### Debug Miner API Directly\n\nUse `netcat` to query a miner:\n\n```bash\nnc localhost 4048\n```\n\nThen type:\n```\nsummary\n```\n\nExpected response (JSON):\n\n```json\n{\"hashrate\":1250000,\"shares\":{\"accepted\":42,\"rejected\":0},\"uptime\":3600}\n```\n\n### Restart a Specific Service\n\n```bash\ndocker compose restart miner1\ndocker compose restart dashboard\n```\n\n---\n\n## Troubleshooting\n\n### Problem: Dashboard shows \"Miner Offline\"\n\n**Solution:**\n\n1. Check if miners are running:\n   ```bash\n   docker compose ps\n   ```\n\n2. Verify miner API is accessible:\n   ```bash\n   echo '{\"command\":\"summary\"}' | nc localhost 4048\n   ```\n\n3. Check miner logs for errors:\n   ```bash\n   docker logs btc-miner1-1\n   ```\n\n### Problem: Miners rejected by pool\n\n**Error in logs:** `Pool rejected share`\n\n**Solution:** Ensure your Bitcoin wallet address is valid (starts with `bc1`, `1`, or `3`).\n\n### Problem: High CPU usage\n\n**Solution:** Reduce threads in `docker-compose.yml`:\n\n```yaml\n-t 1  # Use only 1 CPU thread\n```\n\n### Problem: Dashboard not loading\n\n1. Check if port 5000 is already in use:\n   ```bash\n   lsof -i :5000\n   ```\n\n2. Change dashboard port in `docker-compose.yml`:\n   ```yaml\n   ports:\n     - \"8080:8080\"  # Use port 8080 instead\n   ```\n\n---\n\n\n**Happy Mining! ⛏️**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyash-xoxo%2Fbtc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyash-xoxo%2Fbtc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyash-xoxo%2Fbtc/lists"}