Phase 1: CKPool build infrastructure

Forks CKPool-solo at upstream commit cfb0f83b (v1.0) via a multi-stage Docker build, with an env-driven entrypoint that renders ckpool.conf from a template. The pinned commit already includes every fix referenced in Bassin issue #29 (workbase_id double increment, extended low-power timeouts, configurable dropidle, vardiff burst handling). No patches are applied yet — the patches/ directory holds the workflow and build wiring so Kamado-specific patches can be added incrementally. Build is portable across aarch64/x86_64: yasm is intentionally omitted so CKPool falls back to its C SHA256, and CFLAGS override drops upstream's default -march=native. Runtime image ships ckpool and ckpmsg for socket debugging; share logging (-L) is enabled by default. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-12 19:41:13 +03:00
commit d48035b366
12 changed files with 469 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Kamado Pool
+
+A modern, feature-complete solo Bitcoin mining pool built on a patched fork of CKPool, with a real-time web dashboard and a Go-based API middleware that surfaces everything CKPool knows.
+
+## Why Kamado?
+
+Existing CKPool-based solutions (like Bassin for Umbrel) read only a handful of periodic stats files and miss most of CKPool's rich data. Kamado talks directly to CKPool's Unix socket API to expose:
+
+- Real-time per-client data: hashrate, difficulty, user agent, hardware detection
+- Full block-found history with height, hash, reward, and solving worker
+- Per-worker and per-client best share tracking (current + all-time)
+- Network difficulty, pool efficiency, expected time to block
+- Live dashboard updates via WebSocket (no 60-second file polls)
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────┐
+│  ckpool-solo (C)  ──Unix socket──►  kamado-api (Go) │
+│   ports: 3333                             ports: 80 │
+│                                                    │
+│   ▲ stratum                         ▲ HTTP/WS     │
+│   │                                 │              │
+│  Miners                           Browser          │
+│                                                    │
+│  bitcoind ◄──── RPC + ZMQ ────── ckpool + kamado-api│
+└────────────────────────────────────────────────────┘
+```
+
+Three main components:
+
+| Component      | Language | Purpose                                            |
+| -------------- | -------- | -------------------------------------------------- |
+| `ckpool/`      | C        | Stratum server, share validation, block submission |
+| `api/`         | Go       | Socket client, REST/WebSocket API, persistence     |
+| `ui/`          | Svelte   | Real-time dashboard                                |
+
+## Phases
+
+- [x] **Phase 1** — Fork & fix CKPool, build infrastructure
+- [ ] **Phase 2** — Go API middleware (socket client, REST, WebSocket, SQLite)
+- [ ] **Phase 3** — Svelte UI dashboard
+- [ ] **Phase 4** — Monorepo Docker build, full stack integration
+- [ ] **Phase 5** — Testing (regtest, testnet4), polish
+
+StartOS packaging lives in a separate repository.
+
+## Upstream
+
+CKPool by Con Kolivas: https://bitbucket.org/ckolivas/ckpool
+
+Pinned commit: see [ckpool/CKPOOL_COMMIT](ckpool/CKPOOL_COMMIT)
+
+## License
+
+GPL-3.0. CKPool itself is distributed under GPL-3.