From d9c1baec08a303759e4e99ffde6f4ce97bc1f09e Mon Sep 17 00:00:00 2001 From: "rearden-grok[bot]" <317016512+rearden-grok[bot]@users.noreply.github.com> Date: Thu, 8 Oct 2026 14:25:21 -0700 Subject: [PATCH] docs: map wallets and Lightning nodes onto the listeners we serve Operators were left to guess Electrum versus Core-wallet mode, and Wasabi's RPC path was easy to misread as unsupported. Co-authored-by: Cursor --- COMPAT.md | 2 +- OPERATOR.md | 1 + changelog.d/wallet-backends.md | 6 + docs/ORIENT.md | 1 + docs/README.md | 3 +- docs/lightning.md | 102 +++++++++++++-- docs/operator/interfaces.md | 5 + docs/rpc.md | 4 +- docs/wallets.md | 219 +++++++++++++++++++++++++++++++++ 9 files changed, 330 insertions(+), 13 deletions(-) create mode 100644 changelog.d/wallet-backends.md create mode 100644 docs/wallets.md diff --git a/COMPAT.md b/COMPAT.md index cccab59e3..c51378ce3 100644 --- a/COMPAT.md +++ b/COMPAT.md @@ -20,7 +20,7 @@ backends**: in-process **Electrum** (confirmed + unconfirmed, libre-relay-class admission) and optional **Esplora-compatible REST** for the same role (history, UTXO, broadcast, block/tx fetch by id). Optional **Core-class JSON-RPC subset** (see [`docs/rpc.md`](./docs/rpc.md)) — not full Core wallet / mining parity. -**Scripthash index (`--shindex`) defaults off**. Electrum/Esplora **start without it**; address/scripthash methods fail closed (`scripthash index disabled`). Txid/outpoint/block/broadcast/fees work. Matrix: [`docs/lightning.md`](./docs/lightning.md). +**Scripthash index (`--shindex`) defaults off**. Electrum/Esplora **start without it**; address/scripthash methods fail closed (`scripthash index disabled`). Txid/outpoint/block/broadcast/fees work. Which wallets use that surface: [`docs/wallets.md`](./docs/wallets.md). Lightning chain sources: [`docs/lightning.md`](./docs/lightning.md). On/off costs and start/IBD/tip behavior: [`OPERATOR.md`](./OPERATOR.md) (Scripthash index). Disable later leaves SH files on disk; follow does not wait on SH materialize. diff --git a/OPERATOR.md b/OPERATOR.md index 42921ec9e..8353c6dcd 100644 --- a/OPERATOR.md +++ b/OPERATOR.md @@ -8,6 +8,7 @@ Start with the task you need to do: | Try regtest, use the CLI, monitor the node (logs, health probes, metrics), configure relay and P2P | [Node operations](docs/operator/operations.md) | | Tune store IO and memory, upgrade the schema, manage optional indexes | [Storage and indexes](docs/operator/storage.md) | | Configure Electrum, Esplora, RPC, SV2 templates, or client benchmarking | [Client interfaces](docs/operator/interfaces.md) | +| Point a wallet or Lightning node at this node | [Wallets](docs/wallets.md), [Lightning backends](docs/lightning.md) | | Run signet/mainnet, or tune a constrained host or uplink | [Labs and constrained hosts](docs/operator/field-notes.md) | Product compatibility: [`COMPAT.md`](COMPAT.md). Current on-disk format and diff --git a/changelog.d/wallet-backends.md b/changelog.d/wallet-backends.md new file mode 100644 index 000000000..b30a080f0 --- /dev/null +++ b/changelog.d/wallet-backends.md @@ -0,0 +1,6 @@ +Added + +- **Wallet and Lightning backend guide.** `docs/wallets.md` lists which + wallets speak Electrum, Esplora, or the RPC cookie, including Wasabi's + full-node path. `docs/lightning.md` covers CLN, ldk-node, and LND + `rpcpolling` versus Neutrino and ZMQ. diff --git a/docs/ORIENT.md b/docs/ORIENT.md index b8360ea5b..19c03dd7a 100644 --- a/docs/ORIENT.md +++ b/docs/ORIENT.md @@ -30,6 +30,7 @@ Before the first edit in a crate, read `crates//AGENTS.md` when that file | `rearden-grok[bot]` operator VM (ignore unless that identity) | [`../rearden-vm-HOST.md`](../rearden-vm-HOST.md) | | Intentional Core / Electrum / Esplora differences | [`../COMPAT.md`](../COMPAT.md) | | JSON-RPC surface | [`rpc.md`](./rpc.md) | +| Which wallet or Lightning node connects | [`wallets.md`](./wallets.md), [`lightning.md`](./lightning.md) | | Open, push, or poll a PR | [`../.agents/skills/ship-pr/SKILL.md`](../.agents/skills/ship-pr/SKILL.md) (one worktree; fail-fast `pr-checks-watch.sh`) | | Minor, patch, or major release | [`../.agents/skills/release/SKILL.md`](../.agents/skills/release/SKILL.md) | | Core functional harness | [`../.agents/skills/core-functional/SKILL.md`](../.agents/skills/core-functional/SKILL.md) | diff --git a/docs/README.md b/docs/README.md index 313aca637..4b7bdf2ab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,7 +61,8 @@ into `AGENTS.md`. | [`mempool-fee-estimation.md`](./mempool-fee-estimation.md) | Fee estimator notes. | | [`errata.md`](./errata.md) | Known one-off store/confirm quirks. Retired confirm dual-path names. | | [`peer-clients.md`](./peer-clients.md) | Hornet Node and satd: what to steal (tests/ideas) and what not to copy. Ranked items stay here; do not copy into quality.md. | -| [`lightning.md`](./lightning.md) | CLN and LDK as Bitcoin backends: five `bcli` calls, Esplora/Electrum chain sync, `--sh-index` API matrix. Not LND. | +| [`lightning.md`](./lightning.md) | CLN, ldk-node, and LND as Bitcoin backends: `bcli` calls, Esplora/Electrum chain sync, LND `rpcpolling`, `--sh-index` API matrix. | +| [`wallets.md`](./wallets.md) | Which on-chain wallets connect, and the server string or RPC cookie for each. Lightning stays in `lightning.md`. | | [`external_findings/`](./external_findings/) | Numbered audit reports + regression pointers. Do not flatten into CHANGELOG. | ## Root (stay at root) diff --git a/docs/lightning.md b/docs/lightning.md index 09bb5d22b..b4373d40f 100644 --- a/docs/lightning.md +++ b/docs/lightning.md @@ -1,22 +1,30 @@ -# Lightning backends (CLN and LDK) +# Lightning backends -How **Core Lightning** and **ldk-node** (LDK) use this node as the Bitcoin -chain source. Not a Core wallet. Not LND (ZMQ / Neutrino). 0.x — do not put -mainnet channel funds here until this file says the contract is boring. +How Core Lightning, ldk-node, and LND use this node as the Bitcoin chain +source. On-chain wallets are [`wallets.md`](./wallets.md). This is not a +Core wallet. 0.x — do not put mainnet channel funds here until this file +says the contract is boring. Operator flags: [`OPERATOR.md`](../OPERATOR.md). RPC JSON: [`rpc.md`](./rpc.md). Electrum/Esplora surface: [`COMPAT.md`](../COMPAT.md). Fee math: [`mempool-fee-estimation.md`](./mempool-fee-estimation.md). +Cookie file for TCP clients: [`wallets.md`](./wallets.md#tcp-rpc-cookie). -## Status (spike 2026-09-20) +## Status | Client | Path | Today | |--------|------|--------| | **CLN** stock `bcli` | `bitcoin-cli` → Core RPC | Methods exist on unix `{datadir}/rpc.sock`. Wrapper: [`scripts/lightning/bitcoin-cli`](../scripts/lightning/bitcoin-cli) (`-datadir=` → `--datadir`). Cookie/TCP `rpcauth` is not the product listen. | +| **CLN** `sauron` | Esplora HTTP | Channel watches use tip, tx, outspend, and broadcast. Point the plugin at `--esplora-listen`. No `--sh-index`. | | **ldk-node Esplora** | `--esplora-listen` REST | Tip, `/tx/*` (raw/status/outspend/merkleblock-proof), `/fee-estimates`, `POST /tx` work **without** `--sh-index`. Address/scripthash: 503 `scripthash index disabled`. | | **ldk-node Electrum** | `--electrum-listen` TCP | Headers, `transaction.get` / broadcast, `estimatefee` work **without** `--sh-index`. `blockchain.scripthash.*`: JSON-RPC `scripthash index disabled`. TLS is reverse-proxy only (**Q-63**). | | **ldk-node bitcoind REST** | `--rpc-listen --rest` `GET /rest/block/` | Block bytes, headers, and hash-by-height. TCP `/rest/` is unauthenticated and off unless `--rest` is set. The BDK wallet still needs Esplora or Electrum with `--sh-index`. | -| **LND** | bitcoind + ZMQ or BIP157 | ZMQ stays out. Optional `--block-filter-index` serves BIP158 basic for sealed heights and advertises `NODE_COMPACT_FILTERS` once filters first reach the tip. | +| **LND** `bitcoind` + `rpcpolling` | TCP JSON-RPC, cookie file | Chain, tx, fee, and broadcast methods exist. ZMQ is not required on this path. Taproot detection falls through to `getdeploymentinfo`, which already lists buried taproot. See [LND](#lnd). | +| **LND** Neutrino | BIP157 to a v2 peer | `--block-filter-index` serves basic filters and advertises `NODE_COMPACT_FILTERS` once they first reach the tip. Neutrino does not speak BIP324. This node is v2-only, so Neutrino cannot connect. | +| **LND** default `bitcoind` | ZMQ `rawblock` + `rawtx` | ZMQ is not served. Use `bitcoind.rpcpolling=true` instead. | +| **Eclair** | Core wallet + ZMQ | Needs a wallet-enabled Core node (`getnewaddress` and the watch-only wallet) plus ZMQ. Both are absent here. | +| **Zeus** embedded LND, Lightning Terminal, Loop, Pool, Faraday, tapd | Whatever LND is using | Same as the LND row they configure. | +| **Phoenix, Breez** | Operator backends | The apps talk to their operators' Electrum and Lightning services. They have no home-node setting. | `--sh-index` is **not** required to start Electrum/Esplora or for channel watches (txid / outpoint). SH-only methods fail closed. @@ -98,6 +106,79 @@ BDK on-chain wallet still needs `/address/*` and `/scripthash/*` → **`--sh-ind | `blockchain.estimatefee` | done (10-minute product; `-1` if insufficient) | | `blockchain.scripthash.*` | done **only with SH** | +## LND + +Two chain sources exist in current LND. One can use this node. One cannot. + +### `bitcoind` with RPC polling + +Set `bitcoind.rpcpolling=true`. LND then learns about blocks and +transactions by polling JSON-RPC. It does not open ZMQ. Authenticate with +`bitcoind.rpccookie` pointed at the file from +[`wallets.md`](./wallets.md#tcp-rpc-cookie). There is no `--rpcuser` / +`--rpcpassword`, and LND will not find ZMQ endpoints in a `bitcoin.conf` +because this node does not write one. Pass the cookie path and +`bitcoind.rpchost=127.0.0.1` explicitly. + +```text +bitcoin.node=bitcoind +bitcoind.rpchost=127.0.0.1 +bitcoind.rpccookie=/run/rbitcoin/rpc.cookie +bitcoind.rpcpolling=true +``` + +Start the node with `--rpc-listen` and `--rpc-cookie-file` on that path. +`--sh-index` is not involved. `getrawtransaction` answers from the archive +without a `txindex` flag. + +What LND's startup check actually reads (current `chainreg/taproot_check.go`): + +1. `getblockchaininfo`. This response has no `softforks` object. +2. Because that map is absent, LND does not treat the call as "no taproot". + It calls `getdeploymentinfo`. +3. `deployments.taproot` is present (buried, same object as + `getdeploymentinfo`). LND treats the key as support. It also accepts + `script_flags` containing `TAPROOT`; we do not emit `script_flags`, and + the deployments key is enough for this check. + +`getnetworkinfo.version` is `190000`. LND's health check uses `uptime` +when that integer is at least `150000`, which it is. Raising the integer +toward a current Core release would advertise wallet RPC that this node +does not have. See [`rpc.md`](./rpc.md#getnetworkinfoversion). + +`estimatesmartfee` accepts `estimate_mode` `economical` and `conservative` +and returns the same 10-minute feerate either way. `initialblockdownload` +means relay is inhibited (`--min-chain-work` / `--max-tip-age`), not +"headers are still downloading." + +This path is read from LND's source and from this node's RPC. It has not +been run as a channel smoke. + +### Neutrino + +`--block-filter-index` is the server half: BIP158 basic filters, P2P +`getcfilters` / `getcfheaders` / `getcfcheckpt`, and `NODE_COMPACT_FILTERS` +once the filter watermark first reaches the tip. Peers that connected +before that advertisement do not learn the bit; a later connection does. + +Neutrino's BIP324 handshake is still upstream work +([lightninglabs/neutrino#319](https://github.com/lightninglabs/neutrino/issues/319)). +Until that client speaks v2, it cannot peer with this node. Serving v1 +P2P to make Neutrino connect is out of scope. + +### Default ZMQ mode + +`bitcoind.zmqpubrawblock` and `bitcoind.zmqpubrawtx` have nothing to +connect to. ZMQ is not a 1.0 surface ([`road-to-1.0.md`](./road-to-1.0.md)). +`rpcpolling` is the configuration that matches the RPC we already serve. + +## Eclair + +Current Eclair requires Bitcoin Core's wallet RPC and ZMQ +(`zmqpubhashblock`, `zmqpubrawtx`), plus `rpcuser` / `rpcpassword`. The +wallet calls and ZMQ are both absent. An Esplora or Electrum URL is not a +chain backend Eclair reads. + ## Gaps this plan still implements 1. Optional `scripts/lightning/run-cln.sh` / `run-ldk.sh` if those binaries exist (skip 0 otherwise). @@ -105,7 +186,8 @@ BDK on-chain wallet still needs `/address/*` and `/scripthash/*` → **`--sh-ind ## Not this node -Core wallet RPC, ZMQ, LND’s ZMQ chain source, in-binary Electrum TLS, -cookie/`rpcauth` as the LN listen. BIP158 basic filters are optional -(`--block-filter-index`). Core REST block/header/tx routes are on the RPC -listener. +Core wallet RPC, ZMQ, in-binary Electrum TLS, and v1 P2P. BIP158 basic +filters are optional (`--block-filter-index`). Core REST block/header/tx +routes are on the RPC listener when `--rest` is set. TCP JSON-RPC accepts +a cookie file when `--rpc-cookie-file` is set; that is the LND and Wasabi +credential, not `rpcauth`. diff --git a/docs/operator/interfaces.md b/docs/operator/interfaces.md index 661ff274b..9483261c4 100644 --- a/docs/operator/interfaces.md +++ b/docs/operator/interfaces.md @@ -1,5 +1,10 @@ # Client interfaces +Which wallet or Lightning node to point here, and the server string it +expects: [`docs/wallets.md`](../wallets.md) and +[`docs/lightning.md`](../lightning.md). This file is the listener +behavior. + ## Electrum Internet-facing Electrum is supported as a **wallet-client backend** (Electrum, diff --git a/docs/rpc.md b/docs/rpc.md index bde30386e..9d2dffd4a 100644 --- a/docs/rpc.md +++ b/docs/rpc.md @@ -189,10 +189,12 @@ still wait for durable SH when shindex is on. |-----|-----------------| | `{datadir}/rpc.sock` (filesystem) | TLS in-process / mTLS | | `{datadir}/rpc.token` Bearer on TCP | multi-user tokens | -| Harness `.cookie` + Basic on the test proxy only | `rpcallowip` | +| TCP HTTP Basic from `--rpc-cookie-file` (operator-written; the node never creates it). The functional harness still uses its own cookie on the test proxy | `rpcallowip` | ## Related - [`COMPAT.md`](../COMPAT.md) — product surface - [`OPERATOR.md`](../OPERATOR.md) — flags and shindex tradeoffs - [`mempool-fee-estimation.md`](./mempool-fee-estimation.md) — fee product +- [`wallets.md`](./wallets.md) — which wallets use Electrum, Esplora, or this RPC +- [`lightning.md`](./lightning.md) — CLN, LDK, LND chain sources diff --git a/docs/wallets.md b/docs/wallets.md new file mode 100644 index 000000000..737dbb2a9 --- /dev/null +++ b/docs/wallets.md @@ -0,0 +1,219 @@ +# Wallets + +Which open-source wallets can use this node, and the setting each one +expects. Lightning implementations are [`lightning.md`](./lightning.md). +Listener behavior, DoS limits, and the mempool.space nginx recipe stay in +[`operator/interfaces.md`](./operator/interfaces.md). Method lists stay in +[`COMPAT.md`](../COMPAT.md) and [`rpc.md`](./rpc.md). + +Chains the node actually runs: `mainnet`, `testnet` (testnet3), `signet`, +`regtest`. There is no `--network testnet4`. A wallet left on testnet4 +has nothing to connect to. + +0.x. The Electrum and Esplora listeners are the wallet product. Core +wallet RPC (`importdescriptors`, `walletcreatefundedpsbt`, +`signrawtransactionwithwallet`, and the rest of the keystore) is a +permanent non-goal. + +## Shared behavior + +Address history needs `--sh-index`. Without it, Electrum scripthash +methods return `scripthash index disabled` and Esplora `/address` and +`/scripthash` return HTTP 503 with that phrase. Txid, block, header, +broadcast, and fee calls work with the index off. Lightning channel +watches use those, so they are documented in [`lightning.md`](./lightning.md). + +Electrum is plain TCP (`--electrum-listen`). TLS terminates at a reverse +proxy ([`operator/interfaces.md`](./operator/interfaces.md)). With +`--tor-control`, the node publishes an onion for that port and advertises +`tcp_port` only (no `ssl_port`). Sparrow's onion URL is +`tcp://.onion:`. + +Esplora is plain HTTP (`--esplora-listen`). There is no WebSocket. A +wallet that wants push notifications uses Electrum subscriptions. The +mempool.space UI's `/api/v1/ws` is mempool's own Node process, not this +listener. + +One Electrum connection may hold `--electrum-max-subs` scripthash +subscriptions (default **10000**). That is the cap on one wallet's +receive and change addresses, including the gap limit. + +Fee estimates (`estimatesmartfee`, Electrum `estimatefee`, Esplora +`/fee-estimates`) are a 10-minute inclusion price from the live mempool, +floored at the minimum relay fee. Minimum relay is 0.1 sat/vB. RBF is +always on. A fee slider will not match a Core or Fulcrum server. Detail: +[`mempool-fee-estimation.md`](./mempool-fee-estimation.md). + +Released Electrum through 4.8 speaks protocol 1.4–1.6 and queries by +scripthash. This node advertises `protocol_max` **1.6**. Protocol 1.7 +replaces `blockchain.scripthash.*` with `blockchain.scriptpubkey.*`. +Those methods are not implemented, so a 1.7-only client cannot sync. +`blockchain.outpoint.*` is already served and is not advertised as 1.7. + +## TCP RPC cookie + +Wasabi, LND's `bitcoind` backend, and a stratum pool that polls +`getblocktemplate` all expect Core's `rpcuser` / `rpcpassword`. This node +does not have those flags. TCP JSON-RPC accepts HTTP Basic from a cookie +file you write yourself, plus Bearer from `{datadir}/rpc.token`. + +The file is one line, `username:password`, with **no trailing newline**. +The node refuses to start if the newline is there. Write it before each +start (`/run` is tmpfs): + +```bash +sudo mkdir -p /run/rbitcoin +printf '__cookie__:%s' "$(od -An -N32 -tx1 /dev/urandom | tr -d ' \n')" | + sudo install -m 0640 -o "$(id -un)" -g "$(id -gn)" /dev/stdin /run/rbitcoin/rpc.cookie + +./target/release/rbitcoin-node \ + --datadir ./datadir-mainnet \ + --network mainnet \ + --rpc-listen 127.0.0.1:8332 \ + --rpc-cookie-file /run/rbitcoin/rpc.cookie +``` + +The mempool.space group ownership and unix-socket variant are in +[`operator/interfaces.md`](./operator/interfaces.md#mempoolspace-core_rpc). +Unix `{datadir}/rpc.sock` (`--rpc`, mode 0600) needs no header. +`rbitcoin-cli` and the CLN wrapper use that socket. +[`lightning.md`](./lightning.md) has the LND `rpccookie` lines. + +## Electrum and Esplora wallets + +Start the listener the wallet speaks. Both need `--sh-index` for +balances and history. + +```bash +./target/release/rbitcoin-node \ + --datadir ./datadir-mainnet \ + --network mainnet \ + --sh-index \ + --electrum-listen 127.0.0.1:50001 \ + --esplora-listen 127.0.0.1:3000 +``` + +| Wallet | Setting that works | +|--------|--------------------| +| Electrum desktop, including Electrum's Lightning | Server `127.0.0.1:50001:t` (the trailing `t` is plain TCP). Behind a TLS proxy, `host:443:s`. | +| Sparrow, private Electrum | Server type **Private Electrum**, TCP `127.0.0.1:50001`. Silent Payments uses Frigate `blockchain.silentpayments.subscribe`, which is implemented. Add `--sp-tweaks` so that scan is indexed. Sparrow's **Bitcoin Core** server type imports a descriptor wallet and does not apply. | +| Liana v7+ | Backend **Electrum server** at `127.0.0.1:50001`. The bitcoind backend wants Core's descriptor wallet (Core 24+, 26+ for Taproot) and does not apply. | +| Specter Desktop 2.0 | **External Electrum**. The Bitcoin Core connection needs `disablewallet=0` and wallet RPC, which this node does not serve. | +| Cake Wallet | Electrum server as above, plus `--sp-tweaks` and `--sp-tweaks-dust 546` (Cake's electrs dust floor; our default is 1000). `server.version[0]` is `rbitcoin-electrs ` so Cake's electrs probe will call `blockchain.tweaks.subscribe`. A Cake build that still hardcodes `electrs.cakewallet.com` will not use the server you typed. | +| BlueWallet, Stack Wallet, Keeper, Nunchuk, BitBox App, Envoy / Passport, Caravan, MyCitadel, Blockstream Green personal server | The app's custom Electrum or Esplora field. Same listeners as the table above. | +| BDK wallets on Esplora (Alby Hub's chain source, and the same client shape Mutiny used) | `http://127.0.0.1:3000`, or TLS in front of that port. | + +`--sp-tweaks` is refused together with `--prune-seqsigwit`. Cake and +Sparrow Silent Payments need the tweak index, so that prune stays off +for those wallets. + +## Wasabi + +Wasabi's full-node path is supported. It is a JSON-RPC client, not an +Electrum client. The jobs [Wasabi's full-node +doc](https://docs.wasabiwallet.io/using-wasabi/BitcoinFullNode.html) +assigns to a local node are the methods below, and each one is served: + +| Wasabi uses the node for | Method | Flag | +|--------------------------|--------|------| +| BIP158 filters | `getblockfilter` `basic` | `--block-filter-index` | +| Block download | `getblock` | `--rpc-listen` | +| Fee estimates | `estimatesmartfee` | `--rpc-listen` | +| Broadcast | `sendrawtransaction` | `--rpc-listen` | + +Two configuration facts are easy to read as "unsupported": + +- Wasabi has no Electrum server field on this path. Pointing Sparrow at + `--electrum-listen` does not configure Wasabi. +- The setting is `BitcoinRpcCredentialString`, a `username:password` + sent as HTTP Basic. There is no `--rpcuser` / `--rpcpassword` to put + in a `bitcoin.conf`. Paste the cookie file from [TCP RPC + cookie](#tcp-rpc-cookie) into that string. The bytes must match, + including the lack of a trailing newline. + +```text +BitcoinRpcEndpoint: http://127.0.0.1:8332 +BitcoinRpcCredentialString: +``` + +`estimatesmartfee` accepts Core's `estimate_mode` (`unset`, +`economical`, `conservative`) and returns the same 10-minute feerate +for all three. Wasabi's economical-versus-conservative choice does not +change the number. + +If the endpoint or the credential is wrong, Wasabi keeps loading filters +from its own backend and shows the RPC status as disconnected. That +fallback is Wasabi's. The node is in use when the status bar says the +RPC is connected. Filters are absent until `--block-filter-index` has +sealed the heights Wasabi asks for. `getblockfilter` on a known block +that is not sealed yet is rebuilt from the stored body. REST +`/rest/blockfilter/` and P2P stay watermark-only. + +## Core-wallet applications + +These talk to Bitcoin Core's wallet RPC. Electrum or Esplora mode, where +the table above lists one, is the path that works. The Core mode does +not: + +| Application | What it asks the node to do | +|-------------|----------------------------| +| Sparrow, server type Bitcoin Core | Create and scan a descriptor wallet on the node. | +| Specter Desktop, Bitcoin Core connection | The same, with `disablewallet=0`. | +| Liana bitcoind backend | Watch-only descriptor wallet. Core 24.0.1 minimum, 26.0 for Taproot. | +| Fully Noded | Remote control of a Core wallet. | +| JoinMarket and Jam | `listunspent`, wallet signing, `sendrawtransaction` through the Core wallet. | +| Electrum Personal Server | A watch-only Core wallet, then it serves Electrum. This node already is the Electrum server. EPS is not the way to attach Electrum. | + +## BTCPay Server + +NBXplorer scans blocks with `getblock` (verbosity 2) and +`getrawtransaction`, broadcasts with `sendrawtransaction`, and +authenticates with a cookie file. Those calls and the cookie exist. +Current NBXplorer also requires Bitcoin Core **24.0 or newer**. +`getnetworkinfo.version` is fixed at **190000** so clients do not assume +a descriptor wallet ([`rpc.md`](./rpc.md#getnetworkinfoversion)). That +integer fails NBXplorer's version gate. Raising it would claim wallet +RPC this node does not serve. BTCPay works against this node when +NBXplorer accepts the `subversion` (`/rbitcoin:/`) and keeps +using the block and transaction calls. + +## Compact-filter and SPV wallets + +Wasabi's RPC filter path is above. These are different: + +| Client | What it needs | On this node | +|--------|---------------|--------------| +| bitcoinj wallets (Schildbach Bitcoin Wallet, older Mycelium) | P2P v1 and BIP37 bloom filters (`filterload`) | P2P is BIP324 v2 only. `filterload` disconnects the peer. | +| LND Neutrino, Zeus embedded LND in Neutrino mode | BIP157 to a peer | Filters are served with `--block-filter-index`. Neutrino does not speak v2, so it cannot connect. Detail: [`lightning.md`](./lightning.md#neutrino). | + +## Hardware-wallet apps + +Sparrow, Electrum, Specter, Liana, BitBox App, and Envoy follow the +Electrum rows above. The signer never talks to the node. + +Trezor Suite talks to Blockbook. Ledger Live talks to Ledger's backend. +Neither has an Electrum, Esplora, or Core-RPC-subset setting. + +## Pools + +SV2 Job Declarator clients and pools that speak Template Distribution +over Noise NX use `--sv2-tp-listen`. Setup is +[`operator/interfaces.md`](./operator/interfaces.md#stratum-v2-template-provider). + +Stratum v1 pool software (public-pool, ckpool, Datum) that only polls +`getblocktemplate` and submits a block can use the template RPC. There +is no stratum server in the node. Authentication is the [cookie +file](#tcp-rpc-cookie), not `rpcuser` / `rpcpassword`. + +## What is still missing for other wallets + +| Gap | Who it blocks | What the change is | +|-----|---------------|--------------------| +| Electrum `scriptpubkey.*` (protocol 1.7) | A future Electrum that drops 1.4–1.6, and 1.7-only servers' clients | Hash the provided script and serve the existing scripthash index under the 1.7 response shapes. Then advertise 1.7. | +| TLS on port 50002 inside the node (**Q-63**) | Phone wallets whose only server field is SSL, when the operator will not run a proxy | A listener. The product today is the reverse proxy. | +| `getblockchaininfo.softforks` | A client that reads that object and stops | Copy the buried map `getdeploymentinfo` already returns. Current LND does not stop: a missing `softforks` map falls through to `getdeploymentinfo`, and `deployments.taproot` is present. See [`lightning.md`](./lightning.md#bitcoind-with-rpc-polling). | +| ZMQ | LND's default bitcoind mode, Eclair, Dojo / Ashigaru | A publisher. Not a 1.0 surface. LND's `rpcpolling` path does not need it ([`lightning.md`](./lightning.md)). Eclair and Dojo also need Core wallet RPC. | +| Core wallet RPC | The Core-wallet table above, plus Eclair | Out of scope. | +| Blockbook WebSocket | Trezor Suite | A new API. | +| `--network testnet4` | Wallets whose chain selector is testnet4 | A network. Not implemented. | +| NBXplorer version gate | BTCPay | A client change. The block-scan methods are already served. |