feat: Implement NUT-05: Melting Tokens

[AbdelStark]

Implement NUT-05: Melting Tokens

Issue Description

We need to implement the melting operation as described in NUT-05 of the Cashu protocol. This operation allows users to spend their tokens by requesting the mint to make payments on their behalf, typically via the Lightning Network.

Objectives

1. Implement the melt quote endpoint in the Gakimint mint.
2. Implement the melting endpoint in the Gakimint mint.
3. Update the wallet CLI to support melting operations.
4. Ensure the implementation follows the Cashu protocol specifications.

Tasks

• Implement the melt quote endpoint in the mint:

  • Create a new route POST /v1/melt/quote/bolt11 in the MintController.
  • Implement the melt quote logic in the Mint module.
  • Handle Lightning invoice parsing and fee estimation.

• Implement the melting endpoint in the mint:

  • Create a new route POST /v1/melt/bolt11 in the MintController.
  • Implement the melting logic in the Mint module.
  • Validate input proofs.
  • Execute Lightning payments.
  • Handle payment states (UNPAID, PENDING, PAID).

• Update the wallet CLI:

  • Implement a command to request a melt quote.
  • Implement a command to execute a melt operation.
  • Handle proper token selection for melting.

• Implement security measures:

  • Ensure the sum of input amounts is sufficient for the melt amount plus fee reserve.
  • Verify that input proofs are valid and not already spent.
  • Implement proper error handling for various scenarios.

• Testing:

  • Write unit tests for the melt quote and melting functionality in the mint.
  • Create integration tests for the complete melting process.
  • Test various scenarios: successful melts, failed payments, timeout handling.

• Documentation:

  • Update API documentation to include the new melt quote and melting endpoints.
  • Add examples of how to use the melting operation in the wallet CLI documentation.

API Specification

Melt Quote Request

POST /v1/melt/quote/bolt11

Request body (PostMeltQuoteBolt11Request):

{
  "request": "<bolt11_invoice>",
  "unit": "sat"
}

Melt Quote Response

Response body (PostMeltQuoteBolt11Response):

{
  "quote": "<quote_id>",
  "amount": <int>,
  "fee_reserve": <int>,
  "state": "<UNPAID|PENDING|PAID>",
  "expiry": <int>,
  "payment_preimage": "<preimage>|null"
}

Melting Request

POST /v1/melt/bolt11

Request body (PostMeltBolt11Request):

{
  "quote": "<quote_id>",
  "inputs": [<Proof>]
}

Considerations

• Performance: The melting operation should handle potential delays in Lightning payments.
• Error Handling: Implement robust error handling for various scenarios (e.g., failed payments, timeouts).
• Security: Ensure that proofs are properly invalidated after successful melts.
• Lightning Network Integration: This feature depends on proper Lightning Network integration (see related issue).

Acceptance Criteria

• The mint can successfully process melt quote requests, providing accurate fee estimates.
• The mint can execute melting operations, making Lightning payments and invalidating input proofs.
• The wallet CLI can request melt quotes and execute melting operations.
• All edge cases are handled properly (e.g., insufficient inputs, failed payments).
• The implementation passes all unit and integration tests.
• The API documentation is updated to reflect the new melt quote and melting endpoints.

Resources

• NUT-05 Specification
• Lightning Network Integration Issue (link to the related Lightning integration issue)

Estimated Effort

High: This feature involves complex operations including Lightning Network payments and careful token management.

Priority

High: Melting tokens is a core feature of the Cashu protocol, allowing users to spend their tokens.

[MSghais]

Can I work on it, please?
Let me check the spec of the melting tokens feature of the Mint, I can give an ETA asap