Split MPP by maximizing expected delivered amount

As suggested by @renepickhardt in #2785

Author: thomash-acinq

docs/release-notes/eclair-vnext.md

@@ -52,6 +52,12 @@ eclair.channel.channel-update {
 
 This feature leaks a bit of information about the balance when the channel is almost empty, if you do not wish to use it, set `eclair.channel.channel-update.balance-thresholds = []`.
 
+### 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`).
+These splitting strategies are now specified using `mpp.splitting-strategy = "full-capacity"` or `mpp.splitting-strategy = "randomize"`.
+In addition, a new strategy is available: `mpp.splitting-strategy = "max-expected-amount"` will send through each route the amount that maximizes the expected delivered amount (amount sent times success probability).
+
 ### API changes
 
 - `bumpforceclose` can be used to make a force-close confirm faster, by spending the anchor output (#2743)

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

@@ -394,6 +394,7 @@ eclair {
         mpp {
           min-amount-satoshis = 15000 // minimum amount sent via partial HTLCs
           max-parts = 5 // maximum number of HTLCs sent per payment: increasing this value will impact performance
+          splitting-strategy = "randomize" // Can be either "full-capacity", "randomize" or "max-expected-amount"
         }
       }
 

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

@@ -428,7 +428,12 @@ object NodeParams extends Logging {
       },
       mpp = MultiPartParams(
         Satoshi(config.getLong("mpp.min-amount-satoshis")).toMilliSatoshi,
-        config.getInt("mpp.max-parts")),
+        config.getInt("mpp.max-parts"),
+        config.getString("mpp.splitting-strategy") match {
+          case "full-capacity" => MultiPartParams.FullCapacity
+          case "randomize" => MultiPartParams.Randomize
+          case "max-expected-amount" => MultiPartParams.MaxExpectedAmount
+        }),
       experimentName = name,
       experimentPercentage = config.getInt("percentage"))
 

eclair-core/src/main/scala/fr/acinq/eclair/remote/EclairInternalsSerializer.scala

