Update trampoline payment to blinded path to match spec proposal

We update our trampoline payments to blinded paths to match the official
specification from lightning/bolts#836.

The blinded paths and recipient features are included in the trampoline
onion, which potentially allows using multiple trampoline hops.

That was already what we were doing with experimental TLVs, so we simply
update the TLV values to match the spec values.

Author: t-bast

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

@@ -11,7 +11,7 @@ import fr.acinq.bitcoin.utils.Either
 import fr.acinq.bitcoin.utils.flatMap
 import fr.acinq.lightning.*
 import fr.acinq.lightning.payment.Bolt11Invoice
-import fr.acinq.lightning.payment.Bolt12Invoice
+import fr.acinq.lightning.payment.Bolt12Invoice.Companion.PaymentBlindedContactInfo
 import fr.acinq.lightning.utils.msat
 import fr.acinq.lightning.utils.toByteVector
 
@@ -151,16 +151,43 @@ sealed class OnionPaymentPayloadTlv : Tlv {
     }
 
     /**
-     * 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.
+     * Features that may be used to reach the recipient, provided by the payment sender (usually obtained them from an invoice).
+     * Only included for a trampoline node when relaying to a non-trampoline recipient using [OutgoingBlindedPaths] or [InvoiceRoutingInfo].
      */
-    data class InvoiceFeatures(val features: ByteVector) : OnionPaymentPayloadTlv() {
-        override val tag: Long get() = InvoiceFeatures.tag
+    data class RecipientFeatures(val features: ByteVector) : OnionPaymentPayloadTlv() {
+        override val tag: Long get() = RecipientFeatures.tag
         override fun write(out: Output) = LightningCodecs.writeBytes(features, out)
 
-        companion object : TlvValueReader<InvoiceFeatures> {
-            const val tag: Long = 66097
-            override fun read(input: Input): InvoiceFeatures = InvoiceFeatures(ByteVector(LightningCodecs.bytes(input, input.availableBytes)))
+        companion object : TlvValueReader<RecipientFeatures> {
+            const val tag: Long = 21
+            override fun read(input: Input): RecipientFeatures = RecipientFeatures(ByteVector(LightningCodecs.bytes(input, input.availableBytes)))
+        }
+    }
+
+    /**
+     * Blinded paths that can be used to reach the final recipient.
+     * Only included for a trampoline node when paying a Bolt 12 invoice that doesn't support trampoline.
+     */
+    data class OutgoingBlindedPaths(val paths: List<PaymentBlindedContactInfo>) : OnionPaymentPayloadTlv() {
+        override val tag: Long get() = OutgoingBlindedPaths.tag
+        override fun write(out: Output) {
+            for (path in paths) {
+                OfferTypes.writePath(path.route, out)
+                OfferTypes.writePaymentInfo(path.paymentInfo, out)
+            }
+        }
+
+        companion object : TlvValueReader<OutgoingBlindedPaths> {
+            const val tag: Long = 22
+            override fun read(input: Input): OutgoingBlindedPaths {
+                val paths = ArrayList<PaymentBlindedContactInfo>()
+                while (input.availableBytes > 0) {
+                    val route = OfferTypes.readPath(input)
+                    val payInfo = OfferTypes.readPaymentInfo(input)
+                    paths.add(PaymentBlindedContactInfo(route, payInfo))
+                }
+                return OutgoingBlindedPaths(paths)
+            }
         }
     }
 
@@ -205,30 +232,6 @@ sealed class OnionPaymentPayloadTlv : Tlv {
         }
     }
 
-    /** Blinded paths to relay the payment to */
-    data class OutgoingBlindedPaths(val paths: List<Bolt12Invoice.Companion.PaymentBlindedContactInfo>) : OnionPaymentPayloadTlv() {
-        override val tag: Long get() = OutgoingBlindedPaths.tag
-        override fun write(out: Output) {
-            for (path in paths) {
-                OfferTypes.writePath(path.route, out)
-                OfferTypes.writePaymentInfo(path.paymentInfo, out)
-            }
-        }
-
-        companion object : TlvValueReader<OutgoingBlindedPaths> {
-            const val tag: Long = 66102
-            override fun read(input: Input): OutgoingBlindedPaths {
-                val paths = ArrayList<Bolt12Invoice.Companion.PaymentBlindedContactInfo>()
-                while (input.availableBytes > 0) {
-                    val route = OfferTypes.readPath(input)
-                    val payInfo = OfferTypes.readPaymentInfo(input)
-                    paths.add(Bolt12Invoice.Companion.PaymentBlindedContactInfo(route, payInfo))
-                }
-                return OutgoingBlindedPaths(paths)
-            }
-        }
-    }
-
 }
 
 object PaymentOnion {
@@ -256,9 +259,10 @@ object PaymentOnion {
                     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.InvoiceRoutingInfo.tag to OnionPaymentPayloadTlv.InvoiceRoutingInfo.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
+                    OnionPaymentPayloadTlv.RecipientFeatures.tag to OnionPaymentPayloadTlv.RecipientFeatures.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                     OnionPaymentPayloadTlv.OutgoingBlindedPaths.tag to OnionPaymentPayloadTlv.OutgoingBlindedPaths.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
+                    // The following TLVs aren't official TLVs from the BOLTs.
+                    OnionPaymentPayloadTlv.InvoiceRoutingInfo.tag to OnionPaymentPayloadTlv.InvoiceRoutingInfo.Companion as TlvValueReader<OnionPaymentPayloadTlv>,
                 )
             )
 
