Skip to content

Add a payment_metadata map in blinded * path contexts#4584

Open
TheBlueMatt wants to merge 4 commits intolightningdevkit:mainfrom
TheBlueMatt:2026-04-bolt12-custom-data
Open

Add a payment_metadata map in blinded * path contexts#4584
TheBlueMatt wants to merge 4 commits intolightningdevkit:mainfrom
TheBlueMatt:2026-04-bolt12-custom-data

Conversation

@TheBlueMatt
Copy link
Copy Markdown
Collaborator

Similar to how BOLT 11 payments can use a `payment_metadata` to
provide arbitrary bytes in the invoice to be communicated back to
them when receiving, its useful to be able to provide some bytes
which are communicated back upon receiving a payment.

Here we do so in the BOLT 12 blinded * contexts, offering a
`BTreeMap<u64, Vec<u8>>` instead to enable more easily including
multiple sets of data.

Also note that a `Router` building a blinded path is allowed to
modify the `payment_metadata` without breaking the payment.

Tests by claude

We do so both in the blinded message and payment paths, supporting async payments when data is injected in the blinded payment paths (eg via the Router). We don't expose building offers with metadata yet.

We almost certainly don't want to be moving `option` TLVs during
serialization, and while we had logic elsewhere to work around this
previously its nice not to have to in the future.
@TheBlueMatt TheBlueMatt requested a review from tnull May 1, 2026 02:04
@ldk-reviews-bot
Copy link
Copy Markdown

ldk-reviews-bot commented May 1, 2026

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

@TheBlueMatt TheBlueMatt force-pushed the 2026-04-bolt12-custom-data branch 2 times, most recently from 7c4e653 to ee6ba89 Compare May 1, 2026 02:05
Comment thread lightning/src/onion_message/messenger.rs
Comment thread lightning/src/blinded_path/message.rs Outdated
Comment thread lightning/src/blinded_path/payment.rs
@ldk-claude-review-bot
Copy link
Copy Markdown
Collaborator

ldk-claude-review-bot commented May 1, 2026

No issues found.

All previously flagged issues from prior review passes have been verified as resolved:

  • "tighly" typo: fixed (no occurrences remain)
  • OffersContext::StaticInvoiceRequested::payment_metadata doc reference concern: was a misread; the doc at messenger.rs:474 correctly references OffersContext::InvoiceRequest::payment_metadata which exists

Verification completed across all changed files covering:

  • TLV serialization: Odd type numbers (1) for all new payment_metadata fields ensure backwards compatibility. Ascending TLV order maintained in all structs/enums.
  • Macro (option, encoding) pattern: The .as_ref().map(|f| $encoding(f)) expansion in _encode_tlv! (line 84) and _get_varint_length_prefixed_tlv_length! (line 256) both produce BigSizeKeyedMap<&BTreeMap<...>> which has a matching Writeable impl. Reference-type impls for AccountableBool<&bool>, HighZeroBytesDroppedBigSize<&T>, WithoutLength<&&String>, and WithoutLength<&&Features> correctly support the macro expansion.
  • BigSizeKeyedMap DoS safety: Deserialization uses LengthReadable with LengthLimitedRead, bounding total read bytes by TLV length. No pre-allocation based on declared count. Duplicate keys rejected.
  • Metadata propagation: Flows correctly through all paths — offer message path context → channelmanager extraction → invoice builder → payment context → blinded payment path → Event::PaymentClaimable. The AsyncBolt12OfferContextBolt12OfferContext conversion in channelmanager.rs properly carries payment_metadata.
  • Pattern match exhaustiveness: All 9 pattern matches on OffersContext::InvoiceRequest across 6 files correctly handle the new payment_metadata field.
  • Test coverage: New tests router_modifies_payment_metadata_in_blinded_path, pays_for_offer_with_payment_metadata_in_invoice_request_context, and async_payment_delivers_payment_metadata cover the three main metadata injection paths.

@codecov
Copy link
Copy Markdown

codecov Bot commented May 1, 2026

Codecov Report

❌ Patch coverage is 85.26316% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.15%. Comparing base (42e198c) to head (b8375a7).
⚠️ Report is 4 commits behind head on main.

Files with missing lines Patch % Lines
lightning/src/util/ser.rs 74.07% 1 Missing and 6 partials ⚠️
lightning/src/blinded_path/payment.rs 71.42% 6 Missing ⚠️
lightning/src/util/test_utils.rs 91.66% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #4584   +/-   ##
=======================================
  Coverage   87.15%   87.15%           
=======================================
  Files         161      161           
  Lines      109251   109338   +87     
  Branches   109251   109338   +87     
=======================================
+ Hits        95215    95296   +81     
+ Misses      11560    11559    -1     
- Partials     2476     2483    +7     
Flag Coverage Δ
fuzzing-fake-hashes 31.19% <16.25%> (+0.03%) ⬆️
fuzzing-real-hashes 22.91% <1.25%> (-0.02%) ⬇️
tests 86.22% <85.26%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@TheBlueMatt TheBlueMatt force-pushed the 2026-04-bolt12-custom-data branch from ee6ba89 to 792846c Compare May 1, 2026 11:20
Similar to how BOLT 11 payments can use a `payment_metadata` to
provide arbitrary bytes in the invoice to be communicated back to
them when receiving, its useful to be able to provide some bytes
which are communicated back upon receiving a payment.

Here we do so in the BOLT 12 blinded path contexts, offering a
`BTreeMap<u64, Vec<u8>>` instead to enable more easily including
multiple sets of data.

Also note that a `Router` building a blinded path is allowed to
modify the `payment_metadata` without breaking the payment.

Tests by claude
@TheBlueMatt TheBlueMatt force-pushed the 2026-04-bolt12-custom-data branch from 792846c to 98cff64 Compare May 1, 2026 11:25
Similar to how BOLT 11 payments can use a `payment_metadata` to
provide arbitrary bytes in the invoice to be communicated back to
them when receiving, its useful to be able to provide some bytes
which are communicated back upon receiving a payment.

Here we do so in the BOLT 12 blinded message path contexts,
offering a `BTreeMap<u64, Vec<u8>>` instead to enable more easily
including multiple sets of data.

We don't yet wire it up to the public `ChannelManager` API, but do
allow selecting values for those using the manual
`OffersMessageFlow`.

Tests by claude
@ldk-reviews-bot
Copy link
Copy Markdown

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants