Use official liquidity ads types

docs/release-notes/eclair-vnext.md

@@ -4,6 +4,62 @@
 
 ## Major changes
 
+### Liquidity Ads
+
+This release includes support for the official version of [liquidity ads](https://github.com/lightning/bolts/pull/1153).
+Liquidity ads allow nodes to sell their liquidity in a trustless and decentralized manner.
+Every node advertizes the rates at which they sell their liquidity, and buyers connect to sellers that offer interesting rates.
+
+Node operators who want to sell their liquidity must configure their funding rates in `eclair.conf`:
+
+```conf
+eclair.liquidity-ads.funding-rates = [
+    {
+        min-funding-amount-satoshis = 100000 // minimum funding amount at this rate
+        max-funding-amount-satoshis = 500000 // maximum funding amount at this rate
+        // The seller can ask the buyer to pay for some of the weight of the funding transaction (for the inputs and
+        // outputs added by the seller). This field contains the transaction weight (in vbytes) that the seller asks the
+        // buyer to pay for. The default value matches the weight of one p2wpkh input with one p2wpkh change output.
+        funding-weight = 400
+        fee-base-satoshis = 500 // flat fee that we will receive every time we accept a liquidity request
+        fee-basis-points = 250 // proportional fee based on the amount requested by our peer (2.5%)
+        channel-creation-fee-satoshis = 2500 // flat fee that is added when creating a new channel
+    },
+    {
+      min-funding-amount-satoshis = 500000
+      max-funding-amount-satoshis = 1000000
+      funding-weight = 750
+      fee-base-satoshis = 1000
+      fee-basis-points = 200 // 2%
+      channel-creation-fee-satoshis = 2000
+    }
+]
+```
+
+Node operators who want to purchase liquidity from other nodes must first choose a node that sells liquidity.
+The `nodes` API can be used to filter nodes that support liquidity ads:
+
+```sh
+./eclair-cli nodes --liquidityProvider=true
+```
+
+This will return the corresponding `node_announcement`s that contain the nodes' funding rates.
+After choosing a seller node, liquidity can be purchased on a new channel:
+
+```sh
+./eclair-cli open --nodeId=<seller_node_id> --fundingSatoshis=<local_contribution> --requestFundingSatoshis=<remote_contribution>
+```
+
+If the buyer already has a channel with the seller, and if the seller supports splicing, liquidity can be purchased with a splice:
+
+```sh
+./eclair-cli splicein --channelId=<channel_id> --amountIn=<amount_in> --requestFundingSatoshis=<remote_contribution>
+./eclair-cli spliceout --channelId=<channel_id> --amountOut=<amount_out> --address=<output_address> --requestFundingSatoshis=<remote_contribution>
+```
+
+Note that `amountIn` and `amountOut` can be set to `0` when purchasing liquidity without splicing in or out.
+It is however more efficient to batch operations and purchase liquidity at the same time as splicing in or out.
+
 ### New MPP splitting strategy
 
 Eclair can send large payments using multiple low-capacity routes by sending as much as it can through each route (if `randomize-route-selection = false`) or some random fraction (if `randomize-route-selection = true`).
@@ -39,6 +95,7 @@ Newer versions of Bitcoin Core may be used, but have not been extensively tested
 ### API changes
 
 - the `closedchannels` API now returns human-readable channel data
+- `open`, `rbfopen`, `splicein` and `spliceout` now take an optional `--requestFundingSatoshis` parameter to purchase liquidity from the remote node. (#2926)
 
 ### Miscellaneous improvements and bug fixes
 

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

@@ -23,7 +23,7 @@ import akka.actor.{ActorRef, typed}
 import akka.pattern._
 import akka.util.Timeout
 import fr.acinq.bitcoin.scalacompat.Crypto.PublicKey
-import fr.acinq.bitcoin.scalacompat.{BlockHash, ByteVector32, ByteVector64, Crypto, DeterministicWallet, OutPoint, Satoshi, Script, Transaction, TxId, addressToPublicKeyScript}
+import fr.acinq.bitcoin.scalacompat.{BlockHash, ByteVector32, ByteVector64, Crypto, DeterministicWallet, OutPoint, Satoshi, SatoshiLong, Script, Transaction, TxId, addressToPublicKeyScript}
 import fr.acinq.eclair.ApiTypes.ChannelNotFound
 import fr.acinq.eclair.balance.CheckBalance.GlobalBalance
 import fr.acinq.eclair.balance.{BalanceActor, ChannelsListener}
@@ -92,13 +92,13 @@ trait Eclair {
 
   def disconnect(nodeId: PublicKey)(implicit timeout: Timeout): Future[String]
 
-  def open(nodeId: PublicKey, fundingAmount: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[SupportedChannelType], fundingFeerate_opt: Option[FeeratePerByte], fundingFeeBudget_opt: Option[Satoshi], announceChannel_opt: Option[Boolean], openTimeout_opt: Option[Timeout])(implicit timeout: Timeout): Future[OpenChannelResponse]
+  def open(nodeId: PublicKey, fundingAmount: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[SupportedChannelType], fundingFeerate_opt: Option[FeeratePerByte], fundingFeeBudget_opt: Option[Satoshi], requestFunding_opt: Option[Satoshi], announceChannel_opt: Option[Boolean], openTimeout_opt: Option[Timeout])(implicit timeout: Timeout): Future[OpenChannelResponse]
 
-  def rbfOpen(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]]
+  def rbfOpen(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, requestFunding_opt: Option[Satoshi], lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]]
 
-  def spliceIn(channelId: ByteVector32, amountIn: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]]
+  def spliceIn(channelId: ByteVector32, amountIn: Satoshi, requestFunding_opt: Option[Satoshi], pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]]
 
