[feature]: "standard" encoding for invoice metadata

[positiveblue]

Problem/Case Scenario

Some services are interested in signaling that an invoice is a hodl invoice, indicating it is not intended to be resolved immediately.

Currently, there is no standardized method to encode this information directly within the invoice payment request. The objective is to improve user experience (UX) by ensuring wallets can access this information and effectively communicate it to users during the payment process.

In this specific case, iIf a wallet identifies an invoice as a HODL invoice, it could notify the user with a message such as:

This is a hodl invoice, settlement may take up to X hours.

Relevant context

Invoices already possess a Metadata field, which, despite being underutilized in practice, offers potential for this use case. The field, currently just a series of bytes and lacks a standardized encoding format.

Given the limited size for encoded invoices, it is crucial to avoid encoding methods like JSON that consume excessive space.

We propose utilizing the TLV (Type-Length-Value) format, already prevalent in node-to-node communication. TLV uses 2 bytes for type and length (so at least 4 types per field), we recognize that this may be excessive and are open to modifying the encoding if necessary in the future but by now it may be ok.

Proposed Solution

Our proposal is to add a feature bit (custom range) to signal support for "TLV invoice metadata encoding." This feature bit would be incorporated into the invoice set. Nodes supporting this flag would employ TLV encoding for the invoice.metadata field.

Additionally, we propose introducing a Type for "feature flags". That type would be use in the metadata field. It would be a bitmap with a specific bit indicating "HODL INVOICE."

Alternative/Discarded Solutions

Feature Bit Overloading: One option is to introduce a feature bit within the InvoiceSet to indicate a HODL invoice. However, this approach could potentially overload the intended use of feature bits in invoices, which currently focuses on communicating the capabilities required or supported by the receiver node.

Invoice Tagged Fields: Another possibility is leveraging Invoice Tagged Fields to add an "invoice flags" field. While this is a viable alternative, it could potentially disrupt existing libraries and may require a proposal and approval in the specification before implementation.

Implementation and Future Considerations

This feature can be implemented incrementally, requiring only the sender and receiver to support it initially. This approach allows for testing and refinement in real-world scenarios without immediate specification changes.

If successful, this feature could be submitted as a bLIP/BOLT for broader adoption and formal integration into the Lightning Network specifications.

[kaloudis]

This would go a long way in helping improve wallet UX for hodl invoices

[Perlover]

I think the solution is better implemented differently.

We need to add a signaling message to the protocol of lightning in a onion packet, like we do with error messages or with delivering a payment preimage back to the sender.

It should be possible for the payee to send a message to the sender that all HTLCs have been received, but it now takes time for the HODL invoice to be executed. Upon receiving such a message, the wallet should notify the user and send the payment to pending status.

Adding fields to an invoice that it is a HODL makes no sense, since at this point you still can't distinguish between when payments are in transit but have not yet arrived and when they have arrived. And making an assumption that if a payment or parts of it are in transit and then you have to wait for the service to arrive is not correct. The payment may turn out to be stuck for another reason, and the user will be misinformed by his wallet that the process of service provision is already in progress.

[TonyGiorgio]

This should be a BLIP.

[positiveblue]

@Perlover

I think the solution is better implemented differently. We need to add a signaling message to the protocol of lightning in a onion packet, like we do with error messages or with delivering a payment preimage back to the sender.

That would be even better. This information can be passed to routing nodes if we think that this is something that they need to take into consideration before forwarding a payment. However, that change is a network wide one and I do not think it makes sense to push for it right now.

Adding fields to an invoice that it is a HODL makes no sense, since at this point you still can't distinguish between when payments are in transit but have not yet arrived and when they have arrived.

What we are trying to achieve here is just a way for the receiver node to signal that this is a hodl invoice in the encoded invoice. Why? So wallets can tell the user "this may take some time to be resolved".

The payment may turn out to be stuck for another reason, and the user will be misinformed by his wallet that the process of service provision is already in progress.

Totally agree,. However this is out of the scope of what we are trying to fix here.

@TonyGiorgio

This should be a BLIP.

Yes, that is the plan, but first I would like to develop and see it working on the wild for a while before putting any effort on the "standardizing process"

[TonyGiorgio]

Yes, that is the plan, but first I would like to develop and see it working on the wild for a while before putting any effort on the "standardizing process"

I get it, but this goes beyond just LND and other wallets will have opinions. Spending effort to build it in the "LND only" way with little regards to others could also show to be wasted efforts. Up to you at the end of the day but there's more to consider here than just LND.

[daywalker90]

FYI: CLN only has hodl invoice support via plugins and my holdinvoice plugin just got added to the plugins repo. That said i currently have very little knowledge about TLV's and i don't see a trivial way to use them in that plugin, but i will try to learn more.

[positiveblue]

I'll make sure I tag you when creating the bLIP @daywalker90

TLVs are the encoding for the wire encoding in the LN, which means that we can use the packages that the implementations already have in multiple languages (go, rust, c, etc..) "for free"

[RajGoodF]

Since LND has a separate command to create hodl invoice, surely some metadata should be added of the invoice being a huddle, so all the wallet clients can decode and detect the hodl invoice and process it in that manner. Currently for wallet builders are us, its very tough to handle hodl invoices and make robust system, especially when customers bombard wallets with invoices from services like Robosats.