From 6ade8b4fd1acac13d978ecd237459eddbadf5d5a Mon Sep 17 00:00:00 2001 From: Rob Woodgate Date: Mon, 15 Jun 2026 12:07:53 +0100 Subject: [PATCH] feat(nut04/05): widen common quote structs for custom payment methods Consolidates review feedback on the generic payment method PR. Scoped to the delta NOT covered by #377 (accounting fields) or #387 (method), so those can merge independently: - common mint quote request: optional amount, description, pubkey - common melt quote request: optional amount - common mint quote response: expiry, optional pubkey - common melt quote response: request, optional fee_reserve - custom mint quotes MUST carry the accounting fields - custom melt quotes MUST use the standard UNPAID/PENDING/PAID states --- 04.md | 14 ++++++++++---- 05.md | 11 ++++++++--- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/04.md b/04.md index 46930842..401409af 100644 --- a/04.md +++ b/04.md @@ -40,11 +40,16 @@ Depending on the payment method, the request structure may vary, but all methods ```json { - "unit": + "unit": , + "amount": , // Optional + "description": , // Optional + "pubkey": // Optional, NUT-20 // Additional method-specific fields may be required } ``` +`amount`, `description` and `pubkey` are common optional fields; method-specific NUTs make them required or ignore them as needed (e.g. NUT-23 requires `amount`, NUT-20 defines `pubkey`). + The mint `Bob` responds with a quote that includes some common fields for all methods: ```json @@ -52,11 +57,13 @@ The mint `Bob` responds with a quote that includes some common fields for all me "quote": , "request": , "unit": , + "expiry": , + "pubkey": // Optional // Additional method-specific fields will be included } ``` -Where `quote` is the quote ID, `request` is the payment request for the quote, and `unit` corresponds to the value provided in the request. +Where `quote` is the quote ID, `request` is the payment request for the quote, `unit` corresponds to the value provided in the request, and `expiry` is the Unix timestamp until which the quote is valid (`null` if it does not expire). > [!CAUTION] > @@ -109,8 +116,7 @@ Payment methods not specified in a dedicated NUT can be supported as custom paym For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT. -The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT. - +The mint responds with the common mint quote response format and **MUST** include the `amount_paid`, `amount_issued` and `updated_at` accounting fields. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields are defined by the method-specific NUT. ### Method-Specific Fields diff --git a/05.md b/05.md index 52c606d6..0ae20973 100644 --- a/05.md +++ b/05.md @@ -46,25 +46,30 @@ Depending on the payment method, the request structure may vary, but all methods ```json { "request": , - "unit": + "unit": , + "amount": // Optional // Additional method-specific fields will be required } ``` +`amount` is a common optional field; method-specific NUTs make it required or ignore it as needed (e.g. NUT-30 requires `amount` for onchain melts). + The mint `Bob` responds with a quote that includes some common fields for all methods: ```json { "quote": , + "request": , "amount": , "unit": , + "fee_reserve": , // Optional "state": , "expiry": // Additional method-specific fields will be included } ``` -Where `quote` is the quote ID, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid. +Where `quote` is the quote ID, `request` is the method-specific payment routing target, `amount` and `unit` the amount and unit that need to be provided, `fee_reserve` is the additional fee reserve for using the method (the wallet provides proofs covering at least `amount + fee_reserve + fee`, where `fee` is the keyset input fee per [NUT-02][02]), and `expiry` is the Unix timestamp until which the melt quote is valid. `state` is an enum string field with possible values `"UNPAID"`, `"PENDING"`, `"PAID"`: @@ -211,7 +216,7 @@ Payment methods not specified in a dedicated NUT can be supported as custom paym For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with. -The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT. +The mint responds with the common melt quote response format, using the standard `state` values (`"UNPAID"`, `"PENDING"`, `"PAID"`). Method-specific fields are defined by the method-specific NUT. ### Websocket Notifications