Add custom TLV in Bolt11 Payer API #4263
Conversation
Custom TLVs let the payer attach arbitrary data to the onion packet, enabling everything from richer metadata to custom authentication on the payee's side. Until now, this flexibility existed only through `send_payment`. The simpler `pay_for_bolt11_invoice` API offered no way to pass custom TLVs, limiting its usefulness in flows that rely on additional context. This commit adds custom TLV support to `pay_for_bolt11_invoice`, bringing it to feature parity.
|
👋 Thanks for assigning @jkczyz as a reviewer! |
|
cc @jkczyz |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #4263 +/- ##
==========================================
+ Coverage 89.33% 89.37% +0.03%
==========================================
Files 180 180
Lines 139042 139868 +826
Branches 139042 139868 +826
==========================================
+ Hits 124219 125004 +785
- Misses 12196 12269 +73
+ Partials 2627 2595 -32
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
🔔 1st Reminder Hey @joostjager! This PR has been waiting for your review. |
|
🔔 1st Reminder Hey @jkczyz! This PR has been waiting for your review. |
|
🔔 2nd Reminder Hey @jkczyz! This PR has been waiting for your review. |
shaavan
force-pushed
the
payment-custom
branch
from
ef6edec to
26d7eee
Compare
|
🔔 3rd Reminder Hey @jkczyz! This PR has been waiting for your review. |
TheBlueMatt
left a comment
TheBlueMatt
left a comment
There was a problem hiding this comment.
I'm a bit skeptical of the utility of custom onion TLVs for BOLT 12 payments - in general ISTM we should really be preferring to include custom data in the BOLT 12 onion messages themselves, allowing them to not take up precious space in the payment onion (though the recipient can pipe them through if they want). Do we have intended use-cases for these?
lightning/src/ln/channelmanager.rs
Outdated
| @@ -13376,12 +13129,14 @@ where | |||
| /// [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity | |||
| pub fn pay_for_offer_with_quantity( | |||
| &self, offer: &Offer, amount_msats: Option<u64>, payment_id: PaymentId, | |||
| optional_params: OptionalOfferPaymentParams, quantity: u64, | |||
| custom_tlvs: Vec<(u64, Vec<u8>)>, optional_params: OptionalOfferPaymentParams, | |||
There was a problem hiding this comment.
These should really go in OptionalOfferPaymentParams, given that exists to hide fields we expect users to never set.
|
🔔 4th Reminder Hey @jkczyz! This PR has been waiting for your review. |
shaavan
force-pushed
the
payment-custom
branch
from
26d7eee to
c1ae0ed
Compare
shaavan
changed the title
Extends the payment flow test to assert that custom TLVs passed to `pay_for_bolt11_invoice` are preserved and delivered correctly.
shaavan
force-pushed
the
payment-custom
branch
from
c1ae0ed to
e326fca
Compare
|
Updated: .02 → .03
I agree that it makes more sense to put this data directly into the As for intended use cases, the motivation is to allow passing along auxiliary, non-routing information, for example travel-rule or compliance metadata exchanged between LSPs, VASPs, or other intermediaries, without overloading core payment semantics. For now, I’ve trimmed the branch down to just the BOLT 11 API change, exposing In parallel, I’ll start working on moving custom TLVs fully into the Thanks a lot for the pointer. |
3 participants
This PR adds support for attaching custom TLVs to the BOLT 11 payment flow, giving callers a more ergonomic way to embed arbitrary metadata into the payment onion. These TLVs can carry auxiliary, application-specific information without requiring callers to drop down to lower-level APIs.
What this PR does
Adds custom TLV support to
pay_for_bolt11_invoice.While BOLT 11 already allowed custom TLVs via
send_payment, the higher-level and more commonly usedpay_for_bolt11_invoicepath lacked this capability. This PR brings it to feature parity, allowing callers to attach custom TLVs without manually handling payment hashes or preimages.Why this matters
Lightning applications often need to pass contextual, non-routing metadata alongside a payment. Prior to this change, doing so required using lower-level APIs even for straightforward BOLT 11 payments.
By exposing
custom_tlvsdirectly onpay_for_bolt11_invoice, this PR makes it easier and safer for callers to attach additional data while preserving the existing payment flow abstractions.Note: Support for carrying custom TLVs in BOLT 12 flows is intentionally left out of this PR and will be addressed separately by attaching such data directly to BOLT 12 messages (e.g.,
InvoiceRequest), rather than the payment onion.