@@ -72,7 +72,17 @@ object EclairInternalsSerializer {
 
   val multiPartParamsCodec: Codec[MultiPartParams] = (
     ("minPartAmount" | millisatoshi) ::
-      ("maxParts" | int32)).as[MultiPartParams]
+      ("maxParts" | int32) ::
+      ("splittingStrategy" | int8.narrow[MultiPartParams.SplittingStrategy]({
+        case 0 => Attempt.successful(MultiPartParams.FullCapacity)
+        case 1 => Attempt.successful(MultiPartParams.Randomize)
+        case 2 => Attempt.successful(MultiPartParams.MaxExpectedAmount)
+        case n => Attempt.failure(Err(s"Invalid value $n"))
+      }, {
+        case MultiPartParams.FullCapacity => 0
+        case MultiPartParams.Randomize => 1
+        case MultiPartParams.MaxExpectedAmount => 2
+      }))).as[MultiPartParams]
 
   val pathFindingConfCodec: Codec[PathFindingConf] = (
     ("randomize" | bool(8)) ::

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

@@ -22,7 +22,6 @@ import com.softwaremill.quicklens.ModifyPimp
 import fr.acinq.bitcoin.scalacompat.Crypto.PublicKey
 import fr.acinq.eclair.Logs.LogCategory
 import fr.acinq.eclair._
-import fr.acinq.eclair.message.SendingMessage
 import fr.acinq.eclair.payment.send._
 import fr.acinq.eclair.router.Graph.GraphStructure.DirectedGraph.graphEdgeToHop
 import fr.acinq.eclair.router.Graph.GraphStructure.{DirectedGraph, GraphEdge}
@@ -420,7 +419,7 @@ object RouteCalculation {
       // We want to ensure that the set of routes we find have enough capacity to allow sending the total amount,
       // without excluding routes with small capacity when the total amount is small.
       val minPartAmount = routeParams.mpp.minPartAmount.max(amount / numRoutes).min(amount)
-      routeParams.copy(mpp = MultiPartParams(minPartAmount, numRoutes))
+      routeParams.copy(mpp = MultiPartParams(minPartAmount, numRoutes, routeParams.mpp.splittingStrategy))
     }
     findRouteInternal(g, localNodeId, targetNodeId, routeParams1.mpp.minPartAmount, maxFee, routeParams1.mpp.maxParts, extraEdges, ignoredEdges, ignoredVertices, routeParams1, currentBlockHeight) match {
       case Right(routes) =>
@@ -446,16 +445,16 @@ object RouteCalculation {
         // this route doesn't have enough capacity left: we remove it and continue.
         split(amount, paths, usedCapacity, routeParams, selectedRoutes)
       } else {
-        val route = if (routeParams.randomize) {
-          // randomly choose the amount to be between 20% and 100% of the available capacity.
-          val randomizedAmount = candidate.amount * ((20d + Random.nextInt(81)) / 100)
-          if (randomizedAmount < routeParams.mpp.minPartAmount) {
-            candidate.copy(amount = routeParams.mpp.minPartAmount.min(amount))
-          } else {
-            candidate.copy(amount = randomizedAmount.min(amount))
-          }
-        } else {
-          candidate.copy(amount = candidate.amount.min(amount))
+        val route = routeParams.mpp.splittingStrategy match {
+          case MultiPartParams.Randomize =>
+            // randomly choose the amount to be between 20% and 100% of the available capacity.
+            val randomizedAmount = candidate.amount * ((20d + Random.nextInt(81)) / 100)
+            candidate.copy(amount = randomizedAmount.max(routeParams.mpp.minPartAmount).min(amount))
+          case MultiPartParams.MaxExpectedAmount =>
+            val bestAmount = optimizeExpectedValue(current.path, candidate.amount, usedCapacity)
+            candidate.copy(amount = bestAmount.max(routeParams.mpp.minPartAmount).min(amount))
+          case MultiPartParams.FullCapacity =>
+            candidate.copy(amount = candidate.amount.min(amount))
         }
         updateUsedCapacity(route, usedCapacity)
         // NB: we re-enqueue the current path, it may still have capacity for a second HTLC.
@@ -464,6 +463,26 @@ object RouteCalculation {
     }
   }
 
+  private def optimizeExpectedValue(route: Seq[GraphEdge], capacity: MilliSatoshi, usedCapacity: mutable.Map[ShortChannelId, MilliSatoshi]): MilliSatoshi = {
+    // We search the maximum value of a polynomial between its two smallest roots (0 and the minimum channel capacity on the path).
+    // We use binary search to find where the derivative changes sign.
+    var low = 1L
+    var high = capacity.toLong
+    while (high - low > 1L) {
+      val mid = (high + low) / 2
+      val d = route.drop(1).foldLeft(1.0 / mid) { case (x, edge) =>
+        val availableCapacity = edge.capacity - usedCapacity.getOrElse(edge.desc.shortChannelId, 0 msat)
+        x - 1.0 / (availableCapacity.toLong - mid)
+      }
+      if (d > 0.0) {
+        low = mid
+      } else {
+        high = mid
+      }
+    }
+    MilliSatoshi(high)
+  }
+
   /** Compute the maximum amount that we can send through the given route. */
   private def computeRouteMaxAmount(route: Seq[GraphEdge], usedCapacity: mutable.Map[ShortChannelId, MilliSatoshi]): Route = {
     val firstHopMaxAmount = route.head.maxHtlcAmount(usedCapacity.getOrElse(route.head.desc.shortChannelId, 0 msat))

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

@@ -551,7 +551,20 @@ object Router {
     override def fee(amount: MilliSatoshi): MilliSatoshi = fee
   }
 
-  case class MultiPartParams(minPartAmount: MilliSatoshi, maxParts: Int)
+  object MultiPartParams {
+    sealed trait SplittingStrategy
+
+    /** Send the full capacity of the route */
+    object FullCapacity extends SplittingStrategy
+
+    /** Send between 20% and 100% of the capacity of the route */
+    object Randomize extends SplittingStrategy
+
+    /** Maximize the expected delivered amount */
+    object MaxExpectedAmount extends SplittingStrategy
+  }
+
+  case class MultiPartParams(minPartAmount: MilliSatoshi, maxParts: Int, splittingStrategy: MultiPartParams.SplittingStrategy)
 
   case class RouteParams(randomize: Boolean,
                          boundaries: SearchBoundaries,

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

@@ -204,6 +204,7 @@ object TestConstants {
           mpp = MultiPartParams(
             minPartAmount = 15000000 msat,
             maxParts = 10,
+            splittingStrategy = MultiPartParams.FullCapacity
           ),
           experimentName = "alice-test-experiment",
           experimentPercentage = 100))),
@@ -369,6 +370,7 @@ object TestConstants {
           mpp = MultiPartParams(
             minPartAmount = 15000000 msat,
             maxParts = 10,
+            splittingStrategy = MultiPartParams.FullCapacity
           ),
           experimentName = "bob-test-experiment",
           experimentPercentage = 100))),

eclair-core/src/test/scala/fr/acinq/eclair/integration/IntegrationSpec.scala

@@ -64,7 +64,7 @@ abstract class IntegrationSpec extends TestKitBaseClass with BitcoindService wit
       capacityFactor = 0,
       hopCost = RelayFees(0 msat, 0),
     )),
-    mpp = MultiPartParams(15000000 msat, 6),
+    mpp = MultiPartParams(15000000 msat, 6, MultiPartParams.FullCapacity),
     experimentName = "my-test-experiment",
     experimentPercentage = 100
   ).getDefaultRouteParams

eclair-core/src/test/scala/fr/acinq/eclair/payment/MultiPartPaymentLifecycleSpec.scala

@@ -723,7 +723,7 @@ object MultiPartPaymentLifecycleSpec {
       6,
       CltvExpiryDelta(1008)),
     Left(WeightRatios(1, 0, 0, 0, RelayFees(0 msat, 0))),
-    MultiPartParams(1000 msat, 5),
+    MultiPartParams(1000 msat, 5, MultiPartParams.FullCapacity),
     experimentName = "my-test-experiment",
     experimentPercentage = 100
   ).getDefaultRouteParams

eclair-core/src/test/scala/fr/acinq/eclair/payment/PaymentLifecycleSpec.scala

@@ -279,7 +279,7 @@ class PaymentLifecycleSpec extends BaseRouterSpec {
       randomize = false,
       boundaries = SearchBoundaries(100 msat, 0.0, 20, CltvExpiryDelta(2016)),
       Left(WeightRatios(1, 0, 0, 0, RelayFees(0 msat, 0))),
-      MultiPartParams(10_000 msat, 5),
+      MultiPartParams(10_000 msat, 5, MultiPartParams.FullCapacity),
       "my-test-experiment",
       experimentPercentage = 100
     ).getDefaultRouteParams