feat(nut04/05)!: quote accounting and custom payment method base structs

[robwoodgate]

Summary

Matures the NUT-04/05 base payloads so wallets can handle generic and custom payment methods, implementing:

• Align NUT-04 mint quote accounting with amount_paid / amount_issued nuts#377 — mint quote accounting: amount_paid, amount_issued and updated_at become base mint quote response fields for every payment method; state is deprecated (but always populated for bolt11).

• NUT-04/05: custom payment methods nuts#382 — custom payment methods: base request/response structs widened per the shapes suggested in review, generic quote responses get base normalization + validation, and new MintQuoteGenericResponse / MeltQuoteGenericResponse passthrough types are the defaults on the generic quote methods so custom-method fields are reachable without casting.

• add method field to quote responses, closes #378 nuts#387 — every quote response carries a method field: populated from the request endpoint when the mint omits it (no mint ships it yet), throwing when a reported method disagrees with the endpoint. Once mints implement it, NUT-17 generic mint_quote/melt_quote notifications become routable by method.

Follows up on #672 (nuts#374 method_name), which already merged.

Design notes

• Required-but-derived accounting. For mints that predate quote accounting, amount_paid/amount_issued are derived from the legacy single-use state + amount (UNPAID → 0/0, PAID → amount/0, ISSUED → amount/amount); conversely a missing bolt11 state is derived from the accounting fields. Underivable responses throw, matching the existing melt-side strictness. updated_at is number | null (null when the mint does not report it — it cannot be derived).
• Base shapes per the nuts#382 review suggestions. Mint quote request base gains optional amount/description; expiry moves into the mint quote response base (normalized to null when unset); melt quote request base gains optional amount; melt quote response base gains required request and optional fee_reserve (bolt methods keep it required, onchain keeps fee_options).
• Mintable amount enforced for all methods. validateMintQuoteAvailableAmount loses its bolt12/onchain gate: mintable = amount_paid − amount_issued is checked whenever the quote object carries accounting fields. Stored quotes without them (pre-accounting) skip the check, as before.
• Method-id validation (^[a-z0-9_-]+$) and the generic /v1/{mint,melt}/quote/{method} plumbing already existed and are unchanged.

Breaking changes

• MintQuoteBaseResponse requires amount_paid, amount_issued, updated_at, expiry; MeltQuoteBaseResponse requires request. Type-breaking for code constructing quote literals; runtime consumers are unaffected because normalization guarantees the fields.
• Non-conformant quote responses that previously passed through unvalidated (mint quotes missing quote/request/unit or underivable accounting; melt quotes missing request) now throw Invalid response from mint.

Sequencing

Suggest merging in order:#675 → this.

Test plan

• New unit tests: state↔accounting derivation matrix, updated_at/expiry normalization, custom-method base validation (mint + melt), unknown-field passthrough, generalized available-amount enforcement.
• 1605 node tests pass; tsc clean; api report regenerated.

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.15%. Comparing base (80a55b9) to head (75a302f).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/mint/Mint.ts	95.23%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #698      +/-   ##
==========================================
- Coverage   95.20%   95.15%   -0.06%     
==========================================
  Files          54       54              
  Lines        5068     5098      +30     
  Branches     1253     1267      +14     
==========================================
+ Hits         4825     4851      +26     
- Misses        103      106       +3     
- Partials      140      141       +1     

Flag	Coverage Δ
integration	38.56% <45.45%> (+0.22%)	⬆️

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.

[KvngMikey]

solid work here, LGTM!

[robwoodgate]

Only cashubtc/nuts#382 pending merge now.

That PR makes request a first class NUT-05 (melt) base field (it has to be for custom methods to share their request instructions).

If that PR changes, the fallback is to relax that one field to optional on MeltQuoteBaseResponse. No shipping mint offers custom methods yet, so nothing can break in the interim.

[github-actions]

🧬 Mutation testing (incremental)

✅ Mutation score: 88.9% (break threshold: 80%) — repo-wide 5232 killed / 565 survived / 87 no-coverage.

Surviving mutants in files this PR changed (292):

• mint/Mint.ts:1237 BlockStatement: {}
• mint/Mint.ts:1339 BlockStatement: {}
• mint/Mint.ts:1340 StringLiteral: ""
• mint/Mint.ts:1340 ObjectLiteral: {}
• mint/Mint.ts:1341 StringLiteral: ""
• mint/Mint.ts:216 OptionalChaining: data.signatures
• mint/Mint.ts:473 OptionalChaining: data.signatures
• mint/Mint.ts:548 OptionalChaining: data.signatures
• mint/Mint.ts:859 OptionalChaining: data.states
• mint/Mint.ts:954 OptionalChaining: data.outputs
• mint/Mint.ts:954 OptionalChaining: data.signatures
• mint/Mint.ts:990 OptionalChaining: this.ws.close
• mint/Mint.ts:1030 LogicalOperator: mintInfo && (await this.getLazyMintInfo())
• mint/Mint.ts:1052 LogicalOperator: mintInfo && (await this.getLazyMintInfo())
• mint/Mint.ts:1076 LogicalOperator: init.headers && {}
• mint/Mint.ts:1160 StringLiteral: ‘‘
• mint/Mint.ts:1165 ConditionalExpression: true
• mint/Mint.ts:1180 ConditionalExpression: true
• mint/Mint.ts:1180 LogicalOperator: data.amount_paid != null || data.amount_issued != null
• mint/Mint.ts:1180 ConditionalExpression: true
• mint/Mint.ts:1186 StringLiteral: ""
• mint/Mint.ts:1186 ObjectLiteral: {}
• mint/Mint.ts:1193 StringLiteral: ""
• mint/Mint.ts:1198 LogicalOperator: (typeof data.quote !== 'string' || typeof data.request !== 'string') && typeof d
• mint/Mint.ts:1198 ConditionalExpression: false
• mint/Mint.ts:1198 LogicalOperator: typeof data.quote !== 'string' && typeof data.request !== 'string'
• mint/Mint.ts:1198 ConditionalExpression: false
• mint/Mint.ts:1202 StringLiteral: ""
• mint/Mint.ts:1202 ObjectLiteral: {}
• mint/Mint.ts:1199 ConditionalExpression: false

Full report (all files): download the mutation-report-pr artifact from this run. Codecov shows lines this PR left uncovered; this shows changed lines that run but aren’t asserted.