05.md

NUT-05: Melting tokens

mandatory author: calle

---

Melting tokens is the opposite of minting tokens (see NUT-04). To melt tokens, Alice's wallet sends Proofs to the mint Bob together with a bolt11 Lightning invoice that Alice wants to be paid. This is done using a POST /melt request with a JSON body to the mint. The Proofs included in the request will be burned by the mint and the mint will pay the invoice in exchange.

Alice needs to send two requests to Bob to make a Lightning payment: one request for checking the expected maximum fees, and one for making the actual payment. In the first request, Alice must check the expected maximum fee reserve with the mint by including a CheckFeesRequest JSON body with her request. In the second request, Alice must include a PostMeltRequest JSON body with Proofs that have at least the amount of the invoice to be paid.

Checking Lightning fees

The mint expects Alice to include Proofs of at least total_amount = amount + fee_reserve where amount is the amount to be paid with the Lightning invoice and fee_reserve is the maximum potential Lightning network fees for the payment. A wallet should first call the /checkfees endpoint to ask the mint what the expected maximum fee is by making a CheckFeesRequest POST request:

POST https://mint.host:3338/checkfees

With the data being of the form CheckFeesRequest:

{
  "pr": str
}

Here, pr is the bolt11 Lightning invoice to be paid.

With curl:

curl -X POST https://mint.host:3338/checkfees -d \
{
"pr": "lnbc100n1p3kdrv5sp5lpdxzghe5j67q..."
}

Response CheckFeesResponse from Bob:

{
"fee": int
}

Here, fee is the expected maximum fees in satoshis.

Paying the invoice

Now that Alice knows what the total_amount has to be, she can ask Bob to make a Lightning payment for her.

Request of Alice:

POST https://mint.host:3338/melt

⚠️ Attention: This call will block until the Lightning payment either succeeds or fails. This can take quite a long time in case the Lightning payment is slow. Make sure to use no (or a very long) timeout when making this call!

With the data being of the form PostMeltRequest:

{
  "proofs": 
    [
      Proof,
      ...
    ],
  "pr": str
}

Here, pr is the bolt11 invoice to be paid with an amount amount and proofs are the proofs with a total value of at least total_amount := amount + fee_reserve (see above).

With curl:

curl -X POST https://mint.host:3338/melt -d \
{
"proofs" : 
  [
    {
    "id": "DSAl9nvvyfva",
    "amount": 2,
    "secret": "S+tDfc1Lfsrb06zaRdVTed6Izg",
    "C": "0242b0fb43804d8ba9a64ceef249ad7a60f42c15fe6d4907238b05e857527832a3"
    },
    {
    ...
    }
  ],
"pr": "lnbc100n1p3kdrv5sp5lpdxzghe5j67q..."
}

Response PostMeltResponse from Bob:

{
"paid": true,
"preimage": "da225c115418671b64a67d1d9ea6a..."
}

If the paid==true, Alice's wallet SHOULD delete the Proofs from her database (or move them to a history). If paid==false, Alice can repeat the same request again until the payment is successful.