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

@@ -199,7 +199,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

@@ -315,7 +315,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,17 +89,14 @@ 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)
+            var trampolineOnion = buildOnion(listOf(hop.nodeId), listOf(trampolinePayload), 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 = buildOnion(listOf(hop.nodeId), listOf(trampolinePayload), invoice.paymentHash)
             }
             trampolineOnion
         }

src/commonMain/kotlin/fr/acinq/lightning/wire/PaymentOnion.kt

@@ -98,6 +98,17 @@ sealed class OnionPaymentPayloadTlv : Tlv {
         }
     }
 
+    /** Id of the next node. */
+    data class OutgoingNodeId(val nodeId: PublicKey) : OnionPaymentPayloadTlv() {
+        override val tag: Long get() = OutgoingNodeId.tag
+        override fun write(out: Output) = LightningCodecs.writeBytes(nodeId.value, out)
+
+        companion object : TlvValueReader<OutgoingNodeId> {
+            const val tag: Long = 14
+            override fun read(input: Input): OutgoingNodeId = OutgoingNodeId(PublicKey(LightningCodecs.bytes(input, 33)))
+        }
+    }
+
     /**
      * When payment metadata is included in a Bolt 9 invoice, we should send it as-is to the recipient.
      * This lets recipients generate invoices without having to store anything on their side until the invoice is paid.
@@ -125,6 +136,20 @@ sealed class OnionPaymentPayloadTlv : Tlv {
         }
     }
 
+    /** An encrypted trampoline onion packet. */
+    data class TrampolineOnion(val packet: OnionRoutingPacket) : OnionPaymentPayloadTlv() {
+        override val tag: Long get() = TrampolineOnion.tag
+        override fun write(out: Output) = OnionRoutingPacketSerializer(packet.payload.size()).write(packet, out)
+
+        companion object : TlvValueReader<TrampolineOnion> {
+            const val tag: Long = 20
+            override fun read(input: Input): TrampolineOnion {
+                val payloadLength = input.availableBytes - 66 // 1 byte version + 33 bytes public key + 32 bytes HMAC
+                return TrampolineOnion(OnionRoutingPacketSerializer(payloadLength).read(input))
+            }
+        }
+    }
+
     /**
      * Invoice feature bits. Only included for intermediate trampoline nodes when they should convert to a legacy payment
      * because the final recipient doesn't support trampoline.
@@ -139,17 +164,6 @@ sealed class OnionPaymentPayloadTlv : Tlv {
         }
     }
 
-    /** Id of the next node. */
-    data class OutgoingNodeId(val nodeId: PublicKey) : OnionPaymentPayloadTlv() {
-        override val tag: Long get() = OutgoingNodeId.tag
-        override fun write(out: Output) = LightningCodecs.writeBytes(nodeId.value, out)
-
-        companion object : TlvValueReader<OutgoingNodeId> {
-            const val tag: Long = 66098
-            override fun read(input: Input): OutgoingNodeId = OutgoingNodeId(PublicKey(LightningCodecs.bytes(input, 33)))
-        }
-    }
-
     /**
      * Invoice routing hints. Only included for intermediate trampoline nodes when they should convert to a legacy payment
      * because the final recipient doesn't support trampoline.
@@ -191,20 +205,6 @@ sealed class OnionPaymentPayloadTlv : Tlv {
         }
     }
 
-    /** An encrypted trampoline onion packet. */
-    data class TrampolineOnion(val packet: OnionRoutingPacket) : OnionPaymentPayloadTlv() {
-        override val tag: Long get() = TrampolineOnion.tag
-        override fun write(out: Output) = OnionRoutingPacketSerializer(packet.payload.size()).write(packet, out)
-
-        companion object : TlvValueReader<TrampolineOnion> {
-            const val tag: Long = 66100
-            override fun read(input: Input): TrampolineOnion {
-                val payloadLength = input.availableBytes - 66 // 1 byte version + 33 bytes public key + 32 bytes HMAC
-                return TrampolineOnion(OnionRoutingPacketSerializer(payloadLength).read(input))
-            }
-        }
-    }
-
     /** Blinded paths to relay the payment to */
     data class OutgoingBlindedPaths(val paths: List<Bolt12Invoice.Companion.PaymentBlindedContactInfo>) : OnionPaymentPayloadTlv() {
         override val tag: Long get() = OutgoingBlindedPaths.tag
@@ -249,15 +249,15 @@ object PaymentOnion {
                     OnionPaymentPayloadTlv.AmountToForward.tag to OnionPaymentPayloadTlv.AmountToForward.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.OutgoingCltv.tag to OnionPaymentPayloadTlv.OutgoingCltv.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.OutgoingChannelId.tag to OnionPaymentPayloadTlv.OutgoingChannelId.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
+                    OnionPaymentPayloadTlv.OutgoingNodeId.tag to OnionPaymentPayloadTlv.OutgoingNodeId.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.PaymentData.tag to OnionPaymentPayloadTlv.PaymentData.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.EncryptedRecipientData.tag to OnionPaymentPayloadTlv.EncryptedRecipientData.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.BlindingPoint.tag to OnionPaymentPayloadTlv.BlindingPoint.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.PaymentMetadata.tag to OnionPaymentPayloadTlv.PaymentMetadata.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.TotalAmount.tag to OnionPaymentPayloadTlv.TotalAmount.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
+                    OnionPaymentPayloadTlv.TrampolineOnion.tag to OnionPaymentPayloadTlv.TrampolineOnion.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.InvoiceFeatures.tag to OnionPaymentPayloadTlv.InvoiceFeatures.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
-                    OnionPaymentPayloadTlv.OutgoingNodeId.tag to OnionPaymentPayloadTlv.OutgoingNodeId.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.InvoiceRoutingInfo.tag to OnionPaymentPayloadTlv.InvoiceRoutingInfo.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
-                    OnionPaymentPayloadTlv.TrampolineOnion.tag to OnionPaymentPayloadTlv.TrampolineOnion.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.OutgoingBlindedPaths.tag to OnionPaymentPayloadTlv.OutgoingBlindedPaths.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                 )
             )
