NUT-XX Batched Minting by vnprc · Pull Request #323 · cashubtc/nuts

vnprc · 2025-12-12T23:42:58Z

This document specifies NUT-XX: Batched Mint for the Cashu ecash protocol. It defines how wallets can mint multiple ecash proofs in a single atomic operation instead of individual requests.

Key components:

Quote status checking - endpoint to verify payment status for multiple mint quotes at once
Batch minting - atomic endpoint to mint all quotes together or fail entirely (no partial minting)
Validation rules - strict requirements including:
- non-empty unique quote arrays
- consistent payment methods and currency units
- balanced amounts between quotes and outputs
Error handling - comprehensive error codes and structured error responses for debugging
NUT-20 signature support - handles authentication signatures for locked quotes, with per-quote signatures covering all outputs
Implementation guidance - batch size limits (discoverable via mint info), BOLT12 partial minting support, and compatibility with spending conditions (P2PK, HTLC)

The spec emphasizes atomic processing (all-or-nothing), detailed error reporting, and interoperability with existing Cashu specs (NUT-04, NUT-20, NUT-11, NUT-14, NUT-25).

This commit introduces a new specification, NUT-XX, for batched mint operations. It allows wallets to mint multiple proofs in a single transaction, improving efficiency.

- specify all quotes must share same payment method and currency - expand nut-20 signature section with detailed structure and validation - clarify signature array format and per-quote mapping - add signature message construction specification - document atomicity requirement for signature validation failures - add comprehensive mint responsibilities section - update dependencies to include nut-20

- add validation requirements for empty arrays and duplicate quotes - clarify batch quote status response format per payment method - change batch mint endpoint path to include /batch suffix - add comprehensive request validation section - add error codes table and structured error response format - restructure nut-20 signature support section for clarity - add atomic processing requirement to mint responsibilities - add implementation notes for batch size limits and bolt12 support - add note on spending conditions compatibility - expand error handling documentation with examples

vnprc · 2025-12-12T23:43:25Z

This PR replaces #273

xx.md

thesimplekid · 2025-12-13T10:53:09Z

xx.md

+
+## 1. Checking Quote Status
+
+Before minting, the wallet must verify that each mint quote has been paid.


I don't think this should be a must, a wallet could know the states of the quotes by ws update why must it check again?

Should be SHOULD. I think its good to mention that this endpoint is not supposed to be a batch-check

this endpoint is not supposed to be a batch-check

What do you mean? I thought the purpose was to ensure that a batch was ready to mint before attempting to mint it.

xx.md

thesimplekid · 2025-12-13T11:10:35Z

xx.md

+Unknown quote:
+```json
+{
+  "code": "UNKNOWN_QUOTE",
+  "detail": "Quote 'abc-123' does not exist",
+  "quote": "abc-123"
+}
+```
+
+Quote not paid:
+```json
+{
+  "code": "QUOTE_NOT_PAID",
+  "detail": "Quote 'xyz-789' is not in PAID state",
+  "quote": "xyz-789"
+}
+```


What if multiple quotes are unknown or unpaid? I think it maybe best to not extend out error response and leave it how it is defined in nut00 without a quote id and its up to the wallet to figure it out.

My thinking was that debugging one failing quote ID from a batch of 100 could be a huge pain in the ass. Best effort error reporting could help in some cases. I can see an argument for improving the batch check endpoint for this purpose instead of attempting detailed error messages in the mint endpoint. If you think we shouldn't even try, you're gonna have to convince me.

as discussed in the meeting, we should remove quote ID as a field but still allow quote IDs in the description for human consumption

thesimplekid · 2025-12-13T11:11:55Z

xx.md

+```
+msg_to_sign = quote_id[i] || B_0 || B_1 || ... || B_(n-1)
+```
+
+Where:
+- `quote_id[i]` is the UTF-8 encoded quote ID at index `i`
+- `B_0 ... B_(n-1)` are **all blinded messages** from the `outputs` array (regardless of amount splitting)


~~I don't think we need to redefine it reference the existing nut.~~

We should add test vectors for this.

Am I missing something here? I agree that there is no need to re-define it

@Egge21M the outputs are for all quotes combined, but this should be an addition to NUT-20 and as @thesimplekid says, there should be test vectors.

xx.md

thesimplekid · 2025-12-13T11:16:34Z

xx.md

+### BOLT12 Support
+
+**Partial minting support:**
+
+Mints MAY support partial minting for BOLT12 quotes, where `amount_issued` can be less than `amount_paid`. This allows:
+- **Multiple batch operations**: Same BOLT12 quote can be used in multiple mint requests
+- **Incremental minting**: Each batch mint increments `amount_issued` by the minted amount
+- **State tracking**: Quote remains in PAID state until `amount_issued >= amount_paid`
+
+The mint tracks `amount_paid` and `amount_issued` separately for this purpose.


I think we can remove this as its defined in the bolt12 nut.

