Delegate Bitcoin Core's private key management to Eclair

README.md

@@ -162,7 +162,10 @@ 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.
+
+You can also configure Eclair to manage Bitcoin Core's private keys, see our [guides](./docs/Guides.md) for more details.
 
 ### Java Environment Variables
 

docs/BitcoinCoreKeys.md

@@ -0,0 +1,122 @@
+# 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 feature was designed to take advantage of deployment where your Eclair node runs in a
+"trusted" runtime environment, but is also 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).
+
+## Configuring Eclair and Bitcoin Core to use a new Eclair-backed bitcoin wallet
+
+Follow these steps to delegate on-chain key management to eclair:
+
+### 1. Generate a BIP39 mnemonic code and passphrase
+
+You can use any BIP39-compatible tool, including most hardware wallets.
+
+### 2. Create an `eclair-signer.conf` configuration file add it to eclair's data directory
+
+A signer configuration file uses the HOCON format that we already use for `eclair.conf` and must include the following options:
+
+ key                      | description
+--------------------------|--------------------------------------------------------------------------
+ eclair.signer.wallet     | wallet name
+ eclair.signer.mnemonics  | BIP39 mnemonic words
+ eclair.signer.passphrase | passphrase
+ eclair.signer.timestamp  | wallet creation UNIX timestamp. Set to the current time for new wallets.
+
+This is an example of `eclair-signer.conf` configuration file:
+
+```hocon
+{
+   eclair {
+      signer {
+         wallet = "eclair"
+         mnemonics = "legal winner thank year wave sausage worth useful legal winner thank year wave sausage worth useful legal winner thank year wave sausage worth title"
+         passphrase = ""
+         timestamp = 1686055705
+      }
+   }
+}
+```
+
+### 3. Configure Eclair to handle private keys for this wallet
+
+Set `eclair.bitcoind.wallet` to the name of the wallet in your `eclair-signer.conf` file (`eclair` in the example above) and restart Eclair.
+Eclair will automatically create a new, empty, descriptor-enabled, watch-only wallet in Bitcoin Core and import its descriptors.
+
+:warning: Eclair will not import descriptors if the timestamp set in your `eclair-signer.conf` is more than 2 hours old. If the mnemonics and
+passphrase that your are using are new, you can safely update this timestamp, but if they have been used before you will need to follow
+the steps described in the next section.
+
+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 on-chain 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) that you can use to monitor your Bitcoin Core balance.
+
+:warning: this means that your Bitcoin Core wallet cannot send funds on its own (since it cannot access private keys to sign transactions).
+To send funds on-chain you must use `eclair-cli sendonchain`.
+
+:warning: to backup the private keys of this wallet you must either backup your mnemonic code and passphrase, or backup the `eclair-signer.conf` file in your eclair
+directory (default is `~/.eclair`) along with your channels and node seed files.
+
+:warning: You can also initialize a backup on-chain wallet with the same mnemonic code and passphrase (on a hardware wallet for example), but be warned that using them may interfere with your node's operations (for example you may end up
+double-spending funding transactions generated by your node).
+
+## Importing an existing Eclair-backed Bitcoin Core wallet
+
+The steps above described how you can simply switch to a new Eclair-backed bitcoin wallet.
+Follow the steps below if you are already using an Eclair-backed bitcoin wallet that you want to move to another Bitcoin Core node.
+
+### 1. Create an empty, descriptor-enabled, watch-only wallet in Bitcoin Core
+
+Start by creating a watch-only wallet on your new Bitcoin Core node.
+
+:warning: The name must match the one that you set in `eclair-signer.conf` (here we use "eclair")
+
+```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
+
+Calling `eclair-cli getdescriptors` on your existing Eclair node will return public wallet descriptors in a format that is compatible with Bitcoin Core.
+This is an example of descriptors generated by Eclair:
+
+```json
+[
+   {
+      "desc": "wpkh([0d9250da/84h/1h/0h]tpubDDGF9PnrXww2h1mKNjKiXoqdDFGEcZGCZUNq7g26LdzKXKiE31RrFWsogPy1uMLrbG8ksQ8eJS6u6KFLjYUUSVJRuwmMD2SYCr8uG1TcRgM/0/*)#jz5n2pcp",
+      "internal": false,
+      "timestamp": 1686055705,
+      "active": true
+   },
+   {
+      "desc": "wpkh([0d9250da/84h/1h/0h]tpubDDGF9PnrXww2h1mKNjKiXoqdDFGEcZGCZUNq7g26LdzKXKiE31RrFWsogPy1uMLrbG8ksQ8eJS6u6KFLjYUUSVJRuwmMD2SYCr8uG1TcRgM/1/*)#rk3jh5ge",
+      "internal": true,
+      "timestamp": 1686055705,
+      "active": true
+   }
+]
+```
+
+Generate the descriptors with your Eclair node and import them into a Bitcoin node with the following commands:
+
+```shell
+$ eclair-cli getdescriptors | jq --raw-output -c > descriptors.json
+$ cat descriptors.json | xargs -0 bitcoin-cli -rpcwallet=eclair importdescriptors
+```
+
+:warning: Importing descriptors can take a long time, and your Bitcoin Core node will not be usable until it's done
+
+### 3. Configure Eclair to use your new Bitcoin Core node
+
+Once your new Bitcoin Core node has finished importing the descriptors, it is ready to be used by Eclair.
+
+In your `eclair.conf`:
+
+- set `eclair.bitcoind.host` to the address of your new Bitcoin Core node
+- set `eclair.bitcoind.wallet` to the name of the wallet in `eclair-signer.conf`
+- set `eclair.bitcoind.zmqblock` and `eclair.bitcoind.zmqtx` to use your new Bitcoin Core node
+- update other field in the `eclair.bitcoind` section if necessary (`rpcport`, `auth`, `rpcuser`, `rpcuser`, etc)
+
+Restart Eclair and it will start using your new Bitcoin Core node.

docs/Guides.md

@@ -4,6 +4,7 @@ This section contains how-to guides for more advanced scenarios:
 
 * [Customize Logging](./Logging.md)
 * [Customize Features](./Features.md)
+* [Manage Bitcoin Core's private keys](./BitcoinCoreKeys.md)
 * [Use Tor with Eclair](./Tor.md)
 * [Multipart Payments](./MultipartPayments.md)
 * [Trampoline Payments](./TrampolinePayments.md)

docs/release-notes/eclair-vnext.md

@@ -23,6 +23,12 @@ 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 use Eclair to manage the private keys for on-chain funds monitored by a Bitcoin Core watch-only wallet.
+
+See `docs/BitcoinCoreKeys.md` for more details.
+
 ### API changes
 
 - `bumpforceclose` can be used to make a force-close confirm faster, by spending the anchor output (#2743)

eclair-core/src/main/scala/fr/acinq/eclair/Eclair.scala

@@ -32,6 +32,7 @@ import fr.acinq.eclair.blockchain.OnChainWallet.OnChainBalance
 import fr.acinq.eclair.blockchain.bitcoind.rpc.BitcoinCoreClient
 import fr.acinq.eclair.blockchain.bitcoind.rpc.BitcoinCoreClient.WalletTx
 import fr.acinq.eclair.blockchain.fee.{ConfirmationTarget, FeeratePerByte, FeeratePerKw}
+import fr.acinq.eclair.blockchain.bitcoind.rpc.BitcoinCoreClient.{Descriptors, WalletTx}
 import fr.acinq.eclair.channel._
 import fr.acinq.eclair.crypto.Sphinx
 import fr.acinq.eclair.db.AuditDb.{NetworkFee, Stats}
@@ -130,7 +131,7 @@ trait Eclair {
 
   def sentInfo(id: PaymentIdentifier)(implicit timeout: Timeout): Future[Seq[OutgoingPayment]]
 
-  def sendOnChain(address: String, amount: Satoshi, confirmationTarget: Long): Future[ByteVector32]
+  def sendOnChain(address: String, amount: Satoshi, confirmationTargetOrFeerate: Either[Long, FeeratePerByte]): Future[ByteVector32]
 
   def cpfpBumpFees(targetFeeratePerByte: FeeratePerByte, outpoints: Set[OutPoint]): Future[ByteVector32]
 
@@ -180,6 +181,10 @@ trait Eclair {
 
   def payOfferBlocking(offer: Offer, amount: MilliSatoshi, quantity: Long, externalId_opt: Option[String] = None, maxAttempts_opt: Option[Int] = None, maxFeeFlat_opt: Option[Satoshi] = None, maxFeePct_opt: Option[Double] = None, pathFindingExperimentName_opt: Option[String] = None, connectDirectly: Boolean = false)(implicit timeout: Timeout): Future[PaymentEvent]
 
+  def getOnChainMasterPubKey(account: Long): String
+
+  def getDescriptors(account: Long): Descriptors
+
   def stop(): Future[Unit]
 }
 
@@ -352,9 +357,20 @@ class EclairImpl(appKit: Kit) extends Eclair with Logging {
     }
   }
 
-  override def sendOnChain(address: String, amount: Satoshi, confirmationTarget: Long): Future[ByteVector32] = {
+  override def sendOnChain(address: String, amount: Satoshi, confirmationTargetOrFeerate: Either[Long, FeeratePerByte]): Future[ByteVector32] = {
+    val feeRate = confirmationTargetOrFeerate match {
+      case Left(blocks) =>
+        if (blocks < 3) appKit.nodeParams.currentFeerates.fast
+        else if (blocks > 6) appKit.nodeParams.currentFeerates.slow
+        else appKit.nodeParams.currentFeerates.medium
+      case Right(feeratePerByte) => FeeratePerKw(feeratePerByte)
+    }
     appKit.wallet match {
-      case w: BitcoinCoreClient => w.sendToAddress(address, amount, confirmationTarget)
+      case w: BitcoinCoreClient =>
+        addressToPublicKeyScript(appKit.nodeParams.chainHash, address) match {
+          case Right(pubkeyScript) => w.sendToPubkeyScript(pubkeyScript, amount, feeRate)
+          case Left(failure) => Future.failed(new IllegalArgumentException(s"invalid address ($failure)"))
+        }
       case _ => Future.failed(new IllegalArgumentException("this call is only available with a bitcoin core backend"))
     }
   }
@@ -665,16 +681,16 @@ class EclairImpl(appKit: Kit) extends Eclair with Logging {
     }
   }
 
-  def payOfferInternal(offer: Offer,
-                       amount: MilliSatoshi,
-                       quantity: Long,
-                       externalId_opt: Option[String],
-                       maxAttempts_opt: Option[Int],
-                       maxFeeFlat_opt: Option[Satoshi],
-                       maxFeePct_opt: Option[Double],
-                       pathFindingExperimentName_opt: Option[String],
-                       connectDirectly: Boolean,
-                       blocking: Boolean)(implicit timeout: Timeout): Future[Any] = {
+  private def payOfferInternal(offer: Offer,
+                               amount: MilliSatoshi,
+                               quantity: Long,
+                               externalId_opt: Option[String],
+                               maxAttempts_opt: Option[Int],
+                               maxFeeFlat_opt: Option[Satoshi],
+                               maxFeePct_opt: Option[Double],
+                               pathFindingExperimentName_opt: Option[String],
+                               connectDirectly: Boolean,
+                               blocking: Boolean)(implicit timeout: Timeout): Future[Any] = {
     if (externalId_opt.exists(_.length > externalIdMaxLength)) {
       return Future.failed(new IllegalArgumentException(s"externalId is too long: cannot exceed $externalIdMaxLength characters"))
     }
@@ -717,6 +733,16 @@ class EclairImpl(appKit: Kit) extends Eclair with Logging {
     payOfferInternal(offer, amount, quantity, externalId_opt, maxAttempts_opt, maxFeeFlat_opt, maxFeePct_opt, pathFindingExperimentName_opt, connectDirectly, blocking = true).mapTo[PaymentEvent]
   }
 
+  override def getDescriptors(account: Long): Descriptors = appKit.nodeParams.onChainKeyManager_opt match {
+    case Some(keyManager) => keyManager.descriptors(account)
+    case _ => throw new RuntimeException("on-chain seed is not configured")
+  }
+
+  override def getOnChainMasterPubKey(account: Long): String = appKit.nodeParams.onChainKeyManager_opt match {
+    case Some(keyManager) => keyManager.masterPubKey(account)
+    case _ => throw new RuntimeException("on-chain seed is not configured")
+  }
+
   override def stop(): Future[Unit] = {
     // README: do not make this smarter or more complex !
     // eclair can simply and cleanly be stopped by killing its process without fear of losing data, payments, ... and it should remain this way.

eclair-core/src/main/scala/fr/acinq/eclair/NodeParams.scala

@@ -25,16 +25,16 @@ import fr.acinq.eclair.channel.ChannelFlags
 import fr.acinq.eclair.channel.fsm.Channel
 import fr.acinq.eclair.channel.fsm.Channel.{ChannelConf, UnhandledExceptionStrategy}
 import fr.acinq.eclair.crypto.Noise.KeyPair
-import fr.acinq.eclair.crypto.keymanager.{ChannelKeyManager, NodeKeyManager}
+import fr.acinq.eclair.crypto.keymanager.{ChannelKeyManager, NodeKeyManager, OnChainKeyManager}
 import fr.acinq.eclair.db._
 import fr.acinq.eclair.io.MessageRelay.{RelayAll, RelayChannelsOnly, RelayPolicy}
 import fr.acinq.eclair.io.PeerConnection
 import fr.acinq.eclair.message.OnionMessages.OnionMessageConfig
 import fr.acinq.eclair.payment.relay.Relayer.{AsyncPaymentsParams, RelayFees, RelayParams}
 import fr.acinq.eclair.router.Announcements.AddressException
 import fr.acinq.eclair.router.Graph.{HeuristicsConstants, WeightRatios}
+import fr.acinq.eclair.router.Router._
 import fr.acinq.eclair.router.{Graph, PathFindingExperimentConf}
-import fr.acinq.eclair.router.Router.{MessageRouteParams, MultiPartParams, PathFindingConf, RouterConf, SearchBoundaries}
 import fr.acinq.eclair.tor.Socks5ProxyParams
 import fr.acinq.eclair.wire.protocol._
 import grizzled.slf4j.Logging
@@ -54,6 +54,7 @@ import scala.jdk.CollectionConverters._
  */
 case class NodeParams(nodeKeyManager: NodeKeyManager,
                       channelKeyManager: ChannelKeyManager,
+                      onChainKeyManager_opt: Option[OnChainKeyManager],
                       instanceId: UUID, // a unique instance ID regenerated after each restart
                       private val blockHeight: AtomicLong,
                       private val feerates: AtomicReference[FeeratesPerKw],
@@ -101,7 +102,7 @@ case class NodeParams(nodeKeyManager: NodeKeyManager,
   def currentFeerates: FeeratesPerKw = feerates.get()
 
   /** Only to be used in tests. */
-  def setFeerates(value: FeeratesPerKw) = feerates.set(value)
+  def setFeerates(value: FeeratesPerKw): Unit = feerates.set(value)
 
   /** Returns the features that should be used in our init message with the given peer. */
   def initFeaturesFor(nodeId: PublicKey): Features[InitFeature] = overrideInitFeatures.getOrElse(nodeId, features).initFeatures()
@@ -211,7 +212,8 @@ object NodeParams extends Logging {
     }
   }
 
-  def makeNodeParams(config: Config, instanceId: UUID, nodeKeyManager: NodeKeyManager, channelKeyManager: ChannelKeyManager,
+  def makeNodeParams(config: Config, instanceId: UUID,
+                     nodeKeyManager: NodeKeyManager, channelKeyManager: ChannelKeyManager, onChainKeyManager_opt: Option[OnChainKeyManager],
                      torAddress_opt: Option[NodeAddress], database: Databases, blockHeight: AtomicLong, feerates: AtomicReference[FeeratesPerKw],
                      pluginParams: Seq[PluginParams] = Nil): NodeParams = {
     // check configuration for keys that have been renamed
@@ -475,6 +477,7 @@ object NodeParams extends Logging {
     NodeParams(
       nodeKeyManager = nodeKeyManager,
       channelKeyManager = channelKeyManager,
+      onChainKeyManager_opt = onChainKeyManager_opt,
       instanceId = instanceId,
       blockHeight = blockHeight,
       feerates = feerates,