lnurlcash-conformance 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may add or tighten checks that a previously-passing mint now fails; pin an
 exact version if you gate CI on the grade.
 
+## 0.4.0 - 2026-08-26
+
+**The mint-output naming check now reads the spelling LUD-25 actually
+specifies.** The draft names the output with a LUD-12 `comment = hex(h)`,
+advertised as a `commentAllowed` of at least 64; `mintToHash` is the
+parameter form one mint shipped before the comment form was written. The
+suite knew only the latter, so a mint naming notes exactly as the draft
+describes graded as "not offered - a minted note's k1 is the invoice
+preimage". That is the worst kind of wrong answer a conformance suite can
+give: it tells a wallet author the safe mint is the unsafe one.
+
+Both spellings are now read from the payRequest and the mint address
+document, probed with a fresh hash each (a mint that binds output ids
+uniquely would rightly refuse the second spelling for naming an output the
+first just took), and reported as `named by comment` / `named by h`.
+
+The two are deliberately not probed identically, because the draft's rules
+for them are opposites:
+
+- `h` is a parameter invented for naming, so a malformed one MUST be
+  refused before an invoice exists. Unchanged.
+- `comment` is plain LUD-12 free text any wallet may send for unrelated
+  reasons, so a comment that is not a bare hash MUST fall back to crediting
+  `k1=P` rather than be refused, and the mint MUST NOT serve LUD-21 `verify`
+  on that fallback - there the preimage is not proof of payment, it is the
+  note. Both are now checked, the second as a failure.
+
+Only `mintToHash` is expected in both documents. `commentAllowed` is a
+payRequest field; the mint address document is a withdrawRequest, where a
+LUD-12 comment has nowhere to go, so its absence there is no longer
+reported as a disagreement.
+
+**A rate-limited grade no longer accuses the mint.** Every mint quote
+issues a real invoice on a real node, so a grader firing a dozen looks like
+the abuse a limiter exists to stop - and probing two spellings nearly
+doubled the count. HTTP 429 was indistinguishable from a spec refusal, so
+the mint was reported as violating whatever check happened to be running
+when the bucket ran dry. 429 is now waited out (honouring `Retry-After`)
+and retried, and reported as an incomplete grade rather than a verdict if
+it persists.
+
+The mock mint gains `commentAllowed`, `commentRefusesMalformed` and
+`verifyOnUnnamedMint` to cover all of this.
+
+## 0.3.0 - 2026-08-24
+
+- Add an optional bound-mint settlement receipt for sealed signers. A
+  receipt-capable quote commits to `mint: {h, amount}` before payment; its
+  settled LUD-21 response repeats the invoice, output and exact net value and
+  adds the ordinary LUD-25 note signature. Absence remains compatible with
+  the current preimage-and-rotate flow.
+- `vectors/mint-to-hash.json` now carries the valid quote, unsettled and
+  settled shapes plus wrong-output, wrong-amount, premature-signature and
+  invalid-signature cases. `docs/BOUND-MINT-RECEIPTS.md` contains candidate
+  normative LUD-25 text and the compatibility matrix.
+- The mock mint gains `mintReceipt`; when enabled it publishes the
+  verification key before payment, commits the quote and signs only after
+  settlement. Self-check and self-grade verify the complete lifecycle.
+
 ## 0.2.3 - 2026-08-22
 
 - **New check: `keeps signatures off the informational endpoint`.** LUD-25

package/README.md

