lnurlcash-conformance 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,76 @@ exact version if you gate CI on the grade.
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-04
+
+**`cash-derivation.json`: LUD-25's own seed-recoverable note secrets.** The
+draft specifies a BIP-32 scheme under `m/139'` and the reference wallet
+implements it; `derivation.json` remains, unchanged, as the pre-spec HMAC
+scheme that notes are still outstanding under.
+
+Every case carries `cashRoot`, the four `domainIndices`, a `hardened` flag per
+index, the `domainNode` and the resulting `k1`. The flags are the point of the
+file. `d1..d4` are raw uint32 and BIP-32 reads any index `>= 2^31` as hardened,
+so which levels are hardened is decided by the mint's own host name - an
+implementation that masks the top bit, or hardens all four, derives a
+different tree and restores nothing, silently. Both hosts in the vector land
+on a mix, so an implementation that gets it wrong cannot pass by luck.
+
+`bip32Vector1` carries BIP-32's own published test vector 1, so a port can
+prove its CKDpriv before blaming the LUD-25 path above it. The generator
+implements BIP-32 from `@noble` primitives rather than importing a BIP-32
+library, for the reason at the top of `tools/generate.mjs`: a vector produced
+by the library under test proves nothing.
+
+## 0.6.0 - 2026-09-03
+
+**Offline verification and mutation replay now grade the current LUD-25
+MUSTs.** A rotate, split or merge without a valid note signature fails rather
+than warning, as does a byte-identical retry that is answered as already
+spent. The conforming mock now replays mutations by default; `signatures=false`
+and `retriedMutation=refuse` remain explicit adversarial fixtures.
+
+The optional hash lookup is also checked end to end once a mint offers it.
+The runner requires exactly one of `k1` and `h`, compares the unknown-h response
+with an unknown-k1 response, then burns the original note and confirms its hash
+still gets that same unknown-note answer. This catches the privacy leak where a
+mint answers a burned `h` as already spent. The mock gains separate
+`revealsSpent` and `acceptsBoth` fixtures proving those checks fail.
+
+The signature vectors now describe `mintPubkey` as a stable SERVICE key. It may
+be the funding node identity where compatible signing exists, or a dedicated,
+persistent secp256k1 key where it does not.
+
+**The client-facing vectors carry the same MUSTs.** They had been left behind
+by the prose, still describing a signature as one accepted shape among
+several, so a wallet library could pass every vector while ignoring the
+requirement entirely.
+
+`withdraw-info.json` now puts `mintPubkey` on every accepted withdrawRequest
+and rejects a response that omits it or publishes something that is not a
+33-byte compressed secp256k1 key. A wallet handed a note by a mint that
+publishes no key has nothing to verify it against, which is the gap offline
+verification exists to close.
+
+`responses.json` gains an `unverifiable` outcome for a mutation the SERVICE
+confirms but does not sign. It is deliberately not folded into the existing
+`error` or `ambiguous` outcomes: the mutation definitely landed, so the
+wallet-generated secret is the only key to a real note and must be kept, and
+a consumer that treats this as an ordinary failure loses the money it is
+trying to protect. Every case now also declares the `op` it is driven
+through, because a melt mints nothing and so needs no signature, while a
+rotate returning none is the new outcome.
+
+**The mock mint starts when its path reaches it through a symlink.** The
+standalone guard compared `import.meta.url` against `file://` plus
+`process.argv[1]`, and node resolves a module's URL to its real path while
+argv[1] stays exactly as it was typed. A checkout symlinked into a sibling
+workspace - which is how the language ports pick this repo up locally - failed
+that comparison, so the mint exited silently, printing nothing at all. Every
+port's adversarial suite then hung to EOF and reported the mint as never having
+announced itself, which says nothing about the cause. CI, checking the repo out
+for real, was never affected, so this only ever broke the local run.
+
 ## 0.5.0 - 2026-08-31
 
 **Breaking: the current LUD-25 draft's mandatory mint comment is now the

package/README.md

@@ -92,7 +92,7 @@ must survive:
 | `--echoWrongK1` | answers the informational GET with a different `k1` |
 | `--lieAboutValue=N` | reports a `maxWithdrawable` it never signed |
 | `--signatureLayout=leading` | emits the recovery id at the other end |
-| `--signatures=false` | issues no signatures at all |
+| `--signatures=false` | deliberately violates LUD-25 by issuing no signatures |
 | `--serverGeneratedSecrets` | hands back a secret it generated — the exposure `h` exists to close |
 | `--meltNeverSettles` | holds every melt in flight, so notes stay `pending` |
 | `--meltAlwaysFails` | fails every payment, restoring the note |
@@ -101,6 +101,11 @@ must survive:
 | `--baseFeeMsat=N --feePpm=N` | advertises and withholds a mint fee |
 | `--roundFeeToSat` | rounds the withheld fee up to a whole sat — the note mints short of the formula |
 | `--verifyLeaksEarly` | serves a preimage before settlement, falsely claiming payment proof before payment happened |
+| `--retriedMutation=refuse` | deliberately answers an identical mutation retry as already spent instead of replaying its original success |
+| `--hashLookup=echoesK1` | offers hash lookup but puts a `k1` back in the response |
+| `--hashLookup=answersUnknown` | offers hash lookup but invents a note for an unknown hash |
+| `--hashLookup=revealsSpent` | offers hash lookup but distinguishes a burned hash from an unknown note |
+| `--hashLookup=acceptsBoth` | offers hash lookup but accepts `k1` and `h` together |
 | `--mintToHashAcceptsMalformedH` | claims `mintToHash` and invoices an `h` that is not 64 lowercase hex, so a wallet pays for a quote the mint will refuse |
 | `--mintToHashAcceptsUsedH` | claims it and invoices an `h` that already names a note, an invoice or another quote's output |
 | `--mintToHashIgnoresH` | claims it but accepts `h` and mandatory `comment` naming different outputs |
@@ -108,16 +113,14 @@ must survive:
 The three `mintToHash*` misbehaviours need `--mintToHash` alongside them;
 on their own they do nothing, because a mint that never offered the
 capability cannot misuse it.
-| `--verify=false` | no LUD-21 endpoint at all, not merely unadvertised |
-| `--withdrawLinkForm=lnurlw` | spells `withdrawLink` as `lnurlw://host/w` instead of the plain `https://host/w` the reference mint emits. Both are legal; a client has to take both |
 