-  def spliceOut(channelId: ByteVector32, amountOut: Satoshi, scriptOrAddress: Either[ByteVector, String], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]]
+  def spliceOut(channelId: ByteVector32, amountOut: Satoshi, scriptOrAddress: Either[ByteVector, String], requestFunding_opt: Option[Satoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]]
 
   def rbfSplice(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]]
 
@@ -232,55 +232,74 @@ class EclairImpl(val appKit: Kit) extends Eclair with Logging with SpendFromChan
     (appKit.switchboard ? Peer.Disconnect(nodeId)).mapTo[Peer.DisconnectResponse].map(_.toString)
   }
 
-  override def open(nodeId: PublicKey, fundingAmount: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[SupportedChannelType], fundingFeerate_opt: Option[FeeratePerByte], fundingFeeBudget_opt: Option[Satoshi], announceChannel_opt: Option[Boolean], openTimeout_opt: Option[Timeout])(implicit timeout: Timeout): Future[OpenChannelResponse] = {
+  override def open(nodeId: PublicKey, fundingAmount: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[SupportedChannelType], fundingFeerate_opt: Option[FeeratePerByte], fundingFeeBudget_opt: Option[Satoshi], requestFunding_opt: Option[Satoshi], announceChannel_opt: Option[Boolean], openTimeout_opt: Option[Timeout])(implicit timeout: Timeout): Future[OpenChannelResponse] = {
     // we want the open timeout to expire *before* the default ask timeout, otherwise user will get a generic response
     val openTimeout = openTimeout_opt.getOrElse(Timeout(20 seconds))
     // if no budget is provided for the mining fee of the funding tx, we use a default of 0.1% of the funding amount as a safety measure
     val fundingFeeBudget = fundingFeeBudget_opt.getOrElse(fundingAmount * 0.001)
     for {
-      _ <- Future.successful(0)
+      purchaseFunding_opt <- createLiquidityRequest(nodeId, requestFunding_opt)
       open = Peer.OpenChannel(
         remoteNodeId = nodeId,
         fundingAmount = fundingAmount,
         channelType_opt = channelType_opt,
         pushAmount_opt = pushAmount_opt,
         fundingTxFeerate_opt = fundingFeerate_opt.map(_.perKw),
         fundingTxFeeBudget_opt = Some(fundingFeeBudget),
-        requestFunding_opt = None,
+        requestFunding_opt = purchaseFunding_opt,
         channelFlags_opt = announceChannel_opt.map(announceChannel => ChannelFlags(announceChannel = announceChannel)),
         timeout_opt = Some(openTimeout))
       res <- (appKit.switchboard ? open).mapTo[OpenChannelResponse]
     } yield res
   }
 
-  override def rbfOpen(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]] = {
-    sendToChannelTyped(
-      channel = Left(channelId),
-      cmdBuilder = CMD_BUMP_FUNDING_FEE(_, targetFeerate, fundingFeeBudget, lockTime_opt.getOrElse(appKit.nodeParams.currentBlockHeight.toLong), requestFunding_opt = None)
-    )
+  override def rbfOpen(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, requestFunding_opt: Option[Satoshi], lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]] = {
+    for {
+      purchaseFunding_opt <- createLiquidityRequest(channelId, requestFunding_opt)
+      res <- sendToChannelTyped[CMD_BUMP_FUNDING_FEE, CommandResponse[CMD_BUMP_FUNDING_FEE]](
+        channel = Left(channelId),
+        cmdBuilder = CMD_BUMP_FUNDING_FEE(_, targetFeerate, fundingFeeBudget, lockTime_opt.getOrElse(appKit.nodeParams.currentBlockHeight.toLong), purchaseFunding_opt)
+      )
+    } yield res
   }
 
