Feature/xpay payment description

[Nazarevsky]

Resolves #8514

Problem

xpay RPC call sends funds using Bolt11 or Bolt12 invoices provided. According to Bolt12, Bolt12 invoices support providing descriptions for invoices ('description' field) and messages to a payee ('payer_note' field).

xpay has a couple of RPC calls (like fetchinvoice or create_invoice) under the hood which already have a corresponding logic for sending a custom message to a payee (using payer_note field). However, xpay does not have a field to provide payment description.

Changes

• added payer_note filed to xpay RPC call;
• updated schema;
• added test case with payer_note defined.

Important

26.04 FREEZE March 11th: Non-bugfix PRs not ready by this date will wait for 26.06.

RC1 is scheduled on March 23rd

The final release is scheduled for April 15th.

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

• The changelog has been updated in the relevant commit(s) according to the guidelines.
• Tests have been added or modified to reflect the changes.
• Documentation has been reviewed and updated as needed.
• Related issues have been listed and linked, including any that this PR closes.
• Important All PRs must consider how to reverse any persistent changes for tools/lightning-downgrade

[ShahanaFarooqui]

@Nazarevsky Thanks for the PR! Since this is your first contribution, I’m being a bit more nitpicky about commit structure. Even if this one doesn’t end up being merged for the reason below, this review should be useful as a reference for future PRs.

That said, I wanted to better understand whether this PR serves its intended purpose. Don’t the existing invoice.description and fetchinvoice.payer_note already cover this use case? A node can already inspect these via listinvoices. How is the payer_note sent via xpay received on the other node? Adding @Lagrang3 in case I’ve missed anything.

[ShahanaFarooqui]

The CI is currently failing due to version mismatch in your grpcio. Please downgrade your local grpcio (uv pip install grpcio==1.75.1).

[ShahanaFarooqui]

nit: To keep the formatting consistent and avoid tabs/spaces alignment issues (especially between editors and the GitHub UI), could we format this to match the existing tab-based style?

[ShahanaFarooqui]

Mismatched alignment.

[Nazarevsky]

@Nazarevsky Thanks for the PR! Since this is your first contribution, I’m being a bit more nitpicky about commit structure. Even if this one doesn’t end up being merged for the reason below, this review should be useful as a reference for future PRs.

That said, I wanted to better understand whether this PR serves its intended purpose. Don’t the existing invoice.description and fetchinvoice.payer_note already cover this use case? A node can already inspect these via listinvoices. How is the payer_note sent via xpay received on the other node? Adding @Lagrang3 in case I’ve missed anything.

Thank you @ShahanaFarooqui for comments!

I've updated my PR description a bit about my changes. Nevertheless, I'd like to answer your questions here.

I think that invoice.description is a bit different because it provides a message to a payer. Basically, I'd say that it is rather an invoice description then payment description unlike payer_note. As you mentioned, fetchinvoice.payer_note is indeed exists and a corresponding logic for sending payer_note is implemented. However, no corresponding field in xpay for sending custom messages provided.