From a63e7256c48ca3fcc0ba14c16fe252661f4a641b Mon Sep 17 00:00:00 2001 From: satoshi Date: Tue, 14 Apr 2026 17:10:51 +0300 Subject: [PATCH] Tidy config: drop payout-address field, group niche options under Advanced 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. --- docker_entrypoint.sh | 21 ++-- instructions.md | 8 +- scripts/procedures/getConfig.ts | 167 ++++++++++++++++---------------- 3 files changed, 101 insertions(+), 95 deletions(-) diff --git a/docker_entrypoint.sh b/docker_entrypoint.sh index fb7308b..5b823c1 100755 --- a/docker_entrypoint.sh +++ b/docker_entrypoint.sh @@ -34,18 +34,23 @@ esac export BITCOIN_RPC_USER=$(q '.bitcoind.user') export BITCOIN_RPC_PASSWORD=$(q '.bitcoind.password') -export POOL_BTCADDRESS=$(q '.pool-address') -export POOL_BTCSIG=$(q '.pool-identifier') export STRATUM_PORT=$(q '.stratum-port // 3333') -export STARTDIFF=$(q '.startdiff // 16384') -export MINDIFF=$(q '.mindiff // 1000') -export MAXDIFF=$(q '.maxdiff // 0') -export DROPIDLE=$(q '.dropidle // 0') -LOG_LEVEL=$(q '.log-level // "info"') -ZMQ_ENABLED=$(q '.zmq-enabled // true') +export POOL_BTCSIG=$(q '.advanced.pool-identifier // "/Kamado/"') +export STARTDIFF=$(q '.advanced.startdiff // 16384') +export MINDIFF=$(q '.advanced.mindiff // 1000') +export MAXDIFF=$(q '.advanced.maxdiff // 0') +export DROPIDLE=$(q '.advanced.dropidle // 0') +LOG_LEVEL=$(q '.advanced.log-level // "info"') +ZMQ_ENABLED=$(q '.advanced.zmq-enabled // true') TLS_ENABLED=$(q '.tls.enabled // "disabled"') TLS_PORT=$(q '.tls.port // 3334') +# CKPool-solo uses the worker's stratum username as the payout +# address. Kamado refuses to authenticate workers whose username is +# not a valid BTC address, so the conf `btcaddress` fallback is never +# reached. We still set it to a placeholder the conf parser accepts. +export POOL_BTCADDRESS="1BitcoinEaterAddressDontSendf59kuE" + export LOGDIR=/var/log/ckpool export SOCKET_DIR=/run/ckpool export BITCOIN_NOTIFY=true diff --git a/instructions.md b/instructions.md index e848927..aef90fc 100644 --- a/instructions.md +++ b/instructions.md @@ -5,9 +5,9 @@ Kamado is a solo Bitcoin mining pool built on a patched fork of CKPool-solo, wit ## Setup 1. Install Bitcoin Core (mainnet) **or** Bitcoin Core (testnet4). Kamado supports either as a dependency; pick one in the Kamado config under *Bitcoin Core > Type*. -2. In the Kamado config, set **Payout Address** to the Bitcoin address that should receive solved block rewards. -3. Optionally adjust the **Coinbase Tag** (default `/Kamado/`) and the vardiff parameters. -4. Start Kamado. Open the web UI from the Services page to watch live hashrate, miners, best shares, and solved blocks. +2. Start Kamado. Open the web UI from the Services page to watch live hashrate, miners, best shares, and solved blocks. + +There is no payout address field. CKPool-solo pays the full block reward directly to whichever Bitcoin address the miner connects with as its stratum username — see **Connecting miners** below. Kamado validates worker usernames against Bitcoin Core and **refuses to authenticate any worker whose username is not a valid address on the active network**, so misconfigured miners fail loudly instead of silently mining to the wrong place. ## Connecting miners @@ -20,7 +20,7 @@ Because the cert is self-signed, miners must connect with certificate verificati - **Router port-forward**: Forward an external port on your router directly to your StartOS server's LAN IP on port 3333 and point miners at that. - **simpleproxy on a second host**: Run `simpleproxy -L 3333 -R :3333` on any always-on LAN host and point miners at that host. -Once forwarding is in place, miners connect to `stratum+tcp://:3333` with the username set to **any label you like** (it becomes the worker name in the dashboard) and any password. +Once forwarding is in place, miners connect to `stratum+tcp://:3333` with the username set to **the Bitcoin address that should receive the block reward** (optionally followed by `.workername` for labelling in the dashboard). The password field is ignored. ## Troubleshooting diff --git a/scripts/procedures/getConfig.ts b/scripts/procedures/getConfig.ts index 710a8e9..f7d301c 100644 --- a/scripts/procedures/getConfig.ts +++ b/scripts/procedures/getConfig.ts @@ -4,10 +4,11 @@ export const getConfig: T.ExpectedExports.getConfig = compat.getConfig({ "bitcoind": { "type": "union", "name": "Bitcoin Core", - "description": "Select which Bitcoin Core node Kamado should use.", + "description": + "Select which Bitcoin Core node Kamado should use. Both variants work — pick whichever is installed on your server.", "tag": { "id": "type", - "name": "Type", + "name": "Network", "description": "Mainnet bitcoind or the testnet4 variant.", "variant-names": { "bitcoind": "Bitcoin Core (mainnet)", @@ -62,30 +63,11 @@ export const getConfig: T.ExpectedExports.getConfig = compat.getConfig({ }, }, }, - "pool-address": { - "type": "string", - "name": "Payout Address", - "description": - "Bitcoin address that receives the full block reward when a block is solved. Solo mining — no fees, no splits.", - "nullable": false, - "masked": false, - "copyable": true, - }, - "pool-identifier": { - "type": "string", - "name": "Coinbase Tag", - "description": - "Short string embedded in the coinbase transaction of solved blocks. Max 32 characters.", - "nullable": false, - "default": "/Kamado/", - "masked": false, - "copyable": false, - }, "stratum-port": { "type": "number", "name": "Stratum Port", "description": - "TCP port the plaintext stratum server listens on inside the container. Defaults to 3333. Change this if you are running simpleproxy (or another TCP forwarder) and want Kamado to listen on a different port.", + "TCP port the plaintext stratum server listens on inside the container. Most miners connect here.", "nullable": false, "default": 3333, "range": "[1,65535]", @@ -95,14 +77,14 @@ export const getConfig: T.ExpectedExports.getConfig = compat.getConfig({ "type": "union", "name": "Stratum TLS", "description": - "Accept stratum connections over TLS via an stunnel sidecar. A self-signed certificate is generated on first start and persisted across restarts — miners must connect with TLS verification disabled (most firmware exposes this as 'stratum+ssl://' with a skip-verify or insecure flag).", + "Optionally accept stratum connections over TLS via an stunnel sidecar. A self-signed certificate is generated once on first start and persisted — miners must connect with TLS verification disabled (stratum+ssl:// plus a skip-verify flag).", "tag": { "id": "enabled", - "name": "TLS Mode", - "description": "Disable or enable TLS termination in front of stratum.", + "name": "Mode", + "description": "Disable or enable TLS termination.", "variant-names": { "disabled": "Disabled", - "enabled": "Enabled (stunnel sidecar)", + "enabled": "Enabled", }, }, "default": "disabled", @@ -111,9 +93,9 @@ export const getConfig: T.ExpectedExports.getConfig = compat.getConfig({ "enabled": { "port": { "type": "number", - "name": "TLS Stratum Port", + "name": "TLS Port", "description": - "TCP port stunnel listens on for TLS stratum connections. Forwards decrypted traffic to the plaintext stratum port locally.", + "TCP port stunnel listens on for TLS stratum connections.", "nullable": false, "default": 3334, "range": "[1,65535]", @@ -122,62 +104,81 @@ export const getConfig: T.ExpectedExports.getConfig = compat.getConfig({ }, }, }, - "startdiff": { - "type": "number", - "name": "Starting Difficulty", + "advanced": { + "type": "object", + "name": "Advanced", "description": - "Initial vardiff target for new miner connections. Bitaxe-class miners typically land around 16384.", - "nullable": false, - "default": 16384, - "range": "[1,*)", - "integral": true, - }, - "mindiff": { - "type": "number", - "name": "Minimum Difficulty", - "description": "Floor for the vardiff algorithm.", - "nullable": false, - "default": 1000, - "range": "[1,*)", - "integral": true, - }, - "maxdiff": { - "type": "number", - "name": "Maximum Difficulty", - "description": "Ceiling for the vardiff algorithm. 0 means no cap.", - "nullable": false, - "default": 0, - "range": "[0,*)", - "integral": true, - }, - "dropidle": { - "type": "number", - "name": "Drop Idle (seconds)", - "description": - "Disconnect clients that have not submitted a share in this many seconds. 0 disables the idle disconnect.", - "nullable": false, - "default": 0, - "range": "[0,*)", - "integral": true, - }, - "zmq-enabled": { - "type": "boolean", - "name": "Enable ZMQ Block Notifications", - "description": - "Subscribe to Bitcoin Core's hashblock ZMQ topic for sub-second chain refresh on the dashboard. Requires zmqpubhashblock to be enabled on your bitcoind — the default StartOS bitcoind package exposes it on tcp://bitcoind.embassy:28332.", - "default": true, - }, - "log-level": { - "type": "enum", - "name": "Log Level", - "description": "Verbosity of the kamado-api log output.", - "values": ["debug", "info", "warn", "error"], - "value-names": { - "debug": "Debug", - "info": "Info", - "warn": "Warn", - "error": "Error", + "Fine-tuning knobs for vardiff, logging, and block notifications. Safe to ignore — the defaults work well for Bitaxe-class miners.", + "spec": { + "pool-identifier": { + "type": "string", + "name": "Coinbase Tag", + "description": + "Short string embedded in the coinbase transaction of solved blocks.", + "nullable": false, + "default": "/Kamado/", + "masked": false, + "copyable": false, + }, + "startdiff": { + "type": "number", + "name": "Starting Difficulty", + "description": + "Initial vardiff target for new miner connections. Bitaxe-class miners typically land around 16384.", + "nullable": false, + "default": 16384, + "range": "[1,*)", + "integral": true, + }, + "mindiff": { + "type": "number", + "name": "Minimum Difficulty", + "description": "Floor for the vardiff algorithm.", + "nullable": false, + "default": 1000, + "range": "[1,*)", + "integral": true, + }, + "maxdiff": { + "type": "number", + "name": "Maximum Difficulty", + "description": + "Ceiling for the vardiff algorithm. 0 means no cap.", + "nullable": false, + "default": 0, + "range": "[0,*)", + "integral": true, + }, + "dropidle": { + "type": "number", + "name": "Drop Idle (seconds)", + "description": + "Disconnect clients that have not submitted a share in this many seconds. 0 disables the idle disconnect.", + "nullable": false, + "default": 0, + "range": "[0,*)", + "integral": true, + }, + "zmq-enabled": { + "type": "boolean", + "name": "Enable ZMQ Block Notifications", + "description": + "Subscribe to Bitcoin Core's hashblock ZMQ topic for sub-second chain refresh on the dashboard. Requires zmqpubhashblock on bitcoind.", + "default": true, + }, + "log-level": { + "type": "enum", + "name": "Log Level", + "description": "Verbosity of the kamado-api log output.", + "values": ["debug", "info", "warn", "error"], + "value-names": { + "debug": "Debug", + "info": "Info", + "warn": "Warn", + "error": "Error", + }, + "default": "info", + }, }, - "default": "info", }, });