-Five behaviours are outside LUD-25 and outside that table, because none
-of them is misbehaviour. All are absent or off unless you ask
-for them, so a mock started with no options answers exactly what it always
-answered:
+The remaining flags enable optional features, legal wire variants, or make a
+conforming default explicit. Optional fields stay absent unless requested:
 
 | Flag | What it does |
 | --- | --- |
+| `--verify=false` | provides no LUD-21 endpoint at all, rather than merely leaving it unadvertised |
+| `--withdrawLinkForm=lnurlw` | spells `withdrawLink` as `lnurlw://host/w` instead of the plain `https://host/w` the reference mint emits. Both are legal; a client has to take both |
 | `--name --description --contact --tosUrl --motd --version` | mint info on the experimental discovery endpoint: who runs this, how to reach them, the terms, and what the operator wants holders to know today |
 | `--baseFeeMsat --feePpm` | also publishes `fees: {baseFeeMsat, feePpm}` on that endpoint, the structured twin of the fee line in the payRequest metadata |
 | `--stats` | serves `GET /stats`: what the mint owes, what is in flight, what the node holds, and the coverage between them |
@@ -125,7 +128,8 @@ answered:
 | `--previousPubkeys=a,b` | keys this mint has signed under before, so notes issued before a rotation still verify |
 | `--previousPrivateKey=<hex>` | an old signing key the mock still holds. Its public half joins `previousPubkeys` on its own |
 | `--signWithPreviousKey` | issues every note under that old key while still advertising the new one: the mid-rotation state a mint passes through when the advertisement moves before the signer |
-| `--retriedMutation=replay` | answers a byte-identical repeat of a mutation with the original success instead of `already spent`. The default, `refuse`, is what this mock has always done |
+| `--retriedMutation=replay` | answers a byte-identical repeat of a mutation with the original success. This is the conforming default; use `refuse` only as an adversarial fixture |
+| `--hashLookup=true` | accepts an informational lookup by `h=sha256(k1)` without returning the bearer secret. Off by default because the capability is optional |
 | `--mintToHash` | accepts `h` alongside the mandatory identical comment and enables the additive quote/receipt fields. Off by default; baseline comment-bound minting remains on |
 | `--mintReceipt` | with `--mintToHash`, adds the optional quote commitment and signed LUD-21 settlement receipt |
 | `--mintToHashAdvertisedOn=quote` | narrows which of the three places claim it (`payRequest`, `mintAddress`, `quote`); all three by default. Changes only what is claimed, never what the mint does |
@@ -223,8 +227,7 @@ advertised `mintPubkey` or any key the mint still publishes as a previous
 one, that split and merge conserve value - exactly,
 under LUD-25's fee algebra, when the mint's fee advertisement is known -
 that a byte-identical repeat of a mutation is answered with the original
-success rather than as an already-spent input (a SHOULD, so a mint that
-has not implemented it is reported as such rather than failed), and that a
+success rather than as an already-spent input, and that a
 burned secret cannot be replayed. It also probes three adversarial shapes a
 mint must refuse atomically: a duplicated `k1` (which a careless mint counts
 twice, minting money from nothing), an output hash that collides with an

package/mock-mint/index.d.ts

@@ -10,6 +10,13 @@ export type WithdrawLinkForm = 'lnurlw' | 'plain'
 
 export type RetriedMutation = 'refuse' | 'replay'
 
+export type HashLookup =
+  | boolean
+  | 'echoesK1'
+  | 'answersUnknown'
+  | 'revealsSpent'
+  | 'acceptsBoth'
+
 /** where a mint claims it accepts an `h` on its pay callback */
 export type MintToHashPlace = 'payRequest' | 'mintAddress' | 'quote'
 