@@ -457,20 +457,15 @@ object PaymentOnion {
         }
     }
 
+    /**
+     * Create a trampoline payload to tell our trampoline node to relay to a Bolt 11 recipient that doesn't support trampoline.
+     * This reveals to our trampoline node who the recipient is and details from the invoice.
+     * This must be deprecated once recipients support either trampoline or blinded paths.
+     */
     data class RelayToNonTrampolinePayload(val records: TlvStream<OnionPaymentPayloadTlv>) : PerHopPayload() {
         val amountToForward = records.get<OnionPaymentPayloadTlv.AmountToForward>()!!.amount
         val outgoingCltv = records.get<OnionPaymentPayloadTlv.OutgoingCltv>()!!.cltv
         val outgoingNodeId = records.get<OnionPaymentPayloadTlv.OutgoingNodeId>()!!.nodeId
-        val totalAmount = run {
-            val paymentData = records.get<OnionPaymentPayloadTlv.PaymentData>()
-            when {
-                paymentData == null -> amountToForward
-                paymentData.totalAmount == MilliSatoshi(0) -> amountToForward
-                else -> paymentData.totalAmount
-            }
-        }
-
-        // NB: the following fields are only included in the trampoline-to-legacy case.
         val paymentSecret = records.get<OnionPaymentPayloadTlv.PaymentData>()!!.secret
         val paymentMetadata = records.get<OnionPaymentPayloadTlv.PaymentMetadata>()?.data
         val invoiceFeatures = records.get<OnionPaymentPayloadTlv.InvoiceFeatures>()!!.features

src/commonTest/kotlin/fr/acinq/lightning/payment/OutgoingPaymentHandlerTestsCommon.kt

@@ -240,35 +240,6 @@ class OutgoingPaymentHandlerTestsCommon : LightningTestSuite() {
         val recipientKey = randomKey()
         val invoice = makeInvoice(amount = 195_000.msat, supportsTrampoline = true, privKey = recipientKey)
         val payment = PayInvoice(UUID.randomUUID(), 200_000.msat, LightningOutgoingPayment.Details.Normal(invoice)) // we slightly overpay the invoice amount
-        testSinglePartTrampolinePayment(payment, invoice, recipientKey)
-    }
-
-    @Test
-    fun `successful first attempt -- backwards-compatibility trampoline bit`() = runSuspendTest {
-        val recipientKey = randomKey()
-        val invoice = run {
-            // Invoices generated by older versions of wallets based on lightning-kmp will generate invoices with the following feature bits.
-            val invoiceFeatures = mapOf(
-                Feature.VariableLengthOnion to FeatureSupport.Optional,
-                Feature.PaymentSecret to FeatureSupport.Mandatory,
-                Feature.BasicMultiPartPayment to FeatureSupport.Optional,
-                Feature.ExperimentalTrampolinePayment to FeatureSupport.Optional
-            )
-            Bolt11Invoice.create(
-                chain = Chain.Mainnet,
-                amount = 195_000.msat,
-                paymentHash = randomBytes32(),
-                privateKey = recipientKey,
-                description = Either.Left("trampoline backwards-compatibility"),
-                minFinalCltvExpiryDelta = Bolt11Invoice.DEFAULT_MIN_FINAL_EXPIRY_DELTA,
-                features = Features(invoiceFeatures.toMap()),
-            )
-        }
-        val payment = PayInvoice(UUID.randomUUID(), 200_000.msat, LightningOutgoingPayment.Details.Normal(invoice)) // we slightly overpay the invoice amount
-        testSinglePartTrampolinePayment(payment, invoice, recipientKey)
-    }
-
-    private suspend fun testSinglePartTrampolinePayment(payment: PayInvoice, invoice: Bolt11Invoice, recipientKey: PrivateKey) {
         val (alice, _) = TestsHelper.reachNormal()
         val walletParams = defaultWalletParams.copy(trampolineFees = listOf(TrampolineFees(3.sat, 10_000, CltvExpiryDelta(144))))
         val outgoingPaymentHandler = OutgoingPaymentHandler(TestConstants.Alice.nodeParams, walletParams, InMemoryPaymentsDb())
@@ -336,9 +307,8 @@ class OutgoingPaymentHandlerTestsCommon : LightningTestSuite() {
         assertEquals(300_000.msat, innerB.amountToForward)
         assertEquals(CltvExpiry(TestConstants.defaultBlockHeight.toLong()) + Bolt11Invoice.DEFAULT_MIN_FINAL_EXPIRY_DELTA, innerB.outgoingCltv)
         assertEquals(payment.recipient, innerB.outgoingNodeId)
-        assertEquals(invoice.paymentSecret, innerB.paymentSecret)
+        assertEquals(invoice.paymentSecret, outerB.paymentSecret)
         assertEquals(invoice.features.toByteArray().toByteVector(), innerB.invoiceFeatures)
-        assertFalse(innerB.invoiceRoutingInfo.isEmpty())
         assertEquals(invoice.routingInfo.map { it.hints }, innerB.invoiceRoutingInfo)
 
         val preimage = randomBytes32()
@@ -616,7 +586,7 @@ class OutgoingPaymentHandlerTestsCommon : LightningTestSuite() {
             put(Feature.VariableLengthOnion, FeatureSupport.Optional)
             put(Feature.PaymentSecret, FeatureSupport.Mandatory)
             put(Feature.BasicMultiPartPayment, FeatureSupport.Optional)
-            if (supportsTrampoline) put(Feature.ExperimentalTrampolinePayment, FeatureSupport.Optional)
+            if (supportsTrampoline) put(Feature.TrampolinePayment, FeatureSupport.Optional)
         }
         return Bolt11Invoice.create(
             chain = Chain.Mainnet,