ckpool patch 0004 now bounds generator_submitblock's wait for a live
primary to ~3s rather than spinning indefinitely, and calls submit
before writing the pending-block hex to disk so the happy path adds
zero latency. The right default is small: a fallback should kick in
while the work is still relevant for the current chain tip.
Range widened to [1, 600] so impatient operators can crank further
down. Description updated to reflect the new architecture.
New advanced.block-broadcast-fallback union:
* enabled (default: false)
* grace-seconds (default: 30, range 10-600)
* backup-rpcs: list of full bitcoind RPC URLs, with inline
credentials supported (https://user:pass@host:port/). Up to 10.
docker_entrypoint reads the list with yq, joins with newlines, and
exports BACKUP_RPC_URLS plus PENDING_BLOCKS_DIR=<logdir>/pending-blocks
and PENDING_BLOCKS_GRACE so kamado-api's blocksubmit watcher activates.
If the user enables the fallback but provides no URLs, we log a
warning and disable rather than spam pending-block warnings.
The companion ckpool patch (KamadoPool repo, 0004-dump-pending-block-
for-fallback) writes raw block hex to PENDING_BLOCKS_DIR before each
submit attempt and unlinks on success. The watcher only fires if
ckpool's primary submit fails AND the operator configured backup RPCs.
Two related polish items:
1. Optional custom block explorer. New union under Advanced config
("Block Explorer") defaulting to "mempool.space". Picking
"Custom URL" reveals a single text field where the user can
point Kamado at their own mempool instance — useful for users
running mempool as a sibling StartOS service or on the same LAN.
The entrypoint reads .advanced.mempool-explorer.{type,url} and
exports MEMPOOL_BASE_URL when type=custom; otherwise leaves it
empty and the UI keeps its mempool.space defaults.
2. stunnel debug level 4 (warning) was hiding successful TLS
handshakes — only failures showed up in the service logs, which
made it hard to confirm "yes, my miner did connect over TLS"
without going looking at netstat. Bump to level 5 (notice) so
each successful handshake produces an "accepted connection from
<ip>" / "connected from <ip>" line. Errors stay visible at level
3, so the only thing this changes is making the happy path
observable.
Worker stratum username is the payout address in ckpool-solo, so the
separate field was redundant. Niche vardiff/logging/zmq knobs now
live under an Advanced group with sensible defaults.
New 'tls' union config (disabled by default) spins up an
stunnel4 process inside the container that terminates TLS on
a configurable port (3334 by default) and forwards decrypted
stratum traffic to 127.0.0.1:${STRATUM_PORT}.
Cert is self-signed, generated once on first start with a
10-year validity and persisted at /root/.kamado/tls/ so the
fingerprint stays stable across restarts. SHA-256 fingerprint
is printed to container logs on each startup so users can
pin it on their miners. Miners must connect with
verification disabled (no CA trust chain for a private pool).
Runtime image grows by ~3MB for stunnel4 + openssl. The
supervisor loop now waits on three PIDs and tears all of them
down together if any one exits.
New 'zmq-enabled' boolean (default true) makes the entrypoint
export BITCOIN_ZMQ_BLOCK=tcp://<bitcoind-host>:28332, which
kamado-api's zmqmon subscribes to for sub-second chain refresh
on the dashboard. Disable it if your bitcoind doesn't have
zmqpubhashblock exposed.
Exposes stratum-port in the StartOS config UI so users running
simpleproxy or another TCP forwarder can point Kamado at a
non-default port. Entrypoint substitutes the value into
ckpool.conf serverurl.
Also pins placeholder KAMADO_SHA in the Dockerfile — swap to a
real pushed commit before the first build.
Multi-stage Dockerfile clones KamadoPool at a pinned SHA, builds
ckpool and kamado-api (with embedded Svelte UI), runtime image
supervises both processes via tini + wait -n. Config covers
bitcoind mainnet/testnet4 variant, payout address, coinbase tag,
vardiff knobs, and log level. Web UI interface only — stratum
:3333 requires a router port-forward or simpleproxy workaround
because StartOS 0.3.x does not forward raw TCP on LAN.
TODO before first build: pin KAMADO_REPO + KAMADO_SHA in the
Dockerfile to a pushed commit.
satoshi