Align NUT-04 mint quote accounting with amount_paid / amount_issued by Egge21M · Pull Request #377 · cashubtc/nuts

Egge21M · 2026-05-24T06:09:43Z

This updates NUT-04 to make amount_paid and amount_issued the
canonical way to track mint quote accounting, matching the reusable
quote model already used by NUT-25 and NUT-30.

The deprecated state field is kept as an optional compatibility
field for single-use quotes, with derivation rules documented from
amount_paid and amount_issued. This also adds updated_at to mint
quote responses so clients can avoid applying stale quote updates.

Changes:

Define common amount_paid, amount_issued, and updated_at fields in
NUT-04 mint quote responses
Document mintable amount as amount_paid - amount_issued
Deprecate state while preserving compatibility guidance
Add stale-update handling guidance using updated_at
Update NUT-20, NUT-23, NUT-25, NUT-29, and NUT-30 examples/schemas
to match
- cdk: feat: align mint quote accounting with NUT-04 cdk#2119
- cashu-ts: feat(nut04/05)!: quote accounting and custom payment method base structs cashu-ts#698
- nutshell:

robwoodgate · 2026-05-25T15:14:30Z

The updated_at param is a good idea, both for monotonic state tracking as noted, as well as being potentially useful for tracking stalled or failed payments.

a1denvalu3 · 2026-05-26T07:05:16Z

Agreed.

robwoodgate

ACK

Egge21M · 2026-06-08T08:00:29Z

Chatted with some folks offline. They raised the point that the combination of amount_issued and amount_paid is already enough to allow monotonic state updates (e.g. new_amount_issued + new_amount_paid > old_amount_issued + old_amount_paid). However this is less explicit and mints should not have any issue adding updated_at.

Should I kick it, or keep it?

robwoodgate · 2026-06-08T13:01:54Z

Chatted with some folks offline. They raised the point that the combination of amount_issued and amount_paid is already enough to allow monotonic state updates (e.g. new_amount_issued + new_amount_paid > old_amount_issued + old_amount_paid). However this is less explicit and mints should not have any issue adding updated_at.

Should I kick it, or keep it?

I think it has utility - whilst the combination does tell you if the state has changed, it doesn't tell you WHEN.

So unless payload size is a concern, it might be more useful than not, esp for consumer apps.

Egge21M · 2026-06-13T19:21:13Z

Sign in to view

+
+For reusable quotes, no finite `state` can fully represent whether the quote may receive future payments. Wallets **MUST** use `amount_paid` and `amount_issued` to determine the currently mintable amount.
+
+Mints **MUST** update `updated_at` whenever `amount_paid` or `amount_issued` changes. Mints **SHOULD** ensure that `updated_at` monotonically increases for each quote, even if multiple updates occur within the same timestamp resolution. Wallets that receive multiple responses for the same quote **MUST NOT** replace locally stored quote data with a response whose `updated_at` is lower than the latest processed value for that quote. Wallets **MUST NOT** decrease locally stored `amount_paid` or `amount_issued` values based on stale responses.


TBH I am not sure how to handle this properly. This document is now written in a way that makes updated_at mandatory (e.g. Mints **MUST** include). Including this addition would mean covering off-spec mint behavior. Maybe the new fields should be added as optional an with SHOULD language instead?

On reflection you are right. Handling out of spec older mints is not the protocol's concern.

Ignore my suggestion - leave it as it was.

Implements cashubtc/nuts#377: amount_paid, amount_issued and updated_at become base mint quote response fields for every payment method. For mints that predate quote accounting, the amounts are derived from the legacy single-use state; conversely, a missing bolt11 state is derived from the accounting fields. updated_at is null when not reported. Generic mint quote responses now get base normalization (quote, request, unit, accounting) like melt quotes already did, and the wallet enforces the mintable amount (paid minus issued) for all methods, not just bolt12/onchain. BREAKING CHANGE: MintQuoteBaseResponse requires amount_paid, amount_issued and updated_at; non-conformant mint quote responses that previously passed through unvalidated now throw.

Consolidates review feedback on the generic payment method PR. Scoped to the delta NOT covered by cashubtc#377 (accounting fields) or cashubtc#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

thesimplekid · 2026-06-17T11:05:53Z

+  "amount_paid": <int>,
+  "amount_issued": <int>,
+  "updated_at": <int>,
+  "state": <str_enum[STATE]>, // Deprecated, optional


State should not be in nut04 that is in nut 23 as it is bolt11 specefic.

thesimplekid · 2026-06-17T11:06:07Z

+- `amount_paid` is the total amount that has been paid to the mint for this quote and is eligible for minting, denominated in `unit`
+- `amount_issued` is the total amount of ecash that has been issued for this quote, denominated in `unit`
+- `updated_at` is a Unix timestamp integer indicating when the quote was last updated
+- `state` is a deprecated compatibility field


Suggested change

- `state` is a deprecated compatibility field

thesimplekid · 2026-06-17T11:06:58Z

