Add custom TLV support across Bolt11 and Bolt12 payer flows #4263
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Extends the payment flow test to assert that custom TLVs passed to `pay_for_bolt11_invoice` are preserved and delivered correctly.
Bolt11 payments now allow attaching custom TLVs to the onion packet, giving payers a way to pass metadata ranging from descriptions to custom authentication. Bolt12 lacked an equivalent path, leaving its outbound flow less extensible. This commit adds a `custom_tlvs` field to the Bolt12-related `PendingOutboundPayment` variants, bringing the internal Bolt12 payment state in line with the Bolt11 changes and preparing the ground for user-facing API support. A follow-up commit will expose a way for users to set these TLVs.
With internal support for custom TLVs now in place, this commit extends that capability to all payer-facing entry points, from `create_refund_builder` to the various `pay_for_offer` functions. This brings the full Bolt12 payer API in line with the Bolt11 flow and ensures that callers can attach custom metadata consistently across all payment flows.
Adds an end-to-end test validating that custom TLVs propagate correctly through the Bolt12 payer flow.
|
I've assigned @joostjager as a reviewer! |
Member
Author
|
cc @jkczyz |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #4263 +/- ##
==========================================
- Coverage 89.33% 89.32% -0.02%
==========================================
Files 180 180
Lines 139042 139294 +252
Branches 139042 139294 +252
==========================================
+ Hits 124219 124421 +202
- Misses 12196 12248 +52
+ Partials 2627 2625 -2
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:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds end-to-end support for attaching custom TLVs in both Bolt11 and Bolt12 payment flows, giving callers a consistent way to embed arbitrary metadata into the onion packet. These TLVs can carry anything from richer descriptions to custom authentication cues and application-specific signaling.
What this PR does
1. Adds custom TLV support to
pay_for_bolt11_invoice.Bolt11 already allowed custom TLVs through
send_payment, but the more ergonomicpay_for_bolt11_invoicepath lacked this capability. This PR brings it to feature parity.2. Extends Bolt12 payer-facing functions with
custom_tlvs.To support TLVs in Bolt12, the internal payment state now carries user-supplied metadata, and all payer-facing APIs expose a
custom_tlvsfield accordingly.Why this matters
Lightning applications often need to pass contextual metadata alongside a payment. Until now, support for this was uneven:
send_payment, notpay_for_bolt11_invoice.• Bolt12 had no TLV support at all through
send_payment_for_bolt12_invoiceor related payer APIs.This PR unifies the experience across both payment types, providing a uniform and predictable way to attach custom metadata to payments.