Announce liquidity ads

Configure liquidity ads and include it in our `node_announcement`.

Author: t-bast

docs/release-notes/eclair-vnext.md

@@ -55,6 +55,7 @@ This feature leaks a bit of information about the balance when the channel is al
 ### API changes
 
 - `bumpforceclose` can be used to make a force-close confirm faster, by spending the anchor output (#2743)
+- `nodes` allows filtering nodes that offer liquidity ads (#2550)
 
 ### Miscellaneous improvements and bug fixes
 

eclair-core/src/main/resources/reference.conf

@@ -533,6 +533,14 @@ eclair {
     enabled = true // enable automatic purges of expired invoices from the database
     interval = 24 hours // interval between expired invoice purges
   }
+
+  // Liquidity Ads allow remote nodes to pay us to provide them with inbound liquidity.
+  liquidity-ads {
+    enabled = false // set this field to true if you want to sell your unused on-chain liquidity
+    fee-base-satoshis = 1000 // flat fee that we will receive every time we accept a lease request
+    fee-basis-points = 500 // 5% of the liquidity we will provide
+    max-duration-blocks = 4032 // ~1 month
+  }
 }
 
 akka {

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

@@ -86,7 +86,8 @@ case class NodeParams(nodeKeyManager: NodeKeyManager,
                       blockchainWatchdogThreshold: Int,
                       blockchainWatchdogSources: Seq[String],
                       onionMessageConfig: OnionMessageConfig,
-                      purgeInvoicesInterval: Option[FiniteDuration]) {
+                      purgeInvoicesInterval: Option[FiniteDuration],
+                      liquidityAdsConfig_opt: Option[LiquidityAds.Config]) {
   val privateKey: Crypto.PrivateKey = nodeKeyManager.nodeKey.privateKey
 
   val nodeId: PublicKey = nodeKeyManager.nodeId
@@ -97,6 +98,8 @@ case class NodeParams(nodeKeyManager: NodeKeyManager,
 
   val pluginOpenChannelInterceptor: Option[InterceptOpenChannelPlugin] = pluginParams.collectFirst { case p: InterceptOpenChannelPlugin => p }
 
+  val liquidityRates_opt: Option[LiquidityAds.LeaseRates] = liquidityAdsConfig_opt.map(_.leaseRates(relayParams.defaultFees(announceChannel = true)))
+
   def currentBlockHeight: BlockHeight = BlockHeight(blockHeight.get)
 
   def currentFeerates: FeeratesPerKw = feerates.get()
@@ -604,7 +607,16 @@ object NodeParams extends Logging {
         timeout = FiniteDuration(config.getDuration("onion-messages.reply-timeout").getSeconds, TimeUnit.SECONDS),
         maxAttempts = config.getInt("onion-messages.max-attempts"),
       ),
-      purgeInvoicesInterval = purgeInvoicesInterval
+      purgeInvoicesInterval = purgeInvoicesInterval,
+      liquidityAdsConfig_opt = if (config.getBoolean("liquidity-ads.enabled")) {
+        Some(LiquidityAds.Config(
+          feeBase = Satoshi(config.getInt("liquidity-ads.fee-base-satoshis")),
+          feeProportional = config.getInt("liquidity-ads.fee-basis-points"),
+          maxLeaseDuration = config.getInt("liquidity-ads.max-duration-blocks"),
+        ))
+      } else {
+        None
+      },
     )
   }
 }

eclair-core/src/main/scala/fr/acinq/eclair/router/Announcements.scala

@@ -68,7 +68,7 @@ object Announcements {
     )
   }
 
