NUT-05: add new `state` enum, deprecate `paid`. NUT-05 + NUT-08: use `PostMeltQuoteBolt11Response` instead of `PostMeltBolt11Response`

callebtc commented 3 months ago

What

New enum field: `state`

This change to NUT-05 deprecates the paid field to PostMeltQuoteBolt11Response and replaces it with a state field that is a string enum with three possible values: UNPAID, PENDING, PAID.

"UNPAID" means that the request has not been paid yet.
"PENDING" means that the request is currently being paid.
"PAID" means that the request has been paid successfully.

New return type for `/v1/melt/bolt11`

We also replace PostMeltBolt11Response by PostMeltQuoteBolt11Response as the response of POST /v1/melt/bolt11 but in a backwards-compatible way.

This means

we add a new field payment_preimage to PostMeltQuoteBolt11Response, which holds the bolt11 preimage after a successful payment
to adjust for NUT-08, we add change to PostMeltQuoteBolt11Response, which returns overspent Lightning fees

Why

This change enables wallet to know whether a Lightning payment is still in flight, if the user closes the wallet during a payment. When the wallet comes back online, it can request the melt quote via GET /v1/melt/quote/bolt11/{quote_id} and check its state.

If the payment was successful in the mean time, the wallet also finds payment_preimage there.
If the mint supports NUT-08, the wallet also finds the change and can unblind the response. Previously, wallets would have to restore these tokens to get the overpaid fees back if the payment was interrupted.

Implementation

Mints

add new state field to PostMeltQuoteBolt11Response
keep the paid field around until all wallets update
replace PostMeltBolt11Response by PostMeltQuoteBolt11Response
which means, add payment_preimage
make according changes to NUT-08: add change to PostMeltQuoteBolt11Response
return PostMeltQuoteBolt11Response for POST /v1/melt/bolt11

Wallets

replace the paid field with state and check it instead

As long as paid is kept around, wallets can still function the same way as before, also when the POST /v1/melt/bolt11 is changed (since JSON is "backwards compatible" to new fields).

Tracking progress:

[x] nutshell (mint backwards compatible)
[x] CDK (mint backwards compatible)
[x] cashu-ts
[x] nutmix
[x] gonuts
[ ] ...

minibits-cash commented 3 months ago

Ack. Lightning payments should be modelled as async by the mint api.

thesimplekid commented 3 months ago

Implemented in CDK https://github.com/cashubtc/cdk/pull/181, is backwards compatible

callebtc commented 3 months ago

Ack. Lightning payments should be modelled as async by the mint api.

I suggest we add a new endpoint in a different NUT-05 PR that is async (returns immediately) so we can have both. This should be very easy to add to mints.

gudnuf commented 3 months ago

Should there be a FAILED state? Otherwise, if the lighting payment fails would the lifecycle of a quote be UNPAID -> PENDING -> UNPAID?

lescuer97 commented 3 months ago

I feel PENDING and UNPAID sound a little to close to each other. Maybe PENDING should be called something like ONGOING

lescuer97 commented 3 months ago

Implemented in Nutmix

callebtc commented 2 months ago

Should there be a FAILED state? Otherwise, if the lighting payment fails would the lifecycle of a quote be UNPAID -> PENDING -> UNPAID?

Correct, it would go back to UNPAID if it fails.

callebtc commented 1 month ago

LFG

cashubtc / nuts