forgejo-admin/nuts
0
0
Fork 0
Code Issues 35 Pull requests 32 Projects Releases Packages Wiki Activity Actions

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

Merged
callebtc merged 3 commits from nut-05-state-and-preimage into main 2024-08-09 15:46:27 +00:00
Conversation 15 Commits 3 Files changed 2 +31 -25
callebtc commented 2024-06-17 11:20:04 +00:00 (Migrated from github.com)
Copy link

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:

  • nutshell (mint backwards compatible)
  • CDK (mint backwards compatible)
  • cashu-ts
  • nutmix
  • gonuts
  • ...
## 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 - [ ] ...
callebtc (Migrated from github.com) reviewed 2024-06-17 11:24:03 +00:00
05.md
@ -167,7 +169,7 @@ The settings for this nut indicate the supported method-unit pairs for melting.
}
callebtc (Migrated from github.com) commented 2024-06-17 11:24:03 +00:00
Copy link

We replace PostMeltBolt11Response with the new PostMeltQuoteBolt11Response which also includes the preimage.

We replace `PostMeltBolt11Response` with the new `PostMeltQuoteBolt11Response` which also includes the preimage.
elnosh (Migrated from github.com) reviewed 2024-06-17 14:50:51 +00:00
thesimplekid (Migrated from github.com) reviewed 2024-06-18 16:23:58 +00:00
05.md
@ -167,7 +169,7 @@ The settings for this nut indicate the supported method-unit pairs for melting.
}
thesimplekid (Migrated from github.com) commented 2024-06-18 16:23:58 +00:00
Copy link

github.com/cashubtc/nuts@971ad28477/08.md (L109-L123)

We'll need to update NUT-08 to reflect this

https://github.com/cashubtc/nuts/blob/971ad28477ed56ed9b98ee87c265d264d9c6d2bd/08.md?plain=1#L109-L123 We'll need to update NUT-08 to reflect this
thesimplekid (Migrated from github.com) reviewed 2024-06-18 18:43:22 +00:00
elnosh (Migrated from github.com) reviewed 2024-06-19 15:08:18 +00:00
minibits-cash commented 2024-06-20 06:47:04 +00:00 (Migrated from github.com)
Copy link

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

Ack. Lightning payments should be modelled as async by the mint api.
thesimplekid commented 2024-06-24 19:23:43 +00:00 (Migrated from github.com)
Copy link

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

Implemented in CDK https://github.com/cashubtc/cdk/pull/181, is backwards compatible
thesimplekid (Migrated from github.com) approved these changes 2024-06-25 10:40:11 +00:00
thesimplekid (Migrated from github.com) left a comment
Copy link

ACK 777886cd18

ACK 777886cd18ea2d7ca458f68f06fe046dffff4232
callebtc commented 2024-06-26 13:31:25 +00:00 (Migrated from github.com)
Copy link

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.

> 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.
👍 2
gudnuf commented 2024-06-28 21:05:25 +00:00 (Migrated from github.com)
Copy link

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

Should there be a `FAILED` state? Otherwise, if the lighting payment fails would the lifecycle of a quote be `UNPAID` -> `PENDING` -> `UNPAID`?
lescuer97 commented 2024-06-30 16:12:35 +00:00 (Migrated from github.com)
Copy link

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

I feel `PENDING` and `UNPAID` sound a little to close to each other. Maybe `PENDING` should be called something like `ONGOING`
lescuer97 commented 2024-07-02 18:06:12 +00:00 (Migrated from github.com)
Copy link

Implemented in Nutmix

Implemented in [Nutmix](https://github.com/lescuer97/nutmix/pull/50)
callebtc commented 2024-07-11 15:00:45 +00:00 (Migrated from github.com)
Copy link

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.

> 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.
👍 1
thesimplekid (Migrated from github.com) approved these changes 2024-07-26 16:39:49 +00:00
thesimplekid (Migrated from github.com) left a comment
Copy link

ACK 23db305935

ACK 23db30593543ea453592e3314fb5e96c0b7f0654
callebtc commented 2024-08-09 15:46:47 +00:00 (Migrated from github.com)
Copy link

LFG

LFG
Sign in to join this conversation.
Reviewers
No reviewers
thesimplekid
Labels
Clear labels   
breaking change
This issue/PR entails breaking changes

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
enhancement
New feature or request

  
needs discussion
Needs more discussion

  
needs implementation
Needs a reference implementation

  
new nut
A new protocol NUT

  
ready
Ready to merge

  
wallet-only
A change that affects only wallets

No labels
breaking change
bug
documentation
enhancement
needs discussion
needs implementation
new nut
ready
wallet-only
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo-admin/nuts!136
No description provided.