@@ -401,6 +405,7 @@ object PaymentOnion {
     data class ChannelRelayPayload(val records: TlvStream<OnionPaymentPayloadTlv>) : PerHopPayload() {
         val amountToForward = records.get<OnionPaymentPayloadTlv.AmountToForward>()!!.amount
         val outgoingCltv = records.get<OnionPaymentPayloadTlv.OutgoingCltv>()!!.cltv
+        val outgoingChannelId = records.get<OnionPaymentPayloadTlv.OutgoingChannelId>()!!.shortChannelId
 
         override fun write(out: Output) = tlvSerializer.write(records, out)
 
@@ -427,7 +432,23 @@ object PaymentOnion {
 
         companion object : PerHopPayloadReader<BlindedChannelRelayPayload> {
             override fun read(input: Input): Either<InvalidOnionPayload, BlindedChannelRelayPayload> {
-                return PerHopPayload.read(input).map { BlindedChannelRelayPayload(it) }
+                return PerHopPayload.read(input).flatMap { tlvs ->
+                    when {
+                        tlvs.get<OnionPaymentPayloadTlv.AmountToForward>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.AmountToForward.tag, 0))
+                        tlvs.get<OnionPaymentPayloadTlv.OutgoingCltv>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingCltv.tag, 0))
+                        tlvs.get<OnionPaymentPayloadTlv.OutgoingChannelId>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingChannelId.tag, 0))
+                        tlvs.get<OnionPaymentPayloadTlv.EncryptedRecipientData>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.EncryptedRecipientData.tag, 0))
+                        else -> Either.Right(BlindedChannelRelayPayload(tlvs))
+                    }
+                }
+            }
+
+            fun create(encryptedData: ByteVector, pathKey: PublicKey?): BlindedChannelRelayPayload {
+                val tlvs = buildSet {
+                    add(OnionPaymentPayloadTlv.EncryptedRecipientData(encryptedData))
+                    pathKey?.let { add(OnionPaymentPayloadTlv.PathKey(it)) }
+                }
+                return BlindedChannelRelayPayload(TlvStream(tlvs))
             }
         }
     }
@@ -477,7 +498,7 @@ object PaymentOnion {
         val outgoingNodeId = records.get<OnionPaymentPayloadTlv.OutgoingNodeId>()!!.nodeId
         val paymentSecret = records.get<OnionPaymentPayloadTlv.PaymentData>()!!.secret
         val paymentMetadata = records.get<OnionPaymentPayloadTlv.PaymentMetadata>()?.data
-        val invoiceFeatures = records.get<OnionPaymentPayloadTlv.InvoiceFeatures>()!!.features
+        val invoiceFeatures = records.get<OnionPaymentPayloadTlv.RecipientFeatures>()!!.features
         val invoiceRoutingInfo = records.get<OnionPaymentPayloadTlv.InvoiceRoutingInfo>()!!.extraHops
 
         override fun write(out: Output) = tlvSerializer.write(records, out)
@@ -490,7 +511,7 @@ object PaymentOnion {
                         tlvs.get<OnionPaymentPayloadTlv.OutgoingCltv>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingCltv.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.OutgoingNodeId>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingNodeId.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.PaymentData>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.PaymentData.tag, 0))