@@ -60,6 +60,7 @@ for (const c of cases) {
 | `payment-request.json` | `lnurlcashreq1`: one holder asking another for value |
 | `settle-for-value.json` | the decision table a server works through to take a note as payment |
 | `retried-mutation.json` | what makes a repeated mutation a retry rather than a double-spend |
+| `mint-to-hash.json` | wallet-chosen mint outputs and optional bound LUD-21 receipts |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
 | `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
@@ -67,6 +68,9 @@ Regenerate with `npm run generate`; check them with `npm test`, which
 verifies every digest recomputes, every declared signature really does
 verify, and every fee expectation follows from the formula.
 
+The upstreamable wire text and compatibility matrix for the optional receipt
+are in [`docs/BOUND-MINT-RECEIPTS.md`](docs/BOUND-MINT-RECEIPTS.md).
+
 ## The mock mint
 
 ```bash
@@ -123,6 +127,7 @@ answered:
 | `--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 |
 | `--mintToHash` | takes an optional `h` on the pay callback and credits the minted note there, so the payment preimage is not the money. Off by default, and then `h` is not read at all |
+| `--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 |
 
 As a library, for your own test suite:

package/llms.txt

@@ -54,6 +54,8 @@ payRequest, the same on the mint address document, and the same echoed on
 the pay callback's own response when THAT quote was bound.
 mintToHashAdvertisedOn=payRequest,mintAddress,quote narrows which of the
 three claim it (all three by default; it changes only what is claimed).
+mintReceipt=true adds mint:{h,amount} to an honestly bound quote and adds
+sig only to its settled LUD-21 response; it requires mintToHash.
 Misbehaviours, each needing mintToHash as well: mintToHashAcceptsMalformedH,
 mintToHashAcceptsUsedH, mintToHashIgnoresH.
 
@@ -133,6 +135,14 @@ withdraw callback gives, so no oracle appears. A WALLET MUST persist its
 secret BEFORE asking for the invoice. Purely additive: without h, nothing
 changes. Table in mint-to-hash.json.
 
+For a sealed signer, mint-to-hash may add a bound settlement receipt. The
+quote carries mint:{h,amount}, where amount is exact net msat and no sig is
+allowed. Settled LUD-21 repeats the same h/amount and adds the ordinary
+LUD-25 signature; the wallet matches pr/h/amount and verifies the signature
+before PENDING -> CONFIRMED. Absence of mint is compatible and falls back to
+the legacy preimage/import/rotate flow. Full proposed wire text and matrix:
+docs/BOUND-MINT-RECEIPTS.md.
+
 ## The retried mutation
 
 Every mutation is a GET, and HTTP stacks retry a GET on a dropped

package/mock-mint/index.d.ts

@@ -157,6 +157,12 @@ export interface MockMintOptions {
    * two. A wallet still sends lowercase.
    */
   mintToHash?: boolean
+  /**
+   * Emit the optional mint:{h,amount} quote commitment and add the normal
+   * note signature on settled LUD-21 verification. Requires mintToHash,
+   * verify and signatures. Off by default for baseline compatibility.
+   */
+  mintReceipt?: boolean
   /**
    * non-compliant, and only reachable with mintToHash on: issue an
    * invoice for an `h` that is not 64 lowercase hex, so a wallet pays for
@@ -220,6 +226,8 @@ export interface MockMintState {
       settled: boolean
       /** the output id this quote was bound to, when the wallet named one */
       boundTo?: string
+      /** the exact invoice returned on the quote, for LUD-21 binding */
+      pr?: string
     }
   >
   pubkey: string

package/mock-mint/index.mjs

@@ -187,6 +187,10 @@ const DEFAULTS = {
   // which is the one that matters at the moment money moves: the other
   // two can be cached or stale.
   mintToHash: false,
+  // Add the optional bound LUD-21 receipt to an honestly bound quote and
+  // its verify response. Requires mintToHash, verify and signatures; off
+  // by default so the baseline mock remains the current LUD-25 wire.
+  mintReceipt: false,
   // non-compliant, and only reachable with mintToHash on: issue an
   // invoice for an `h` that is not 64 lowercase hex, so a wallet pays for
   // a quote this mint was always going to refuse
@@ -207,7 +211,30 @@ const DEFAULTS = {
   // 'payRequest,mintAddress' is the one that binds without confirming at
   // the moment money moves. Read only when mintToHash is on. Accepts an
   // array or a comma-separated string, so the CLI can pass one.
-  mintToHashAdvertisedOn: undefined
+  mintToHashAdvertisedOn: undefined,
+
+  // The SAME capability in the spelling LUD-25 actually specifies:
+  // `comment = hex(sha256(secret))` (LUD-12), advertised as a
+  // `commentAllowed` of at least 64. A number advertises that many
+  // characters and reads `comment` as the output name; false says
+  // nothing and reads nothing. Independent of mintToHash - a mint may
+  // ship either, both, or neither.
+  //
+  // The two spellings are not symmetric, and that is the whole reason
+  // both exist here. `h` is a parameter invented for naming, so a
+  // malformed one MUST be refused before an invoice exists. `comment` is
+  // plain LUD-12 free text any wallet may send for unrelated reasons, so
+  // LUD-25 requires the opposite: fall back to crediting k1=P, never
+  // refuse - and MUST NOT serve verify on that fallback, where P is not
+  // proof of payment but the note itself.
+  commentAllowed: false,
+  // non-compliant, commentAllowed on: refuse a comment that is not a
+  // bare 32-byte hex hash instead of falling back, so an ordinary LUD-12
+  // wallet cannot pay this mint at all
+  commentRefusesMalformed: false,
+  // non-compliant, commentAllowed on: serve LUD-21 verify even on the
+  // no-comment fallback, where the preimage it hands out IS the note
+  verifyOnUnnamedMint: false
 }
 
 export const createMockMint = async (options = {}) => {
@@ -461,7 +488,19 @@ export const createMockMint = async (options = {}) => {
         // one a wallet should decide from. Spread in last and only when
         // the option is on, so a mock started with no options answers
         // exactly what it always answered.
-        ...(mintToHashPlaces.has('payRequest') ? {mintToHash: true} : {})
+        ...(mintToHashPlaces.has('payRequest') ? {mintToHash: true} : {}),
+        // LUD-25: "A mint payLink intending to support this SHOULD
+        // advertise a commentAllowed of at least 64". A payRequest field
+        // only - the mint address document is a withdrawRequest, where a
+        // LUD-12 comment has nowhere to go.
+        ...(opts.commentAllowed ? {commentAllowed: opts.commentAllowed} : {}),
+        // A receipt verifier needs the signing key before payment. The
+        // baseline mock remains byte-for-byte unchanged when receipts are
+        // off; a real node-key signer can alternatively be recovered from
+        // the BOLT-11 invoice itself.
+        ...(opts.mintReceipt && opts.verify && opts.signatures
+          ? {mintPubkey: pubkey}
+          : {})
       })
     }
 
@@ -626,20 +665,67 @@ export const createMockMint = async (options = {}) => {
         }
       }
 
+      // The LUD-25 spelling. Read after `h` so a mock offering both lets
+      // an explicit comment name the output, and deliberately NOT an
+      // else-branch: a mint may ship either spelling or both.
+      let namedByComment = false
+      if (opts.commentAllowed) {
+        const sent = q.get('comment')
+        if (sent !== null && sent !== '') {
+          const wellFormed = /^[0-9a-f]{64}$/i.test(sent)
+          if (wellFormed) {
+            const h = sent.toLowerCase()
+            // Same collision rule the `h` spelling gets: an id already
+            // spoken for must never be minted over, whichever parameter
+            // named it.
+            if (outputIdInUse(h) && !opts.mintToHashAcceptsUsedH) {
+              return fail('Invalid or already spent k1.')
+            }
+            if (!opts.mintToHashIgnoresH) {
+              boundTo = h
+              namedByComment = true
+            }
+          } else if (opts.commentRefusesMalformed) {
+            // The non-compliant branch. LUD-25 says a comment that is not
+            // a bare hash MUST fall back, because plain LUD-12 comments
+            // are free text: refusing one turns an ordinary "thanks!"
+            // into a mint that cannot be paid.
+            return fail('Invalid comment.')
+          }
+        }
+      }
+
       const preimage = bytesToHex(randomBytes(32))
       const paymentHash = noteId(preimage)
-      const invoice = {amountMsat: net, preimage, settled: false}
+      const pr = fakeInvoice(amount, preimage)
+      const invoice = {amountMsat: net, preimage, settled: false, pr}
       if (boundTo) {
         invoice.boundTo = boundTo
         boundOutputs.set(boundTo, paymentHash)
       }
       invoices.set(paymentHash, invoice)
-      const body = {pr: fakeInvoice(amount, preimage), disposable: false}
-      if (opts.verify) body.verify = `${origin}/verify/${paymentHash}`
+      const body = {pr, disposable: false}
+      // LUD-25 gates verify on whether the note was named: in the
+      // no-comment fallback the preimage verify would hand out IS the
+      // note's entire bearer secret, so a mint offering the comment
+      // spelling must withhold verify from quotes that used it. A mock
+      // that never heard of the comment spelling keeps answering exactly
+      // as it always did.
+      const verifySafe = !opts.commentAllowed || namedByComment || opts.verifyOnUnnamedMint
+      if (opts.verify && verifySafe) body.verify = `${origin}/verify/${paymentHash}`
       // Appended last, and only when the quote really was bound, so a
       // mock that was never told about any of this answers byte for byte
       // what it always answered.
       if (echoBound) body.mintToHash = true
+      if (
+        echoBound &&
+        boundTo &&
+        opts.mintReceipt &&
+        opts.verify &&
+        opts.signatures
+      ) {
+        body.mint = {h: boundTo, amount: net}
+      }
       return send(body)
     }
 
@@ -652,7 +738,7 @@ export const createMockMint = async (options = {}) => {
       }
       const invoice = invoices.get(verifyMatch[1].toLowerCase())
       if (!invoice) return fail('Unknown payment hash.')
