feat!: nut-18 mint preferences (mp, sm)

[d4rp4t]

NUT: cashubtc/nuts#381

Summary

Aligns the NUT-18 / NUT-26 mint-preferences fields with the latest payment-request consolidation candidate.

• mp (mint_preferred, TLV 0x09) — whether the mint list is advisory. Supersedes the earlier ms (mint_strict) flag with inverted polarity: a strict mint list is now the omitted default, and an advisory/preferred list is the explicit mp = true
• sm (supported_method, TLV 0x0a, repeatable) — payment methods the payee accepts (e.g. bolt11, bolt12, onchain), each carrying an optional per-method fee (mf)

The per-method fee compensates the receiver for melting out: it applies only to payments from a mint outside m (or from any mint if m is not set), and the payer owes the lowest mf among the listed methods their mint supports. Payments from a listed mint carry no fee.

The requested amount is always net of input fees (NUT-18): the payer selects proofs such that the receiver can swap/melt them without dipping below the amount. This maps directly onto the existing includeFees(true) proof-selection machinery; the usage guide shows the wiring.

Motivation

The original branch implemented ms (mint_strict) from an earlier draft. The consolidation candidate renames the strictness flag to mp (mint_preferred) and inverts the default so the flag only needs to be set for the non-default (advisory) case — strict is implied by omission — removing the redundant "omitted == explicit default" encoding the ms form carried.

Later revisions promoted sm from a bare list of method-name strings to a list of {mn, mf?} objects, replaced the top-level non-preferred-mint fee (fr) with a net-of-input-fees flag (nf), folding all melt-out pricing into the per-method mf, and finally dropped nf entirely: the spec now makes the requested amount unconditionally net of input fees, so the flag carried no information. With nf gone, supported_method moved down to TLV tag 0x0a.

Changes

• RawPaymentRequest: rename ms → mp; add sm?: RawSupportedMethod[] ({mn, mf?})
• PaymentRequest: rename mintsStrict → mintsPreferred; add supportedMethods (SupportedMethod[], {method, fee?: Amount}); plumb through toRawRequest, toEncodedCreqA, toEncodedCreqB, fromRawRequest, fromEncodedRequest
• DecodedTLVPaymentRequest: rename mintsStrict → mintsPreferred; add supportedMethods?: Array<{method, fee?: bigint}>
• TLV codec: TLV 0x09 renamed mint_strict → mint_preferred (default-if-absent flips 1 → 0); tag 0x0a (supported_method, repeatable) is a sub-TLV — sub-tag 0x01 method (string), 0x02 fee (u64, optional). Duplicate method/fee sub-tags are rejected, matching the nut10 sub-TLV
• get isMintListStrict(): resolves the spec's default-to-strict semantic — undefined when no mint list is set, mintsPreferred !== true otherwise
• feesFor(mint, mintMethods?) / amountToSend(mint, mintMethods?): price the applicable per-method fee — 0 for a mint in m, otherwise the lowest mf among the sm entries the mint supports (mintMethods). Pure fee calculators; they do not validate admissibility (strict-list / sm-method gating is the caller's concern). amountToSend throws on an amountless request
• single_use is now tri-state optional (absent / false / true) instead of a boolean defaulting to false, so it round-trips the absent-vs-explicit-false distinction rather than always serializing single_use = 0. Breaking (v5): a decoded request that omits the flag now exposes singleUse: undefined (was false) — documented in migration-5.0.0.md
• Both flags (mp, single_use) are defensively coerced to real booleans on decode, so an untyped CBOR value can't leak a non-boolean into the getter or be re-serialized verbatim
• Breaking (v5): the PaymentRequest constructor now takes a single PaymentRequestOptions object whose keys mirror the class properties, replacing the positional form. The old signature had grown to 11 optional slots (three of them adjacent booleans), making call sites undefined-padded and swap-prone, and every spec revision appended another slot. A positional call fails to type-check; documented in migration-5.0.0.md
• Public exports: PaymentRequestOptions, RawSupportedMethod, SupportedMethod
• Usage guide (docs-src/usage/payment_requests.md) covers decoding, strictness, fee pricing and selecting proofs with includeFees(true) so the receiver nets the requested amount

Reviewer Notes

• Wire identity preserved: mp and sm are only serialized when explicitly set, and single_use is omitted when absent — encoded requests round-trip canonically (minimal CBOR, no redundant default tags). The NUT-18 and NUT-26 spec vectors for the combined mp/sm payload (with a per-method fee on bolt12) are pinned byte-for-byte (creqA + creqB) and match the upstream test vectors
• mintsPreferred reflects raw wire state (undefined when absent). The spec's "absent means strict when m is set" semantic is exposed via the isMintListStrict getter rather than mutated into the field on decode — keeps roundtrip clean and avoids gaining a tag the original didn't carry
• Per-method fee uses Amount in the class, mirroring how amount is handled; raw/TLV layers stay numeric/bigint
• canPayFrom-style admissibility helper was considered and deliberately skipped: the mint-list case is already a correct one-liner via isMintListStrict, and a useful sm-method check needs the sending mint's MintInfo (not self-contained on PaymentRequest), so it is left for when a caller actually needs to gate

[codecov]

Codecov Report

❌ Patch coverage is 98.79518% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 95.48%. Comparing base (1c959da) to head (397e6d5).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/utils/tlv.ts	97.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #683      +/-   ##
==========================================
+ Coverage   95.44%   95.48%   +0.04%     
==========================================
  Files          55       55              
  Lines        5292     5363      +71     
  Branches     1309     1329      +20     
==========================================
+ Hits         5051     5121      +70     
  Misses        107      107              
- Partials      134      135       +1     

Flag	Coverage Δ
integration	39.13% <4.81%> (-0.44%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[robwoodgate]

Thanks @d4rp4t - Please can you run npm run prtasks to update the api report and formatting.

[robwoodgate]

closing / reopening to force refresh