-  override def spliceIn(channelId: ByteVector32, amountIn: Satoshi, pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]] = {
-    val spliceIn = SpliceIn(additionalLocalFunding = amountIn, pushAmount = pushAmount_opt.getOrElse(0.msat))
-    sendToChannelTyped(
-      channel = Left(channelId),
-      cmdBuilder = CMD_SPLICE(_, spliceIn_opt = Some(spliceIn), spliceOut_opt = None, requestFunding_opt = None, channelType_opt = channelType_opt)
-    )
+  override def spliceIn(channelId: ByteVector32, amountIn: Satoshi, requestFunding_opt: Option[Satoshi], pushAmount_opt: Option[MilliSatoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]] = {
+    for {
+      purchaseFunding_opt <- createLiquidityRequest(channelId, requestFunding_opt)
+      spliceIn_opt = if (amountIn > 0.sat) Some(SpliceIn(additionalLocalFunding = amountIn, pushAmount = pushAmount_opt.getOrElse(0 msat))) else None
+      res <- sendToChannelTyped[CMD_SPLICE, CommandResponse[CMD_SPLICE]](
+        channel = Left(channelId),
+        cmdBuilder = CMD_SPLICE(_,
+          spliceIn_opt = spliceIn_opt,
+          spliceOut_opt = None,
+          requestFunding_opt = purchaseFunding_opt,
+          channelType_opt = channelType_opt
+        )
+      )
+    } yield res
   }
 
-  override def spliceOut(channelId: ByteVector32, amountOut: Satoshi, scriptOrAddress: Either[ByteVector, String], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]] = {
+  override def spliceOut(channelId: ByteVector32, amountOut: Satoshi, scriptOrAddress: Either[ByteVector, String], requestFunding_opt: Option[Satoshi], channelType_opt: Option[ChannelType])(implicit timeout: Timeout): Future[CommandResponse[CMD_SPLICE]] = {
     val script = scriptOrAddress match {
       case Left(script) => script
       case Right(address) => addressToPublicKeyScript(this.appKit.nodeParams.chainHash, address) match {
         case Left(failure) => throw new IllegalArgumentException(failure.toString)
         case Right(script) => Script.write(script)
       }
     }
-    val spliceOut = SpliceOut(amount = amountOut, scriptPubKey = script)
-    sendToChannelTyped(
-      channel = Left(channelId),
-      cmdBuilder = CMD_SPLICE(_, spliceIn_opt = None, spliceOut_opt = Some(spliceOut), requestFunding_opt = None, channelType_opt = channelType_opt)
-    )
+    for {
+      purchaseFunding_opt <- createLiquidityRequest(channelId, requestFunding_opt)
+      spliceOut_opt = if (amountOut > 0.sat) Some(SpliceOut(amount = amountOut, scriptPubKey = script)) else None
+      res <- sendToChannelTyped[CMD_SPLICE, CommandResponse[CMD_SPLICE]](
+        channel = Left(channelId),
+        cmdBuilder = CMD_SPLICE(_,
+          spliceIn_opt = None,
+          spliceOut_opt = spliceOut_opt,
+          requestFunding_opt = purchaseFunding_opt,
+          channelType_opt = channelType_opt
+        )
+      )
+    } yield res
   }
 
   override def rbfSplice(channelId: ByteVector32, targetFeerate: FeeratePerKw, fundingFeeBudget: Satoshi, lockTime_opt: Option[Long])(implicit timeout: Timeout): Future[CommandResponse[CMD_BUMP_FUNDING_FEE]] = {
@@ -672,6 +691,37 @@ class EclairImpl(val appKit: Kit) extends Eclair with Logging with SpendFromChan
     } yield res
   }
 