-  def makeNodeAnnouncement(nodeSecret: PrivateKey, alias: String, color: Color, nodeAddresses: List[NodeAddress], features: Features[NodeFeature], timestamp: TimestampSecond = TimestampSecond.now()): NodeAnnouncement = {
+  def makeNodeAnnouncement(nodeSecret: PrivateKey, alias: String, color: Color, nodeAddresses: List[NodeAddress], features: Features[NodeFeature], liquidityRates_opt: Option[LiquidityAds.LeaseRates], timestamp: TimestampSecond = TimestampSecond.now()): NodeAnnouncement = {
     require(alias.length <= 32)
     // sort addresses by ascending address descriptor type; do not reorder addresses within the same descriptor type
     val sortedAddresses = nodeAddresses.map {
@@ -78,7 +78,10 @@ object Announcements {
       case address@(_: Tor3) => (4, address)
       case address@(_: DnsHostname) => (5, address)
     }.sortBy(_._1).map(_._2)
-    val witness = nodeAnnouncementWitnessEncode(timestamp, nodeSecret.publicKey, color, alias, features.unscoped(), sortedAddresses, TlvStream.empty)
+    val tlvs: Set[NodeAnnouncementTlv] = Set(
+      liquidityRates_opt.map(NodeAnnouncementTlv.LiquidityAdsTlv),
+    ).flatten
+    val witness = nodeAnnouncementWitnessEncode(timestamp, nodeSecret.publicKey, color, alias, features.unscoped(), sortedAddresses, TlvStream(tlvs))
     val sig = Crypto.sign(witness, nodeSecret)
     NodeAnnouncement(
       signature = sig,
@@ -87,7 +90,8 @@ object Announcements {
       rgbColor = color,
       alias = alias,
       features = features.unscoped(),
-      addresses = sortedAddresses
+      addresses = sortedAddresses,
+      tlvStream = TlvStream(tlvs)
     )
   }
 

eclair-core/src/main/scala/fr/acinq/eclair/router/Router.scala

@@ -99,7 +99,7 @@ class Router(val nodeParams: NodeParams, watcher: typed.ActorRef[ZmqWatcher.Comm
 
     // on restart we update our node announcement
     // note that if we don't currently have public channels, this will be ignored
-    val nodeAnn = Announcements.makeNodeAnnouncement(nodeParams.privateKey, nodeParams.alias, nodeParams.color, nodeParams.publicAddresses, nodeParams.features.nodeAnnouncementFeatures())
+    val nodeAnn = Announcements.makeNodeAnnouncement(nodeParams.privateKey, nodeParams.alias, nodeParams.color, nodeParams.publicAddresses, nodeParams.features.nodeAnnouncementFeatures(), nodeParams.liquidityRates_opt)
     self ! nodeAnn
 
     log.info("initialization completed, ready to process messages")

eclair-core/src/main/scala/fr/acinq/eclair/router/Validation.scala

@@ -209,7 +209,7 @@ object Validation {
     // in case this was our first local channel, we make a node announcement
     if (!d.nodes.contains(nodeParams.nodeId) && isRelatedTo(ann, nodeParams.nodeId)) {
       log.info("first local channel validated, announcing local node")
-      val nodeAnn = Announcements.makeNodeAnnouncement(nodeParams.privateKey, nodeParams.alias, nodeParams.color, nodeParams.publicAddresses, nodeParams.features.nodeAnnouncementFeatures())
+      val nodeAnn = Announcements.makeNodeAnnouncement(nodeParams.privateKey, nodeParams.alias, nodeParams.color, nodeParams.publicAddresses, nodeParams.features.nodeAnnouncementFeatures(), nodeParams.liquidityRates_opt)
       handleNodeAnnouncement(d1, nodeParams.db.network, Set(LocalGossip), nodeAnn)
     } else d1
   }

eclair-core/src/main/scala/fr/acinq/eclair/wire/protocol/LiquidityAds.scala

@@ -23,7 +23,7 @@ import fr.acinq.eclair.payment.relay.Relayer.RelayFees
 import fr.acinq.eclair.transactions.Transactions
 import fr.acinq.eclair.wire.protocol.CommonCodecs.{blockHeight, millisatoshi32, publicKey, satoshi32}
 import fr.acinq.eclair.wire.protocol.TlvCodecs.tmillisatoshi32
-import fr.acinq.eclair.{BlockHeight, CltvExpiryDelta, MilliSatoshi, ToMilliSatoshiConversion}
+import fr.acinq.eclair.{BlockHeight, MilliSatoshi, ToMilliSatoshiConversion}
 import scodec.Codec
 import scodec.bits.ByteVector
 import scodec.codecs._
@@ -41,8 +41,13 @@ import java.nio.charset.StandardCharsets
  */
 object LiquidityAds {
 
-  /** Liquidity leases are valid for a fixed duration, after which they must be renewed. */
-  val LeaseDuration = CltvExpiryDelta(1008) // 1 week
+  case class Config(feeBase: Satoshi, feeProportional: Int, maxLeaseDuration: Int) {
+    def leaseRates(relayFees: RelayFees): LeaseRates = {
+      // We make the remote node pay for one p2wpkh input and one p2wpkh output.
+      // If we need more inputs, we will pay the fees for those additional inputs ourselves.
+      LeaseRates(Transactions.claimP2WPKHOutputWeight, feeProportional, (relayFees.feeProportionalMillionths / 100).toInt, feeBase, relayFees.feeBase)
+    }
+  }
 
   /**
    * Liquidity is leased using the following rates:
@@ -70,12 +75,6 @@ object LiquidityAds {
     }
   }
 
-  object LeaseRates {
-    def apply(fundingWeight: Int, leaseFeeBase: Satoshi, leaseFeeProportional: Int, relayFees: RelayFees): LeaseRates = {
-      LeaseRates(fundingWeight, leaseFeeProportional, (relayFees.feeProportionalMillionths / 100).toInt, leaseFeeBase, relayFees.feeBase)
-    }
-  }
-
   val leaseRatesCodec: Codec[LeaseRates] = (
     ("funding_weight" | uint16) ::
       ("lease_fee_basis" | uint16) ::

eclair-core/src/test/scala/fr/acinq/eclair/TestConstants.scala

@@ -30,7 +30,7 @@ import fr.acinq.eclair.payment.relay.Relayer.{AsyncPaymentsParams, RelayFees, Re
 import fr.acinq.eclair.router.Graph.{MessagePath, WeightRatios}
 import fr.acinq.eclair.router.PathFindingExperimentConf
 import fr.acinq.eclair.router.Router.{MessageRouteParams, MultiPartParams, PathFindingConf, RouterConf, SearchBoundaries}
-import fr.acinq.eclair.wire.protocol.{Color, EncodingType, NodeAddress, OnionRoutingPacket}
+import fr.acinq.eclair.wire.protocol.{Color, EncodingType, LiquidityAds, NodeAddress, OnionRoutingPacket}
 import org.scalatest.Tag
 import scodec.bits.{ByteVector, HexStringSyntax}
 
@@ -51,6 +51,7 @@ object TestConstants {
   val feeratePerKw: FeeratePerKw = FeeratePerKw(10_000 sat)
   val anchorOutputsFeeratePerKw: FeeratePerKw = FeeratePerKw(2_500 sat)
   val emptyOnionPacket: OnionRoutingPacket = OnionRoutingPacket(0, ByteVector.fill(33)(0), ByteVector.fill(1300)(0), ByteVector32.Zeroes)
+  val defaultLiquidityRates: LiquidityAds.LeaseRates = LiquidityAds.LeaseRates(500, 100, 10, 100 sat, 200 msat)
 
   case object TestFeature extends Feature with InitFeature with NodeFeature {
     val rfcName = "test_feature"
@@ -224,7 +225,8 @@ object TestConstants {
         timeout = 200 millis,
         maxAttempts = 2,
       ),
-      purgeInvoicesInterval = None
+      purgeInvoicesInterval = None,
+      liquidityAdsConfig_opt = None,
     )
 
     def channelParams: LocalParams = OpenChannelInterceptor.makeChannelParams(
@@ -389,7 +391,8 @@ object TestConstants {
         timeout = 100 millis,
         maxAttempts = 2,
       ),
-      purgeInvoicesInterval = None
+      purgeInvoicesInterval = None,
+      liquidityAdsConfig_opt = None,
     )
 
     def channelParams: LocalParams = OpenChannelInterceptor.makeChannelParams(

eclair-core/src/test/scala/fr/acinq/eclair/db/NetworkDbSpec.scala

@@ -29,7 +29,7 @@ import fr.acinq.eclair.router.Announcements
 import fr.acinq.eclair.router.Router.PublicChannel
 import fr.acinq.eclair.wire.protocol.LightningMessageCodecs.{channelAnnouncementCodec, channelUpdateCodec, nodeAnnouncementCodec}
 import fr.acinq.eclair.wire.protocol._
-import fr.acinq.eclair.{CltvExpiryDelta, Features, MilliSatoshiLong, RealShortChannelId, ShortChannelId, TestDatabases, randomBytes32, randomKey}
+import fr.acinq.eclair.{CltvExpiryDelta, Features, MilliSatoshiLong, RealShortChannelId, ShortChannelId, TestConstants, TestDatabases, randomBytes32, randomKey}
 import org.scalatest.funsuite.AnyFunSuite
 import scodec.bits.HexStringSyntax
 
@@ -56,11 +56,11 @@ class NetworkDbSpec extends AnyFunSuite {
     forAllDbs { dbs =>
       val db = dbs.network
 
-      val node_1 = Announcements.makeNodeAnnouncement(randomKey(), "node-alice", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features.empty)
-      val node_2 = Announcements.makeNodeAnnouncement(randomKey(), "node-bob", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features(VariableLengthOnion -> Optional))
-      val node_3 = Announcements.makeNodeAnnouncement(randomKey(), "node-charlie", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features(VariableLengthOnion -> Optional))
-      val node_4 = Announcements.makeNodeAnnouncement(randomKey(), "node-eve", Color(100.toByte, 200.toByte, 300.toByte), Tor3("of7husrflx7sforh3fw6yqlpwstee3wg5imvvmkp4bz6rbjxtg5nljad", 42000) :: Nil, Features.empty)
-      val node_5 = Announcements.makeNodeAnnouncement(randomKey(), "node-frank", Color(100.toByte, 200.toByte, 300.toByte), DnsHostname("eclair.invalid", 42000) :: Nil, Features.empty)
+      val node_1 = Announcements.makeNodeAnnouncement(randomKey(), "node-alice", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features.empty, None)
+      val node_2 = Announcements.makeNodeAnnouncement(randomKey(), "node-bob", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features(VariableLengthOnion -> Optional), Some(TestConstants.defaultLiquidityRates))
+      val node_3 = Announcements.makeNodeAnnouncement(randomKey(), "node-charlie", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features(VariableLengthOnion -> Optional), None)
+      val node_4 = Announcements.makeNodeAnnouncement(randomKey(), "node-eve", Color(100.toByte, 200.toByte, 300.toByte), Tor3("of7husrflx7sforh3fw6yqlpwstee3wg5imvvmkp4bz6rbjxtg5nljad", 42000) :: Nil, Features.empty, None)
+      val node_5 = Announcements.makeNodeAnnouncement(randomKey(), "node-frank", Color(100.toByte, 200.toByte, 300.toByte), DnsHostname("eclair.invalid", 42000) :: Nil, Features.empty, None)
 
       assert(db.listNodes().toSet == Set.empty)
       db.addNode(node_1)
@@ -401,7 +401,7 @@ object NetworkDbSpec {
                              update_2_data_opt: Option[Array[Byte]])
 
   val nodeTestCases: Seq[NodeTestCase] = for (_ <- 0 until 10) yield {
-    val node = Announcements.makeNodeAnnouncement(randomKey(), "node-alice", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features.empty)
+    val node = Announcements.makeNodeAnnouncement(randomKey(), "node-alice", Color(100.toByte, 200.toByte, 300.toByte), NodeAddress.fromParts("192.168.1.42", 42000).get :: Nil, Features.empty, None)
     val data = nodeAnnouncementCodec.encode(node).require.toByteArray
     NodeTestCase(
       nodeId = node.nodeId,

eclair-core/src/test/scala/fr/acinq/eclair/db/PgUtilsSpec.scala

@@ -170,9 +170,9 @@ class PgUtilsSpec extends TestKitBaseClass with AnyFunSuiteLike with Eventually
       val db = Databases.postgres(baseConfig, UUID.randomUUID(), datadir, None, LockFailureHandler.logAndThrow)
       db.channels.addOrUpdateChannel(ChannelCodecsSpec.normal)
       db.channels.updateChannelMeta(ChannelCodecsSpec.normal.channelId, ChannelEvent.EventType.Created)
-      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-A", Color(50, 99, -80), Nil, Features.empty, TimestampSecond.now() - 45.days))
-      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-B", Color(50, 99, -80), Nil, Features.empty, TimestampSecond.now() - 3.days))
-      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-C", Color(50, 99, -80), Nil, Features.empty, TimestampSecond.now() - 7.minutes))
+      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-A", Color(50, 99, -80), Nil, Features.empty, None, TimestampSecond.now() - 45.days))
+      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-B", Color(50, 99, -80), Nil, Features.empty, None, TimestampSecond.now() - 3.days))
+      db.network.addNode(Announcements.makeNodeAnnouncement(randomKey(), "node-C", Color(50, 99, -80), Nil, Features.empty, None, TimestampSecond.now() - 7.minutes))
       db.audit.add(ChannelPaymentRelayed(421 msat, 400 msat, randomBytes32(), randomBytes32(), randomBytes32(), TimestampMilli.now() - 5.seconds, TimestampMilli.now() - 3.seconds))
       db.dataSource.close()
     }