Document how to create Bitcoin Core wallets where private keys are ma…

…naged by Eclair

README.md

@@ -162,7 +162,81 @@ limitdescendantcount=20
 
 Setting these parameters lets you unblock long chains of unconfirmed channel funding transactions by using child-pays-for-parent (CPFP) to make them confirm.
 
-With the default `bitcoind` parameters, if your node created a chain of 25 unconfirmed funding transactions with a low-feerate, you wouldn't be able to use CPFP to raise their fees because your CPFP transaction would likely be rejected by the rest of the network.
+With the default `bitcoind` parameters, if your node created a chain of 25 unconfirmed funding transactions with a low-feerate, you wouldn't be able to use CPFP to raise their fees because your CPFP transaction would likely be rejected by
+the rest of the network.
+
+#### Using Eclair to manage your Bitcoin Core wallet's private keys
+
+You can configure Eclair to control (and never expose) the private keys of your Bitcoin Core wallet. This is very useful if your Bitcoin and Eclair nodes run on different machines for example, with a setup for the Bitcoin host that
+is less secure than for Eclair (because it is shared among several services for example).
+
+1) Create an empty, descriptor-enabled, watch-only wallet in Bitcoin Core:
+
+```shell
+$ bitcoin-cli -named createwallet wallet_name=eclair disable_private_keys=true blank=true descriptors=true load_on_startup=true
+```
+
+2) Import public descriptors generated by Eclair
+
+`eclair-cli listdescriptors` will return public wallet descriptors in a format that is compatible with Bitcoin Core, and that you can import with `bitcoin-cli -rpcwallet=eclair importdescriptors`
+
+This is an example of descriptors generated by Eclair:
+
+```json
+{
+  "wallet_name": "eclair",
+  "descriptors": [
+    {
+      "desc": "wpkh([0f09f381/84'/1'/0']tpubDCAVQRxWnkXjyYbsHdUsHA7krYSRyVS8EuWeWE6K2V34goMaUCdCTjfSFS8ZkE5iESaWQsZoM9HL7ZANi5bW7Ly3EqDqthEyvdZHSrBTNHq/0/*)#gj3mq2sl",
+      "timestamp": 1684150749,
+      "active": true,
+      "internal": false,
+      "range": [
+        0,
+        1003
+      ],
+      "next": 4
+    },
+    {
+      "desc": "wpkh([0f09f381/84'/1'/0']tpubDCAVQRxWnkXjyYbsHdUsHA7krYSRyVS8EuWeWE6K2V34goMaUCdCTjfSFS8ZkE5iESaWQsZoM9HL7ZANi5bW7Ly3EqDqthEyvdZHSrBTNHq/1/*)#ex56alq8",
+      "timestamp": 1684150749,
+      "active": true,
+      "internal": true,
+      "range": [
+        0,
+        1001
+      ],
+      "next": 2
+    }
+  ]
+}
+```
+
+You can combine the generation and import of descriptors with:
+
+```shell
+$ eclair-cli getdescriptors | jq --raw-output -c | xargs -0 bitcoin-cli -rpcwallet=eclair importdescriptors
+```
+
+3) Configure Eclair to handle private keys for this wallet
+
+Add the following lines to your `eclair.conf` file:
+
+```
+eclair.bitcoind.wallet = eclair
+eclair.bitcoind.use-eclair-signer = true
+```
+
+You now have a Bitcoin Core watch-only wallet for which only your Eclair node can sign transactions. This Bitcoin Core wallet can
+safely be copied to another Bitcoin Core node to monitor your onchain funds.
+You can also use `eclair-cli getmasterxpub` to get a BIP32 extended public key that you can import into any compatible Bitcoin wallet
+to create a watch-only wallet (Electrum for example).
+
+:warning: this means that your Bitcoin Core wallet cannot send funds on its on (since it cannot access private keys to sign transactions).
+To send funds onchain you must use `eclair-cli sendonchain`.
+
+:warning: to backup the private keys of this wallet you must backup the onchain seed file `onchain_seed.dat` that is located in your eclair
+directory (default is `~/.eclair`) along with your channels and node seed files.
 
 ### Java Environment Variables
 

docs/release-notes/eclair-vnext.md

@@ -32,23 +32,40 @@ All this data is signed and encrypted so that it can not be read or forged by th
 
 ### Data model
 
-The database model has been completely reworked to handle splices. Mainly, a channel can have several commitments in parallel.
-Node operators that use Postgres as database backend and make SQL queries on channels' JSON content should reset the JSON column:
+The database model has been completely reworked to handle splices. Mainly, a channel can have several commitments in
+parallel.
+Node operators that use Postgres as database backend and make SQL queries on channels' JSON content should reset the
+JSON column:
 
 1. Set `eclair.db.postgres.reset-json-columns = true` before restarting eclair
 2. Once restarted, set `eclair.db.postgres.reset-json-columns = false` (no need to restart again)
 
+### Managing Bitcoin Core wallet keys
+
+You can now create Bitcoin Core watch-only wallets and have Eclair manage their private keys:
+
+1. Create an empty, descriptors-enabled watch-only wallet in Bitcoin Core
+2. Import wallet descriptors generated by Eclair into this wallet
+3. Configure Eclair to use this wallet and set the `eclair.bitcoind.use-eclair-signer` to `true`
+
 ### API changes
 
 - `audit` now accepts `--count` and `--skip` parameters to limit the number of retrieved items (#2474, #2487)
 - `sendtoroute` removes the `--trampolineNodes` argument and implicitly uses a single trampoline hop (#2480)
 - `payinvoice` always returns the payment result when used with `--blocking`, even when using MPP (#2525)
 - `node` returns high-level information about a remote node (#2568)
-- `channel-created` is a new websocket event that is published when a channel's funding transaction has been broadcast (#2567)
-- `channel-opened` websocket event was updated to contain the final `channel_id` and be published when a channel is ready to process payments (#2567)
+- `channel-created` is a new websocket event that is published when a channel's funding transaction has been broadcast (
+  #2567)
+- `channel-opened` websocket event was updated to contain the final `channel_id` and be published when a channel is
+  ready to process payments (#2567)
 - `getsentinfo` can now be used with `--offer` to list payments sent to a specific offer.
 - `listreceivedpayments` lists payments received by your node (#2607)
-- `cpfpbumpfees` can be used to unblock chains of unconfirmed transactions by creating a child transaction that pays a high fee (#1783)
+- `cpfpbumpfees` can be used to unblock chains of unconfirmed transactions by creating a child transaction that pays a
+  high fee (#1783)
+- `getdescriptors` is a new API call that returns wallet descriptors to import in a watch-only Bitcoin Core wallet where
+  private keys are managed by Eclair (#2613)
+- `getmasterxpub` is a new API call that returns a BIP32-compatible xpub that can be used to derive public keys for
+  watch-only wallets where private keys are managed by Eclair (#2613)
 
 ### Miscellaneous improvements and bug fixes