Skip to content

Commit

Permalink
Document how to create Bitcoin Core wallets where private keys are ma…
Browse files Browse the repository at this point in the history
…naged by Eclair
  • Loading branch information
sstone committed Jun 21, 2023
1 parent f69ec92 commit 425378f
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 1 deletion.
76 changes: 75 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 8 additions & 0 deletions docs/release-notes/eclair-vnext.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down

0 comments on commit 425378f

Please sign in to comment.