From 437c08b005ead2b94d4a979d3edd884b2fba8a4e Mon Sep 17 00:00:00 2001 From: Alec Date: Sun, 12 Jul 2026 15:53:15 +0400 Subject: [PATCH 1/2] docs: add FAQ.md (merged mining, address autoconversion, payouts, dashboard) Answers common operator questions surfaced by a downstream pool operator: - adding merged coins via --merged COIN:chain_id:host:port:user:pass (LTC/DOGE embedded SPV; others via external AuxPoW daemon) - DGB-Scrypt as a merged child under LTC (daemon) vs the planned embedded-SPV DGB parent (--net digibyte) - payout model: no wallet in c2pool; coinbase pays the miner's own address; single primary address auto-derives merged payouts (conditional on p2pkh/ p2wpkh/p2sh; not p2wsh/p2tr) with explicit slash/separator overrides - dashboard is built in and served at :8080 (web-static/); optional explorer Links the missing docs/DASHBOARD_INTEGRATION.md to tracking issue #677. Adds a FAQ pointer to README. --- README.md | 2 + docs/FAQ.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 docs/FAQ.md diff --git a/README.md b/README.md index 89464834f..76b230e84 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,8 @@ Miners connect to stratum and set their LTC payout address as the username Full step-by-step guides: [Linux](doc/build-unix.md) | [macOS](doc/build-macos.md) | [Windows](doc/build-windows.md) +Common operator questions (merged coins, payouts, dashboard): [docs/FAQ.md](docs/FAQ.md) + --- ## Operating modes diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 000000000..292a11bac --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,192 @@ +# c2pool FAQ + +Common questions from operators running `./c2pool`. See the +[README](../README.md) for the full option reference and `./c2pool --help` +for every flag. + +--- + +## Merged mining + +### How do I add merged coins? Do I implement them in code, or is there a command? + +It's a **runtime command-line flag — no code changes**. + +- **LTC + DOGE are built in.** They run as **embedded SPV** nodes (no coin + daemon, no config). DOGE merged mining activates automatically — running + `./c2pool` with no arguments already merge-mines LTC + DOGE. + +- **Other aux chains** are added by running *their* daemon and passing + `--merged`: + + ```bash + ./c2pool --merged PEP:63:127.0.0.1:29377:rpcuser:rpcpass + ``` + + Format: `COIN:chain_id:host:port:rpcuser:rpcpass`. c2pool drives the aux + daemon over its `createauxblock` / `submitauxblock` RPC. Repeat `--merged` + for multiple chains. + +| Coin | chain_id | Backend | Notes | +|-------|----------|------------------------|------------------------------------| +| DOGE | 98 | **Embedded SPV** | auto-configured, on by default | +| PEP | 63 | External daemon | `--merged PEP:63:host:port:user:pass` | +| BELLS | 16 | External daemon | `--merged BELLS:16:host:port:user:pass` | +| LKY | 8211 | External daemon | `--merged LKY:8211:host:port:user:pass` | +| JKC | 8224 | External daemon | `--merged JKC:8224:host:port:user:pass` | +| SHIC | 74 | External daemon | `--merged SHIC:74:host:port:user:pass` | + +Only **LTC and DOGE** are daemonless (embedded SPV). Every other aux chain +needs its own full node running locally with AuxPoW RPC +(`createauxblock`/`submitauxblock`) enabled. + +--- + +### Can I merge-mine DigiByte (DGB)? Is DigiByte "SPV" now? + +DGB has **two separate roles** — don't confuse them: + +1. **DGB-Scrypt as a merged child under an LTC parent — supported today, via a + daemon (not SPV).** DGB-Scrypt shares Litecoin's Scrypt proof-of-work, so it + merge-mines cleanly under the LTC parent using the same generic merged + engine as the coins above. You run a `digibyted` node with AuxPoW RPC + enabled and wire it in: + + ```bash + ./c2pool --merged DGB::127.0.0.1:14022:rpcuser:rpcpass + ``` + + Use the AuxPoW chain id your `digibyted` reports. Because DGB is not yet in + the stratum address auto-detection table (see the payout question below), + set your DGB payout address **explicitly** — either with the slash form in + your stratum username (`LTCADDR/:DGBADDR`) or via the + `mining.set_merged_addresses` stratum method. + +2. **DGB-Scrypt as its own parent chain (`--net digibyte`) — planned.** A + standalone DGB-Scrypt P2Pool node with an *embedded* SPV backend (its own + sharechain, like the LTC/DOGE embedded nodes) is in development, not yet in + the stable release. Until it ships, DGB is **not** an embedded-SPV coin — + reach it via the merged-child path (1) with an external daemon. + +So: **DGB is not embedded SPV today.** It can be merge-mined under LTC with a +DGB daemon now; a native embedded-SPV DGB parent is planned. + +--- + +## Payouts & funds + +### Where does it mine to when using SPV? How do I access the funds? + +**c2pool holds no wallet and never custodies coins.** The embedded SPV nodes +are header-only — they validate the chain but store no keys. Block rewards are +paid **directly in the block's coinbase** to an address **you** control in your +own wallet (Litecoin Core, Dogecoin Core, etc.). There is nothing to "withdraw" +from c2pool — the coins land in your address the moment a block matures. + +You set your payout address as your **stratum username** (the P2Pool +convention): + +``` +LcYourLitecoinAddress.worker1 +``` + +**You normally supply just one address.** c2pool **auto-derives** the payout +address for every merged chain from that single primary address — LTC, DOGE and +the other Scrypt aux chains all share the same secp256k1 keys, so the same +`hash160` is re-encoded into each chain's address format automatically. Give +your LTC address and your DOGE reward is paid to the matching DOGE address with +no extra configuration. + +**This auto-conversion is conditional on your address type:** + +| Primary address type | Merged payout auto-derived? | +|----------------------|-----------------------------| +| P2PKH (`L...`, legacy) | ✅ yes | +| P2SH (`M...` / `3...`) | ✅ yes | +| P2WPKH (`ltc1q...`, segwit) | ✅ yes | +| P2WSH (`ltc1q...`, 32-byte) | ❌ no — supply merged addresses explicitly | +| P2TR (`ltc1p...`, taproot) | ❌ no — supply merged addresses explicitly | + +The 32-byte witness programs (P2WSH/P2TR) can't be reduced to a 20-byte +`hash160`, so for those you must name each chain's address yourself. + +**To override or set addresses per chain explicitly**, use any of: + +- **Slash + chain_id** (most explicit): + `LTCADDR/98:DOGEADDR` — pays DOGE (chain_id 98) to `DOGEADDR`. + Chain multiple: `LTCADDR/98:DOGEADDR/63:PEPADDR`. +- **Simple separator** (`,` `|` `;` or space): `LTCADDR,DOGEADDR` — first is + the parent (LTC), second is the merged child. +- **Stratum method**: send `mining.set_merged_addresses`. + +c2pool also **auto-corrects a swapped order** (if it detects the merged-chain +address first and the LTC address second) and, if you enter a DOGE address as +the primary, **reverse-derives** the LTC payout from the same key. + +Worker names (`.worker1` or `_worker1`) are stripped from each address before +use. + +### Which mode pays whom? + +| Mode | CLI flag | Who gets paid | +|------|----------|---------------| +| **Integrated** (default) | *(none)* | All miners in the PPLNS window, by sharechain weight — paid to each miner's stratum-username address | +| **Solo** | `--solo` | Your connected miners, proportional to hashrate — paid to their addresses | +| **Custodial** | `--custodial --address ADDR` | **100% to the operator's `--address`**; miners are tracked off-chain via `/stratum_stats` | + +In integrated and solo modes the miner's address appears **directly in the +coinbase** — the pool never holds the funds. Only `--custodial` routes +everything to the operator for off-chain accounting. + +--- + +## Dashboard & explorer + +### How do I add the dashboard? The docs don't have the integration files anymore. + +**The dashboard is built in — there is nothing to install.** Whenever c2pool +runs (integrated, solo, or custodial mode), it serves the web dashboard and +REST API automatically: + +``` +http://localhost:8080/ +``` + +Just open that URL in a browser. Change the port with `--web-port PORT` +(`web_port:` in YAML). The dashboard files live in `web-static/` and are +fully user-customizable — edit the HTML/JS/CSS there to restyle it. + +**Optional lite block explorer** — a separate bundled Python app for browsing +recent blocks, decoded coinbase scripts, and THE commitment proofs: + +```yaml +# in your config +explorer: true +explorer_url: "http://localhost:9090" +``` + +```bash +python3 explorer/explorer.py \ + --ltc-c2pool http://127.0.0.1:8080/api/explorer \ + --web-port 9090 +``` + +Then browse `http://localhost:9090/`. + +> **Note:** the README currently links `docs/DASHBOARD_INTEGRATION.md` for the +> full REST API reference, but that file is missing from the tree — tracked in +> [#677](https://github.com/frstrtr/c2pool/issues/677). The API endpoints +> themselves work and are listed in the README's API table; the dashboard is +> served automatically as described above. + +--- + +## Ports (defaults) + +| Port | Purpose | Override | +|-------|----------------------------------|------------------| +| 9326 | P2Pool sharechain (peer-to-peer) | `--p2pool-port` | +| 9327 | Stratum mining | `-w PORT` | +| 8080 | Web dashboard + REST API | `--web-port` | + +On `--testnet`, P2P shifts to 19326 and stratum to 19327. From e61465b1e43f091212ac8682872762f8681e33e6 Mon Sep 17 00:00:00 2001 From: Alec Date: Sun, 12 Jul 2026 15:58:20 +0400 Subject: [PATCH 2/2] =?UTF-8?q?docs(FAQ):=20correct=20DGB=20=E2=80=94=20Mu?= =?UTF-8?q?ltiAlgo=20primary=20chain,=20not=20an=20AuxPoW=20merged=20child?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DGB has no AuxPoW chain ID and cannot be merge-mined under LTC. It secures its own chain via MultiAlgo (Scrypt, SHA-256d, Qubit, Skein, Odocrypt), each mined directly on the DGB main chain with independent difficulty. --merged is AuxPoW-only (DOGE/PEP/BELLS/LKY/JKC/SHIC). In c2pool DGB-Scrypt is its own parent chain (--net digibyte), in development — never an aux child. --- docs/FAQ.md | 44 ++++++++++++++++++-------------------------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 292a11bac..4237bf10e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -44,32 +44,24 @@ needs its own full node running locally with AuxPoW RPC ### Can I merge-mine DigiByte (DGB)? Is DigiByte "SPV" now? -DGB has **two separate roles** — don't confuse them: - -1. **DGB-Scrypt as a merged child under an LTC parent — supported today, via a - daemon (not SPV).** DGB-Scrypt shares Litecoin's Scrypt proof-of-work, so it - merge-mines cleanly under the LTC parent using the same generic merged - engine as the coins above. You run a `digibyted` node with AuxPoW RPC - enabled and wire it in: - - ```bash - ./c2pool --merged DGB::127.0.0.1:14022:rpcuser:rpcpass - ``` - - Use the AuxPoW chain id your `digibyted` reports. Because DGB is not yet in - the stratum address auto-detection table (see the payout question below), - set your DGB payout address **explicitly** — either with the slash form in - your stratum username (`LTCADDR/:DGBADDR`) or via the - `mining.set_merged_addresses` stratum method. - -2. **DGB-Scrypt as its own parent chain (`--net digibyte`) — planned.** A - standalone DGB-Scrypt P2Pool node with an *embedded* SPV backend (its own - sharechain, like the LTC/DOGE embedded nodes) is in development, not yet in - the stable release. Until it ships, DGB is **not** an embedded-SPV coin — - reach it via the merged-child path (1) with an external daemon. - -So: **DGB is not embedded SPV today.** It can be merge-mined under LTC with a -DGB daemon now; a native embedded-SPV DGB parent is planned. +**No — DGB cannot be merge-mined as a child of LTC, and it is not an embedded +SPV coin today.** + +DigiByte does **not** support AuxPoW (auxiliary proof-of-work) and has **no +AuxPoW chain ID**. Unlike Dogecoin (chain_id 98) or Namecoin (chain_id 1), +which are child chains that inherit security from a parent's hashrate, DigiByte +secures its own chain directly through a **MultiAlgo** consensus: five +independent proof-of-work algorithms — **Scrypt, SHA-256d, Qubit, Skein, and +Odocrypt** — each mined directly on the DGB main chain with its own independent +difficulty adjustment. Because DGB is a primary chain with no aux-chain role, it +is **not** a valid `--merged` target. The `--merged` flag is only for true +AuxPoW coins (DOGE, PEP, BELLS, LKY, JKC, SHIC). + +In c2pool, DGB-Scrypt is therefore handled as its **own parent chain** — a +standalone DGB-Scrypt P2Pool node running its own sharechain (Scrypt-only in +V36; the other four DGB algos are out of scope for now). That parent-chain +support is **in development** (`--net digibyte`), not yet in the stable LTC +release. Until it ships there is no LTC-side path to mine DGB through c2pool. ---