Add support for trampoline blinded payments

We add the ability to pay recipients that support trampoline *and*
blinded paths. We include the blinded path data in the trampoline
payloads for each node inside the blinded path. This doesn't reveal
unnecessary information to the trampoline node: this is specified in
details in lightning/bolts#836.

Author: t-bast

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

@@ -151,7 +151,7 @@ sealed class Feature {
     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)
+        override val scopes: Set<FeatureScope> get() = setOf(FeatureScope.Init, FeatureScope.Node, FeatureScope.Invoice, FeatureScope.Bolt12)
     }
 
     // The following features have not been standardised, hence the high feature bits to avoid conflicts.

modules/core/src/commonMain/kotlin/fr/acinq/lightning/payment/IncomingPaymentPacket.kt

@@ -48,12 +48,11 @@ object IncomingPaymentPacket {
                     when (val trampolineOnion = outer.records.get<OnionPaymentPayloadTlv.TrampolineOnion>()) {
                         null -> validate(htlcAmount, htlcExpiry, outer)
                         else -> {
-                            when (val inner = decryptOnion(paymentHash, trampolineOnion.packet, privateKey, null)) {
+                            when (val inner = decryptOnion(paymentHash, trampolineOnion.packet, privateKey, outer.records.get<OnionPaymentPayloadTlv.PathKey>()?.publicKey)) {
                                 is Either.Left -> Either.Left(inner.value)
                                 is Either.Right -> when (val innerPayload = inner.value) {
                                     is PaymentOnion.FinalPayload.Standard -> validate(htlcAmount, htlcExpiry, outer, innerPayload)
-                                    // Blinded trampoline paths are not supported.
-                                    is PaymentOnion.FinalPayload.Blinded -> Either.Left(InvalidOnionPayload(0, 0))
+                                    is PaymentOnion.FinalPayload.Blinded -> validate(htlcAmount, htlcExpiry, trampolineOnion.packet, innerPayload)
                                 }
                             }
                         }
@@ -72,7 +71,6 @@ object IncomingPaymentPacket {
                     when (val encryptedRecipientData = tlvs.get<OnionPaymentPayloadTlv.EncryptedRecipientData>()?.data) {
                         null -> when {
                             pathKey != null -> Either.Left(InvalidOnionBlinding(hash(packet)))
-                            tlvs.get<OnionPaymentPayloadTlv.PathKey>() != null -> Either.Left(InvalidOnionBlinding(hash(packet)))
                             else -> PaymentOnion.FinalPayload.Standard.read(decrypted.payload)
                         }
                         else -> when {

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

@@ -311,11 +311,10 @@ class OutgoingPaymentHandler(val nodeParams: NodeParams, val walletParams: Walle
             is Bolt11Invoice -> {
                 val minFinalExpiryDelta = paymentRequest.minFinalExpiryDelta ?: Channel.MIN_CLTV_EXPIRY_DELTA
                 val expiry = nodeParams.paymentRecipientExpiryParams.computeFinalExpiry(currentBlockHeight, minFinalExpiryDelta)
-                val invoiceFeatures = paymentRequest.features
                 if (request.recipient == walletParams.trampolineNode.id) {
                     // We are directly paying our trampoline node.
                     OutgoingPaymentPacket.buildPacketToTrampolinePeer(paymentRequest, request.amount, expiry)
-                } else if (invoiceFeatures.hasFeature(Feature.TrampolinePayment)) {
+                } else if (paymentRequest.features.hasFeature(Feature.TrampolinePayment)) {
                     OutgoingPaymentPacket.buildPacketToTrampolineRecipient(paymentRequest, request.amount, expiry, hop)
                 } else {
                     OutgoingPaymentPacket.buildPacketToLegacyRecipient(paymentRequest, request.amount, expiry, hop)
@@ -325,7 +324,16 @@ class OutgoingPaymentHandler(val nodeParams: NodeParams, val walletParams: Walle
                 // The recipient already included a final cltv-expiry-delta in their invoice blinded paths.
                 val minFinalExpiryDelta = CltvExpiryDelta(0)
                 val expiry = nodeParams.paymentRecipientExpiryParams.computeFinalExpiry(currentBlockHeight, minFinalExpiryDelta)
-                OutgoingPaymentPacket.buildPacketToBlindedRecipient(paymentRequest, request.amount, expiry, hop)
+                if (paymentRequest.features.hasFeature(Feature.TrampolinePayment)) {
+                    // If there are multiple blinded paths, we choose one at random that doesn't require resolving the introduction node.
+                    // If we can't find one, we default to letting our trampoline node relay to the invoice's blinded paths.
+                    when (val path = paymentRequest.blindedPaths.filter { it.route.route.firstNodeId is EncodedNodeId.WithPublicKey }.randomOrNull()) {
+                        null -> OutgoingPaymentPacket.buildPacketToBlindedRecipient(paymentRequest, request.amount, expiry, hop)
+                        else -> OutgoingPaymentPacket.buildPacketToTrampolineRecipient(paymentRequest.paymentHash, request.amount, expiry, path, hop)
+                    }
+                } else {
+                    OutgoingPaymentPacket.buildPacketToBlindedRecipient(paymentRequest, request.amount, expiry, hop)
+                }
             }
         }
     }

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

@@ -5,10 +5,7 @@ import fr.acinq.bitcoin.ByteVector32
 import fr.acinq.bitcoin.PrivateKey
 import fr.acinq.bitcoin.PublicKey
 import fr.acinq.bitcoin.utils.Either
-import fr.acinq.lightning.CltvExpiry
-import fr.acinq.lightning.Feature
-import fr.acinq.lightning.Lightning
-import fr.acinq.lightning.MilliSatoshi
+import fr.acinq.lightning.*
 import fr.acinq.lightning.channel.ChannelCommand
 import fr.acinq.lightning.crypto.sphinx.FailurePacket
 import fr.acinq.lightning.crypto.sphinx.PacketAndSecrets
@@ -58,6 +55,42 @@ object OutgoingPaymentPacket {
         return Triple(trampolineAmount, trampolineExpiry, paymentOnion)
     }
 
+    /**
+     * Build an encrypted payment onion packet when the final recipient supports trampoline.
+     * We use each hop in the blinded path as a trampoline hop, which doesn't reveal anything to our trampoline node.
+     * From their point of view, they will be relaying a trampoline payment to another trampoline node.
+     * They won't even know that a blinded path is being used.
+     */
+    fun buildPacketToTrampolineRecipient(paymentHash: ByteVector32, amount: MilliSatoshi, expiry: CltvExpiry, path: Bolt12Invoice.Companion.PaymentBlindedContactInfo, hop: NodeHop): Triple<MilliSatoshi, CltvExpiry, PacketAndSecrets> {
+        require(path.route.route.firstNodeId is EncodedNodeId.WithPublicKey) { "blinded path must provide the introduction node_id" }
+        val (trampolineAmount, trampolineExpiry, trampolineOnion) = run {
+            val blindedAmount = amount + path.paymentInfo.fee(amount)
+            val blindedExpiry = expiry + path.paymentInfo.cltvExpiryDelta
+            val blindedNodes = listOf(path.route.route.firstNodeId.publicKey) + path.route.route.blindedNodeIds.drop(1)
+            val blindedPayloads = when {
+                blindedNodes.size == 1 -> {
+                    val finalPayload = PaymentOnion.FinalPayload.Blinded.create(amount, expiry, path.route.route.encryptedPayloads.last(), path.route.route.firstPathKey)
+                    listOf(finalPayload)
+                }
+                else -> {
+                    val finalPayload = PaymentOnion.FinalPayload.Blinded.create(amount, expiry, path.route.route.encryptedPayloads.last(), pathKey = null)
+                    val intermediatePayloads = path.route.route.encryptedPayloads.drop(1).dropLast(1).map { PaymentOnion.BlindedChannelRelayPayload.create(it, pathKey = null) }
+                    val introductionPayload = PaymentOnion.BlindedChannelRelayPayload.create(path.route.route.encryptedPayloads.first(), path.route.route.firstPathKey)
+                    listOf(introductionPayload) + intermediatePayloads + listOf(finalPayload)
+                }
+            }
+            val trampolinePayload = PaymentOnion.NodeRelayPayload.create(blindedAmount, blindedExpiry, blindedNodes.first())
+            val trampolineOnion = buildOnion(listOf(hop.nodeId) + blindedNodes, listOf(trampolinePayload) + blindedPayloads, paymentHash)
+            val trampolineAmount = blindedAmount + hop.fee(blindedAmount)
+            val trampolineExpiry = blindedExpiry + hop.cltvExpiryDelta
+            Triple(trampolineAmount, trampolineExpiry, trampolineOnion)
+        }
+        val trampolinePaymentSecret = Lightning.randomBytes32()
+        val payload = PaymentOnion.FinalPayload.Standard.createTrampolinePayload(trampolineAmount, trampolineAmount, trampolineExpiry, trampolinePaymentSecret, trampolineOnion.packet)
+        val paymentOnion = buildOnion(listOf(hop.nodeId), listOf(payload), paymentHash, OnionRoutingPacket.PaymentPacketLength)
+        return Triple(trampolineAmount, trampolineExpiry, paymentOnion)
+    }
+
     /**
      * Build an encrypted payment onion packet when the final recipient is our trampoline node.
      *

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

@@ -399,6 +399,21 @@ object PaymentOnion {
                         else -> Either.Right(Blinded(records, blindedRecords))
                     }
                 }
+
+                fun create(amount: MilliSatoshi, expiry: CltvExpiry, encryptedData: ByteVector, pathKey: PublicKey?): Blinded {
+                    val tlvs = TlvStream(
+                        setOfNotNull(
+                            OnionPaymentPayloadTlv.AmountToForward(amount),
+                            OnionPaymentPayloadTlv.OutgoingCltv(expiry),
+                            OnionPaymentPayloadTlv.TotalAmount(amount),
+                            OnionPaymentPayloadTlv.EncryptedRecipientData(encryptedData),
+                            pathKey?.let { OnionPaymentPayloadTlv.PathKey(it) },
+                        )
+                    )
+                    // We're creating a payload for an outgoing payment: we don't have access to the decrypted data, so we create an unused dummy one.
+                    val dummyPathId = ByteVector.fromHex("deadbeef")
+                    return Blinded(tlvs, RouteBlindingEncryptedData(TlvStream(RouteBlindingEncryptedDataTlv.PathId(dummyPathId))))
+                }
             }
         }
     }

modules/core/src/commonTest/kotlin/fr/acinq/lightning/payment/OfferManagerTestsCommon.kt

@@ -95,6 +95,8 @@ class OfferManagerTestsCommon : LightningTestSuite() {
         assertIs<OnionMessageAction.PayInvoice>(payInvoice)
         assertEquals(OfferInvoiceReceived(payOffer, payInvoice.invoice), bobOfferManager.eventsFlow.first())
         assertEquals(payOffer, payInvoice.payOffer)
+        assertTrue(payInvoice.invoice.features.hasFeature(Feature.BasicMultiPartPayment))
+        assertTrue(payInvoice.invoice.features.hasFeature(Feature.TrampolinePayment))
         assertEquals(1, payInvoice.invoice.blindedPaths.size)
         val path = payInvoice.invoice.blindedPaths.first()
         assertEquals(EncodedNodeId(aliceTrampolineKey.publicKey()), path.route.route.firstNodeId)