+
+`amount_paid` and `amount_issued` are the canonical way to track the state of a mint quote. The deprecated `state` field **SHOULD** be included for single-use quotes for compatibility with older clients. Wallets **SHOULD** use `amount_paid` and `amount_issued` instead of `state` whenever these fields are present.
+
+For single-use quotes, the deprecated finite `state` can be derived from `amount_paid` and `amount_issued`:
+
+- `"UNPAID"` if `amount_paid == 0` and `amount_issued == 0`
+- `"PAID"` if `amount_paid > amount_issued`
+- `"ISSUED"` if `amount_paid == amount_issued` and `amount_issued > 0`
+
+For reusable quotes, no finite `state` can fully represent whether the quote may receive future payments. Wallets **MUST** use `amount_paid` and `amount_issued` to determine the currently mintable amount.


Nut23 specefic

robwoodgate · 2026-06-17T13:09:00Z

Cashu-TS implements in:

feat(nut04/05)!: quote accounting and custom payment method base structs cashu-ts#693

Implement the mint quote accounting changes from cashubtc/nuts#377 by exposing amount_paid, amount_issued, and updated_at on mint quote responses. Keep the deprecated state field only for BOLT11 compatibility while deriving local quote state from the canonical counters for all mint methods. Persist updated_at in wallet quote storage so stale responses cannot move amount_paid or amount_issued backwards.

robwoodgate · 2026-06-18T19:06:08Z

Cashu-TS implements in:

feat(nut04/05)!: quote accounting and custom payment method base structs cashu-ts#693

Sorry, now moved to:

feat(nut04/05)!: quote accounting and custom payment method base structs cashu-ts#698

github-project-automation Bot added this to nuts May 24, 2026

github-project-automation Bot moved this to Backlog in nuts May 24, 2026

This comment was marked as outdated.

Sign in to view

robwoodgate mentioned this pull request May 26, 2026

NUT-20: harden mint quote signature (breaking) + NUT-04 UUIDv7 quote ids #379

Closed

robwoodgate approved these changes May 26, 2026

View reviewed changes

robwoodgate mentioned this pull request May 28, 2026

custom payment methods #382

Open

a1denvalu3 approved these changes Jun 7, 2026

View reviewed changes

feat: align nut04 with amount_paid/issued + updated_at

4f4f697

Egge21M force-pushed the generic-paid-issued branch from d251850 to 4f4f697 Compare June 9, 2026 09:48

thesimplekid self-requested a review June 9, 2026 14:48

thesimplekid approved these changes Jun 9, 2026

View reviewed changes

thesimplekid mentioned this pull request Jun 9, 2026

Add extra fields for nut04/05 cashubtc/cdk#2077

Open

a1denvalu3 mentioned this pull request Jun 10, 2026

feat(mint): align NUT-04 with amount_paid/issued + updated_at cashubtc/nutshell#1044

Open

asmogo approved these changes Jun 10, 2026

View reviewed changes

robwoodgate mentioned this pull request Jun 12, 2026

feat(nut04/05)!: quote accounting and custom payment method base structs cashubtc/cashu-ts#693

Closed

robwoodgate approved these changes Jun 12, 2026

View reviewed changes

robwoodgate mentioned this pull request Jun 15, 2026

Widen common quote structs for custom payment methods asmogo/nuts#1

Merged

thesimplekid requested changes Jun 17, 2026

View reviewed changes

thesimplekid mentioned this pull request Jun 17, 2026

feat: align mint quote accounting with NUT-04 cashubtc/cdk#2119

Open

3 tasks

robwoodgate mentioned this pull request Jun 18, 2026

feat(nut04/05)!: quote accounting and custom payment method base structs cashubtc/cashu-ts#698

Open


		For reusable quotes, no finite `state` can fully represent whether the quote may receive future payments. Wallets MUST use `amount_paid` and `amount_issued` to determine the currently mintable amount.

		Mints MUST update `updated_at` whenever `amount_paid` or `amount_issued` changes. Mints SHOULD ensure that `updated_at` monotonically increases for each quote, even if multiple updates occur within the same timestamp resolution. Wallets that receive multiple responses for the same quote MUST NOT replace locally stored quote data with a response whose `updated_at` is lower than the latest processed value for that quote. Wallets MUST NOT decrease locally stored `amount_paid` or `amount_issued` values based on stale responses.

Conversation

Egge21M commented May 24, 2026 • edited by thesimplekid Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

robwoodgate commented May 25, 2026

Uh oh!

a1denvalu3 commented May 26, 2026

Uh oh!

robwoodgate left a comment

Choose a reason for hiding this comment

Uh oh!

Egge21M commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robwoodgate commented Jun 8, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Egge21M Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thesimplekid Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

thesimplekid Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

thesimplekid Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

robwoodgate commented Jun 17, 2026

Uh oh!

robwoodgate commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Egge21M commented May 24, 2026 •

edited by thesimplekid

Loading

Egge21M commented Jun 8, 2026 •

edited

Loading

robwoodgate Jun 13, 2026 •

edited

Loading