xx.md

a1denvalu3 · 2025-12-15T13:08:59Z

xx.md

+```
+msg_to_sign = quote_id[i] || B_0 || B_1 || ... || B_(n-1)
+```
+
+Where:
+- `quote_id[i]` is the UTF-8 encoded quote ID at index `i`
+- `B_0 ... B_(n-1)` are **all blinded messages** from the `outputs` array (regardless of amount splitting)


@Egge21M the outputs are for all quotes combined, but this should be an addition to NUT-20 and as @thesimplekid says, there should be test vectors.

a1denvalu3 · 2025-12-15T13:17:29Z

I think the changes to the mint quote signing process should be an addition to NUT-20 under "Multi-Quote Signature"

a1denvalu3 · 2025-12-16T11:46:55Z

Why did we choose to invent a whole new spec for minting, instead of just generalizing what we already have n-way? For example:

curl -X POST https://mint.host:3338/v1/mint/bolt11/batch -H "Content-Type: application/json" -d \
'[
  {
    "quote": "DSGLX9kevM...",
    "outputs": [
      {
        "amount": 8,
        "id": "009a1f293253e41e",
        "B_": "035015e6d7ade60ba8426cefaf1832bbd27257636e44a76b922d78e79b47cb689d"
      },
      {
        "amount": 2,
        "id": "009a1f293253e41e",
        "B_": "0288d7649652d0a83fc9c966c969fb217f15904431e61a44b14999fabc1b5d9ac6"
      }
    ]
  },
  ...
]'

This way we don't introduce unforeseen bugs and we don't have to amend NUT-20.
Also, we can still succeed even if some of them were not successful. A response could be:
BatchPostMintResponse:

{
  "succeeded": [PostMintResponse],
  "failed": [PostMintFailure],
}

Co-authored-by: tsk <tsk@thesimplekid.com> Co-authored-by: lollerfirst <43107113+lollerfirst@users.noreply.github.com>

vnprc · 2025-12-16T15:11:57Z

@lollerfirst as discussed in a recent meeting, the wallet can specify the outputs they want to mint so this precludes the possibility of partial success. Atomic batch mint transactions also massively reduce complexity around partial success.

- wallet SHOULD verify paid quotes, not must - remove redundant requirements and unnecessary statements - deduplicate request validation and mint responsibilities - remove http status from error codes

callebtc · 2025-12-18T14:18:20Z

xx.md

+  "quotes":   [ "quote_id_1", "quote_id_2", … ],
+  "quote_amounts": [ 50, 50 ],
+  "outputs": [ BlindedMessage_1, BlindedMessage_2, … ],
+  "signatures": [signature_1, signature_2, ... ]


what if some mint quotes are not locked? maybe: for a quote_id_n that does not require a NUT-20 lock, the signature at the same index should be null.

callebtc

good PR but text still reads AI-sloppy, could probably be compressed to 50% dense human spec.

callebtc · 2025-12-18T14:19:40Z

xx.md

+  - **All quotes MUST be from the same payment method** (indicated by `{method}` in the URL path).
+  - **All quotes MUST use the same currency unit**.
+- **quote_amounts**: array of expected mint amounts per quote, in the same order as `quote`.
+  - REQUIRED for bolt12 batches; OPTIONAL for bolt11.


optional quote_amounts and signatures should be annotated in the JSON itself

callebtc · 2025-12-18T14:20:00Z

xx.md