-      return send({
+      const body = {
         status: 'OK',
         settled: invoice.settled,
         // the preimage IS the bearer secret here - a real SERVICE should
@@ -661,8 +747,18 @@ export const createMockMint = async (options = {}) => {
         // bound with its own h: that note is credited elsewhere, so the
         // preimage is an ordinary payment proof and leaks nothing.
         preimage: invoice.settled || opts.verifyLeaksEarly ? invoice.preimage : null,
-        pr: fakeInvoice(invoice.amountMsat, invoice.preimage)
-      })
+        pr: invoice.pr ?? fakeInvoice(invoice.amountMsat, invoice.preimage)
+      }
+      if (invoice.boundTo && opts.mintReceipt && opts.signatures) {
+        body.mint = {
+          h: invoice.boundTo,
+          amount: invoice.amountMsat,
+          ...(invoice.settled
+            ? {sig: sign(invoice.boundTo, invoice.amountMsat)}
+            : {})
+        }
+      }
+      return send(body)
     }
 
     // ---- LUD-03 informational GET ----
@@ -776,7 +872,8 @@ export const createMockMint = async (options = {}) => {
           invoices.set(paymentHash, {
             amountMsat: note.amountMsat,
             preimage: meltPreimage,
-            settled: false
+            settled: false,
+            pr
           })
         }
         if (!opts.meltNeverSettles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.2.3",
+  "version": "0.4.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

@@ -89,7 +89,17 @@ const isNpub = value => {
   }
 }
 
-const get = async (url, timeoutMs = 15_000) => {
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+// A mint may rate limit, and the good ones do: every mint quote issues a
+// real invoice on a real node, so a grader firing a dozen of them looks
+// exactly like the abuse the limiter exists to stop. An HTTP 429 is the
+// grade failing to complete, NOT a verdict on the mint, so it is waited
+// out (honouring Retry-After) and retried. Without this the mint is
+// accused of whatever the check happened to be probing when the bucket
+// ran dry - a conforming mint graded as broken, which is worse than no
+// grade at all.
+const get = async (url, timeoutMs = 15_000, retriesLeft = 2) => {
   const res = await fetch(url.toString(), {signal: AbortSignal.timeout(timeoutMs)})
   const text = await res.text()
   let body
@@ -98,6 +108,17 @@ const get = async (url, timeoutMs = 15_000) => {
   } catch {
     throw new Error(`response was not JSON: ${text.slice(0, 120)}`)
   }
+  if (res.status === 429) {
+    if (retriesLeft > 0) {
+      const after = Number(res.headers.get('retry-after'))
+      const waitMs = Math.min(Number.isFinite(after) && after > 0 ? after * 1000 : 10_000, 30_000)
+      await sleep(waitMs + 250)
+      return get(url, timeoutMs, retriesLeft - 1)
+    }
+    throw soft(
+      `the mint rate limited this grade (HTTP 429${body?.reason ? `: ${body.reason}` : ''}) - space the run out and grade again; nothing here is a verdict on the mint`
+    )
+  }
   return body
 }
 
@@ -449,119 +470,186 @@ export const gradeMint = async (payUrl, report) => {
     return detail
   })
 
-  // Naming the note you are buying. Optional, outside LUD-25, and soft in
-  // the direction that matters: a mint that says nothing anywhere and
-  // ignores `h` mints exactly what the draft describes, which is every
-  // mint today and not a defect. What is graded is a mint that CLAIMS the
+  // Naming the note you are buying. No longer outside LUD-25: the draft
+  // spells it `comment = hex(sha256(secret))` (Protecting a freshly minted
+  // note from a preimage race), advertised as a `commentAllowed` of at
+  // least 64 - enough for a hex-encoded 32-byte hash. `mintToHash` is the
+  // parameter form one mint shipped before the comment form was written.
+  // Both are read here: a suite that knows only one spelling reports a
+  // mint that names notes perfectly well in the other as not offering it
+  // at all, which is worse than silence - it tells a wallet author the
+  // safe mint is the unsafe one.
+  //
+  // Soft in the direction that matters: a mint that says nothing anywhere
+  // and names nothing mints exactly what the draft's fallback describes,
+  // which is not a defect. What is graded is a mint that CLAIMS the
   // capability, because a wallet then stops rotating on sight and trusts
   // the mint to bind the note.
   //
