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

@@ -22,6 +22,14 @@ eclair.on-chain-fees.confirmation-priority {
 
 This configuration section replaces the previous `eclair.on-chain-fees.target-blocks` section.
 
+### 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
 
 <insert changes>