Files

T

satoshi d37a23bc57 Phase 3: Svelte 5 UI skeleton

Svelte 5 + Vite + TypeScript dashboard that consumes kamado-api over
REST for the first paint and then subscribes to /api/ws for live
updates. Zero runtime deps beyond svelte itself; plain CSS, no
component library.

Layout:

- Header with brand, WebSocket status badge, chain + height
- PoolOverview: hashrate (1m/5m/1h/24h), miner count, network
  hashrate + diff, pool share (ppb), expected time to block, uptime
- BlocksTable: recent solves from the in-memory ring (will be
  SQLite-backed in Phase 2b.5)
- BestShares: top-10 workers by bestever, falling back to bestdiff
  when the ckpool patch isn't present
- MinersTable: joined view of stratum clients and workers with
  user-agent-based hardware detection (Bitaxe, NerdQAxe, Antminer,
  ...), hashrate, best-round, best-ever, last share

State is a single $state() snapshot store in svelte-runes form;
components read from it via $derived. The store does one initial
REST snapshot fetch, then owns the WebSocket with exponential
backoff reconnects.

Vite dev server on :5173 proxies /api and /api/ws to localhost:8080
so you can run `make ui-dev` alongside `make up` in development.
Production serving (bundled into the Go binary via embed, behind /
on :8080) lands in Phase 4.

2026-04-13 03:07:59 +03:00

4.2 KiB

Raw Blame History

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

Phase 1 — Fork & fix CKPool, build infrastructure
[~] Phase 2 — Go API middleware
- Phase 2a: CKPool socket client, bitcoind RPC, state aggregator, REST API
- 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)
ckpool patch 0001: expose bestever in runtime socket JSON so the UI can show "this round" and "all-time" best share side by side
[~] Phase 3 — Svelte UI dashboard (skeleton: header, pool overview, miners table, blocks, best shares leaderboard; live WS updates)
Phase 4 — Monorepo Docker build, full stack integration
Phase 5 — Testing (regtest, testnet4), polish

Quick start (dev)

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

License

GPL-3.0. CKPool itself is distributed under GPL-3.

4.2 KiB Raw Blame History