@@ -26,7 +33,7 @@ export interface MockMintOptions {
    * signmessage output unreordered.
    */
   signatureLayout?: SignatureLayout
-  /** withhold sig/sig2 entirely, as a SERVICE with no funding source does */
+  /** non-compliant: withhold the mandatory sig/sig2 */
   signatures?: boolean
   /**
    * How the payRequest spells its withdrawLink. 'plain' (default) is the
@@ -124,14 +131,18 @@ export interface MockMintOptions {
   /**
    * What a retried mutation gets. A rotate, split or merge is a GET and
    * HTTP stacks retry a GET on a dropped connection, so a SERVICE sees
-   * the byte-identical request twice. 'refuse' (default) answers the
-   * second one as an already-spent input; 'replay' answers it with the
-   * original success, which is what stops a holder discarding a note the
-   * SERVICE really did mint. Identical means the same input k1 set, the
+   * the byte-identical request twice. 'replay' (default) returns the
+   * original success as LUD-25 requires; 'refuse' is the non-compliant
+   * fixture. Identical means the same input k1 set, the
    * same h, the same h2 and the same amount; anything else naming a
    * burned input is refused exactly as before.
    */
   retriedMutation?: RetriedMutation
+  /**
+   * Optional informational lookup by sha256(k1). `true` is conforming;
+   * string values reproduce distinct non-compliant responses.
+   */
+  hashLookup?: HashLookup
   /** serve GET /stats, the liabilities endpoint. Off means 404, as before. */
   stats?: boolean
   /** what the node behind a stats-publishing mock claims to hold */
@@ -230,8 +241,8 @@ export interface MockMintState {
   opts: Required<MockMintOptions>
   /**
    * Fund a note directly, bypassing the minting flow. Returns the note's
-   * signature, or undefined when this mint was started with `signatures:
-   * false` (as a SERVICE with no funding source behaves).
+   * signature, or undefined only for the deliberately non-compliant
+   * `signatures: false` fixture.
    *
    * Pass `{previousKey: true}` to sign it under `previousPrivateKey`
    * instead, which is how a case puts one note under the old signing key

package/mock-mint/index.mjs

@@ -15,6 +15,8 @@ import {sha256} from '@noble/hashes/sha2.js'
 import {secp256k1} from '@noble/curves/secp256k1.js'
 import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
 import {randomBytes} from 'node:crypto'
+import {realpathSync} from 'node:fs'
+import {pathToFileURL} from 'node:url'
 
 const LSM_PREFIX = 'Lightning Signed Message:'
 
@@ -148,12 +150,9 @@ const DEFAULTS = {
   signWithPreviousKey: false,
   // What a retried mutation gets. A rotate, split or merge is a GET, and
   // HTTP stacks retry a GET when the connection they used is dropped, so
-  // a SERVICE sees the byte-identical request twice. 'refuse' answers the
-  // second one as an already-spent input, which is what this mock has
-  // always done and remains the default. 'replay' answers it with the
-  // original success, which is what LUD-25 SHOULD say and what stops a
-  // holder discarding a note the SERVICE really did mint.
-  retriedMutation: 'refuse',
+  // a SERVICE sees the byte-identical request twice. 'replay' is the
+  // conforming default. 'refuse' is retained as the adversarial fixture.
+  retriedMutation: 'replay',
   // Liabilities. Off means 404, exactly as before; on serves GET /stats.
   stats: false,
   // What the node behind a stats-publishing mock claims to hold. Read
@@ -191,6 +190,9 @@ const DEFAULTS = {
   //                      on the wire the lookup existed to keep it off
   //   'answersUnknown' - non-compliant: answers for a hash it never
   //                      registered, instead of the unknown-note refusal
+  //   'revealsSpent'   - non-compliant: distinguishes a burned h from an
+  //                      unknown note
+  //   'acceptsBoth'    - non-compliant: accepts k1 and h together
   hashLookup: false,
   // LUD-25 lets a SERVICE refuse an oversized merge outright rather than
   // let the URL be mangled upstream. 0 is no explicit cap; a positive number
@@ -297,7 +299,7 @@ export const createMockMint = async (options = {}) => {
   // minted. Recorded, never inferred - matching on "a note exists at h"
   // alone would let anyone holding a burned k1 and any outstanding note
   // id pull a success out of the mint.
-  const swaps = new Map() // identity -> [{id, amountMsat}]
+  const swaps = new Map() // identity -> [{id, amountMsat, sig}]
   // Output ids a mint quote has already claimed: h -> the payment hash of
   // the invoice that will credit it. Only ever written when mintToHash is
   // on, so with the option off this is empty and every collision check
@@ -803,13 +805,16 @@ export const createMockMint = async (options = {}) => {
       // `h` is only ever read here, never at the callback, where the same
       // letter means the hash of a NEW note.
       const asked = q.get('h')?.toLowerCase()
+      if (k1 && asked && opts.hashLookup !== 'acceptsBoth') return fail('Unknown note.')
       if (!k1 && asked && opts.hashLookup) {
         if (!/^[0-9a-f]{64}$/.test(asked)) return fail('Unknown note.')
         const held = notes.get(asked)
         const invent = opts.hashLookup === 'answersUnknown' && !held
         if (!invent) {
           if (!held) return fail('Unknown note.')
-          if (held.state === 'burned') return fail('Note already spent.')
+          if (held.state === 'burned') {
+            return fail(opts.hashLookup === 'revealsSpent' ? 'Note already spent.' : 'Unknown note.')
+          }
         }
         return send({
           tag: 'withdrawRequest',
@@ -871,18 +876,16 @@ export const createMockMint = async (options = {}) => {
 
       // The retry branch, before anything is refused for a burned input.
       // This path is a READ: it burns nothing, mints nothing and moves no
-      // balance, so it does not go through finish() either. The signature
-      // is deterministic over (id, amount), so it is recomputed rather
-      // than stored.
+      // balance, so it does not go through finish() either. The exact
+      // signatures are part of the recorded success, including which
+      // published key produced them during a deliberate key rotation.
       if (opts.retriedMutation === 'replay' && !pr) {
         const outputs = swaps.get(swapIdentity(k1s, h, h2, amountRaw))
         if (outputs) {
           const replay = {status: 'OK'}
-          const first = sign(outputs[0].id, outputs[0].amountMsat)
-          if (first) replay.sig = first
+          if (outputs[0].sig) replay.sig = outputs[0].sig
           if (outputs[1]) {
-            const second = sign(outputs[1].id, outputs[1].amountMsat)
-            if (second) replay.sig2 = second
+            if (outputs[1].sig) replay.sig2 = outputs[1].sig
           }
           if (opts.serverGeneratedSecrets) {
             replay.k1 = 'a'.repeat(64)
@@ -1004,8 +1007,8 @@ export const createMockMint = async (options = {}) => {
         const sig = mintNote(h, amount)
         const sig2 = mintNote(h2, change)
         swaps.set(swapIdentity(k1s, h, h2, amountRaw), [
-          {id: h, amountMsat: amount},
-          {id: h2, amountMsat: change}
+          {id: h, amountMsat: amount, sig},
+          {id: h2, amountMsat: change, sig: sig2}
         ])
         const body = {status: 'OK'}
         if (sig) body.sig = sig
@@ -1025,7 +1028,7 @@ export const createMockMint = async (options = {}) => {
       for (const {note} of found) note.state = 'burned'
       const sig = mintNote(h, total + refund)
       swaps.set(swapIdentity(k1s, h, h2, amountRaw), [
-        {id: h, amountMsat: total + refund}
+        {id: h, amountMsat: total + refund, sig}
       ])
       const body = {status: 'OK'}
       if (sig) body.sig = sig
@@ -1048,8 +1051,28 @@ export const createMockMint = async (options = {}) => {
   }
 }
 
+// Is this file the entry point?
+//
+// The obvious `import.meta.url === \`file://${process.argv[1]}\`` is wrong
+// wherever the path reaches node through a symlink: node resolves a module's
+// URL to its real path, while argv[1] stays exactly as it was typed. A
+// checkout symlinked into a sibling workspace - which is how the language
+// ports pick this repo up locally - then fails the comparison, and the mint
+// exits silently, printing nothing at all. Every test that waits for the
+// "listening on" line hangs to EOF and reports the mint as never having
+// announced itself, which says nothing about the real cause.
+const isEntryPoint = () => {
+  const entry = process.argv[1]
+  if (!entry) return false
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href
+  } catch {
+    return false
+  }
+}
+
 // standalone
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isEntryPoint()) {
   const flags = {}
   // A flag's value becomes a number only when it really is one. A 64-hex
   // key made of nothing but digits parses as a Number and loses every

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Language-neutral conformance vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25) implementations",
   "author": "TheCryptoDonkey",
   "license": "MIT",

package/runner/index.mjs

@@ -886,6 +886,7 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
   // the same answer an unknown `k1` gets, so a mint that never implemented
   // it is indistinguishable from one asked about a note it does not hold.
   // A live note's own hash is therefore the only probe that separates them.
+  let hashLookupOffered = false
   await report.check('answers a note lookup by hash without the secret (optional)', async () => {
     const byHash = new URL(url)
     byHash.searchParams.delete('k1')
@@ -895,6 +896,7 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     if (body.status === 'ERROR' || body.tag !== 'withdrawRequest') {
       return 'not offered - every informational lookup puts the live secret in a query string, where any proxy that logs full URLs keeps it'
     }
+    hashLookupOffered = true
     // The whole point of the lookup. A wallet asking by hash already holds
     // the secret - it could not have computed the hash otherwise - so the
     // field buys it nothing, and filling it in puts the note back on the
@@ -910,16 +912,37 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     // An h it never registered must get the unknown-note answer. One that
     // answers anyway reports a note where none exists, and a wallet
     // restoring from seed reads that as a note it has lost the secret to.
+    const unknownSecret = bytesToHex(randomBytes(32))
     const nobody = new URL(url)
     nobody.searchParams.delete('k1')
     nobody.searchParams.delete('amount')
-    nobody.searchParams.set('h', noteId(bytesToHex(randomBytes(32))))
+    nobody.searchParams.set('h', noteId(unknownSecret))
     const invented = await get(nobody)
+    const unknownK1 = new URL(url)
+    unknownK1.searchParams.set('k1', unknownSecret)
+    unknownK1.searchParams.delete('h')
+    unknownK1.searchParams.delete('amount')
+    const ordinaryUnknown = await get(unknownK1)
     assert(
       invented.status === 'ERROR' || invented.tag !== 'withdrawRequest',
       'answered for a hash it never registered - an unrecognized h must get the same response an unknown k1 would'
     )
-    return 'by hash, with no k1 in the reply'
+    assert(
+      invented.status === ordinaryUnknown.status && invented.reason === ordinaryUnknown.reason,
+      `an unknown h answered ${JSON.stringify(invented)} but an unknown k1 answered ${JSON.stringify(ordinaryUnknown)}`
+    )
+
+    // `h` is accepted in place of `k1`, not alongside it. Accepting both
+    // lets an intermediary add a second lookup identity and leaves clients
+    // unable to know which note the response describes.
+    const both = new URL(url)
+    both.searchParams.set('h', noteId(k1))
+    const ambiguous = await get(both)
+    assert(
+      ambiguous.status === 'ERROR',
+      'accepted both k1 and h on one informational lookup - exactly one lookup identity is allowed'
+    )
+    return 'by hash, with no k1 in the reply; unknown and mixed lookups refused'
   })
 
   // The merge cap. LUD-25 bounds a merge by URL length rather than by the
@@ -1011,9 +1034,10 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return 'burned the old secret, minted the new'
   })
 
-  await report.check('signs the notes it issues (optional)', async () => {
-    if (!info.mintPubkey) throw soft('no mintPubkey advertised - offline verification unavailable')
-    if (!currentSig) throw soft('mintPubkey advertised but no sig returned')
+  await report.check('signs the notes it issues', async () => {
+    assert(info.mintPubkey, 'no mintPubkey advertised - offline verification is mandatory')
+    assert(isCompressedPubkey(info.mintPubkey), 'mintPubkey is not a 33-byte compressed secp256k1 key')
+    assert(currentSig, 'the rotate returned no sig - offline verification is mandatory')
     // A mint that has rotated its signing key publishes the old ones as
     // previousPubkeys, so notes it issued before the rotation still
     // verify. Any key it currently stands behind is an acceptable signer.
@@ -1031,6 +1055,28 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
       : `verified offline against a previous signing key (${signedBy.slice(0, 16)}...)`
   })
 
+  await report.check('does not reveal a burned note through hash lookup', async () => {
+    if (!hashLookupOffered) throw soft('hash lookup is not offered')
+    const burned = new URL(url)
+    burned.searchParams.delete('k1')
+    burned.searchParams.delete('amount')
+    burned.searchParams.set('h', noteId(k1))
+    const burnedResponse = await get(burned)
+
+    const unknown = new URL(url)
+    unknown.searchParams.set('k1', bytesToHex(randomBytes(32)))
+    unknown.searchParams.delete('h')
+    unknown.searchParams.delete('amount')
+    const unknownResponse = await get(unknown)
+
+    assert(
+      burnedResponse.status === unknownResponse.status &&
+        burnedResponse.reason === unknownResponse.reason,
+      `a burned h answered ${JSON.stringify(burnedResponse)} but an unknown k1 answered ${JSON.stringify(unknownResponse)}`
+    )
+    return 'burned h is indistinguishable from an unknown note'
+  })
+
   await report.check('keeps signatures off the informational endpoint', async () => {
     // LUD-25: "Signatures are only ever delivered in the
     // withdrawSuccessResponse of a rotate, split or merge, the
@@ -1260,11 +1306,9 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
   // discards the only copy of a secret the SERVICE really did mint a note
   // against. Nobody is told; the money is simply gone.
   //
-  // Soft, because this is a SHOULD. A SERVICE that has not implemented it
-  // is reported as not having implemented it, not failed. What is NOT
-  // soft is damage: a retry that burns the output, or changes its value,
-  // fails outright whichever answer it gives.
-  await report.check('replays a retried mutation rather than refusing it (optional)', async () => {
+  // This is a MUST. A retry must replay the original success and must not
+  // burn or alter either output.
+  await report.check('replays a retried mutation rather than refusing it', async () => {
     const valueAt = async secret => {
       const u = new URL(url)
       u.searchParams.set('k1', secret)
@@ -1295,22 +1339,18 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
       `the retried rotate changed the note's value: ${minted} -> ${stillThere}`
     )
 
-    const problems = []
-    if (retried.status === 'ERROR') {
-      problems.push(
-        `a retried rotate is answered "${retried.reason}" while the note it minted is live and worth ${stillThere} msat`
-      )
-    } else if (first.sig && retried.sig !== first.sig) {
-      problems.push('a retried rotate replied OK but with a different sig than the original')
-    }
+    assert(
+      retried.status === 'OK',
+      `a retried rotate is answered "${retried.reason}" while the note it minted is live and worth ${stillThere} msat`
+    )
+    assert(retried.sig === first.sig, 'a retried rotate returned a different sig than the original')
 
     // --- a split, retried ---
     // h2 and the change amount are part of what makes a request the same
     // request, so a rotate on its own does not cover it.
     const half = Math.floor(minted / 2)
     if (half < 1 || (knownBaseFee !== null && minted - half < knownBaseFee + 1)) {
-      if (problems.length > 0) throw soft(problems.join('; ') + '; note too small to retry a split')
-      return 'a byte-identical rotate replays; note too small to retry a split'
+      throw soft('a byte-identical rotate replays; note too small to exercise a split retry')
     }
     const a = bytesToHex(randomBytes(32))
     const b = bytesToHex(randomBytes(32))
@@ -1321,8 +1361,7 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     split.searchParams.append('h2', noteId(b))
     const splitFirst = await get(split)
     if (splitFirst.status !== 'OK') {
-      if (problems.length > 0) throw soft(problems.join('; ') + `; the split itself was refused: ${splitFirst.reason}`)
-      throw soft(`a byte-identical rotate replays; the split itself was refused: ${splitFirst.reason}`)
+      throw new Error(`the split itself was refused: ${splitFirst.reason}`)
     }
     const [va, vb] = [await valueAt(a), await valueAt(b)]
     const splitRetried = await get(split)
@@ -1331,11 +1370,12 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
       va2 === va && vb2 === vb,
       `the retried split changed its outputs: ${va}/${vb} -> ${va2}/${vb2}`
     )
-    if (splitRetried.status === 'ERROR') {
-      problems.push(`a retried split is answered "${splitRetried.reason}" while both its outputs are live`)
-    } else if (splitFirst.sig2 && splitRetried.sig2 !== splitFirst.sig2) {
-      problems.push('a retried split replied OK but with a different sig2 than the original')
-    }
+    assert(
+      splitRetried.status === 'OK',
+      `a retried split is answered "${splitRetried.reason}" while both its outputs are live`
+    )
+    assert(splitRetried.sig === splitFirst.sig, 'a retried split returned a different sig than the original')
+    assert(splitRetried.sig2 === splitFirst.sig2, 'a retried split returned a different sig2 than the original')
 
     // put the two halves back together, so the runner ends holding one note
     const merged = bytesToHex(randomBytes(32))
@@ -1349,7 +1389,6 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
       currentSig = mergeBody.sig ?? null
     }
 
-    if (problems.length > 0) throw soft(problems.join('; '))
     return 'a byte-identical rotate and split both replay the original success'
   })
 

package/vectors/cash-derivation.json

@@ -0,0 +1,160 @@
+{
+  "version": 1,
+  "spec": "LUD-25 draft (lnurl/luds#301)",
+  "description": "LUD-25's specified seed-recoverable note secrets, the BIP-32 scheme under m/139'. cashRoot is m/139' as privateKey||chainCode hex (64 bytes, no version/depth/fingerprint framing). domainIndices are the four raw uint32 read big-endian from the first 16 bytes of HMAC-SHA256(key = the private key at m/139'/0, msg = utf8(host)); they are used as BIP-32 child indices exactly as they fall, so `hardened` records which of them land >= 2^31 by magnitude - an implementation that masks the top bit or hardens all four derives a different tree and will restore nothing. domainNode is m/139'/d1/d2/d3/d4. k1 is the private key at the hardened child `index` of that node, 32 bytes lowercase hex, and the mint sees only sha256(k1) as ever. host is the mint host exactly as the wallet stores it, with the port when there is one. seedHex is the 64-byte BIP39 seed with no passphrase. bip32Vector1 is BIP-32's own published test vector 1, so CKDpriv itself can be checked first.",
+  "scheme": {
+    "purpose": "m/139'",
+    "hashingKey": "m/139'/0",
+    "domainMsg": "host",
+    "secretPath": "m/139'/d1/d2/d3/d4/i'",
+    "hardenedByMagnitudeOnly": true
+  },
+  "bip32Vector1": [
+    {
+      "index": null,
+      "node": "e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35873dff81c02f525623fd1fe5167eac3a55a049de3d314bb42ee227ffed37d508"
+    },
+    {
+      "index": 2147483648,
+      "hardened": true,
+      "node": "edb2e14f9ee77d26dd93b4ecede8d16ed408ce149b6cd80b0715a2d911a0afea47fdacbd0f1097043b78c63c20c34ef4ed9a111d980047ad16282c7ae6236141"
+    },
+    {
+      "index": 1,
+      "hardened": false,
+      "node": "3c6cb8d0f6a264c91ea8b5030fadaa8e538b020f0a387421a12de9319dc933682a7857631386ba23dacac34180dd1983734e444fdbf774041578e9b6adb37c19"
+    },
+    {
+      "index": 2147483650,
+      "hardened": true,
+      "node": "cbce0d719ecf7431d88e6a89fa1483e02e35092af60c042b1df2ff59fa424dca04466b9cc8e161e966409ca52986c584f07e9dc81f735db683c3ff6ec7b1503f"
+    },
+    {
+      "index": 2,
+      "hardened": false,
+      "node": "0f479245fb19a38a1954c5c7c0ebab2f9bdfd96a17563ef28a6a4b1a2a764ef4cfb71883f01676f587d023cc53a35bc7f88f724b1f8c2892ac1275ac822a3edd"
+    },
+    {
+      "index": 1000000000,
+      "hardened": false,
+      "node": "471b76e389e528d6de6d816857e012c5455051cad6660850e58372a6c3e6e7c8c783e67b921d2beb8f6b389cc646d7263b4145701dadd2161548a8b078e65e9e"
+    }
+  ],
+  "cases": [
+    {
+      "name": "standard mnemonic, index 0",
+      "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      "seedHex": "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4",
+      "host": "mint.example",
+      "index": 0,
+      "cashRoot": "c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60",
+      "domainIndices": [
+        2589708612,
+        3693348916,
+        172082394,
+        3793182078
+      ],
+      "hardened": [
+        true,
+        true,
+        false,
+        true
+      ],
+      "domainNode": "72056e5cde21458b13689c3950904dfd327415a506d064290e5e5f4296a40543dd5e9504ddb6eefbafa4ad3b00ad421858fafc0ed9ea4abd9cb68793f845cfc1",
+      "k1": "de5b81405a12e1297b350d80e2ad85043ed5b9436a0c5592d3302778de330499",
+      "noteId": "7db9da2845cd45c1c3c2e302d6135da46823e245f756b830ef59ac324b769e02"
+    },
+    {
+      "name": "standard mnemonic, index 1",
+      "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      "seedHex": "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4",
+      "host": "mint.example",
+      "index": 1,
+      "cashRoot": "c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60",
+      "domainIndices": [
+        2589708612,
+        3693348916,
+        172082394,
+        3793182078
+      ],
+      "hardened": [
+        true,
+        true,
+        false,
+        true
+      ],
+      "domainNode": "72056e5cde21458b13689c3950904dfd327415a506d064290e5e5f4296a40543dd5e9504ddb6eefbafa4ad3b00ad421858fafc0ed9ea4abd9cb68793f845cfc1",
+      "k1": "267570df5ba8098d728e839a698f729c2df6fa7b8b7ae7c9c7ffa7dda3417e1d",
+      "noteId": "99b98cb845940e0d6401e176aaca1446365aa315201803861e17f3c530ed1dcf"
+    },
+    {
+      "name": "standard mnemonic, index 20 (one past a 20-index gap limit)",
+      "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      "seedHex": "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4",
+      "host": "mint.example",
+      "index": 20,
+      "cashRoot": "c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60",
+      "domainIndices": [
+        2589708612,
+        3693348916,
+        172082394,
+        3793182078
+      ],
+      "hardened": [
+        true,
+        true,
+        false,
+        true
+      ],
+      "domainNode": "72056e5cde21458b13689c3950904dfd327415a506d064290e5e5f4296a40543dd5e9504ddb6eefbafa4ad3b00ad421858fafc0ed9ea4abd9cb68793f845cfc1",
+      "k1": "1f2b8080d4c9431b1dec780abb4eee3c4aaf7ff03f7dd126a7e005ec7af372e0",
+      "noteId": "0daebdd7f9355a215c511cadc96e73f586e07238c352b43b21c080713b79cbfc"
+    },
+    {
+      "name": "a second mnemonic, same host and index",
+      "mnemonic": "legal winner thank year wave sausage worth useful legal winner thank yellow",
+      "seedHex": "878386efb78845b3355bd15ea4d39ef97d179cb712b77d5c12b6be415fffeffe5f377ba02bf3f8544ab800b955e51fbff09828f682052a20faa6addbbddfb096",
+      "host": "mint.example",
+      "index": 0,
+      "cashRoot": "e58252908e0c10965d15d1e3894cbf206a2102c20eb9519e466e2e0e852075d430afaa22bb69ef2151cdffacc463e51068e854152b0b7c08fa2f93e6b8d16741",
+      "domainIndices": [
+        3862277158,
+        545631060,
+        182776155,
+        2195829862
+      ],
+      "hardened": [
+        true,
+        false,
+        false,
+        true
+      ],
+      "domainNode": "df3c9156afc2e416286df9bbfda49c6ab72305ba3d65ae0b7e2214caf581b111959d96bc0c075185ff7304214496a78f43b22ea511f97a7bf408454a7e3d3a85",
+      "k1": "d5376fa38f01b39d55be6dc0ea8f3aa6b91f37c183c5a394bb7e30b624855a78",
+      "noteId": "5b4ba51285373e8a8c0414e6b3607ea0a6b70968c94f2b9f73ffdfdedfba1c15"
+    },
+    {
+      "name": "a host carrying a port",
+      "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      "seedHex": "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4",
+      "host": "127.0.0.1:8899",
+      "index": 0,
+      "cashRoot": "c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60",
+      "domainIndices": [
+        2087962263,
+        3073061246,
+        2281736429,
+        1205328740
+      ],
+      "hardened": [
+        false,
+        true,
+        true,
+        false
+      ],
+      "domainNode": "80bdd2d71f0235bd9e22d5838a4a4f346cf5415309ada559942a409a630e102ce214425b89b36d03d4835fdf6592d2619c74d37b746711b4ed85759ea1d358a6",
+      "k1": "d7bcc5c9e7015ca2688ed10e24db3f82163d5b59fc887e5dd346abf2426b1270",
+      "noteId": "1a8a732d7ec9811654183ecbb27b1887dec947a42c877a12bd93f952837a3887"
+    }
+  ]
+}

package/vectors/index.json

@@ -6,6 +6,7 @@
   "files": [
     "signature.json",
     "derivation.json",
+    "cash-derivation.json",
     "bech32.json",
     "url-admission.json",
     "input-resolution.json",

package/vectors/lifecycle.json

@@ -58,7 +58,7 @@
         "the connection drops after the SERVICE applied it",
         "the HTTP stack silently resends the identical request"
       ],
-      "requirement": "a WALLET MUST ensure its HTTP stack does not retry a mutating callback. Every mutation is a GET, HTTP treats GET as idempotent, and an LNURLcash mutation is not: the first attempt burns the input. A retried mutation is answered \"invalid or already spent k1\", which classifies as a DEFINITIVE rejection - so the WALLET concludes nothing happened and discards the fresh secret that was the only copy of the note the SERVICE just minted. This is not hypothetical: it was found in two independent implementations during this suite's own development. Java's java.net.http.HttpClient retries idempotent GETs on a mid-flight connection reset and cannot be configured out of it (use a client that can); Go's net/http retries when the request went over a REUSED connection, and a client with no explicit Transport shares a process-wide pool, so the behaviour depends on what unrelated code did first (disable keep-alives). Browsers retry on a stale pooled connection for the same reason. Test this deliberately: the mock mint's dropAfterMutation mode reproduces it."
+      "requirement": "a SERVICE MUST recognize the byte-identical retry from the same k1 set, h, h2 and amount, and return the original success with the same sig and sig2 without moving balance again. A WALLET still persists every fresh output secret before sending the first request and keeps it across an ambiguous transport failure. A request that changes any recorded field is a genuine double-spend attempt and gets the ordinary already-spent refusal."
     },
     {
       "name": "settle a merge or split output",

package/vectors/note-url.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-25 draft (lnurl/luds#301)",
-  "description": "A note is an ordinary LUD-03 withdrawRequest URL whose k1 IS the asset. `amount` alongside it is only a claim by whoever encoded the note - the authoritative value is always maxWithdrawable from an informational GET. `sig` is the optional offline-verification signature.",
+  "description": "A note is an ordinary LUD-03 withdrawRequest URL whose k1 IS the asset. `amount` alongside it is only a claim by whoever encoded the note - the authoritative value is always maxWithdrawable from an informational GET. A SERVICE returning a rotate, split or merge MUST include the offline-verification signature in `sig` (and `sig2` for the second split output).",
   "parse": [
     {
       "url": "https://mint.example/w?k1=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&amount=21000",

package/vectors/responses.json

@@ -1,9 +1,10 @@
 {
   "version": 1,
   "spec": "LUD-25 draft (lnurl/luds#301)",
-  "description": "Classifying a SERVICE response. The distinction that matters for funds is definitive-rejection versus ambiguous-outcome: a parsed {\"status\":\"ERROR\"} means the request was processed and refused, while a transport failure, an unparseable body, or a 200 that does not confirm means the mutation MAY have landed - and for rotate/split/merge the WALLET-generated secrets are then the only copy of the outputs, so they must ride the error rather than be discarded.",
+  "description": "Classifying a SERVICE response. The distinction that matters for funds is definitive-rejection versus ambiguous-outcome: a parsed {\"status\":\"ERROR\"} means the request was processed and refused, while a transport failure, an unparseable body, or a 200 that does not confirm means the mutation MAY have landed - and for rotate/split/merge the WALLET-generated secrets are then the only copy of the outputs, so they must ride the error rather than be discarded. A confirmed mutation carrying no signature is its own outcome: it definitely landed, so the secrets matter more than ever, and the SERVICE is non-conforming. `op` says which call each case is driven through - a melt is the one mutation with no signature to return.",
   "outcomes": {
     "ok": "the operation is confirmed",
+    "unverifiable": "the mutation is confirmed but carries no signature. LUD-25 requires one on every rotate, split and merge, so this SERVICE is non-conforming - but the note EXISTS at the hash the WALLET disclosed, and its secret is the only key to that value. Keep the secret; report the mint",
     "pending": "this k1 has another operation in flight (a melt); retry shortly",
     "spent": "the SERVICE is authoritative that the note is already burned; a holder may lock it as spent",
     "unknown": "the SERVICE does not recognise this note; surface it, do not silently lock it",
@@ -13,14 +14,17 @@
   "cases": [
     {
       "name": "plain success",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "OK"
       },
-      "expect": "ok"
+      "expect": "unverifiable",
+      "why": "a bare OK was a conforming rotate answer while offline verification was optional. It is not one now: the note is real and the WALLET must keep its secret, but nobody the holder hands it to can check it"
     },
     {
       "name": "success with an offline-verification signature",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "OK",
@@ -31,6 +35,7 @@
     },
     {
       "name": "split success with both signatures",
+      "op": "split",
       "http": 200,
       "body": {
         "status": "OK",
@@ -41,8 +46,20 @@
       "signature": "ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
       "changeSignature": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
     },
+    {
+      "name": "a split that signs only its first output",
+      "op": "split",
+      "http": 200,
+      "body": {
+        "status": "OK",
+        "sig": "ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
+      },
+      "expect": "unverifiable",
+      "why": "both outputs of a split are notes and both need a signature; the change is not a lesser note"
+    },
     {
       "name": "melt success with a LUD-21 style proof",
+      "op": "melt",
       "http": 200,
       "body": {
         "status": "OK",
@@ -50,10 +67,11 @@
         "verify": "https://mint.example/verify/abc"
       },
       "expect": "ok",
-      "why": "OK on a melt means the payment is in flight, NOT that the note is confirmed spent"
+      "why": "OK on a melt means the payment is in flight, NOT that the note is confirmed spent. A melt mints nothing, so it has no signature to return and none is required"
     },
     {
       "name": "pending",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -64,6 +82,7 @@
     },
     {
       "name": "already spent",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -73,6 +92,7 @@
     },
     {
       "name": "unknown note",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -82,6 +102,7 @@
     },
     {
       "name": "not found wording",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -91,6 +112,7 @@
     },
     {
       "name": "ambiguous callback wording is treated as spent",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -101,6 +123,7 @@
     },
     {
       "name": "some other refusal",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR",
@@ -110,6 +133,7 @@
     },
     {
       "name": "error with no reason",
+      "op": "mutation",
       "http": 200,
       "body": {
         "status": "ERROR"
@@ -118,6 +142,7 @@
     },
     {
       "name": "200 with neither OK nor ERROR",
+      "op": "mutation",
       "http": 200,
       "body": {
         "something": "else"
@@ -127,23 +152,27 @@
     },
     {
       "name": "unparseable body",
+      "op": "mutation",
       "http": 200,
       "bodyRaw": "not json at all",
       "expect": "ambiguous"
     },
     {
       "name": "server error",
+      "op": "mutation",
       "http": 500,
       "bodyRaw": "upstream failure",
       "expect": "ambiguous"
     },
     {
       "name": "transport failure",
+      "op": "mutation",
       "transportError": true,
       "expect": "ambiguous"
     },
     {
       "name": "timeout",
+      "op": "mutation",
       "timeout": true,
       "expect": "ambiguous"
     }

package/vectors/retried-mutation.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-25 draft (lnurl/luds#301)",
-  "description": "What counts as a retry of a mutation, and what is still a double-spend attempt. Every mutation in LUD-25 is a GET, and HTTP stacks retry a GET when the connection they used is dropped, so a SERVICE sees the byte-identical request twice and the second one arrives with its inputs already burned. A SERVICE that answers the retry as an already-spent input tells the holder the mutation never happened, and the holder discards the only copy of a secret the SERVICE really did mint a note against. Replaying the original success instead is a SHOULD, not a MUST: a SERVICE that has not implemented it is not broken, but a SERVICE that has must draw the line in exactly this place, or two SERVICEs give the same wallet two different answers to the same dropped connection. The replay path is a read - it burns nothing, mints nothing and moves no balance - and the signature is deterministic over the output id and amount, so it is recomputed rather than stored. Anything that is NOT a retry and names a burned input is refused exactly as an ordinary double-spend is, with the same reason string, so no oracle appears for whoever is holding a burned secret.",
+  "description": "What counts as a retry of a mutation, and what is still a double-spend attempt. Every mutation in LUD-25 is a GET, and HTTP stacks retry a GET when the connection they used is dropped, so a SERVICE sees the byte-identical request twice and the second one arrives with its inputs already burned. A SERVICE that answers the retry as an already-spent input tells the holder the mutation never happened, and the holder discards the only copy of a secret the SERVICE really did mint a note against. Replaying the original success is therefore a MUST. The replay path is a read: it burns nothing, mints nothing and moves no balance, and returns the same signature or signatures. Anything that is NOT a retry and names a burned input is refused exactly as an ordinary double-spend is, with the same reason string, so no oracle appears for whoever is holding a burned secret.",
   "identity": [
     "the same input k1 set, compared as a SET: a merge naming the same notes in a different order is the same merge",
     "the same h",

package/vectors/signature.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-25 draft (lnurl/luds#301)",
-  "description": "Offline verification of a note (LUD-25). A SERVICE signs (note id, amount) with its Lightning node identity key via the standard signmessage wrapping; a holder recovers the pubkey and compares it to mintPubkey without contacting the SERVICE.",
+  "description": "Offline verification of a note (LUD-25). A SERVICE signs (note id, amount) with a stable secp256k1 key it controls; this should be the funding node identity where compatible signing exists, or may be a dedicated persistent SERVICE key otherwise. A holder recovers the pubkey and compares it to the pinned current or previous mintPubkey without contacting the SERVICE.",
   "scheme": {
     "domainTag": "LNURLcash",
     "lightningSignedMessagePrefix": "Lightning Signed Message:",

package/vectors/withdraw-info.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-03, LUD-25",
-  "description": "The informational GET on a note. Never burns, rotates or alters it. maxWithdrawable is the ONLY authoritative statement of what a note is worth - the URL's own `amount` is a claim and the SERVICE ignores it here. The response's k1 MUST be the bearer secret itself, never a derived or opaque id.",
+  "description": "The informational GET on a note. Never burns, rotates or alters it. maxWithdrawable is the ONLY authoritative statement of what a note is worth - the URL's own `amount` is a claim and the SERVICE ignores it here. The response's k1 MUST be the bearer secret itself, never a derived or opaque id. Offline verification is mandatory in the current draft, so the response MUST also carry `mintPubkey`, the stable compressed secp256k1 key the SERVICE's note signatures verify against; without it a holder handed a note has nothing to check it against.",
   "queriedUrl": "https://mint.example/w?k1=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&amount=99999&sig=ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
   "requestMustNotSend": [
     "sig"
@@ -17,42 +17,45 @@
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         "minWithdrawable": 0,
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "maxWithdrawable": 21000
     },
     {
-      "name": "with a mint pubkey for offline verification",
+      "name": "minWithdrawable omitted",
       "body": {
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "minWithdrawable": 0,
         "maxWithdrawable": 21000,
         "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "maxWithdrawable": 21000
     },
     {
-      "name": "minWithdrawable omitted",
+      "name": "echoed k1 in a different casing",
       "body": {
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
-        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 21000
+        "k1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
-      "maxWithdrawable": 21000
+      "maxWithdrawable": 21000,
+      "why": "k1 is bytes; casing carries no meaning"
     },
     {
-      "name": "echoed k1 in a different casing",
+      "name": "mintPubkey in a different casing",
       "body": {
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
-        "k1": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
-        "maxWithdrawable": 21000
+        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034F355BDCB7CC0AF728EF3CCEB9615D90684BB5B2CA5F859AB0F0B704075871AA"
       },
       "maxWithdrawable": 21000,
-      "why": "k1 is bytes; casing carries no meaning"
+      "why": "a pubkey is bytes too, and a SERVICE that upper-cases its hex is still naming the same key"
     },
     {
       "name": "zero value note",
@@ -60,7 +63,8 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 0
+        "maxWithdrawable": 0,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "maxWithdrawable": 0
     }
@@ -72,7 +76,8 @@
         "tag": "payRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -80,7 +85,8 @@
       "body": {
         "tag": "withdrawRequest",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -88,7 +94,8 @@
       "body": {
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -96,7 +103,8 @@
       "body": {
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
-        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -105,7 +113,8 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": "21000"
+        "maxWithdrawable": "21000",
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -114,7 +123,8 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": -1
+        "maxWithdrawable": -1,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -123,7 +133,8 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 21000.5
+        "maxWithdrawable": 21000.5,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "why": "msat are integers"
     },
@@ -133,7 +144,8 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "maxWithdrawable": 18446744073709552000
+        "maxWithdrawable": 18446744073709552000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "why": "no common integer type holds it and a double rounds it - refuse rather than guess the amount"
     },
@@ -144,7 +156,8 @@
         "callback": "https://mint.example/w/cb",
         "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         "minWithdrawable": 30000,
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
     },
     {
@@ -153,9 +166,32 @@
         "tag": "withdrawRequest",
         "callback": "https://mint.example/w/cb",
         "k1": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-        "maxWithdrawable": 21000
+        "maxWithdrawable": 21000,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       },
       "why": "spec MUST: the response k1 is the bearer secret itself. A SERVICE returning something else is non-compliant, or the note was rotated by someone else"
+    },
+    {
+      "name": "no mintPubkey",
+      "body": {
+        "tag": "withdrawRequest",
+        "callback": "https://mint.example/w/cb",
+        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "minWithdrawable": 0,
+        "maxWithdrawable": 21000
+      },
+      "why": "offline verification is mandatory. Without the key a note signature verifies against nothing, and whoever is handed the note is back to the leap of faith the signature exists to remove"
+    },
+    {
+      "name": "mintPubkey that is not a compressed secp256k1 key",
+      "body": {
+        "tag": "withdrawRequest",
+        "callback": "https://mint.example/w/cb",
+        "k1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "maxWithdrawable": 21000,
+        "mintPubkey": "4f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
+      },
+      "why": "an x-only key, a node URI or a truncated hex string verifies nothing. Refused at the response rather than at the first signature check, where the same fault would look like a forged note"
     }
   ]
 }