Recommend UUID v7 for quote and websocket subscription IDs #383

2026-05-28T07:24:34Z

callebtc commented

2026-05-28 07:24:34 +00:00

(Migrated from github.com)

This pull request updates the Cashu specifications (NUTs) to recommend UUID v7 for both quote IDs and WebSocket subscription IDs (subId).

Summary of Changes

UUID v7 Recommendations added:
- Modified NUT-04 (Minting) and NUT-05 (Melting) to state that quote IDs generated by the mint SHOULD be in UUID v7 format.
- Updated NUT-17 (WebSockets) to state that subscription IDs (subId) generated by the wallet SHOULD use UUID v7.
Standardized Example Payloads:
- Replaced all legacy base64 or alphanumeric placeholder quote IDs and subscription IDs with realistic, valid UUID v7 strings.
- Files updated with UUID v7 examples include:
  - NUT-05 (Melting)
  - NUT-08 (Lightning Fee Return)
  - NUT-17 (WebSockets)
  - NUT-23 (BOLT11)
  - NUT-25 (BOLT12)
  - NUT-29 (Batched Minting)
  - NUT-30 (Onchain Bitcoin Method)
  - tests/29-tests.md (Batched Minting Tests)

This pull request updates the Cashu specifications (NUTs) to recommend UUID v7 for both quote IDs and WebSocket subscription IDs (`subId`). ### Summary of Changes 1. **UUID v7 Recommendations added**: - Modified **NUT-04 (Minting)** and **NUT-05 (Melting)** to state that quote IDs generated by the mint **SHOULD** be in UUID v7 format. - Updated **NUT-17 (WebSockets)** to state that subscription IDs (`subId`) generated by the wallet **SHOULD** use UUID v7. 2. **Standardized Example Payloads**: - Replaced all legacy base64 or alphanumeric placeholder quote IDs and subscription IDs with realistic, valid UUID v7 strings. - Files updated with UUID v7 examples include: - **NUT-05** (Melting) - **NUT-08** (Lightning Fee Return) - **NUT-17** (WebSockets) - **NUT-23** (BOLT11) - **NUT-25** (BOLT12) - **NUT-29** (Batched Minting) - **NUT-30** (Onchain Bitcoin Method) - **tests/29-tests.md** (Batched Minting Tests)

robwoodgate (Migrated from github.com) approved these changes

2026-05-28 10:36:27 +00:00

robwoodgate (Migrated from github.com) left a comment

nit: a UUIDv7 implementation that uses predictable counters or monotonic suffixes could weaken quote secrecy. We should specify that all 74 variable bits (after timestamp, version, and variant) are CSPRNG-generated.

04.md

					
				@ -49,18 +49,18 @@ The mint `Bob` responds with a quote that includes some common fields for all me

> `quote` is a **unique and random** id generated by the mint to internally look up the payment state. `quote` **SHOULD** be UUID v7 with all 74 variable bits generated by a CSPRNG and **MUST** remain a secret between user and mint and **MUST NOT** be derivable from the payment request. A third party who knows the `quote` ID can front-run and steal the tokens that this operation mints. To prevent this, use [NUT-20][20] locks to enforce public key authentication during minting.

```suggestion > `quote` is a **unique and random** id generated by the mint to internally look up the payment state. `quote` **SHOULD** be UUID v7 with all 74 variable bits generated by a CSPRNG and **MUST** remain a secret between user and mint and **MUST NOT** be derivable from the payment request. A third party who knows the `quote` ID can front-run and steal the tokens that this operation mints. To prevent this, use [NUT-20][20] locks to enforce public key authentication during minting. ```

05.md

					
				@ -64,7 +64,7 @@ The mint `Bob` responds with a quote that includes some common fields for all me

				}

Where `quote` is the quote ID string in UUID v7 format with all 74 variable bits generated by a CSPRNG, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid.

```suggestion Where `quote` is the quote ID string in UUID v7 format with all 74 variable bits generated by a CSPRNG, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid. ```

KvngMikey (Migrated from github.com) reviewed

2026-05-31 20:42:41 +00:00

04.md

					
				@ -49,18 +49,18 @@ The mint `Bob` responds with a quote that includes some common fields for all me

@robwoodgate, great catch, cause without this a bad actor who sees one quote ID can start making educated guesses about other quote IDs generated around the same time.