NUT-18: Payment request consolidation (and extra fees for non-preferred mints)

[robwoodgate]

Consolidates and Supersedes: #355, #380

• Cashu-TS: feat!: nut-18 mint preferences (mp, sm) cashu-ts#683
• CDK: feat: add mints_strict field to payment requests cdk#2007
• Nutshell: feat(core): Updates to nut18 and nut26 payment request nutshell#1059
• Dotnut feat: mint strict flag Kukks/DotNut#37

Summary

Consolidates the two open NUT-18 payment request proposals around mint preferences, strict mint lists, fee 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 and how the payer compensates the receiver for fees.

Changes

• Retains sm (supported_method) from feat(nut-18, nut-26): add preferred_mints to payment requests #355 to require that the payer's mint supports at least one listed payment method (e.g. bolt11, bolt12, onchain), now as a list of {mn, mf?} objects. The optional per-method fee mf compensates the receiver for melting out via that method:
  • applies only to payments from a mint outside m, or from any mint if m is not set; payments from a listed mint carry no per-method fee
  • the payer owes the lowest mf among the listed methods their mint supports
• Adds mp (mint_preferred) to signal whether the m mint list is strict or preferred (this is a flip from ms in feat: preferred mints #380):
  • absent / false: receiver only accepts proofs from listed mints
  • true: listed mints are preferred, but other mints may be accepted
• Specifies that the requested amount is net of input fees: the payer MUST select proofs such that sum(proofs) - input_fee(proofs) >= amount owed, with the input fee computed from the sending mint's input_fee_ppk (NUT-02). This protects the receiver from pathological proof sets (e.g. 1000 x 1 sat proofs at 250 ppk costs the receiver 250 sats to swap).
• Updates NUT-26 TLV tags for the new fields
• Adds test vectors covering the combined behaviour

Note: earlier revisions had a flat fr (fee_required) surcharge for non-preferred mints, then an nf (net_fees) opt-in flag. Review discussion concluded fr was redundant once mf is scoped to non-preferred mints, and nf had no sensible false case (no receiver wants to be underpaid by dust), so net-of-input-fees is now the unconditional rule. Both flags have been dropped and the supported_method sub-TLV uses tag 0x0a.

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
• mp defines whether that list is strict or advisory
• sm lets receivers express the mint capabilities required for the payment flow, with per-method fees that compensate for melting out of a non-preferred mint
• the requested amount is net of input fees, so receivers get the amount they asked for regardless of the sender's proof selection

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

[robwoodgate]

@callebtc , @thesimplekid - we have three implementations, can we consider final review / merge please.

cc @ye0man

[KvngMikey]

4 implementations:
cashubtc/nutshell#1059

[robwoodgate]

The only thing I still don't love about this is the mint_strict boolean being true if omitted.

It opens up all kinds of edge case issues as undefined is true but other falsey values are false.

I'd rather default to false on omitted, or if strict is the desirable default, flip the boolean semantic to mint_prefer, where true means the list of mints is a preference and false or omitted means it is strict

What are the thoughts on this?

[thesimplekid]

The only thing I still don't love about this is the mint_strict boolean being true if omitted.

It opens up all kinds of edge case issues as undefined is true but other falsey values are false.

I'd rather default to false on omitted, or if strict is the desirable default, flip the boolean semantic to mint_prefer, where true means the list of mints is a preference and false or omitted means it is strict

What are the thoughts on this?

I agree, I think default true is an anti pattern and we should avoid it.

[robwoodgate]

I agree, I think default true is an anti pattern and we should avoid it.

Agreed. Would you prefer to keep mint_strict and make the default false, or flip the boolean semantics to mint_prefer / mint_suggest or similar?

[thesimplekid]

I agree, I think default true is an anti pattern and we should avoid it.

Agreed. Would you prefer to keep mint_strict and make the default false, or flip the boolean semantics to mint_prefer / mint_suggest or similar?

I would flip the semantics. mint_preferred / mp: absent or false means the existing strict m behavior, true means the m list is advisory/preferred.

[robwoodgate]

I would flip the semantics. mint_preferred / mp: absent or false means the existing strict m behavior, true means the m list is advisory/preferred.

yeah, that's my leaning too. @d4rp4t @a1denvalu3, do you agree?

[KvngMikey]

I would flip the semantics. mint_preferred / mp: absent or false means the existing strict m behavior, true means the m list is advisory/preferred.

i agree with this ...

[robwoodgate]

ms (mint_strict) now replaced with mp (mint_preferred).

This gives the same semantic, but flipped so an omitted value means false (strict).

[robwoodgate]

Cashu-TS updated to use new mp semantic (replacing ms)

[robwoodgate]

CTS updated to use new fee per method:

• cashubtc/cashu-ts@7ecf99d

[callebtc]

what is the point of "fr" if there are "mf" fees as well?

[robwoodgate]

fr is the fee for using a non-preferred mint (mint not in the m list, mp=true)
mf is the fee for using a specific payment method.

This allows fee adds for unknown mints, as well as for using expensive methods.

Example:

// preferred list (mp=true), fr=5, and onchain carries mf=10
pr.amountToSend('https://in-list.mint'); // Amount, base only    → 100
pr.amountToSend('https://in-list.mint', 'onchain'); // + mf      → 110
pr.amountToSend('https://other.mint', 'bolt11'); // + fr         → 105
pr.amountToSend('https://other.mint', 'onchain'); // + fr + mf   → 115

[thesimplekid]

I think this is redundant? As presumably the fee for using a non default mint is because they are going to melt out and that fee will be dependent on method so can just include it in the mf? And mf should only apply to mints outside of preferred?

[robwoodgate]

The thing I'm confused about with the whole per-method fee idea is how the sender knows which method the receiver will use to cash out?

[callebtc]

I think this is redundant?

I think so too.

If the mint is in the list, you should accept the ecash (no method fee applies). If it's a foreign mint, you required a method and a certain fee buffer for that method.

[robwoodgate]

So what shape would you want to see? If the sender cannot know which method the receiver will use, it seems that fee per method itself seems redundant.

sm can just be a single method string (your mint must support x) and fr the fee as now.

"sm": "bolt11",
"fr": "2",

Otherwise, given a menu, the sender is likely to just choose the "cheapest" because they cannot know whether the receiver will offload via bolt11, onchain etc

Alternatively, we can go back to the original multi-list sm (your mint must support at least one of these methods) and a single fr for using the non-preferred mint.

"sm": [ "bolt11", "onchain" ],
"fr": "2",

[robwoodgate]

Some thoughts on this, and the wider payment request needs / issues we've discussed over time:

Fee per method

I suppose a sender is rightfully able to send cheapest per method fee if their chosen mint support 2 or more methods.

So if payment request says:

"sm": [
  { "mn": "bolt11" },  // omitted mf = 0
  { "mn": "onchain", "mf": 50 }
]

And the sender mint supports both, they add no extra mf fee because their mint was compliant with request.

But if a sender's mint is onchain only, they have to pay the lowest per method fee their mint supports (50 in example).

Is that how you envisaged it @callebtc ?

And should the mf per mint fee apply in all cases, or just when using a non-preferred mint?

Fee Required (fr)

I'm not sure the fr is totally redundant. We discussed a case where a sender can use a mint they control with high lightning fees. The fr was an extra fee for using a mint the sender doesn't explicitly trust, regardless of the methods they support.

If the mf fee applies only to non-preferred mint, then I agree, fr is redundant.

Include input fees

Nothing we have discussed so far handles the case where a sender sends a pathological set of proofs - example, 1000 x 1 sat proofs from a mint with 250ppk fee = 250 sats. Which is kind of what I imagined the fr fee would help to mitigate. "If you choose to send from your own mint, add this fee".

Maybe the input fee issue could disappear along with fr by replacing it with an "include fees" boolean, or mandating the amount is net of input fees?

[robwoodgate]

Following discussion in the TS Devs meeting, I've updated the spec as follows:

Commit: 7ff7864

• fr (fee required) dropped
• mf (method fee) semantics clarified to ONLY apply for non-preferred mints (or when m is unset)
• amount specified as being net of per-proof input fees

Note: Change of spec, implementations will need to be updated if this new direction is agreeable

Related discussion: #381 (comment)

cc @callebtc , @thesimplekid , @d4rp4t , @KvngMikey

[thesimplekid]

Updated cdk to current spec in cashubtc/cdk@b5a5eb4

[KvngMikey]

Nutshell updated to current spec cashubtc/nutshell@91195fd