Configure dust in flight threshold

docs/release-notes/eclair-vnext.md

@@ -53,6 +53,23 @@ You **MUST** ensure you have some utxos available in your Bitcoin Core wallet fo
 
 Do note that anchor outputs may still be unsafe in high-fee environments until the Bitcoin network provides support for [package relay](https://bitcoinops.org/en/topics/package-relay/).
 
+### Configurable dust tolerance
+
+Dust HTLCs are converted to miner fees when a channel is force-closed and these HTLCs are still pending.
+Node operators can now configure the maximum amount of dust HTLCs that can be pending in a channel by setting `eclair.on-chain-fees.feerate-tolerance.max-dust-htlc-exposure-satoshis` in their `eclair.conf`.
+
+Choosing the right value for your node involves trade-offs.
+The lower you set it, the more protection it will offer against malicious peers.
+But if it's too low, your node may reject some dust HTLCs that it would have otherwise relayed, which lowers the amount of relay fees you will be able to collect.
+
+Another related parameter has been added: `eclair.on-chain-fees.feerate-tolerance.close-on-update-fee-dust-exposure-overflow`.
+When this parameter is set to `true`, your node will automatically close channels when the amount of dust HTLCs overflows your configured limits.
+This gives you a better protection against malicious peers, but may end up closing channels with honest peers as well.
+This parameter is deactivated by default and unnecessary when using `option_anchors_zero_fee_htlc_tx`.
+
+Note that you can override these values for specific peers, thanks to the `eclair.on-chain-fees.override-feerate-tolerance` mechanism.
+You can for example set a high `eclair.on-chain-fees.feerate-tolerance.max-dust-htlc-exposure-satoshis` with peers that you trust.
+
 ### Path-finding improvements
 
 This release contains many improvements to path-finding and paves the way for future experimentation.

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

@@ -142,6 +142,13 @@ eclair {
       // when using anchor outputs, we only need to use a commitment feerate that allows the tx to propagate: we will use CPFP to speed up confirmation if needed.
       // the following value is the maximum feerate we'll use for our commit tx (in sat/byte)
       anchor-output-max-commit-feerate = 10
+      // dust htlcs cannot be claimed on-chain and will instead go to miners if the channel is force-closed
+      // a malicious peer may want to abuse that, so we limit the value of pending dust htlcs in a channel
+      // this value cannot be lowered too much if you plan to relay a lot of htlcs
+      max-dust-htlc-exposure-satoshis = 100000
+      // when we receive an UpdateFee, it could increase our dust exposure and overflow max-dust-htlc-exposure-satoshis
+      // this parameter should be set to true if you want to force-close the channel when that happens
+      close-on-update-fee-dust-exposure-overflow = false
     }
     override-feerate-tolerance = [ // optional per-node feerate tolerance
       #  {
@@ -150,6 +157,8 @@ eclair {
       #      ratio-low = 0.1
       #      ratio-high = 20.0
       #      anchor-output-max-commit-feerate = 10
+      #      max-dust-htlc-exposure-satoshis = 25000
+      #      close-on-update-fee-dust-exposure-overflow = true
       #    }
       #  }
     ]

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

@@ -383,14 +383,18 @@ object NodeParams extends Logging {
         defaultFeerateTolerance = FeerateTolerance(
           config.getDouble("on-chain-fees.feerate-tolerance.ratio-low"),
           config.getDouble("on-chain-fees.feerate-tolerance.ratio-high"),
-          FeeratePerKw(FeeratePerByte(Satoshi(config.getLong("on-chain-fees.feerate-tolerance.anchor-output-max-commit-feerate"))))
+          FeeratePerKw(FeeratePerByte(Satoshi(config.getLong("on-chain-fees.feerate-tolerance.anchor-output-max-commit-feerate")))),
+          Satoshi(config.getLong("on-chain-fees.feerate-tolerance.max-dust-htlc-exposure-satoshis")),
+          config.getBoolean("on-chain-fees.feerate-tolerance.close-on-update-fee-dust-exposure-overflow")
         ),
         perNodeFeerateTolerance = config.getConfigList("on-chain-fees.override-feerate-tolerance").asScala.map { e =>
           val nodeId = PublicKey(ByteVector.fromValidHex(e.getString("nodeid")))
           val tolerance = FeerateTolerance(
             e.getDouble("feerate-tolerance.ratio-low"),
             e.getDouble("feerate-tolerance.ratio-high"),
-            FeeratePerKw(FeeratePerByte(Satoshi(e.getLong("feerate-tolerance.anchor-output-max-commit-feerate"))))
+            FeeratePerKw(FeeratePerByte(Satoshi(e.getLong("feerate-tolerance.anchor-output-max-commit-feerate")))),
+            Satoshi(e.getLong("feerate-tolerance.max-dust-htlc-exposure-satoshis")),
+            e.getBoolean("feerate-tolerance.close-on-update-fee-dust-exposure-overflow")
           )
           nodeId -> tolerance
         }.toMap

eclair-core/src/main/scala/fr/acinq/eclair/blockchain/fee/FeeEstimator.scala

@@ -32,7 +32,7 @@ trait FeeEstimator {
 
 case class FeeTargets(fundingBlockTarget: Int, commitmentBlockTarget: Int, mutualCloseBlockTarget: Int, claimMainBlockTarget: Int)
 
-case class FeerateTolerance(ratioLow: Double, ratioHigh: Double, anchorOutputMaxCommitFeerate: FeeratePerKw) {
+case class FeerateTolerance(ratioLow: Double, ratioHigh: Double, anchorOutputMaxCommitFeerate: FeeratePerKw, maxDustHtlcExposure: Satoshi, closeOnUpdateFeeDustExposureOverflow: Boolean) {
   /**
    * @param channelType     channel type
    * @param networkFeerate  reference fee rate (value we estimate from our view of the network)

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

@@ -30,6 +30,7 @@ import fr.acinq.eclair.blockchain._
 import fr.acinq.eclair.blockchain.bitcoind.ZmqWatcher
 import fr.acinq.eclair.blockchain.bitcoind.ZmqWatcher._
 import fr.acinq.eclair.blockchain.bitcoind.rpc.BitcoinCoreClient
+import fr.acinq.eclair.channel.Commitments.PostRevocationAction
 import fr.acinq.eclair.channel.Helpers.{Closing, Funding, getRelayFees}
 import fr.acinq.eclair.channel.Monitoring.Metrics.ProcessMessage
 import fr.acinq.eclair.channel.Monitoring.{Metrics, Tags}
@@ -41,6 +42,7 @@ import fr.acinq.eclair.db.DbEventHandler.ChannelEvent.EventType
 import fr.acinq.eclair.db.PendingCommandsDb
 import fr.acinq.eclair.io.Peer
 import fr.acinq.eclair.payment.PaymentSettlingOnChain
+import fr.acinq.eclair.payment.relay.Relayer
 import fr.acinq.eclair.router.Announcements
 import fr.acinq.eclair.transactions.Transactions.{ClosingTx, TxOwner}
 import fr.acinq.eclair.transactions._
@@ -769,7 +771,7 @@ class Channel(val nodeParams: NodeParams, val wallet: OnChainChannelFunder, remo
       }
 
     case Event(c: CMD_UPDATE_FEE, d: DATA_NORMAL) =>
-      Commitments.sendFee(d.commitments, c) match {
+      Commitments.sendFee(d.commitments, c, nodeParams.onChainFeeConf) match {
         case Right((commitments1, fee)) =>
           if (c.commit) self ! CMD_SIGN()
           context.system.eventStream.publish(AvailableBalanceChanged(self, d.channelId, d.shortChannelId, commitments1))
@@ -839,19 +841,28 @@ class Channel(val nodeParams: NodeParams, val wallet: OnChainChannelFunder, remo
     case Event(revocation: RevokeAndAck, d: DATA_NORMAL) =>
       // we received a revocation because we sent a signature
       // => all our changes have been acked
-      Commitments.receiveRevocation(d.commitments, revocation) match {
-        case Right((commitments1, forwards)) =>
+      Commitments.receiveRevocation(d.commitments, revocation, nodeParams.onChainFeeConf.feerateToleranceFor(remoteNodeId).maxDustHtlcExposure) match {
+        case Right((commitments1, actions)) =>
           cancelTimer(RevocationTimeout.toString)
           log.debug("received a new rev, spec:\n{}", Commitments.specs2String(commitments1))
-          forwards.foreach {
-            case Right(forwardAdd) =>
-              log.debug("forwarding {} to relayer", forwardAdd)
-              relayer ! forwardAdd
-            case Left(result) =>
+          actions.foreach {
+            case PostRevocationAction.RelayHtlc(add) =>
+              log.debug("forwarding incoming htlc {} to relayer", add)
+              relayer ! Relayer.RelayForward(add)
+            case PostRevocationAction.RejectHtlc(add) =>
+              log.debug("rejecting incoming htlc {}", add)
+              // NB: we don't set commit = true, we will sign all updates at once afterwards.
+              self ! CMD_FAIL_HTLC(add.id, Right(TemporaryChannelFailure(d.channelUpdate)))
+            case PostRevocationAction.RelayFailure(result) =>
               log.debug("forwarding {} to relayer", result)
               relayer ! result
           }
-          if (Commitments.localHasChanges(commitments1) && d.commitments.remoteNextCommitInfo.left.map(_.reSignAsap) == Left(true)) {
+          val signAsap = actions.exists {
+            case _: PostRevocationAction.RejectHtlc => true
+            case _: PostRevocationAction.RelayHtlc => false
+            case _: PostRevocationAction.RelayFailure => false
+          } || (Commitments.localHasChanges(commitments1) && d.commitments.remoteNextCommitInfo.left.map(_.reSignAsap) == Left(true))
+          if (signAsap) {
             self ! CMD_SIGN()
           }
           if (d.remoteShutdown.isDefined && !Commitments.localHasUnsignedOutgoingHtlcs(commitments1)) {
@@ -1127,7 +1138,7 @@ class Channel(val nodeParams: NodeParams, val wallet: OnChainChannelFunder, remo
       }
 
     case Event(c: CMD_UPDATE_FEE, d: DATA_SHUTDOWN) =>
-      Commitments.sendFee(d.commitments, c) match {
+      Commitments.sendFee(d.commitments, c, nodeParams.onChainFeeConf) match {
         case Right((commitments1, fee)) =>
           if (c.commit) self ! CMD_SIGN()
           handleCommandSuccess(c, d.copy(commitments = commitments1)) sending fee
@@ -1199,18 +1210,22 @@ class Channel(val nodeParams: NodeParams, val wallet: OnChainChannelFunder, remo
     case Event(revocation: RevokeAndAck, d@DATA_SHUTDOWN(commitments, localShutdown, remoteShutdown, closingFeerates)) =>
       // we received a revocation because we sent a signature
       // => all our changes have been acked including the shutdown message
-      Commitments.receiveRevocation(commitments, revocation) match {
-        case Right((commitments1, forwards)) =>
+      Commitments.receiveRevocation(commitments, revocation, nodeParams.onChainFeeConf.feerateToleranceFor(remoteNodeId).maxDustHtlcExposure) match {
+        case Right((commitments1, actions)) =>
           cancelTimer(RevocationTimeout.toString)
           log.debug("received a new rev, spec:\n{}", Commitments.specs2String(commitments1))
-          forwards.foreach {
-            case Right(forwardAdd) =>
+          actions.foreach {
+            case PostRevocationAction.RelayHtlc(add) =>
               // BOLT 2: A sending node SHOULD fail to route any HTLC added after it sent shutdown.
-              log.debug("closing in progress: failing {}", forwardAdd.add)
-              self ! CMD_FAIL_HTLC(forwardAdd.add.id, Right(PermanentChannelFailure), commit = true)
-            case Left(forward) =>
-              log.debug("forwarding {} to relayer", forward)
-              relayer ! forward
+              log.debug("closing in progress: failing {}", add)
+              self ! CMD_FAIL_HTLC(add.id, Right(PermanentChannelFailure))
+            case PostRevocationAction.RejectHtlc(add) =>
+              // BOLT 2: A sending node SHOULD fail to route any HTLC added after it sent shutdown.
+              log.debug("closing in progress: rejecting {}", add)
+              self ! CMD_FAIL_HTLC(add.id, Right(PermanentChannelFailure))
+            case PostRevocationAction.RelayFailure(result) =>
+              log.debug("forwarding {} to relayer", result)
+              relayer ! result
           }
           if (commitments1.hasNoPendingHtlcsOrFeeUpdate) {
             log.debug("switching to NEGOTIATING spec:\n{}", Commitments.specs2String(commitments1))
@@ -1223,7 +1238,12 @@ class Channel(val nodeParams: NodeParams, val wallet: OnChainChannelFunder, remo
               goto(NEGOTIATING) using DATA_NEGOTIATING(commitments1, localShutdown, remoteShutdown, closingTxProposed = List(List()), bestUnpublishedClosingTx_opt = None) storing()
             }
           } else {
-            if (Commitments.localHasChanges(commitments1) && d.commitments.remoteNextCommitInfo.left.map(_.reSignAsap) == Left(true)) {
+            val signAsap = actions.exists {
+              case _: PostRevocationAction.RelayHtlc => true
+              case _: PostRevocationAction.RejectHtlc => true
+              case _: PostRevocationAction.RelayFailure => false
+            } || (Commitments.localHasChanges(commitments1) && d.commitments.remoteNextCommitInfo.left.map(_.reSignAsap) == Left(true))
+            if (signAsap) {
               self ! CMD_SIGN()
             }
             stay() using d.copy(commitments = commitments1) storing()

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

@@ -78,6 +78,7 @@ case class ExpiryTooBig                            (override val channelId: Byte
 case class HtlcValueTooSmall                       (override val channelId: ByteVector32, minimum: MilliSatoshi, actual: MilliSatoshi) extends ChannelException(channelId, s"htlc value too small: minimum=$minimum actual=$actual")
 case class HtlcValueTooHighInFlight                (override val channelId: ByteVector32, maximum: UInt64, actual: MilliSatoshi) extends ChannelException(channelId, s"in-flight htlcs hold too much value: maximum=$maximum actual=$actual")
 case class TooManyAcceptedHtlcs                    (override val channelId: ByteVector32, maximum: Long) extends ChannelException(channelId, s"too many accepted htlcs: maximum=$maximum")
+case class DustHtlcExposureTooHighInFlight         (override val channelId: ByteVector32, maximum: Satoshi, actual: MilliSatoshi) extends ChannelException(channelId, s"dust htlcs hold too much value: maximum=$maximum actual=$actual")
 case class InsufficientFunds                       (override val channelId: ByteVector32, amount: MilliSatoshi, missing: Satoshi, reserve: Satoshi, fees: Satoshi) extends ChannelException(channelId, s"insufficient funds: missing=$missing reserve=$reserve fees=$fees")
 case class RemoteCannotAffordFeesForNewHtlc        (override val channelId: ByteVector32, amount: MilliSatoshi, missing: Satoshi, reserve: Satoshi, fees: Satoshi) extends ChannelException(channelId, s"remote can't afford increased commit tx fees once new HTLC is added: missing=$missing reserve=$reserve fees=$fees")
 case class InvalidHtlcPreimage                     (override val channelId: ByteVector32, id: Long) extends ChannelException(channelId, s"invalid htlc preimage for htlc id=$id")