satoshiandClaude Opus 4.6
bd0b1b0318
Go 1.22 module that polls CKPool's Unix socket control API, queries
Bitcoin Core over JSON-RPC, merges both into a thread-safe snapshot, and
serves it over REST. Layout:
api/
├── cmd/kamado-api/main.go signal-aware entrypoint
└── internal/
├── config/ env var loader with validation
├── ckpool/ socket client (4-byte LE length-prefixed wire
│ protocol verified against libckpool.c), typed
│ response models for poolstats/users/workers/
│ clients/uptime, + unit tests using a fake
│ unix socket server
├── bitcoind/ minimal JSON-RPC client, getblockchaininfo
│ and getnetworkhashps
├── state/ Aggregator that refreshes a merged Snapshot
│ on a ticker; readers get a copy under RWMutex
└── httpapi/ REST handlers on Go 1.22 ServeMux:
/api/health /api/pool /api/users
/api/workers /api/clients /api/snapshot
CKPool stores hashrate as "dsps" (diff shares per second); we convert
to H/s via the 2^32 constant used by GoBrrr-Pool and other clients.
Every stat CKPool exposes to its socket API is surfaced — useragent,
IP, per-client diff, per-worker best diff — closing the gap against
Bassin which only reads the 60-second stats files.
Dockerfile does a CGO_ENABLED=0 static build on golang:1.22-bookworm
with -trimpath -ldflags=-s -w. docker-compose now runs both ckpool and
kamado-api, sharing a named volume for /run/ckpool so the API can
dial the stratifier socket directly.
Deferred to Phase 2b (called out in README):
- Bitcoin Core ZMQ hashblock subscriber
- WebSocket push for real-time UI updates
- SQLite persistence (block history, best-share history)
- CKPool log tailer for "Solved and confirmed block" detection
Tests and build NOT run in this commit — Go isn't installed in the
dev environment. Run `make api-test` or `make api` to verify.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# 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
|
|
- [x] Phase 2a: CKPool socket client, bitcoind RPC, state aggregator, REST API
|
|
- [ ] Phase 2b: ZMQ block notifier, WebSocket push, SQLite persistence, log tailer
|
|
- [ ] **Phase 3** — Svelte UI dashboard
|
|
- [ ] **Phase 4** — Monorepo Docker build, full stack integration
|
|
- [ ] **Phase 5** — Testing (regtest, testnet4), polish
|
|
|
|
## Quick start (dev)
|
|
|
|
```sh
|
|
cp .env.example .env # set POOL_BTCADDRESS and bitcoind creds
|
|
make up # build + start ckpool + api
|
|
curl localhost:8080/api/health
|
|
curl localhost:8080/api/pool
|
|
```
|
|
|
|
REST endpoints (Phase 2a):
|
|
|
|
| Route | Returns |
|
|
| -------------------- | ---------------------------------------------------- |
|
|
| `GET /api/health` | CKPool + bitcoind health |
|
|
| `GET /api/pool` | Pool stats + derived hashrate windows + chain info |
|
|
| `GET /api/users` | All users from `users` socket command |
|
|
| `GET /api/workers` | All workers from `workers` socket command |
|
|
| `GET /api/clients` | All connected stratum sessions (useragent, IP, diff) |
|
|
| `GET /api/snapshot` | Full merged snapshot (everything) |
|
|
|
|
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.
|