# 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.