Update trampoline to match spec proposal

We update the trampoline feature to match the official specification
from lightning/bolts#836.

We remove support for the previous version of trampoline, which means
that when paying nodes that use the experimental version, we will use
the trampoline-to-non-trampoline flow instead. Similarly, when older
nodes pay updated nodes, they won't understand the new trampoline
feature bit and will use the trampoline-to-non-trampoline flow.

We update the trampoline-to-non-trampoline flow to remove the unused
trampoline payload in the onion, which saves some space. Note that we
don't want to officially specify this scenario, as it leaks some data
about the recipient to the trampoline node. We rather wait for nodes
to either support trampoline or blinded paths, which fixes this issue.

Author: t-bast

src/commonMain/kotlin/fr/acinq/lightning/Features.kt

@@ -147,6 +147,13 @@ sealed class Feature {
         override val scopes: Set<FeatureScope> get() = setOf(FeatureScope.Invoice)
     }
 
+    @Serializable
+    object TrampolinePayment : Feature() {
+        override val rfcName get() = "trampoline_routing"
+        override val mandatory get() = 56
+        override val scopes: Set<FeatureScope> get() = setOf(FeatureScope.Init, FeatureScope.Node, FeatureScope.Invoice)
+    }
+
     // The following features have not been standardised, hence the high feature bits to avoid conflicts.
 
     /** This feature bit should be activated when a node accepts having their channel reserve set to 0. */
@@ -189,15 +196,6 @@ sealed class Feature {
         override val scopes: Set<FeatureScope> get() = setOf(FeatureScope.Init, FeatureScope.Node)
     }
 