+{
+  "quotes":   [ "quote_id_1", "quote_id_2", … ],
+  "quote_amounts": [ 50, 50 ],
+  "outputs": [ BlindedMessage_1, BlindedMessage_2, … ],
+  "signatures": [signature_1, signature_2, ... ]


should use the same JSON annotation format that we use in other specs

callebtc · 2025-12-18T14:20:19Z

xx.md

+  - For bolt11, each entry MUST equal the quoted amount. For bolt12, each entry MUST NOT exceed the quote's remaining mintable amount. In all cases, the sum of `quote_amounts` MUST equal the sum of `outputs`.
+- **outputs**: an array of blinded messages (see [NUT-00][00]).
+  - The total value represented by all blinded messages must equal the sum of all quote amounts.
+- **signatures**: array of signatures for NUT-20 locked quotes. See [NUT-20 Support][nut-20-support]


callebtc · 2025-12-18T14:20:58Z

xx.md

+  - Array MUST NOT be empty
+  - All quote IDs MUST be unique (no duplicates)
+  - **All quotes MUST be from the same payment method** (indicated by `{method}` in the URL path).
+  - **All quotes MUST use the same currency unit**.


redundant here, there's a validation section below

callebtc · 2025-12-18T14:21:21Z

xx.md

+4. **Payment method consistency**: All quotes MUST have the same payment method, matching `{method}` in the URL path
+5. **Currency unit consistency**: All quotes MUST use the same currency unit
+6. **Quote state**: All quotes MUST be in PAID state (or have mintable amount for BOLT12)
+7. **Amount balance**: The sum of output amounts MUST equal the sum of `quote_amounts` (bolt11) or MUST NOT exceed it (bolt12)


amounts should probably be ignored for bolt11?

callebtc · 2025-12-18T14:24:14Z

xx.md

+| Signature on unlocked quote | `UNEXPECTED_SIGNATURE` |
+| Missing required signature | `SIGNATURE_MISSING` |
+
+### Error Response Format


this seems too excessive, would remove and use a simpler approach

callebtc · 2025-12-18T14:26:45Z

xx.md

+### Signature Structure
+
+**Array structure:**
+- The `signature` field is an array with length equal to `quote.length` (one entry per quote)


it's called signatures (plural) above

callebtc · 2025-12-18T14:27:08Z

xx.md

+
+**Per-quote signatures:**
+- **Locked quotes** (with `pubkey`): `signature[i]` contains the signature string
+- **Unlocked quotes**: `signature[i]` is `null`


I suggested null above too, should be defined above.

callebtc · 2025-12-18T14:27:51Z

xx.md

+
+**Array structure:**
+- The `signature` field is an array with length equal to `quote.length` (one entry per quote)
+- `signature[i]` corresponds to `quote[i]`


quotes[i]

callebtc · 2025-12-18T14:28:48Z

xx.md

+- Total: 225 sats across 3 outputs
+- Both signatures cover all 3 outputs to prevent output tampering
+
+## Mint Responsibilities


this section is not needed. atomicity should be mentioned very briefly in the first paragraph.

Egge21M · 2026-01-18T05:37:45Z

@vnprc are you still actively working on this? Otherwise I would offer to take over again, so that we can get this wrapped soonish

callebtc · 2026-01-20T10:35:52Z

@vnprc, you have been contacted by multiple people. please get in touch personally or through some other channel if you want to talk about your situation.

callebtc · 2026-01-25T14:03:47Z

closed for #333 where work continues

callebtc · 2026-01-25T14:03:47Z

closed for #333 where work continues

Egge21M and others added 5 commits July 9, 2025 12:45

docs: Add NUT-XX for batched minting

41dc819

This commit introduces a new specification, NUT-XX, for batched mint operations. It allows wallets to mint multiple proofs in a single transaction, improving efficiency.

docs: added nut-20 support to xx.md

00d0c08

docs: clarified uniqueness

f71defc

thesimplekid mentioned this pull request Dec 13, 2025

Add NUT-XX for batched minting #273

Closed

thesimplekid reviewed Dec 13, 2025

View reviewed changes

vnprc mentioned this pull request Dec 13, 2025

Batch Minting Implementation (NUT-XX) cashubtc/cdk#1414

Open

a1denvalu3 suggested changes Dec 15, 2025

View reviewed changes

add quote_amounts to batch quote request

67983ea

minor wording improvements

d0dbc58

Co-authored-by: tsk <tsk@thesimplekid.com> Co-authored-by: lollerfirst <43107113+lollerfirst@users.noreply.github.com>

vnprc added 3 commits December 16, 2025 11:03

updates from PR review

2c3e72a

- wallet SHOULD verify paid quotes, not must - remove redundant requirements and unnecessary statements - deduplicate request validation and mint responsibilities - remove http status from error codes

remove quote id field from errors

81597f8

add batch minting spec test vectors

6b705d8

callebtc reviewed Dec 18, 2025

View reviewed changes

callebtc requested changes Dec 18, 2025

View reviewed changes

rewrite test vectors in the appropriate file

28b5431

ye0man added this to nuts Jan 13, 2026

github-project-automation bot moved this to Backlog in nuts Jan 13, 2026

ye0man moved this from Backlog to Needs Review in nuts Jan 15, 2026

cashubtc deleted a comment from vnprc Jan 19, 2026

cashubtc deleted a comment from vnprc Jan 20, 2026

Egge21M mentioned this pull request Jan 24, 2026

Updated: NUT-XX Batch-Minting and Quote Checks #333

Open

3 tasks

callebtc closed this Jan 25, 2026

github-project-automation bot moved this from Needs Review to Done in nuts Jan 25, 2026


		## 1. Checking Quote Status

		Before minting, the wallet must verify that each mint quote has been paid.

Conversation

vnprc commented Dec 12, 2025

Uh oh!

vnprc commented Dec 12, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thesimplekid Dec 13, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

a1denvalu3 commented Dec 15, 2025

Uh oh!

a1denvalu3 commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vnprc commented Dec 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

callebtc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Egge21M commented Jan 18, 2026

Uh oh!

callebtc commented Jan 20, 2026

Uh oh!

callebtc commented Jan 25, 2026

Uh oh!

callebtc commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

thesimplekid Dec 13, 2025 •

edited

Loading

a1denvalu3 commented Dec 16, 2025 •

edited

Loading