feat: async melt requests

[a1denvalu3]

Summary

This PR adds support for prefer_async option in the POST /v1/melt/bolt11 request body. If a request contains this option set to true, the Mint no longer blocks until the operation is completed, but rather it schedules a task for the backend and returns immediately with a PENDING melt quote response.

Relevant specification PR is here.

Changes

• Added prefer_async field to PostMeltRequest model.
• Updated Wallet.melt to support prefer_async argument.
• Updated Mint's POST /v1/melt/bolt11 endpoint to handle prefer_async from the request body.

[codecov]

Codecov Report

❌ Patch coverage is 84.12698% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.21%. Comparing base (a5f950a) to head (572ece8).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
cashu/mint/ledger.py	85.96%	8 Missing ⚠️
cashu/mint/router.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #801      +/-   ##
==========================================
+ Coverage   61.12%   64.21%   +3.08%     
==========================================
  Files          89       90       +1     
  Lines       10565    10875     +310     
==========================================
+ Hits         6458     6983     +525     
+ Misses       4107     3892     -215     

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

[TheRealCheebs]

LGTM

[TheRealCheebs]

I might add a comment to clarify that internal melts are always processed synchronously, ignoring the prefer_async header. Even though the synchronous processing is acceptable per the RFC it might be unexpected given we are signaling support for the header now.

[callebtc]

I might add a comment to clarify that internal melts are always processed synchronously, ignoring the prefer_async header. Even though the synchronous processing is acceptable per the RFC it might be unexpected given we are signaling support for the header now.

yes we could, but the support for async doesn't mean that the mint will always honor the request. I'm thinking about whether it makes sense to process transactions synchronously up to, say, 2s time and return the PENDING if it hasn't resolved in that time or not.

[callebtc]

found an issue (likely race condition) that causes a db exception when you call get_melt_quote(). we need to figure out why and should throw the error in the mint rather than in the database. will get back to this.

[TheRealCheebs]

I might add a comment to clarify that internal melts are always processed synchronously, ignoring the prefer_async header. Even though the synchronous processing is acceptable per the RFC it might be unexpected given we are signaling support for the header now.

yes we could, but the support for async doesn't mean that the mint will always honor the request. I'm thinking about whether it makes sense to process transactions synchronously up to, say, 2s time and return the PENDING if it hasn't resolved in that time or not.

2s probably sounds reasonable. I had just been thinking about the slog of defining SLAs and communicating those out in my past life. It might be good to set some basic SLA goals we can unify around for mints in the larger space. Cashu is pretty good about defining everything in specs and setting out expectations.

I tend to error on the side of being overly verbose around these kinds of things. Its nice for a consumer to be able to build against expectations for the final end user, and everything starts to add up.

[a1denvalu3]

found an issue (likely race condition) that causes a db exception when you call get_melt_quote(). we need to figure out why and should throw the error in the mint rather than in the database. will get back to this.

I have fixed this.

[minibits-cash]

Sorry I am a little late to the discussion (if the NUT update would be still in the making I'd likely propose to have sync or async as a property of a melt method, to avoid all optionality here). Now with the custom header in place, I'd vote for having either sync or async behavior depending on header - and just handle internal bolt11 melts as async from outside POV if that's what wallet asked for.

The melt handling from wallet POV is already now full of traps and limit the number of possible behaviors would be a good choice.

[a1denvalu3]

@minibits-cash

It is already merged.

[a1denvalu3]

I have refactored the code to use request body for prefer_async options.

[a1denvalu3]

Updated the implementation to provide prefer_async field directly in PostMeltRequest body.

[robwoodgate]

@a1denvalu3 - are you going to add the wallet cli flag support etc from #887?