satoshi/KamadoPool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Polish README

Browse Source
This commit is contained in:
satoshi
2026-05-28 08:11:24 +03:00
parent 71cf277796
commit 85f61e5c53
1 changed files with 51 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+51 -17
View File
@@ -55,6 +55,13 @@ The Go API (`kamado-api`) bridges CKPool's Unix socket protocol, bitcoind's JSON
- **Block reconciliation** — On startup, cross-references in-memory blocks with the database and bitcoind to detect orphans and fill gaps.
- **Chain reorg detection** — Scoped to the active chain; clears stale state on tip changes.
- **SQLite persistence** — Blocks, accelerated transactions, and log cursor survive restarts. Non-fatal if unavailable (in-memory ring fallback).
- **Transaction accelerator** — Inspects the current block template to find the marginal (lowest fee-rate) transaction, calls `prioritisetransaction` to boost a target tx, and reports the displaced fee as revenue impact. Includes a hard cap (2000 sat/vB) and lifecycle cleanup.
### Stratum TLS
Optional encrypted stratum via stunnel. CKPool binds two stratum sockets — a public plaintext port and a loopback-only internal port. Stunnel terminates TLS on the external port and forwards decrypted traffic to the internal bind. CKPool tags connections by `serverurl` index (`server === 1` means TLS), which the dashboard reads to display a lock icon next to encrypted miners — no source-IP heuristics needed.
The TLS certificate is auto-generated on first start with broad SAN coverage (`.local`, `.embassy`, `.onion`, `.lan`, `.home.arpa`, `.internal`) so miner firmware that validates the SAN against the connection hostname (e.g. AxeOS with mbedtls) works without manual cert pinning. A version marker triggers automatic regeneration when the cert format changes.
### Dashboard
@@ -63,12 +70,17 @@ The Svelte 5 dashboard connects via WebSocket for real-time push updates (no pol
- **Pool overview** — Hashrate (1m/5m/1h/24h), uptime, workers online, shares accepted/rejected, expected time to block, round effort
- **Hashrate chart** — Interactive multi-window visualization
- **Miners table** — Per-user and per-worker stats: hashrate, difficulty, latency, best shares, idle detection
- **Hardware detection** — Parses stratum user-agent strings to identify miner hardware (Bitaxe, Bitaxe Hex, NerdMiner, NerdAxe, NerdQAxe, NerdOCTAXE, NerdEKO, NerdNOS, PiAxe, QAxe, 0xAxe, LeafMiner, and more). Open-source hardware is flagged with a star badge so operators can see their fleet composition at a glance.
- **TLS badges** — Miners connected via the encrypted stratum port display a lock icon in the miners table, derived from CKPool's `server` field (no IP heuristics).
- **User/worker detail pages** — Deep dive into individual miner stats, cumulative work, and luck
- **Block history** — Found blocks with height, hash, reward, solving worker, orphan status
- **Best share leaderboard** — "This round" and "all-time" tracking with per-worker breakdown
- **Transaction accelerator** — Boost transactions via bitcoind's `prioritisetransaction` RPC with marginal fee displacement analysis
- **Block history** — Found blocks with height, hash, reward, solving worker, chain name, orphan status
- **Best share leaderboard** — "This round" and "all-time" tracking with per-worker breakdown and glowing difficulty range indicators
- **Transaction accelerator** — Boost transactions via `prioritisetransaction` with marginal fee displacement analysis showing the revenue impact of each boost
- **Block-found animation** — Celebratory toast on solve events
- **Health banners** — Live status indicators for CKPool, bitcoind, ZMQ, and submit-gap diagnostics
- **Block-update latency** — Tracks and displays average, last, and wasted-work latency for block notifications so operators can tune ZMQ and polling
- **Shares bar** — Accepted/rejected/stale share summary with ratio visualization
- **Custom mempool explorer** — Transaction and block links can point at a self-hosted mempool instance instead of the public mempool.space
- **Mobile responsive** — Full breakpoint coverage for phone and tablet
- **Donation footer** — BTC address with hover QR code
@@ -78,6 +90,7 @@ The Svelte 5 dashboard connects via WebSocket for real-time push updates (no pol
- **ckpool kill-on-failure** — When bitcoind becomes unreachable, kamado-api kills ckpool so miners can failover to another pool. ckpool restarts automatically when bitcoind recovers.
- **Deferred RPC** — Dashboard RPCs wait until the ckpool notifier completes on tip change to prioritize system resources for block reconstruction and validation.
- **Log cursor persistence** — The tailer's file offset is stored in SQLite so block-solve detection resumes correctly after restart.
- **Warm-up resilience** — The ckpool socket client handles transient EOFs during startup gracefully instead of crashing.
## API Reference
@@ -160,14 +173,31 @@ Starts Vite on `:5173` with hot reload. API calls are proxied to `:8080` — run
### Testing
```bash
make api-test # Go unit tests
make api-test # Go unit tests (race detector enabled)
cd api && go test -race ./... # same thing without Make
./test/regtest_smoke.sh # Full regtest integration test
```
#### Go Unit Tests
The test suite covers the critical mining path with 38 tests across 5 packages:
| Package | Tests | Coverage |
|---------|-------|----------|
| `bitcoind` | RPC retry logic (transient 503s, warmup errors, semantic errors, exhausted retries), coinbase reward extraction | Ensures the RPC client retries on transport failures and bitcoind warmup but fails fast on semantic errors |
| `ckpool` | Socket client ping, pool stats parsing, client listing, dial error handling | Validates the 4-byte length-prefixed binary protocol against a mock Unix socket |
| `logmon` | Line parsing (solved blocks, submitting variants, diff reset, unrelated lines), tailer run (basic read, cursor resume after restart, log rotation) | Covers the full log tailer lifecycle including inotify-based file watching |
| `state` | Block reconciliation (chain-scoped filtering, genuine reorgs, RPC errors, legacy blocks, cross-network), block ingestion (new blocks, dedup, chain stamping) | Ensures reorg detection never false-orphans blocks from other chains |
| `store` | SQLite roundtrips (insert, dedup, orphan marking, enrichment updates, enrichment queries, chain column migration, KV store) | Validates schema migrations and all persistence operations |
#### Regtest Smoke Test
The smoke test runs two phases on regtest:
1. **Log-inject path** — Injects a synthetic block-solve line into ckpool's log, verifies the tailer detects it, enriches it via bitcoind RPC, and surfaces it at `/api/blocks`.
2. **Full stratum path** — Starts ckpool, connects a Python stratum miner, mines a real block, verifies the coinbase contains the "kamado" tag and the configured pool identifier, and confirms bitcoind accepted the block.
1. **Log-inject path** — Injects a synthetic block-solve line into ckpool's log, verifies the tailer detects it, enriches it via bitcoind RPC, and surfaces it at `/api/blocks`. Quick, no ckpool binary needed.
2. **Full stratum path** — Starts ckpool, connects a Python stratum miner, mines a real block, verifies the coinbase contains the "kamado" tag and the configured pool identifier, validates that bitcoind accepted the block with confirmations > 0, and checks that the block validation log shows correct chain acceptance.
The smoke test auto-builds ckpool from the pinned upstream source with patches applied if not cached (build cached in `~/.cache/kamado-dev/`).
### Project Structure
@@ -175,24 +205,28 @@ The smoke test runs two phases on regtest:
api/
cmd/kamado-api/ Main entry point
internal/
accelerator/ Transaction priority boosting
bitcoind/ Minimal JSON-RPC client
ckpool/ Unix socket protocol client
config/ Environment variable loading
accelerator/ Transaction priority boosting via prioritisetransaction
bitcoind/ Minimal JSON-RPC client with retry logic
ckpool/ Unix socket protocol client (4-byte LE framing)
config/ Environment variable loading and validation
httpapi/ REST routes, WebSocket hub, SPA handler
logmon/ inotify-based CKPool log tailer
state/ Snapshot aggregator, block reconciliation
store/ SQLite persistence layer
state/ Snapshot aggregator, block reconciliation, reorg detection
store/ SQLite persistence (blocks, KV, accelerated txs, cursor)
webui/ Embedded Svelte assets (go:embed)
zmqmon/ ZMQ hashblock subscriber
ckpool/
patches/ Patch series applied to upstream
config/ ckpool.conf template
patches/ Seven-patch series applied to upstream
config/ ckpool.conf.template (sed-rendered at startup)
Dockerfile Two-stage ckpool build
ui/
src/ Svelte 5 components and stores
docker/ Shared entrypoint scripts
test/ Regtest smoke test
src/
lib/ Svelte 5 components (dashboard, miners, blocks, accelerator)
format.ts Hardware detection, hashrate formatting, address parsing
snapshot.svelte.ts Global reactive store (WebSocket + REST fallback)
types.ts TypeScript interfaces for API responses
test/
regtest_smoke.sh Two-phase integration test (log-inject + full stratum)
```
## StartOS