Add a payment_metadata map in blinded * path contexts

[TheBlueMatt]

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.

[ldk-reviews-bot]

👋 Thanks for assigning @jkczyz 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.

[ldk-claude-review-bot]

I've thoroughly reviewed the entire PR diff, cross-referencing serialization macros, flow propagation, pattern match exhaustiveness, backward compatibility, and deserialization safety. All areas I previously flagged have been verified as resolved (typos fixed, doc references corrected).

After this comprehensive re-review, I found no new issues beyond those already covered by my prior inline comments.

No new issues found.

Prior inline comments status:

• lightning/src/blinded_path/message.rs:407 — "tighly" typo: verified fixed
• lightning/src/blinded_path/payment.rs:621 — "tighly" typo across all doc comments: verified fixed
• lightning/src/onion_message/messenger.rs:475 — OffersContext::StaticInvoiceRequested::payment_metadata doc reference: verified the actual code references OffersContext::InvoiceRequest::payment_metadata which is correct (my prior comment was based on a misread; the reference exists as a field on the InvoiceRequest variant)

Verification summary of key areas:

• TLV serialization: All payment_metadata fields use odd type 1 (backward-compatible optional). Ascending TLV order maintained in all structs/enums.
• (option, encoding) macro expansion: BigSizeKeyedMap<&BTreeMap<...>>, AccountableBool<&bool>, WithoutLength<&&Features> all have matching Writeable impls for the reference-based expansion path.
• BigSizeKeyedMap deserialization: Uses LengthReadable with LengthLimitedRead, bounding total bytes by TLV length. Duplicate keys rejected. No pre-allocation from declared count.
• Metadata propagation: Correct through all three paths — (1) offer message context → channelmanager extraction → payment context, (2) router override in create_blinded_payment_paths, (3) AsyncBolt12OfferContext → Bolt12OfferContext conversion for keysend.
• Pattern match exhaustiveness: All 9 pattern matches on OffersContext::InvoiceRequest and all constructions of the variant across 6 files correctly include payment_metadata.
• Test coverage: Three new tests cover the three main injection paths.

[codecov]

Codecov Report

❌ Patch coverage is 85.26316% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.23%. Comparing base (42e198c) to head (6bfdc0d).
⚠️ Report is 19 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%   86.23%   -0.92%     
==========================================
  Files         161      159       -2     
  Lines      109251   109248       -3     
  Branches   109251   109248       -3     
==========================================
- Hits        95215    94209    -1006     
- Misses      11560    12423     +863     
- Partials     2476     2616     +140     

Flag	Coverage Δ
fuzzing-fake-hashes	?
fuzzing-real-hashes	?
tests	86.23% <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.

[ldk-reviews-bot]

🔔 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.

[tnull]

Looks good, but it would be nice to provide a bit more ergonomic/self-descriptive types here. At the very least we should document what the semantics of the u64s are (or rather, that there are ~none and the user is free to set them).

Tagging @jkczyz as second reviewer on this.

[tnull]

See above: what are we expecting users to set the u64 to?

Shouldn't we rather use a dedicated PaymentMetadata type for this, or even an Option<Box<dyn Writeable>> or similar?

[TheBlueMatt]

Answered at #4584 (comment) but I do really want to force users into the K-V-map box here. Can do a type if we want but its a bit awkward that we have a separate BOLT 11 and BOLT 12 PaymentMetadata type...

[jkczyz]

The Box<dyn Writeable> would get a bit ugly at read time. You'd need to parameterize the onion message parsing with your types.

[jkczyz]

Why use a map? Wouldn't a user's wrapper struct be just as efficient encoding -- or could be even more efficient if each part is of a fixed length? Deserialization would be simpler, too, if they didn't need to iterate a map.

[TheBlueMatt]

The intention is both to force users to think about forward compatibility from day one (in the sense that its already a K-V) but also because we want to reserve some keys in LDK (eg in #4463).

[jkczyz]

The intention is both to force users to think about forward compatibility from day one (in the sense that its already a K-V)

Isn't that what using our serialization macros provide? Blinded paths are also not expected to be useable indefinitely, so the compatibility argument isn't as strong, IMO.

FWIW, the rationale given in the commit message only mentions composability.

but also because we want to reserve some keys in LDK (eg in #4463).

Wouldn't it be simpler to add a dedicated field for anything LDK-specific? Then we wouldn't need custom parsing / serialization logic (for each variant of PaymentContext) or need to worry about checking if users took a reserved type. This would need to be added somewhere in the code vs a simple declaration in the impl_writeable_tlv_based uses.