NUT08: mint fee return

05.md

@@ -9,7 +9,7 @@ Melting tokens is the opposite of minting tokens (see [NUT-04][04]). Like mintin
 
 In the first request the wallet asks the mint for a quote for a `request` it wants paid by the mint and the `unit` the wallet would like to spend as inputs. The mint responds with a quote that includes a `quote` id and an `amount` the mint demands in the requested unit. For the method `bolt11`, the mint includes a `fee_reserve` field indicating the reserve fee for a Lightning payment.
 
-In the second request, the wallet includes the `quote` id and provides `inputs` that sum up to `amount+fee_reserve` in the first response. For the method `bolt11`, the wallet can also include `outputs` in order for the mint to return overpaid Lightning fees (see [NUT-08][08]). The mint responds with a payment status `paid` and a `proof` of payment. If the request included `outputs`, the mint may respond with `change` for the overpaid fees (see [NUT-08][08]).
+In the second request, the wallet includes the `quote` id and provides `inputs` that sum up to `amount+fee+fee_reserve` in the first response. For the method `bolt11`, the wallet can also include `outputs` in order for the mint to return overpaid Lightning fees (see [NUT-08][08]). The mint responds with a payment status `paid` and a `proof` of payment. If the request included `outputs`, the mint may respond with `change` for the overpaid fees (see [NUT-08][08]).
 
 We limit this document to mint quotes of `unit="sat"` and `method="bolt11"` which requests a bolt11 Lightning payment (typically paid by the mint from its Bitcoin reserves) using ecash denominated in Satoshis. 
 
@@ -44,7 +44,7 @@ Here, `request` is the bolt11 Lightning invoice to be paid and `unit` is the uni
   "expiry": <int>
 }
 ```
-Where `quote` is the quote ID, `amount` the amount that needs to be provided, and `fee_reserve` the additional fee reserve that is required. The mint expects `Alice` to include `Proofs` of *at least* `total_amount = amount + fee_reserve`. `paid` indicates whether the request has been paid and `expiry` is the Unix timestamp until which the melt quote is valid.
+Where `quote` is the quote ID, `amount` the amount that needs to be provided, and `fee_reserve` the additional fee reserve that is required. The mint expects `Alice` to include `Proofs` of *at least* `total_amount = amount + fee + fee_reserve`. `paid` indicates whether the request has been paid and `expiry` is the Unix timestamp until which the melt quote is valid.
 
 ## Example
 
@@ -88,7 +88,7 @@ curl -X GET http://localhost:3338/v1/melt/quote/bolt11/TRmjduhIsPxd...
 
 # Melting tokens
 
-Now that `Alice` knows what the total amount is (`amount + fee_reserve`) in her requested `unit`, she can proceed for melting tokens for which a payment will be executed by the mint. She calls the `POST /v1/melt/{method}` endpoint where `method` is the payment method requested (here `bolt11`).
+Now that `Alice` knows what the total amount is (`amount + fee + fee_reserve`) in her requested `unit`, she can proceed for melting tokens for which a payment will be executed by the mint. She calls the `POST /v1/melt/{method}` endpoint where `method` is the payment method requested (here `bolt11`).
 
 ```http
 POST https://mint.host:3338/v1/melt/bolt11
@@ -105,7 +105,7 @@ The wallet of `Alice` includes the following `PostMeltBolt11Request` data in its
 }
 ```
 
-Here, `quote` is the melt quote ID to be paid and `inputs` are the proofs with a total amount of at least `amount + fee_reserve` (see previous melt quote response).
+Here, `quote` is the melt quote ID to be paid and `inputs` are the proofs with a total amount of at least `amount + fee + fee_reserve` (see previous melt quote response).
 
 The mint `Bob` then responds with a `PostMeltBolt11Response`:
 

08.md

@@ -28,13 +28,13 @@ def calculate_number_of_blank_outputs(fee_reserve_sat: int) -> int:
 The wallet wants to pay an invoice with `amount := 100 000 sat` and determines by asking the mint that `fee_reserve` is `1000 sats`. The wallet then provides `101 000 sat` worth of proofs and 10 blank `outputs` to make the payment (since `ceil(log2(1000))=ceil(9.96..)=10`). The mint pays the invoice and determines that the actual fee was `100 sat`, i.e, the overpaid fee to return is `fee_return = 900 sat`. The mint splits the amount `900` into summands of `2^n` which is `4, 128, 256, 512`. The mint inserts these amounts into the blank `outputs` it received form the wallet and generates 4 new promises. The mint then returns these `BlindSignature`s to the wallet together with the successful payment status.
 
 ## Wallet flow
-The wallet asks the mint for the `fee_reserve` for paying a specific bolt11 invoice of value `amount` by calling `POST /v1/melt/quote` as described in [NUT-05][05]. The wallet then provides a `PostMeltBolt11Request` to `POST /v1/melt/bolt11` that has (1) proofs of the value `amount+fee_reserve`, (2) the bolt11 invoice to be paid, and finally, as a new entry, (3) a field `outputs` that has `n_blank_outputs` blinded messages that are generated before the payment attempt to receive potential overpaid fees back to her.
+The wallet asks the mint for the `fee_reserve` for paying a specific bolt11 invoice of value `amount` by calling `POST /v1/melt/quote` as described in [NUT-05][05]. The wallet then provides a `PostMeltBolt11Request` to `POST /v1/melt/bolt11` that has (1) proofs of the value `amount+fee+fee_reserve`, (2) the bolt11 invoice to be paid, and finally, as a new entry, (3) a field `outputs` that has `n_blank_outputs` blinded messages that are generated before the payment attempt to receive potential overpaid fees back to her.
 
 ## Mint flow
 
-Here we describe how the mint generates `BlindSignature`s for the overpaid fees. The mint `Bob` returns in `PostMeltBolt11Response` the field `change` **ONLY IF** `Alice` has previously provided `outputs` for the change **AND** if the Lightning `actual_fees` were smaller than the `fee_reserve`.
+Here we describe how the mint generates `BlindSignature`s for the overpaid fees. The mint `Bob` returns in `PostMeltBolt11Response` the field `change` **ONLY IF** `Alice` has previously provided `outputs` for the change **AND** if the the `inputs` provided were greater then the `total_amount_paid - fees`.
 
-If the `overpaid_fees = fee_reserve - actual_fees` is positive, `Bob` decomposes it to values of `2^n` (as in [NUT-00][00]) and then imprints them into the `blank_outputs` provided by `Alice`. 
+If the `overpaid_fees = input_amount - fees - total_paid` is positive, `Bob` decomposes it to values of `2^n` (as in [NUT-00][00]) and then imprints them into the `blank_outputs` provided by `Alice`. 
 
 `Bob` then signs these blank outputs (now with the imprinted amounts) and thus generates `BlindSignature`s. `Bob` then returns a payment status to the wallet, and, in addition, all blind signatures it generated for the overpaid fees.