-                        tlvs.get<OnionPaymentPayloadTlv.InvoiceFeatures>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.InvoiceFeatures.tag, 0))
+                        tlvs.get<OnionPaymentPayloadTlv.RecipientFeatures>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.RecipientFeatures.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.InvoiceRoutingInfo>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.InvoiceRoutingInfo.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.EncryptedRecipientData>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.EncryptedRecipientData.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.PathKey>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.PathKey.tag, 0))
@@ -508,19 +529,23 @@ object PaymentOnion {
                             add(OnionPaymentPayloadTlv.OutgoingNodeId(targetNodeId))
                             add(OnionPaymentPayloadTlv.PaymentData(invoice.paymentSecret, totalAmount))
                             invoice.paymentMetadata?.let { add(OnionPaymentPayloadTlv.PaymentMetadata(it)) }
-                            add(OnionPaymentPayloadTlv.InvoiceFeatures(invoice.features.toByteArray().toByteVector()))
+                            add(OnionPaymentPayloadTlv.RecipientFeatures(invoice.features.toByteArray().toByteVector()))
                             add(OnionPaymentPayloadTlv.InvoiceRoutingInfo(routingInfo.map { it.hints }))
                         }
                     )
                 )
         }
     }
 
+    /**
+     * Create a trampoline payload to tell our trampoline node to relay to a blinded path, where the recipient doesn't support trampoline.
+     * This only reveals the blinded path to our trampoline node, which doesn't reveal the recipient's identity.
+     */
     data class RelayToBlindedPayload(val records: TlvStream<OnionPaymentPayloadTlv>) : PerHopPayload() {
         val amountToForward = records.get<OnionPaymentPayloadTlv.AmountToForward>()!!.amount
         val outgoingCltv = records.get<OnionPaymentPayloadTlv.OutgoingCltv>()!!.cltv
         val outgoingBlindedPaths = records.get<OnionPaymentPayloadTlv.OutgoingBlindedPaths>()!!.paths
-        val invoiceFeatures = records.get<OnionPaymentPayloadTlv.InvoiceFeatures>()!!.features
+        val recipientFeatures = records.get<OnionPaymentPayloadTlv.RecipientFeatures>()?.features ?: Features.empty
 
         override fun write(out: Output) = tlvSerializer.write(records, out)
 
@@ -530,7 +555,6 @@ object PaymentOnion {
                     when {
                         tlvs.get<OnionPaymentPayloadTlv.AmountToForward>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.AmountToForward.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.OutgoingCltv>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingCltv.tag, 0))
-                        tlvs.get<OnionPaymentPayloadTlv.InvoiceFeatures>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.InvoiceFeatures.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.OutgoingBlindedPaths>() == null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.OutgoingBlindedPaths.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.EncryptedRecipientData>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.EncryptedRecipientData.tag, 0))
                         tlvs.get<OnionPaymentPayloadTlv.PathKey>() != null -> Either.Left(InvalidOnionPayload(OnionPaymentPayloadTlv.PathKey.tag, 0))
@@ -539,14 +563,14 @@ object PaymentOnion {
                 }
             }
 
-            fun create(amount: MilliSatoshi, expiry: CltvExpiry, features: Features, blindedPaths: List<Bolt12Invoice.Companion.PaymentBlindedContactInfo>): RelayToBlindedPayload =
+            fun create(amount: MilliSatoshi, expiry: CltvExpiry, features: Features, blindedPaths: List<PaymentBlindedContactInfo>): RelayToBlindedPayload =
                 RelayToBlindedPayload(
                     TlvStream(
                         setOf(
                             OnionPaymentPayloadTlv.AmountToForward(amount),
                             OnionPaymentPayloadTlv.OutgoingCltv(expiry),
                             OnionPaymentPayloadTlv.OutgoingBlindedPaths(blindedPaths),
-                            OnionPaymentPayloadTlv.InvoiceFeatures(features.toByteArray().toByteVector())
+                            OnionPaymentPayloadTlv.RecipientFeatures(features.toByteArray().toByteVector())
                         )
                     )
                 )