diff --git a/19.md b/19.md index 1da92905..9ad9d7dd 100644 --- a/19.md +++ b/19.md @@ -1,4 +1,5 @@ # NUT-19: Signature on Mint Quote + `optional` This NUT defines a protocol extension that enables signature-based authentication for mint quote redemption. When requesting a mint quote, clients can provide a public key. The mint will then require a valid signature from the corresponding secret key before processing the mint. @@ -7,6 +8,7 @@ Caution: If the mint does not support this NUT, anyone with the mint quote id wi # Mint quote To request a mint quote, the wallet of `Alice` makes a `POST /v1/mint/quote/{method}` request where `method` is the payment method requested (here `bolt11`). + ```http POST https://mint.host:3338/v1/mint/quote/bolt11 ``` @@ -21,8 +23,10 @@ The wallet of `Alice` includes the following `PostMintQuoteBolt11Request` data i "pubkey": <-- New } ``` + with the requested `amount` and the `unit`. An optional `description` can be passed if the mint signals support for it in `MintMethodSetting`. `pubkey` is the public key that will be required for signature verification during the minting process. The mint will only mint ecash after receiving a valid signature from the corresponding private key in the `PostMintRequest`. The mint `Bob` then responds with a `PostMintQuoteBolt11Response`: + ```json { "quote": , @@ -34,11 +38,11 @@ The mint `Bob` then responds with a `PostMintQuoteBolt11Response`: Where `quote` is the quote ID and `request` is the payment request to fulfill. `expiry` is the Unix timestamp until which the mint quote is valid. `state` is an enum string field with possible values `"UNPAID"`, `"PAID"`, `"ISSUED"`: + - `"UNPAID"` means that the quote's request has not been paid yet. - `"PAID"` means that the request has been paid. - `"ISSUED"` means that the quote has already been issued. - ## Example Request of `Alice` with curl: @@ -59,14 +63,19 @@ Response of `Bob`: ``` #### Signature scheme + To mint a quote where a public key was provided, the minter needs to include signatures in the `PostMintBolt11Request`. We use `libsecp256k1`'s serialized 64-byte Schnorr signatures on the SHA256 hash of the message to sign. The message to sign is the field `PostMintQuoteBolt11Response.quote`. # Minting tokens + After requesting a mint quote and paying the request, the wallet proceeds with minting new tokens by calling the `POST /v1/mint/{method}` endpoint where `method` is the payment method requested (here `bolt11`). + ```http POST https://mint.host:3338/v1/mint/bolt11 ``` + The wallet `Alice` includes the following `PostMintBolt11Request` data in its request + ```json { "quote": , @@ -74,15 +83,17 @@ The wallet `Alice` includes the following `PostMintBolt11Request` data in its re "witness": <-- New } ``` + with the `quote` being the quote ID from the previous step and `outputs` being `BlindedMessages` (see [NUT-00][00]) that the wallet requests signatures on whose sum is `amount` as requested in the quote. `witness` is the signature on the mint quote id as defined above. The mint `Bob` then responds with a `PostMintBolt11Response`: + ```json { "signatures": } ``` -where `signatures` is an array of blind signatures on the outputs. +where `signatures` is an array of blind signatures on the outputs. ## Example @@ -109,7 +120,6 @@ curl -X POST https://mint.host:3338/v1/mint/bolt11 -H "Content-Type: application }' ``` - Response of `Bob`: ```json @@ -131,9 +141,10 @@ Response of `Bob`: If the invoice was not paid yet, `Bob` responds with an error. In that case, `Alice` **CAN** repeat the same request until the Lightning invoice is settled, as in NUT04. If `Alice` does not include a witness on the `PostMintBolt11Request` but did include a `pubkey` in the `PostMintBolt11QuoteRequest` the `Bob` **MUST** respond with an error, `Alice` **CAN** repeat the request with a witness in order to mint the ecash. - ## Settings + The settings for this NUT indicate the support for requiring a signature before minting. They are part of the info response of the mint ([NUT-06][06]) which in this case reads + ```json { "19": { @@ -141,4 +152,3 @@ The settings for this NUT indicate the support for requiring a signature before } } ``` - diff --git a/error_codes.md b/error_codes.md index 74725689..76b2fcde 100644 --- a/error_codes.md +++ b/error_codes.md @@ -16,7 +16,7 @@ | 20005 | Quote is pending | [NUT-04][04], [NUT-05][05] | | 20006 | Invoice already paid | [NUT-05][05] | | 20007 | Quote is expired | [NUT-04][04], [NUT-05][05] | -| 20008 | Witness not provided for mint quote | [NUT-19][19] | +| 20008 | Witness not provided for mint quote | [NUT-19][19] | [00]: 00.md [01]: 01.md