Align NUT-04 mint quote accounting with amount_paid / amount_issued #377

Open

Egge21M wants to merge 1 commit from Egge21M/generic-paid-issued into main

Egge21M commented

2026-05-24 06:09:43 +00:00

(Migrated from github.com)

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

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

robwoodgate commented

2026-05-25 15:09:46 +00:00

(Migrated from github.com)

In offline discussion, it was proposed to add a version param to mint quotes.

This would allow us to make the changes (eg remove state, evolve NUT-20 signing) cleanly, as wallets can adjust their handling appropriately to the version.

I'd recommend we start at version: 02, so that any quote with unspecified version param is treated as an impleictversion: 01 quote with state param.

In offline discussion, it was proposed to add a `version` param to mint quotes. This would allow us to make the changes (eg remove `state`, evolve NUT-20 signing) cleanly, as wallets can adjust their handling appropriately to the version. I'd recommend we start at `version: 02`, so that any quote with unspecified `version` param is treated as an impleict`version: 01` quote with `state` param.

👍 1

robwoodgate commented

2026-05-25 15:14:30 +00:00

(Migrated from github.com)

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.

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.

👍 1

a1denvalu3 commented

2026-05-26 07:05:16 +00:00

(Migrated from github.com)

Agreed.

robwoodgate (Migrated from github.com) approved these changes

2026-05-26 18:25:22 +00:00

robwoodgate (Migrated from github.com) left a comment

ACK

a1denvalu3 (Migrated from github.com) approved these changes

2026-06-07 20:34:15 +00:00

Egge21M commented

2026-06-08 08:00:29 +00:00

(Migrated from github.com)

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?

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 commented

2026-06-08 13:01:54 +00:00

(Migrated from github.com)

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.

> 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.

This pull request has changes conflicting with the target branch.

04.md

View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Merge commit title

Merge pull request 'Align NUT-04 mint quote accounting with amount_paid /   amount_issued' (#377) from Egge21M/generic-paid-issued into main

Merge commit body

Reviewed-on: https://git.cashu.dev/forgejo-admin/nuts/pulls/377

Merge pull request 'Align NUT-04 mint quote accounting with amount_paid /   amount_issued' (#377) from Egge21M/generic-paid-issued into main

Reviewed-on: https://git.cashu.dev/forgejo-admin/nuts/pulls/377

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin Egge21M/generic-paid-issued:Egge21M/generic-paid-issued

git switch Egge21M/generic-paid-issued

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff Egge21M/generic-paid-issued

git switch Egge21M/generic-paid-issued

git rebase main

git switch main

git merge --ff-only Egge21M/generic-paid-issued

git switch Egge21M/generic-paid-issued

git rebase main

git switch main

git merge --no-ff Egge21M/generic-paid-issued

git switch main

git merge --squash Egge21M/generic-paid-issued