-    // The version of trampoline enabled by this feature bit does not match the latest spec PR: once the spec is accepted,
-    // we will introduce a new version of trampoline that will work in parallel to this one, until we can safely deprecate it.
-    @Serializable
-    object ExperimentalTrampolinePayment : Feature() {
-        override val rfcName get() = "trampoline_payment_experimental"
-        override val mandatory get() = 148
-        override val scopes: Set<FeatureScope> get() = setOf(FeatureScope.Init, FeatureScope.Node, FeatureScope.Invoice)
-    }
-
     @Serializable
     object ExperimentalSplice : Feature() {
         override val rfcName get() = "splice_experimental"
@@ -288,7 +286,7 @@ data class Features(val activated: Map<Feature, FeatureSupport>, val unknown: Se
             Feature.Quiescence,
             Feature.ChannelType,
             Feature.PaymentMetadata,
-            Feature.ExperimentalTrampolinePayment,
+            Feature.TrampolinePayment,
             Feature.ZeroReserveChannels,
             Feature.WakeUpNotificationClient,
             Feature.WakeUpNotificationProvider,
@@ -327,7 +325,7 @@ data class Features(val activated: Map<Feature, FeatureSupport>, val unknown: Se
             Feature.PaymentSecret to listOf(Feature.VariableLengthOnion),
             Feature.BasicMultiPartPayment to listOf(Feature.PaymentSecret),
             Feature.AnchorOutputs to listOf(Feature.StaticRemoteKey),
-            Feature.ExperimentalTrampolinePayment to listOf(Feature.PaymentSecret),
+            Feature.TrampolinePayment to listOf(Feature.BasicMultiPartPayment),
             Feature.OnTheFlyFunding to listOf(Feature.ExperimentalSplice),
             Feature.FundingFeeCredit to listOf(Feature.OnTheFlyFunding)
         )

src/commonMain/kotlin/fr/acinq/lightning/NodeParams.kt

@@ -197,7 +197,7 @@ data class NodeParams(
             Feature.Quiescence to FeatureSupport.Mandatory,
             Feature.ChannelType to FeatureSupport.Mandatory,
             Feature.PaymentMetadata to FeatureSupport.Optional,
-            Feature.ExperimentalTrampolinePayment to FeatureSupport.Optional,
+            Feature.TrampolinePayment to FeatureSupport.Optional,
             Feature.ZeroReserveChannels to FeatureSupport.Optional,
             Feature.WakeUpNotificationClient to FeatureSupport.Optional,
             Feature.ChannelBackupClient to FeatureSupport.Optional,

src/commonMain/kotlin/fr/acinq/lightning/payment/OutgoingPaymentHandler.kt

@@ -344,7 +344,7 @@ class OutgoingPaymentHandler(val nodeParams: NodeParams, val walletParams: Walle
                 if (request.recipient == walletParams.trampolineNode.id) {
                     // We are directly paying our trampoline node.
                     OutgoingPaymentPacket.buildPacketToTrampolinePeer(paymentRequest, request.amount, expiry)
-                } else if (invoiceFeatures.hasFeature(Feature.ExperimentalTrampolinePayment)) {
+                } else if (invoiceFeatures.hasFeature(Feature.TrampolinePayment)) {
                     OutgoingPaymentPacket.buildPacketToTrampolineRecipient(paymentRequest, request.amount, expiry, hop)
                 } else {
                     OutgoingPaymentPacket.buildPacketToLegacyRecipient(paymentRequest, request.amount, expiry, hop)

src/commonMain/kotlin/fr/acinq/lightning/payment/OutgoingPaymentPacket.kt

@@ -26,7 +26,7 @@ object OutgoingPaymentPacket {
         return buildOnion(sessionKey, nodes, payloads, associatedData, payloadLength)
     }
 
-    private fun buildOnion(sessionKey: PrivateKey, nodes: List<PublicKey>, payloads: List<PaymentOnion.PerHopPayload>, associatedData: ByteVector32, payloadLength: Int? = null): PacketAndSecrets {
+    fun buildOnion(sessionKey: PrivateKey, nodes: List<PublicKey>, payloads: List<PaymentOnion.PerHopPayload>, associatedData: ByteVector32, payloadLength: Int? = null): PacketAndSecrets {
         require(nodes.size == payloads.size)
         val payloadsBin = payloads.map { it.write() }
         val totalPayloadLength = payloadLength ?: payloadsBin.sumOf { it.size + Sphinx.MacLength }
@@ -43,12 +43,11 @@ object OutgoingPaymentPacket {
      * @param hop the trampoline hop from the trampoline node to the recipient.
      */
     fun buildPacketToTrampolineRecipient(invoice: Bolt11Invoice, amount: MilliSatoshi, expiry: CltvExpiry, hop: NodeHop): Triple<MilliSatoshi, CltvExpiry, PacketAndSecrets> {
-        require(invoice.features.hasFeature(Feature.ExperimentalTrampolinePayment)) { "invoice must support trampoline" }
+        require(invoice.features.hasFeature(Feature.TrampolinePayment)) { "invoice must support trampoline" }
         val trampolineOnion = run {
             val finalPayload = PaymentOnion.FinalPayload.Standard.createSinglePartPayload(amount, expiry, invoice.paymentSecret, invoice.paymentMetadata)
             val trampolinePayload = PaymentOnion.NodeRelayPayload.create(amount, expiry, hop.nextNodeId)
-            // We may be paying an older version of lightning-kmp that only supports trampoline packets of size 400.
-            buildOnion(listOf(hop.nodeId, hop.nextNodeId), listOf(trampolinePayload, finalPayload), invoice.paymentHash, payloadLength = 400)
+            buildOnion(listOf(hop.nodeId, hop.nextNodeId), listOf(trampolinePayload, finalPayload), invoice.paymentHash)
         }
         val trampolineAmount = amount + hop.fee(amount)
         val trampolineExpiry = expiry + hop.cltvExpiryDelta
@@ -67,7 +66,7 @@ object OutgoingPaymentPacket {
      * @param expiry cltv expiry that should be received by the final recipient.
      */
     fun buildPacketToTrampolinePeer(invoice: Bolt11Invoice, amount: MilliSatoshi, expiry: CltvExpiry): Triple<MilliSatoshi, CltvExpiry, PacketAndSecrets> {
-        require(invoice.features.hasFeature(Feature.ExperimentalTrampolinePayment)) { "invoice must support trampoline" }
+        require(invoice.features.hasFeature(Feature.TrampolinePayment)) { "invoice must support trampoline" }
         val trampolineOnion = run {
             val finalPayload = PaymentOnion.FinalPayload.Standard.createSinglePartPayload(amount, expiry, invoice.paymentSecret, invoice.paymentMetadata)
             buildOnion(listOf(invoice.nodeId), listOf(finalPayload), invoice.paymentHash)
@@ -90,23 +89,20 @@ object OutgoingPaymentPacket {
      */
     fun buildPacketToLegacyRecipient(invoice: Bolt11Invoice, amount: MilliSatoshi, expiry: CltvExpiry, hop: NodeHop): Triple<MilliSatoshi, CltvExpiry, PacketAndSecrets> {
         val trampolineOnion = run {
-            // NB: the final payload will never reach the recipient, since the trampoline node will convert that to a legacy payment.
-            // We use the smallest final payload possible, otherwise we may overflow the trampoline onion size.
-            val dummyFinalPayload = PaymentOnion.FinalPayload.Standard.createSinglePartPayload(amount, expiry, invoice.paymentSecret, null)
-            var routingInfo = invoice.routingInfo
-            var trampolinePayload = PaymentOnion.RelayToNonTrampolinePayload.create(amount, amount, expiry, hop.nextNodeId, invoice, routingInfo)
-            var trampolineOnion = buildOnion(listOf(hop.nodeId, hop.nextNodeId), listOf(trampolinePayload, dummyFinalPayload), invoice.paymentHash)
-            // Ensure that this onion can fit inside the outer 1300 bytes onion. The outer onion fields need ~150 bytes and we add some safety margin.
-            while (trampolineOnion.packet.payload.size() > 1000) {
-                routingInfo = routingInfo.dropLast(1)
-                trampolinePayload = PaymentOnion.RelayToNonTrampolinePayload.create(amount, amount, expiry, hop.nextNodeId, invoice, routingInfo)
-                trampolineOnion = buildOnion(listOf(hop.nodeId, hop.nextNodeId), listOf(trampolinePayload, dummyFinalPayload), invoice.paymentHash)
-            }
-            trampolineOnion
+            // We create a trampoline onion detailing what to forward to the recipient.
+            val trampolinePayload = PaymentOnion.NodeRelayPayload.create(amount, expiry, hop.nextNodeId)
+            buildOnion(listOf(hop.nodeId), listOf(trampolinePayload), invoice.paymentHash)
         }
+        // We wrap that trampoline onion in a payment onion that contains the invoice's routing hints.
+        // We remove routing hints until they fit inside the payment onion.
         val trampolineAmount = amount + hop.fee(amount)
         val trampolineExpiry = expiry + hop.cltvExpiryDelta
-        val payload = PaymentOnion.FinalPayload.Standard.createTrampolinePayload(trampolineAmount, trampolineAmount, trampolineExpiry, invoice.paymentSecret, trampolineOnion.packet)
+        var routingInfo = invoice.routingInfo
+        var payload = PaymentOnion.FinalPayload.Standard.createTrampolineToLegacyPayload(trampolineAmount, trampolineExpiry, invoice, routingInfo, trampolineOnion.packet)
+        while (payload.write().size + Sphinx.MacLength > OnionRoutingPacket.PaymentPacketLength) {
+            routingInfo = routingInfo.dropLast(1)
+            payload = PaymentOnion.FinalPayload.Standard.createTrampolineToLegacyPayload(trampolineAmount, trampolineExpiry, invoice, routingInfo, trampolineOnion.packet)
+        }
         val paymentOnion = buildOnion(listOf(hop.nodeId), listOf(payload), invoice.paymentHash, OnionRoutingPacket.PaymentPacketLength)
         return Triple(trampolineAmount, trampolineExpiry, paymentOnion)
     }