-  // The claim lives in three places and they say different things. The
-  // payRequest's `mintToHash: true` means "I accept an h on my pay
-  // callback", and since every mint publishes a payRequest while the mint
-  // address document is experimental, that is the one to decide from. The
-  // mint address document repeats it, as corroboration. The pay
-  // callback's own response echoes it when THAT quote was bound, which is
-  // the one that matters at the moment money moves: the other two can be
-  // cached or stale. Anything that is not exactly the boolean true is no.
-  await report.check('accepts an output hash on the mint quote (mintToHash, optional)', async () => {
+  // The claim lives in three places. The payRequest is the one to decide
+  // from, since every mint publishes one while the mint address document
+  // is experimental; the mint address repeats it as corroboration; and the
+  // pay callback's own response echoes `mintToHash` when THAT quote was
+  // bound. LUD-25 defines no echo for the comment spelling, so a missing
+  // echo is only held against a mint claiming `mintToHash`.
+  //
+  // The two spellings are NOT symmetric, and that is why this cannot be
+  // one probe with two parameter names:
+  //
+  //   `h` is a parameter invented for exactly this purpose, so a malformed
+  //   one is a wallet error and MUST be refused before an invoice exists.
+  //
+  //   `comment` is plain LUD-12 free text that any wallet may send for
+  //   unrelated reasons, so LUD-25 requires the opposite (line 80 of the
+  //   draft): a comment that is not a bare hex-encoded 32-byte hash MUST
+  //   fall back to crediting the note as k1=P, never be refused - and on
+  //   that fallback the mint MUST NOT serve LUD-21 verify, because there
+  //   P is not proof of payment, it is the entire note.
+  await report.check('accepts a named output on the mint quote (LUD-25 comment / mintToHash, optional)', async () => {
     const amount = Math.max(pay.minSendable, 1000)
-    const quoteAt = async (h, msat = amount) => {
+
+    // LUD-25: "A mint payLink intending to support this SHOULD advertise a
+    // commentAllowed of at least 64". Anything shorter cannot carry the
+    // hash at all, so it is not this capability whatever else it is.
+    const spellingsOf = source => {
+      const found = []
+      if (source?.mintToHash === true) found.push('h')
+      if (Number.isFinite(source?.commentAllowed) && source.commentAllowed >= 64) found.push('comment')
+      return found
+    }
+    const quoteAt = async (spelling, value, msat = amount) => {
       const url = new URL(pay.callback)
       url.searchParams.set('amount', String(msat))
-      url.searchParams.set('h', h)
+      url.searchParams.set(spelling, value)
       return get(url)
     }
+    const spelt = spelling => (spelling === 'comment' ? 'a LUD-12 comment' : 'an h parameter')
+
+    const advertised = spellingsOf(pay)
+    const corroborated = spellingsOf(mintAddress)
+    const claimed = [...new Set([...advertised, ...corroborated])]
 
     // Asked of every mint, advertisement or not: a mint that echoes the
     // capability without publishing it is still claiming it, and a wallet
     // reading the echo would believe it. Nothing pays the invoice that
     // comes back, so this is read-only - an unpaid quote costs a mint an
     // invoice and nothing else.
-    const secret = bytesToHex(randomBytes(32))
-    const h = noteId(secret)
-    const bound = await quoteAt(h)
-    const advertised = pay.mintToHash === true
-    const corroborated = mintAddress?.mintToHash === true
-    const echoed = bound.mintToHash === true
-
-    if (!advertised && !corroborated && !echoed) {
+    // A fresh secret per spelling, never one shared between them: a mint
+    // that accepts both and binds an output id uniquely - as it should,
+    // and as the repeat probe below asserts - would rightly refuse the
+    // second spelling for naming an output the first just took.
+    const probed = claimed.length > 0 ? claimed : ['h']
+    const named = Object.fromEntries(
+      probed.map(spelling => {
+        const secret = bytesToHex(randomBytes(32))
+        return [spelling, {secret, h: noteId(secret)}]
+      })
+    )
+    const bound = {}
+    for (const spelling of probed) bound[spelling] = await quoteAt(spelling, named[spelling].h)
+    const echoedIn = probed.filter(spelling => bound[spelling].mintToHash === true)
+
+    if (claimed.length === 0 && echoedIn.length === 0) {
+      const refused = probed.map(spelling => bound[spelling]).find(body => body.status === 'ERROR')
       throw soft(
-        bound.status === 'ERROR'
-          ? `not offered, and an h on the quote was refused outright: ${bound.reason}`
+        refused
+          ? `not offered, and a named output was refused outright: ${refused.reason}`
           : 'not offered - a minted note\'s k1 is the invoice preimage, which every routing node on the payment path learns, so a wallet must claim and rotate the instant it settles'
       )
     }
 
     const problems = []
     const claimedBy = [
-      advertised && 'the payRequest',
-      corroborated && 'the mint address',
-      echoed && 'the quote itself'
+      advertised.length > 0 && `the payRequest (${advertised.join(', ')})`,
+      corroborated.length > 0 && `the mint address (${corroborated.join(', ')})`,
+      echoedIn.length > 0 && 'the quote itself'
     ].filter(Boolean)
 
-    assert(
-      bound.status !== 'ERROR',
-      `claims mintToHash (${claimedBy.join(', ')}) and refused a well-formed h: ${bound.reason}`
-    )
-    assert(typeof bound.pr === 'string', 'no pr in the response')
-    const invoiced = invoiceAmountMsat(bound.pr)
-    if (invoiced !== null) {
-      assert(invoiced === amount, `asked for ${amount} msat, invoiced ${invoiced} msat`)
+    for (const spelling of probed) {
+      const body = bound[spelling]
+      assert(
+        body.status !== 'ERROR',
+        `claims this capability (${claimedBy.join(', ')}) and refused a well-formed hash sent as ${spelt(spelling)}: ${body.reason}`
+      )
+      assert(typeof body.pr === 'string', `no pr in the response to ${spelt(spelling)}`)
+      const invoiced = invoiceAmountMsat(body.pr)
+      if (invoiced !== null) {
+        assert(invoiced === amount, `asked for ${amount} msat, invoiced ${invoiced} msat`)
+      }
     }
 
     // A quote is not a note. Crediting one before its invoice settles
     // would hand out money for nothing.
     const withdrawUrl = pay.withdrawLink ? fromLud17(pay.withdrawLink) : null
     if (withdrawUrl) {
-      const probe = new URL(withdrawUrl)
-      probe.searchParams.set('k1', secret)
-      const early = await get(probe)
-      assert(
-        early.status === 'ERROR',
-        'the note exists before anything paid for it - a quote is not a note'
-      )
+      for (const spelling of probed) {
+        const probe = new URL(withdrawUrl)
+        probe.searchParams.set('k1', named[spelling].secret)
+        const early = await get(probe)
+        assert(
+          early.status === 'ERROR',
+          'the note exists before anything paid for it - a quote is not a note'
+        )
+      }
     }
 
-    // A malformed h must be refused BEFORE an invoice exists. A wallet
-    // that pays a quote the mint was always going to reject has bought
-    // nothing, and the mint keeps the sats.
-    //
     // Malformed means not 32 bytes of hex, in any casing. Upper case is a
     // spelling, not a defect, and it is deliberately not probed: a WALLET
     // MUST send lowercase and every client here does, a SERVICE SHOULD
     // normalise before comparing, and one that refuses upper case outright
     // is strict rather than wrong - the wallet learns before it pays.
-    for (const [what, value] of [
+    const malformed = [
       ['not hex', 'z'.repeat(64)],
       ['a character short', '0'.repeat(63)],
       ['a character long', '0'.repeat(65)],
       ['empty', '']
-    ]) {
-      const body = await quoteAt(value)
-      assert(
-        body.status === 'ERROR' && !body.pr,
-        `issued an invoice for an h that is ${what} - a wallet would pay for a quote this mint cannot honour`
-      )
+    ]
+
+    for (const spelling of probed) {
+      for (const [what, value] of malformed) {
+        const body = await quoteAt(spelling, value)
+        if (spelling === 'h') {
+          // A wallet that pays a quote the mint was always going to reject
+          // has bought nothing, and the mint keeps the sats.
+          assert(
+            body.status === 'ERROR' && !body.pr,
+            `issued an invoice for an h that is ${what} - a wallet would pay for a quote this mint cannot honour`
+          )
+          continue
+        }
+        // The comment spelling, where the draft says the opposite.
+        assert(
+          body.status !== 'ERROR',
+          `refused a comment that is ${what} (${body.reason}) - LUD-25 requires the no-name fallback here, because plain LUD-12 comments are free text and any wallet may send one`
+        )
+        assert(
+          !body.verify,
+          `served a LUD-21 verify URL on a quote whose comment is ${what}, which the draft credits as k1=P - verify then hands the note itself to anyone holding the invoice, not merely proof that it was paid`
+        )
+      }
     }
 
-    // The three claims must agree. None of these disagreements loses
-    // anyone money on its own - a wallet reading a missing field as false
-    // falls back to the preimage flow, which is safe - so each is named
-    // rather than failed. Whether the mint really binds is the one thing
-    // this check cannot see, because that needs a settlement: it is
-    // graded separately, and failed rather than warned.
-    if (!echoed) {
+    // The claims must agree. None of these disagreements loses anyone
+    // money on its own - a wallet reading a missing field as false falls
+    // back to the preimage flow, which is safe - so each is named rather
+    // than failed. Whether the mint really binds is the one thing this
+    // check cannot see, because that needs a settlement: it is graded
+    // separately, and failed rather than warned.
+    if (advertised.includes('h') && echoedIn.length === 0) {
       problems.push(
         'bound quotes carry no mintToHash in the response, so a wallet cannot confirm at the one moment it is worth confirming, and falls back to racing the preimage'
       )
     }
-    if (echoed && !advertised) {
+    if (echoedIn.length > 0 && advertised.length === 0) {
       problems.push(
         'echoes mintToHash on a quote but does not advertise it on the payRequest, which is the endpoint every mint publishes and the one a wallet decides from'
       )
     }
-    if (advertised && mintAddress && !corroborated) {
+    // Only the `mintToHash` spelling belongs in both documents. LUD-25 asks
+    // a mint *payLink* to advertise `commentAllowed`, and the mint address
+    // document is a withdrawRequest, where a LUD-12 comment has nowhere to
+    // go - its absence there is correct, not a disagreement.
+    if (advertised.includes('h') && mintAddress && !corroborated.includes('h')) {
       problems.push('the payRequest advertises mintToHash and the mint address document does not')
     }
 
@@ -573,15 +661,17 @@ export const gradeMint = async (payUrl, report) => {
     // rule the withdraw callback already enforces.
     const otherAmount = Math.min(pay.maxSendable, amount * 2)
     if (otherAmount !== amount) {
-      const twice = await quoteAt(h, otherAmount)
-      if (twice.status !== 'ERROR') {
-        problems.push(
-          'issued a second quote against an output hash it had already bound - whichever payment settles first takes the id, and the other payer has bought nothing'
-        )
+      for (const spelling of probed) {
+        const twice = await quoteAt(spelling, named[spelling].h, otherAmount)
+        if (twice.status !== 'ERROR') {
+          problems.push(
+            `issued a second quote against an output already named by ${spelt(spelling)} - whichever payment settles first takes the id, and the other payer has bought nothing`
+          )
+        }
       }
     }
     if (problems.length > 0) throw soft(problems.join('; '))
-    return `claimed by ${claimedBy.join(', ')}; bound a quote to a hash of the runner's own secret and refused four malformed ones`
+    return `named by ${probed.join(' and ')}; claimed by ${claimedBy.join(', ')}; bound a quote to a hash of the runner's own secret and handled four malformed ones as the draft requires`
   })
 
   // The payRequest, with the mint address the checks above fetched hung

package/vectors/mint-to-hash.json

@@ -198,7 +198,7 @@
       "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "k1": "0505050505050505050505050505050505050505050505050505050505050505",
       "preimageIsAValidK1": false,
-      "note": "the wallet can claim by asking the withdraw endpoint for its own secret directly - it never needs the verify poll at all"
+      "note": "a software wallet can claim by asking the withdraw endpoint for its own secret directly. A sealed signer that will not export that secret instead uses the optional bound receipt below to confirm the note without revealing k1"
     },
     "unbound": {
       "noteId": "e802086ad6a1e16b78352ad7296d2aabd835b1b16dbe951e1135b97c68e29d81",
@@ -207,6 +207,108 @@
       "note": "the wallet must poll verify for the preimage, and rotate the instant it has it"
     }
   },
+  "receipt": {
+    "description": "An optional LUD-21 settlement receipt for a bound quote. This is needed by a sealed signer that generated k1 but will not export it merely so its companion app can probe the withdraw endpoint. The quote commits to the exact output id and net amount before payment. Once settled, verify repeats that commitment and adds the ordinary LUD-25 note signature. No field changes the legacy LUD-21 meaning of preimage: it remains payment proof and still does not open the bound note.",
+    "optional": true,
+    "field": "mint",
+    "keyEstablishment": {
+      "rule": "The WALLET must know the receipt verification key before it pays: recover the signing node identity from the BOLT-11 invoice, or read mintPubkey from the payRequest under the wallet's existing trust/pinning policy.",
+      "payRequest": {
+        "mintToHash": true,
+        "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
+      }
+    },
+    "commitment": {
+      "h": "the normalised output id committed by this quote; 32 bytes as 64 lowercase hex",
+      "amount": "the exact net note value in millisatoshis after fees",
+      "sig": "absent before settlement; after settlement, the ordinary recoverable LUD-25 signature over LNURLcash:<amount>:<h>"
+    },
+    "quote": {
+      "pr": "lnbc210n1pjqrstuvwxyz",
+      "verify": "https://mint.example/verify/e802086ad6a1e16b78352ad7296d2aabd835b1b16dbe951e1135b97c68e29d81",
+      "mintToHash": true,
+      "mint": {
+        "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+        "amount": 21000
+      }
+    },
+    "unsettled": {
+      "status": "OK",
+      "settled": false,
+      "preimage": null,
+      "pr": "lnbc210n1pjqrstuvwxyz",
+      "mint": {
+        "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+        "amount": 21000
+      }
+    },
+    "settled": {
+      "status": "OK",
+      "settled": true,
+      "preimage": "0606060606060606060606060606060606060606060606060606060606060606",
+      "pr": "lnbc210n1pjqrstuvwxyz",
+      "mint": {
+        "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+        "amount": 21000,
+        "sig": "5559e4ad39ea32a9f8dba641cc69e2874e962fd569cd661b5278ccd13f647d6e74bce7105178f3817f1938cee81765cc3ab9005a5821c5d2228c2003418542ea01"
+      }
+    },
+    "walletRules": [
+      "A WALLET that requires a receipt MUST refuse to show or pay an invoice unless quote.mintToHash is exactly true and quote.mint matches the h it requested and the exact amount it expects to receive.",
+      "Before accepting settlement, it MUST match verify.pr to quote.pr, match verify.mint.h and verify.mint.amount to the quote commitment, require settled to be exactly true, and verify mint.sig with the mint public key and its locally held k1.",
+      "A SERVICE MUST NOT return mint.sig before settlement. An unsettled response MAY repeat h and amount so a wallet can diagnose a mismatch, but that repetition is not a receipt.",
+      "Absence of quote.mint means the optional receipt is not offered. A software wallet can still use mintToHash and claim with its own k1; a sealed signer falls back before payment to the legacy preimage-and-rotate flow."
+    ],
+    "invalid": [
+      {
+        "name": "quote commits a different h",
+        "quote": {
+          "mintToHash": true,
+          "mint": {
+            "h": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
+            "amount": 21000
+          }
+        },
+        "reason": "the invoice is not demonstrably buying the output the wallet named"
+      },
+      {
+        "name": "verify changes the net amount",
+        "verify": {
+          "settled": true,
+          "mint": {
+            "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+            "amount": 20999,
+            "sig": "5559e4ad39ea32a9f8dba641cc69e2874e962fd569cd661b5278ccd13f647d6e74bce7105178f3817f1938cee81765cc3ab9005a5821c5d2228c2003418542ea01"
+          }
+        },
+        "reason": "the settled receipt is not the commitment shown before payment"
+      },
+      {
+        "name": "signature appears before settlement",
+        "verify": {
+          "settled": false,
+          "mint": {
+            "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+            "amount": 21000,
+            "sig": "5559e4ad39ea32a9f8dba641cc69e2874e962fd569cd661b5278ccd13f647d6e74bce7105178f3817f1938cee81765cc3ab9005a5821c5d2228c2003418542ea01"
+          }
+        },
+        "reason": "a note signature is evidence of minted value and cannot be issued speculatively"
+      },
+      {
+        "name": "settled response has the wrong signature",
+        "verify": {
+          "settled": true,
+          "mint": {
+            "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+            "amount": 21000,
+            "sig": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
+          }
+        },
+        "reason": "the signer cannot confirm a note the mint has not authenticated"
+      }
+    ]
+  },
   "normalisation": {
     "description": "One worked pair, so an implementation can check that the two spellings name one output rather than two.",
     "sent": "F849D67325FACF04177BC663B2DC544051831C589EF581D412F2EBA44834E77C",
@@ -441,7 +543,7 @@
     "A WALLET MUST send `h` as 64 lowercase hex. A SERVICE SHOULD normalise case before comparing and MUST NOT read the two spellings as two outputs, but a wallet that leans on that will meet a SERVICE that refuses upper case outright.",
     "A WALLET MUST decide from the payRequest, which every SERVICE publishes, rather than from the experimental mint address document, which many do not. A SERVICE that does not advertise `mintToHash` ignores `h`, and the note it mints is the preimage's.",
     "A WALLET MUST check the pay callback's own `mintToHash` before it pays. The other two advertisements can be cached or stale; that one is this quote, now. Absent means not bound, so claim the preimage way and rotate on sight.",
-    "Against a SERVICE that does advertise it, a WALLET needs no verify poll to claim: it knows its own secret, so it asks the withdraw endpoint for it directly. Keep the poll as the fallback for SERVICEs without the capability.",
+    "Against a SERVICE that advertises mintToHash, a software WALLET needs no verify poll to claim: it knows its own secret, so it asks the withdraw endpoint for it directly. A sealed signer that will not export k1 MAY require the optional bound receipt and use verify only as authenticated settlement evidence.",
     "A note minted at a WALLET-chosen hash is the WALLET's from birth. A wallet deriving its secrets from a seed can restore that note from the seed alone, which a preimage-secret note can never be."
   ]
 }