+  private def createLiquidityRequest(nodeId: PublicKey, requestedAmount_opt: Option[Satoshi])(implicit timeout: Timeout): Future[Option[LiquidityAds.RequestFunding]] = {
+    requestedAmount_opt match {
+      case Some(requestedAmount) =>
+        getLiquidityRate(nodeId, requestedAmount)
+          .map(fundingRate => Some(LiquidityAds.RequestFunding(requestedAmount, fundingRate, LiquidityAds.PaymentDetails.FromChannelBalance)))
+      case None => Future.successful(Option.empty[LiquidityAds.RequestFunding])
+    }
+  }
+
+  private def createLiquidityRequest(channelId: ByteVector32, requestedAmount_opt: Option[Satoshi])(implicit timeout: Timeout): Future[Option[LiquidityAds.RequestFunding]] = {
+    requestedAmount_opt match {
+      case Some(requestedAmount) =>
+        channelInfo(Left(channelId)).map(_.nodeId)
+          .flatMap(nodeId => getLiquidityRate(nodeId, requestedAmount))
+          .map(fundingRate => Some(LiquidityAds.RequestFunding(requestedAmount, fundingRate, LiquidityAds.PaymentDetails.FromChannelBalance)))
+      case None => Future.successful(Option.empty[LiquidityAds.RequestFunding])
+    }
+  }
+
+  private def getLiquidityRate(nodeId: PublicKey, requestedAmount: Satoshi)(implicit timeout: Timeout): Future[LiquidityAds.FundingRate] = {
+    appKit.switchboard.toTyped.ask[Peer.PeerInfoResponse] { replyTo =>
+      Switchboard.GetPeerInfo(replyTo, nodeId)
+    }.map {
+      case p: PeerInfo => p.fundingRates_opt.flatMap(_.findRate(requestedAmount)) match {
+        case Some(fundingRate) => fundingRate
+        case None => throw new RuntimeException(s"peer $nodeId doesn't support funding $requestedAmount, please check their funding rates")
+      }
+      case _: Peer.PeerNotFound => throw new RuntimeException(s"peer $nodeId not connected")
+    }
+  }
+
   override def getInfo()(implicit timeout: Timeout): Future[GetInfoResponse] = Future.successful(
     GetInfoResponse(
       version = Kit.getVersionLong,

eclair-core/src/main/scala/fr/acinq/eclair/channel/ChannelData.scala

@@ -261,8 +261,8 @@ sealed trait ChannelFundingCommand extends Command {
 }
 case class SpliceIn(additionalLocalFunding: Satoshi, pushAmount: MilliSatoshi = 0 msat)
 case class SpliceOut(amount: Satoshi, scriptPubKey: ByteVector)
-final case class CMD_SPLICE(replyTo: akka.actor.typed.ActorRef[CommandResponse[ChannelFundingCommand]], spliceIn_opt: Option[SpliceIn], spliceOut_opt: Option[SpliceOut], requestFunding_opt: Option[LiquidityAds.RequestFunding], channelType_opt:Option[ChannelType]) extends ChannelFundingCommand {
-  require(spliceIn_opt.isDefined || spliceOut_opt.isDefined, "there must be a splice-in or a splice-out")
+final case class CMD_SPLICE(replyTo: akka.actor.typed.ActorRef[CommandResponse[ChannelFundingCommand]], spliceIn_opt: Option[SpliceIn], spliceOut_opt: Option[SpliceOut], requestFunding_opt: Option[LiquidityAds.RequestFunding], channelType_opt: Option[ChannelType]) extends ChannelFundingCommand {
+  require(spliceIn_opt.isDefined || spliceOut_opt.isDefined || requestFunding_opt.isDefined, "there must be a splice-in, a splice-out or a liquidity purchase")
   val additionalLocalFunding: Satoshi = spliceIn_opt.map(_.additionalLocalFunding).getOrElse(0 sat)
   val pushAmount: MilliSatoshi = spliceIn_opt.map(_.pushAmount).getOrElse(0 msat)
   val spliceOutputs: List[TxOut] = spliceOut_opt.toList.map(s => TxOut(s.amount, s.scriptPubKey))

eclair-core/src/main/scala/fr/acinq/eclair/io/OpenChannelInterceptor.scala

@@ -187,14 +187,14 @@ private class OpenChannelInterceptor(peer: ActorRef[Any],
     nodeParams.pluginOpenChannelInterceptor match {
       case Some(plugin) => queryPlugin(plugin, request, localParams, ChannelConfig.standard, channelType)
       case None =>
+        val addFunding_opt = request.open.fold(_ => None, _.requestFunding_opt).map(requestFunding => LiquidityAds.AddFunding(requestFunding.requestedAmount, nodeParams.liquidityAdsConfig.rates_opt))
         request.open.fold(_ => None, _.requestFunding_opt) match {
-          case Some(requestFunding) if Features.canUseFeature(request.localFeatures, request.remoteFeatures, Features.OnTheFlyFunding) && localParams.paysCommitTxFees =>
-            val addFunding = LiquidityAds.AddFunding(requestFunding.requestedAmount, nodeParams.liquidityAdsConfig.rates_opt)
-            val accept = SpawnChannelNonInitiator(request.open, ChannelConfig.standard, channelType, Some(addFunding), localParams, request.peerConnection.toClassic)
+          case Some(_) if Features.canUseFeature(request.localFeatures, request.remoteFeatures, Features.OnTheFlyFunding) && localParams.paysCommitTxFees =>
+            val accept = SpawnChannelNonInitiator(request.open, ChannelConfig.standard, channelType, addFunding_opt, localParams, request.peerConnection.toClassic)
             checkNoExistingChannel(request, accept)
           case _ =>
-            // We don't honor liquidity ads for new channels: node operators should use plugin for that.
-            peer ! SpawnChannelNonInitiator(request.open, ChannelConfig.standard, channelType, addFunding_opt = None, localParams, request.peerConnection.toClassic)
+            // TODO: we must change the utxo locking behavior before releasing that change to protect against liquidity griefing.
+            peer ! SpawnChannelNonInitiator(request.open, ChannelConfig.standard, channelType, addFunding_opt, localParams, request.peerConnection.toClassic)
             waitForRequest()
         }
     }