From 7399d178b1279ea9f74dad644b11189fa18af287 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Tue, 2 Jul 2024 17:22:46 +0100 Subject: [PATCH 1/3] NUT08: mint fee return --- 05.md | 6 +++--- 08.md | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/05.md b/05.md index be55a41..e775d7e 100644 --- a/05.md +++ b/05.md @@ -8,7 +8,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. @@ -94,7 +94,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 to 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 @@ -111,7 +111,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). Like before, the mint `Bob` then responds with a `PostMeltQuoteBolt11Response`. If the payment was successful, the `state` field is set to `"PAID"` and the response includes the `payment_preimage` field containing the payment secret of the bolt11 payment. diff --git a/08.md b/08.md index abb8d0f..dfcaf8a 100644 --- a/08.md +++ b/08.md @@ -27,14 +27,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 `PostMeltQuoteBolt11Response` 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. From 867ee4db03c515813e97457f53d1143a1d7335be Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 11 Sep 2024 09:13:38 +0100 Subject: [PATCH 2/3] chore: prettier --- 08.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/08.md b/08.md index dfcaf8a..691df2c 100644 --- a/08.md +++ b/08.md @@ -27,13 +27,14 @@ 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+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 the `inputs` provided were greater then the `total_amount_paid - fees`. -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`. +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. From a8aebe62d4d98e4b4048924c736954ddb28ff1e2 Mon Sep 17 00:00:00 2001 From: thesimplekid Date: Wed, 11 Sep 2024 09:17:01 +0100 Subject: [PATCH 3/3] update wording of fee --- 05.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/05.md b/05.md index e775d7e..507617f 100644 --- a/05.md +++ b/05.md @@ -8,7 +8,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+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 where `fee` is calculated from the keyset's `input_fee_ppk` as described in [NUT-02][02]. 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.