# 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
    - [x] Phase 2b: CKPool log tailer, block history, stdlib WebSocket push
    - [ ] Phase 2b.5: ZMQ block notifier, SQLite persistence (deferred until s9pk repo exists — need real Go build env for new deps)
- [ ] **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:

| 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/blocks`    | Recent solved blocks (in-memory ring, SQLite in Phase 2b.5) |
| `GET /api/snapshot`  | Full merged snapshot (everything)                           |
| `GET /api/ws`        | WebSocket push: full snapshot on every refresh + on solve   |

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.