Payment request consolidation (and extra fees for non-preferred mints) #381

Open

robwoodgate wants to merge 13 commits from robwoodgate/payment-request-consolidation into main

robwoodgate commented

2026-05-27 15:08:55 +00:00

(Migrated from github.com)

Consolidates and Supersedes: #355, #380

Cashu-TS: https://github.com/cashubtc/cashu-ts/pull/683
CDK: TBC
Nutshell: TBC

Summary

Consolidates the two open NUT-18 payment request proposals around mint preferences, strict mint lists, fee reserve signalling, and required mint payment methods.

This PR keeps the existing m mint list as the single mint-list field, and adds small companion fields to clarify how that list should be interpreted.

Changes

Retains ms (mint_strict) to signal whether the m mint list is strict or preferred from #380:
- absent / true: receiver only accepts proofs from listed mints
- false: listed mints are preferred, but other mints may be accepted
Retains sm (supported_methods) to require that the mint used by the payer supports at least one listed payment method, e.g. bolt11, bolt12, onchain from #355
Adds fr (fee_reserve) to signal an additional amount the payer MUST include when paying from a non-preferred mint, to cover potential swap/melt fees
Updates NUT-26 TLV tags for the new fields
Adds test vectors covering the combined behaviour

Rationale

There were overlapping proposals for preferred mints and strict mint lists. Instead of introducing a separate preferred mint list, this keeps the request format minimal:

m remains the mint list
ms defines whether that list is strict or advisory
fr gives wallets a way to compensate for extra fees when ignoring the preference
sm lets receivers express the mint capabilities required for the payment flow

This avoids two competing mint-list fields while covering the three desired behaviours.

# Consolidates and Supersedes: #355, #380 - [x] Cashu-TS: https://github.com/cashubtc/cashu-ts/pull/683 - [ ] CDK: TBC - [ ] Nutshell: TBC ## Summary Consolidates the two open NUT-18 payment request proposals around mint preferences, strict mint lists, fee reserve signalling, and required mint payment methods. This PR keeps the existing `m` mint list as the single mint-list field, and adds small companion fields to clarify how that list should be interpreted. ## Changes - Retains `ms` (`mint_strict`) to signal whether the `m` mint list is strict or preferred from #380: - absent / `true`: receiver only accepts proofs from listed mints - `false`: listed mints are preferred, but other mints may be accepted - Retains `sm` (`supported_methods`) to require that the mint used by the payer supports at least one listed payment method, e.g. `bolt11`, `bolt12`, `onchain` from #355 - Adds `fr` (`fee_reserve`) to signal an additional amount the payer MUST include when paying from a non-preferred mint, to cover potential swap/melt fees - Updates NUT-26 TLV tags for the new fields - Adds test vectors covering the combined behaviour ## Rationale There were overlapping proposals for preferred mints and strict mint lists. Instead of introducing a separate preferred mint list, this keeps the request format minimal: - `m` remains the mint list - `ms` defines whether that list is strict or advisory - `fr` gives wallets a way to compensate for extra fees when ignoring the preference - `sm` lets receivers express the mint capabilities required for the payment flow This avoids two competing mint-list fields while covering the three desired behaviours.

a1denvalu3 (Migrated from github.com) approved these changes

2026-05-31 13:43:20 +00:00

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

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

git fetch -u origin robwoodgate/payment-request-consolidation:robwoodgate/payment-request-consolidation

git switch robwoodgate/payment-request-consolidation

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 robwoodgate/payment-request-consolidation

git switch robwoodgate/payment-request-consolidation

git rebase main

git switch main

git merge --ff-only robwoodgate/payment-request-consolidation

git switch robwoodgate/payment-request-consolidation

git rebase main

git switch main

git merge --no-ff robwoodgate/payment-request-consolidation

git switch main

git merge --squash robwoodgate/payment-request-consolidation