custom payment methods by asmogo · Pull Request #382 · cashubtc/nuts

asmogo · 2026-05-27T21:57:04Z

Implementations

Cashu-TS: feat(nut04/05)!: quote accounting and custom payment method base structs cashu-ts#698
CDK: feat(nut04/05): optional amount cdk#2146
Nutshell: TBC

support custom payment methods not defined in a dedicated NUT.

robwoodgate

I think this is a fantastic step forward for wallets to be able to better support unknown methods - I've added some suggested tweaks to the base structs to make life even better.

robwoodgate · 2026-05-28T10:42:03Z

+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_mint_quote"`.


Related: #372

robwoodgate · 2026-05-28T10:42:35Z

+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_melt_quote"`.


Related: #372

Sign in to view

 {
  "unit": <str_enum[UNIT]>
  // Additional method-specific fields may be required
 }


Sign in to view

 {
  "quote": <str>,
  "request": <str>,
  "unit":  <str_enum[UNIT]>,
  // Additional method-specific fields will be included
 }


Sign in to view

 {
  "request": <str>,
  "unit": <str_enum[UNIT]>
  // Additional method-specific fields will be required
 }


Sign in to view

robwoodgate · 2026-05-28T11:31:44Z

Sorry @asmogo - I questioned an earlier draft that included method in the quote structs (thinking mint and wallet know by virtue of the endpoint used to request it), but this related issue highlights that for WS, and especially with the suggestion on harmonizing the base structs for custom methods, the distinction is easy to blur/lose.

So maybe we DO need to include method: <str>, in the quote structs for both mint and melt.

robwoodgate · 2026-05-28T13:32:27Z

Related #377

which adds the amount_oaid, amount_issued, updated_at parms to default quote structs

robwoodgate

Have implemented custom method support in cashu-ts on top of this + #377 + #387 (cashubtc/cashu-ts#698) and it works nicely. Wallets can quote, mint and melt methods they don't fully understand using just the base structs.

A few tweaks below that came out of implementing. Note the suggestions assume #377 merges first.

Related to my base struct suggestions above: expiry really wants to be in the common mint quote response - every method has one, and a wallet showing a quote for an unknown method needs to know when to stop polling. With #377 in, it's the only field from the suggested base response still left as method-specific.

(method in the quote structs is now covered by #387, which also resolves the WS routing question from #378.)

Can also confirm the optional fee_reserve in the melt base works in practice - onchain can't make it required (it uses fee_options), and bolt11/12 tighten it to required in their own NUTs.

Sign in to view

+
+For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT.
+
+The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.


Sign in to view

+
+For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with.
+
+The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT.


Implements the base-shape harmonization proposed on cashubtc/nuts#382: - MintQuoteBaseRequest gains optional amount and description; method NUTs tighten as needed (bolt11 requires amount). - MintQuoteBaseResponse gains expiry (normalized to null when unset), subsuming the per-method expiry fields. - MeltQuoteBaseRequest gains optional amount (onchain requires it). - MeltQuoteBaseResponse gains request and optional fee_reserve; bolt methods keep fee_reserve required. - Melt base validation now requires the payment request for every method, and normalizes fee_reserve when present. - New MintQuoteGenericResponse/MeltQuoteGenericResponse passthrough types are the defaults on the generic quote methods, so custom-method fields are reachable without casting. BREAKING CHANGE: melt quote responses without a request field now throw; generic quote methods default to the Generic response types.

Consolidates review feedback on the generic payment method PR. Scoped to the delta NOT covered by cashubtc#377 (accounting fields) or cashubtc#387 (method), so those can merge independently: - common mint quote request: optional amount, description, pubkey - common melt quote request: optional amount - common mint quote response: expiry, optional pubkey - common melt quote response: request, optional fee_reserve - custom mint quotes MUST carry the accounting fields - custom melt quotes MUST use the standard UNPAID/PENDING/PAID states

robwoodgate · 2026-06-15T16:04:49Z

Added asmogo#1 with my suggestions ready to merge into this PR if acceptable.

Widen common quote structs for custom payment methods

Add generic payment method support

2ed6709

github-project-automation Bot added this to nuts May 27, 2026

github-project-automation Bot moved this to Backlog in nuts May 27, 2026

robwoodgate reviewed May 28, 2026

View reviewed changes

thesimplekid self-requested a review June 9, 2026 14:47

robwoodgate mentioned this pull request Jun 12, 2026

feat(nut04/05)!: quote accounting and custom payment method base structs cashubtc/cashu-ts#693

Closed

robwoodgate reviewed Jun 12, 2026

View reviewed changes

asmogo added 2 commits June 15, 2026 23:00

Merge pull request #1 from robwoodgate/feat/382-custom-base-structs

491d3c3

Widen common quote structs for custom payment methods

Merge branch 'main' into generic-payment-method

3d98925

robwoodgate approved these changes Jun 15, 2026

View reviewed changes

fix: prettier

b984b1f

robwoodgate mentioned this pull request Jun 18, 2026

feat(nut04/05)!: quote accounting and custom payment method base structs cashubtc/cashu-ts#698

Open


		### Websocket Notifications

		Custom methods MAY support websocket subscriptions via [NUT-17][17] with kind `"{method}_mint_quote"`.


		For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT.

		The mint responds with the common mint quote response format. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields (such as `amount` or `expiry`) are defined by the method-specific NUT.


		For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with.

		The mint responds with the common melt quote response format. Method-specific fields are defined by the method-specific NUT.

Uh oh!

Conversation

asmogo commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementations

Uh oh!

robwoodgate left a comment

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

robwoodgate May 28, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate commented May 28, 2026

Uh oh!

robwoodgate left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

robwoodgate commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

asmogo commented May 27, 2026 •

edited

Loading

robwoodgate left a comment •

edited

Loading