lnurlcash-conformance 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.
 
+## Unreleased
+
+## 0.5.0 - 2026-08-31
+
+**Breaking: the current LUD-25 draft's mandatory mint comment is now the
+baseline.** Every minting payRequest must advertise `commentAllowed >= 64`,
+and every quote must carry `comment=hex(sha256(secret))`; missing or malformed
+comments are refused before invoice creation. The payment preimage is
+settlement proof and never a bearer credential. `mintToHash`/`h` remains an
+additive ForgeSworn compatibility and receipt extension: when used, `h` must
+repeat the mandatory comment and cannot replace it. The mock, runner,
+lifecycle and pay-request vectors all enforce the same rule, including a
+mismatched `h`/`comment` refusal. `commentFallsBack` remains only as the
+non-compliant historical fixture documented in
+`docs/COMMENT-IS-MANDATORY.md`.
+
+**A mint that is not a Lightning Address is no longer failed for having no
+mint address document.** The document is probed by swapping
+`/.well-known/lnurlp/` for `/.well-known/lnurlw/` in the payRequest URL. On a
+mint served from a plain path that swap changes nothing, so the probe
+re-fetched the payRequest, read `tag: "payRequest"`, and failed the mint for
+an optional document it has nowhere to publish. Found by grading
+`bitkarrot/lnurlmint`, which is served at `/lnurlmint/lnurlp/<id>`; it now
+grades 6 passed, 0 failed on the checks that predate the mandate above.
+
+
+**Two checks for the draft's 25 August additions, both optional-graded.**
+
+`answers a note lookup by hash without the secret` covers "Checking a note
+without exposing it". The capability is detected rather than announced: the
+draft deliberately gives an unrecognized `h` the same answer an unknown
+`k1` gets, so a live note's own hash is the only probe that separates a
+mint which implements the lookup from one which never did. A mint that does
+not offer it is not graded down; one that offers it must omit `k1` from the
+reply - a wallet asking by hash already holds the secret, and filling the
+field in puts the note back on the wire the lookup exists to keep it off -
+must report the same value by hash as by `k1`, and must refuse a hash it
+never registered.
+
+`refuses an oversized merge cleanly` covers the merge cap. The cap itself
+is a MAY, so a mint that does not name one is not graded down, only
+reported, since a wallet must then batch by URL length rather than rely on
+a refusal. The one answer that fails is `OK`: every input on that probe is
+fabricated by the runner, so a mint accepting it has minted an output
+against notes it never held, which is what a truncated `k1` list read as a
+shorter merge looks like from outside.
+
 ## 0.4.0 - 2026-08-26
 
 **The mint-output naming check now reads the spelling LUD-25 actually

package/README.md

@@ -60,7 +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 |
+| `mint-to-hash.json` | additive `mintToHash` compatibility and optional bound LUD-21 receipts; not baseline LUD-25 |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
 | `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
@@ -100,10 +100,10 @@ must survive:
 | `--sunset` | refuses anything that grows its liabilities |
 | `--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 the preimage from verify before settlement — the bearer secret, to anyone with the hash |
+| `--verifyLeaksEarly` | serves a preimage before settlement, falsely claiming payment proof before payment happened |
 | `--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, echoes it back on the quote, and mints at the payment hash anyway, so the preimage is still the money |
+| `--mintToHashIgnoresH` | claims it but accepts `h` and mandatory `comment` naming different outputs |
 
 The three `mintToHash*` misbehaviours need `--mintToHash` alongside them;
 on their own they do nothing, because a mint that never offered the
@@ -126,7 +126,7 @@ answered:
 | `--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 |
-| `--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 |
+| `--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 |
 
@@ -155,43 +155,23 @@ npx lnurlcash-conform mint@example.com
 
 Read-only by default: resolves the payRequest, checks the `withdrawLink`
 (either legal spelling, and the report says which one the mint uses),
-the fee advertisement, invoice amounts, that LUD-21 verify serves no
-preimage before settlement (on a mint that value IS the bearer secret, and
-everyone on the payment's route knows the payment hash), whether an
+the fee advertisement, invoice amounts, mandatory `commentAllowed: 64`,
+pre-invoice rejection of missing or malformed mint comments, whether an
 unknown note is reported distinguishably from a spent one, and the
 experimental mint address.
 
-One more is graded softly, and it is the one that changes what a bearer
-note is. In LUD-25 a minted note's `k1` is the payment preimage, so the
-preimage is the money, and every routing node on the payment path learns
-it, as does anyone who merely saw the invoice and polled LUD-21 verify with
-its payment hash. A QR on a desktop screen is exactly that. A mint may
-instead take an `h` on its pay callback, the sha256 of a secret the wallet
-chose, and credit the note there; the preimage is then an ordinary payment
-proof that opens nothing. The mint says so in three places, and they mean
-different things: `mintToHash: true` on the payRequest (every mint has one,
-so it is what a wallet decides from), the same on the experimental mint
-address document (corroboration), and the same echoed on the pay callback's
-own response when *that* quote was bound (the one that matters at the moment
-money moves, because the other two can be cached). Anything that is not
-exactly the boolean `true` is no.
-
-A mint that says nothing anywhere is reported as not offering it and passes,
-which is every mint today. A mint that claims it is asked to prove the
-refusals: a malformed `h` must get no invoice at all, since a wallet that
-pays for a quote the mint will reject has bought nothing. Malformed means
-not 32 bytes of hex, in any casing. A wallet MUST send `h` as 64 lowercase
-hex and every client here does, but hex is case-insensitive, so a service
-SHOULD normalise before comparing and MUST NOT read `AAAA...` and `aaaa...`
-as two different outputs: keying the string it was handed files the note
-where the wallet will never look for it, and nobody is told. A service that
-refuses upper case outright is being strict rather than wrong, so the grader
-does not probe it either way. Where the three
-claims disagree, the grader names the disagreement rather than failing it:
-none of those loses anyone money on its own. What is failed is a mint that
-claims the capability and does not bind, because a wallet believing the
-claim stops rotating on sight; that one needs a settlement to see, so it
-rides on `--preimage`.
+Current LUD-25 minting is always comment-bound. The wallet persists a secret,
+sends `comment=hex(sha256(secret))`, and the payment preimage remains ordinary
+settlement proof. A mint that cannot accept the 64-character commitment, or
+that silently creates a preimage-backed note, fails grading.
+
+`mintToHash` is retained as an additive compatibility field. When advertised,
+the runner sends `h` alongside the mandatory comment and requires both to name
+the same output. A malformed `h` must be rejected before invoice creation.
+The payRequest, experimental mint-address document and quote echo are checked
+separately because each claim has a different lifetime. Disagreement between
+those extension advertisements warns; failure to honour a claimed binding
+fails when the paid `--preimage` check proves where the note actually landed.
 
 Three other things a mint may publish are graded softly, because none of them
 is in LUD-25: the mint info on the discovery endpoint, a `/stats` endpoint

package/mock-mint/index.d.ts

@@ -137,14 +137,10 @@ export interface MockMintOptions {
   /** what the node behind a stats-publishing mock claims to hold */
   localBalanceMsat?: number
   /**
-   * Let a WALLET name the note it is buying. Off, and nothing about it
-   * reaches the wire: nothing is advertised anywhere and the pay callback
-   * does not read `h` at all. On, the callback takes an optional `h` - 64
-   * lowercase hex, the sha256 of a secret the wallet chose, the same
-   * thing `h` means on the withdraw callback - and credits the note at
-   * that id when the invoice settles. The payment preimage is then not a
-   * valid k1 for that note, which matters because every routing node on
-   * the payment path learns it, and so does anyone who saw the invoice.
+   * Additive compatibility spelling for the mandatory mint comment. Off,
+   * `h` is not advertised or read, while comment-bound minting remains the
+   * baseline. On, WALLET may repeat the same 64-hex output commitment as
+   * `h`, enabling the ForgeSworn/Moneyer quote and receipt vocabulary.
    *
    * The capability is advertised in three places: `mintToHash: true` on
    * the payRequest (every mint has one, so it is what a wallet decides
@@ -176,11 +172,9 @@ export interface MockMintOptions {
    */
   mintToHashAcceptsUsedH?: boolean
   /**
-   * non-compliant, mintToHash on: advertise the capability, echo it back
-   * on the quote, and credit the note at the payment hash anyway - the
-   * preimage is still the money and the wallet's own secret names
-   * nothing. The wallet stopped rotating on sight because it was told it
-   * did not need to, so this is the worst of both schemes.
+   * non-compliant, mintToHash on: accept `h` and mandatory `comment` even
+   * when they name different outputs. The normative comment still binds
+   * the note, but the extension claim and any h-watching signer disagree.
    */
   mintToHashIgnoresH?: boolean
   /**

package/mock-mint/index.mjs

@@ -66,9 +66,8 @@ const DEFAULTS = {
   // WALLET that handles one but not the other fails against real mints.
   // Run your client against both.
   withdrawLinkForm: 'plain',
-  // LUD-21 verify endpoint. Off means 404, not merely unadvertised: the
-  // preimage it serves IS a bearer secret, so an operator needs a real
-  // off switch.
+  // LUD-21 verify endpoint. Off means 404, not merely unadvertised, so the
+  // mock can exercise current mints that provide no settlement polling.
   verify: true,
   // Publish `payLink` on a note's informational GET, the way home for a
   // holder who has nothing but the note. On by default because the
@@ -166,17 +165,14 @@ const DEFAULTS = {
   //
   // ---- naming the note you are buying ----
   //
-  // Off, and nothing about it reaches the wire: nothing is advertised
-  // anywhere, the pay callback does not read `h` at all, and a minted
-  // note's secret is the payment preimage exactly as it always was.
+  // Off means only the additive `h` spelling is absent: it is not advertised
+  // and the pay callback does not read it. Mandatory comment-bound minting
+  // remains active independently.
   //
-  // On, a WALLET MAY add h=<64 lowercase hex> to the LUD-06 pay callback -
-  // the sha256 of a secret it chose, the same thing `h` means on the
-  // withdraw callback. The note is then credited at that id when the
-  // invoice settles, and the payment preimage is NOT a valid k1 for it.
-  // Which matters because two sets of untrusted people learn a preimage:
-  // every routing node on the payment path, and anyone who merely saw the
-  // invoice and polled /verify with its payment hash.
+  // On, a WALLET MAY repeat the mandatory comment hash as
+  // h=<64 lowercase hex> on the LUD-06 pay callback. This enables the
+  // earlier ForgeSworn/Moneyer capability and receipt vocabulary without
+  // changing which output the normative comment names.
   //
   // The capability is claimed in three places and they say different
   // things. `mintToHash: true` on the payRequest means "I accept an h on
@@ -187,6 +183,23 @@ const DEFAULTS = {
   // which is the one that matters at the moment money moves: the other
   // two can be cached or stale.
   mintToHash: false,
+  // LUD-25 "Checking a note without exposing it": answer the informational
+  // GET by `?h=sha256(k1)` as well as by `?k1=`, so a wallet can look a note
+  // up without putting the live secret in a query string. Optional.
+  //   true             - compliant
+  //   'echoesK1'       - non-compliant: fills in k1, putting the secret back
+  //                      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
+  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
+  // refuses more than that many k1 with the draft's own reason string.
+  mergeCap: 0,
+  // non-compliant: answer OK to an oversized merge whatever its inputs -
+  // what a mint that parses a truncated k1 list and shrugs looks like from
+  // outside. It has minted an output against notes it never saw.
+  acceptsOversizedMerge: 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.
@@ -199,10 +212,10 @@ const DEFAULTS = {
   // already names a note, an invoice or another quote's output, so two
   // payers' money points at one id
   mintToHashAcceptsUsedH: false,
-  // non-compliant, mintToHash on: advertise the capability, echo it back
-  // on the quote, and credit the note at the payment hash anyway. The
-  // wallet stopped rotating on sight because it was told it did not need
-  // to, so this is the worst of both schemes
+  // non-compliant, mintToHash on: accept h and mandatory comment even when
+  // they name different outputs. The comment still binds the note, but the
+  // extension claim is false and a receipt-watching signer follows the
+  // other commitment.
   mintToHashIgnoresH: false,
   // Which of the three the mock actually says it in. Undefined means all
   // three, which is what an honest mint publishes. Narrowing it changes
@@ -213,25 +226,27 @@ const DEFAULTS = {
   // array or a comma-separated string, so the CLI can pass one.
   mintToHashAdvertisedOn: undefined,
 
-  // The SAME capability in the spelling LUD-25 actually specifies:
+  // The mandatory minting commitment in the spelling LUD-25 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.
+  // characters and reads `comment` as the output name. The conforming
+  // default is 64. Setting it false or below 64 deliberately models a
+  // SERVICE that cannot mint under the current draft.
   //
-  // 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,
+  // `h` remains an additive Moneyer compatibility field. When supplied it
+  // must be well formed and equal the mandatory comment; it never replaces
+  // the comment and cannot make an otherwise unnamed quote valid.
+  commentAllowed: 64,
+  // non-compliant, commentAllowed on: fall back to a preimage-keyed note
+  // when the comment is missing or malformed, instead of refusing. This was
+  // the draft's line 80 behaviour and is now the defect - see
+  // docs/COMMENT-IS-MANDATORY.md.
+  commentFallsBack: false,
+  // non-compliant, and narrower: refuse a malformed comment - an empty value
+  // included - but fall back when the key is absent entirely. That is the
+  // distinction the malformed loop cannot reach, and the commonest way to
+  // arrive unnamed, since it is what every ordinary LUD-06 wallet sends.
+  commentFallsBackWhenAbsent: 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
@@ -401,10 +416,9 @@ export const createMockMint = async (options = {}) => {
       const invoice = hash ? invoices.get(hash) : null
       if (!invoice) return fail('unknown payment hash')
       invoice.settled = true
-      // paying a mint invoice is what brings its note into existence. The
-      // preimage IS the note secret and the note id IS the payment hash,
-      // unless the wallet named an output hash of its own on the quote -
-      // then the note is credited there and the preimage is nobody's key.
+      // Paying a mint invoice brings its comment-bound note into existence.
+      // The payment-hash target is reachable only under deliberate legacy
+      // defect flags that allowed an unnamed quote.
       const target = invoice.boundTo ?? hash
       if (!notes.has(target)) mintNote(target, invoice.amountMsat)
       if (invoice.boundTo) boundOutputs.delete(invoice.boundTo)
@@ -461,7 +475,13 @@ export const createMockMint = async (options = {}) => {
     const origin = `http://${req.headers.host}`
 
     // ---- LUD-16 payRequest (minting) ----
-    const lnurlpMatch = url.pathname.match(/^\/\.well-known\/lnurlp\/(.+)$/)
+    // Both shapes are in the wild. A Lightning Address mint lives under
+    // /.well-known/lnurlp/<name>; an LNbits extension serves the same
+    // payRequest at a plain path with no well-known anywhere, which is the
+    // case a grader must not mistake for a missing mint address document.
+    const lnurlpMatch =
+      url.pathname.match(/^\/\.well-known\/lnurlp\/(.+)$/) ??
+      url.pathname.match(/^\/lnurlp\/(.+)$/)
     if (lnurlpMatch) {
       const user = lnurlpMatch[1]
       if (user !== opts.username && user !== '_') {
@@ -627,6 +647,7 @@ export const createMockMint = async (options = {}) => {
       // before the option existed.
       let boundTo = null
       let echoBound = false
+      let requestedH = null
       if (opts.mintToHash) {
         // absent is not the same as empty: a wallet that sent `h=` meant
         // to bind, and must not be handed an unbound quote in silence
@@ -655,6 +676,7 @@ export const createMockMint = async (options = {}) => {
             return fail('Invalid or already spent k1.')
           }
           if (wellFormed) {
+            requestedH = h
             // The echo says "this quote is bound", so an honest mint
             // sets it exactly when it did bind. mintToHashIgnoresH is the
             // mint that says it and does not; leaving 'quote' out of
@@ -665,14 +687,17 @@ 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.
+      // The LUD-25 spelling. It is mandatory for every mint quote. The
+      // additive `h` spelling may corroborate it, but never substitutes for
+      // it and must name the same output when both are present.
       let namedByComment = false
-      if (opts.commentAllowed) {
+      // >= 64, the same threshold the runner reads the capability at: a
+      // commentAllowed too short to carry a 32-byte hash is not this
+      // capability, so nothing about it may be required either.
+      if (opts.commentAllowed >= 64) {
         const sent = q.get('comment')
-        if (sent !== null && sent !== '') {
-          const wellFormed = /^[0-9a-f]{64}$/i.test(sent)
+        const wellFormed = sent !== null && sent !== '' && /^[0-9a-f]{64}$/i.test(sent)
+        {
           if (wellFormed) {
             const h = sent.toLowerCase()
             // Same collision rule the `h` spelling gets: an id already
@@ -681,16 +706,28 @@ export const createMockMint = async (options = {}) => {
             if (outputIdInUse(h) && !opts.mintToHashAcceptsUsedH) {
               return fail('Invalid or already spent k1.')
             }
-            if (!opts.mintToHashIgnoresH) {
-              boundTo = h
-              namedByComment = true
+            if (
+              requestedH !== null &&
+              requestedH !== h &&
+              !opts.mintToHashIgnoresH
+            ) {
+              return fail('h and comment must name the same output.')
             }
-          } 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.')
+            // The normative comment always binds the quote. The defect flag
+            // only models an extension implementation that ignores or fails
+            // to compare h.
+            boundTo = h
+            namedByComment = true
+          } else if (
+            !opts.commentFallsBack &&
+            !(opts.commentFallsBackWhenAbsent && sent === null)
+          ) {
+            // A mint quote without the mandatory comment can only fall back
+            // to the payment preimage. The current draft forbids that even
+            // when the additive `h` field happened to name an output too.
+            return fail(
+              'Missing or malformed comment: a hex-encoded 32-byte hashed secret is required to mint.'
+            )
           }
         }
       }
@@ -705,13 +742,12 @@ export const createMockMint = async (options = {}) => {
       }
       invoices.set(paymentHash, invoice)
       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
+      // Verify is safe for every conforming quote because comment-bound
+      // minting makes the payment preimage ordinary settlement proof. The
+      // conditional remains only so the mock can reproduce the retired
+      // preimage-backed behaviour when commentAllowed is deliberately off.
+      const verifySafe =
+        !(opts.commentAllowed >= 64) || Boolean(boundTo) || 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
@@ -741,11 +777,9 @@ export const createMockMint = async (options = {}) => {
       const body = {
         status: 'OK',
         settled: invoice.settled,
-        // the preimage IS the bearer secret here - a real SERVICE should
-        // think hard before serving it, and a WALLET that receives one
-        // must rotate immediately. The exception is a quote the wallet
-        // bound with its own h: that note is credited elsewhere, so the
-        // preimage is an ordinary payment proof and leaks nothing.
+        // For a conforming comment-bound quote this is ordinary payment
+        // proof and never the bearer secret. It becomes a bearer secret only
+        // in the mock's deliberately non-compliant legacy mode.
         preimage: invoice.settled || opts.verifyLeaksEarly ? invoice.preimage : null,
         pr: invoice.pr ?? fakeInvoice(invoice.amountMsat, invoice.preimage)
       }
@@ -764,6 +798,31 @@ export const createMockMint = async (options = {}) => {
     // ---- LUD-03 informational GET ----
     if (url.pathname === '/w') {
       const k1 = q.get('k1')?.toLowerCase()
+      // The hash lookup. Notes are already keyed by sha256(k1) internally,
+      // so this is a second way in to a lookup the mint can always do - and
+      // `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) {
+        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.')
+        }
+        return send({
+          tag: 'withdrawRequest',
+          callback: `${origin}/w/cb`,
+          // k1 is omitted: a wallet asking by hash already holds the secret,
+          // which is the only way it could have computed the hash to send.
+          ...(opts.hashLookup === 'echoesK1' ? {k1: 'c'.repeat(64)} : {}),
+          minWithdrawable: 0,
+          maxWithdrawable: (held?.amountMsat ?? 21000) + opts.lieAboutValue,
+          defaultDescription: 'an LNURLcash note',
+          mintPubkey: pubkey
+        })
+      }
       if (!k1) return fail('Unknown note.')
       if (!/^[0-9a-f]{64}$/.test(k1)) return fail('Unknown note.')
       const note = notes.get(noteId(k1))
@@ -802,6 +861,8 @@ export const createMockMint = async (options = {}) => {
       const h2 = q.get('h2')
 
       if (k1s.length === 0) return fail('Missing k1.')
+      if (opts.acceptsOversizedMerge && k1s.length > 20) return send({status: 'OK'})
+      if (opts.mergeCap > 0 && k1s.length > opts.mergeCap) return fail('too many k1')
       // a repeated k1 would count one note's value twice into the output -
       // refused atomically, as the reference mint does
       if (new Set(k1s).size !== k1s.length) return fail('Invalid or already spent k1.')

package/package.json

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

@@ -279,6 +279,14 @@ export const gradeMint = async (payUrl, report) => {
     const amount = Math.max(pay.minSendable, 1000)
     const url = new URL(pay.callback)
     url.searchParams.set('amount', String(amount))
+    // A mint advertising comment protection requires a named quote (see
+    // docs/COMMENT-IS-MANDATORY.md), so the plain LUD-06 request an
+    // ordinary wallet would send is refused there by design. Name it the
+    // way a LUD-25 wallet does, or this check grades the mandate rather
+    // than the invoice.
+    if (Number.isFinite(pay.commentAllowed) && pay.commentAllowed >= 64) {
+      url.searchParams.set('comment', noteId(bytesToHex(randomBytes(32))))
+    }
     const body = await get(url)
     assert(body.status !== 'ERROR', `refused: ${body.reason}`)
     assert(typeof body.pr === 'string', 'no pr in the response')
@@ -297,10 +305,8 @@ export const gradeMint = async (payUrl, report) => {
   })
 
   await report.check('verify serves no secret before settlement', async () => {
-    // On a mint the invoice preimage IS the bearer secret of the note the
-    // payment will create, and everyone on the payment's route learns the
-    // payment hash. A verify endpoint that answers the hash with the
-    // preimage before settlement hands the note to whoever polls first.
+    // The payment preimage is safe from bearer-note use once comment-bound,
+    // but it is still a settlement proof and must not exist before payment.
     if (!verifyUrl) throw soft('no LUD-21 verify URL to probe')
     const body = await get(verifyUrl)
     assert(body.status !== 'ERROR', `refused its own verify URL: ${body.reason}`)
@@ -310,7 +316,7 @@ export const gradeMint = async (payUrl, report) => {
     )
     assert(
       body.preimage == null,
-      'served a preimage before settlement - on a mint that value is the bearer secret itself'
+      'served a payment preimage before the invoice settled'
     )
     return 'settled: false, no preimage'
   })
@@ -332,6 +338,15 @@ export const gradeMint = async (payUrl, report) => {
 
   await report.check('publishes a mint address (experimental, optional)', async () => {
     const mirror = payUrl.replace('/.well-known/lnurlp/', '/.well-known/lnurlw/')
+    // The document only has a canonical location on a LUD-16 Lightning
+    // Address, where it mirrors the payRequest's own well-known path. A
+    // mint served from a plain path - an LNbits extension, say - has
+    // nowhere to publish it, and the swap above leaves the URL untouched:
+    // probing it anyway re-fetches the payRequest and reads its
+    // tag as a malformed mint address.
+    if (mirror === payUrl) {
+      throw soft('not published - this mint is not served from a Lightning Address, so there is no well-known lnurlw path to mirror')
+    }
     let body
     try {
       body = await get(mirror)
@@ -470,21 +485,10 @@ export const gradeMint = async (payUrl, report) => {
     return detail
   })
 
-  // 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.
+  // Naming the note being bought is mandatory in the current LUD-25 draft:
+  // `comment = hex(sha256(secret))`, with `commentAllowed` large enough for
+  // all 64 characters. `mintToHash` is the additive parameter spelling one
+  // mint shipped first. It may corroborate the comment, never replace it.
   //
   // The claim lives in three places. The payRequest is the one to decide
   // from, since every mint publishes one while the mint address document
@@ -493,24 +497,24 @@ export const gradeMint = async (payUrl, report) => {
   // 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:
+  // The two spellings are not symmetric:
   //
   //   `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 () => {
+  //   `comment` is the normative commitment and MUST be present and valid
+  //   before any invoice exists. For an `h` probe the same hash is therefore
+  //   carried in both fields.
+  await report.check('requires comment-bound minting and honours the mintToHash extension', async () => {
     const amount = Math.max(pay.minSendable, 1000)
 
-    // 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.
+    assert(
+      Number.isFinite(pay.commentAllowed) && pay.commentAllowed >= 64,
+      `minting payRequest must advertise commentAllowed: 64, got ${JSON.stringify(pay.commentAllowed)}`
+    )
+
+    // Current LUD-25 minting requires commentAllowed of at least 64.
+    // Anything shorter cannot carry the output commitment at all.
     const spellingsOf = source => {
       const found = []
       if (source?.mintToHash === true) found.push('h')
@@ -521,6 +525,14 @@ export const gradeMint = async (payUrl, report) => {
       const url = new URL(pay.callback)
       url.searchParams.set('amount', String(msat))
       url.searchParams.set(spelling, value)
+      if (spelling === 'h') {
+        // `h` is an additive compatibility field. A conforming quote still
+        // carries the mandatory LUD-12 comment, and both name one output.
+        url.searchParams.set(
+          'comment',
+          /^[0-9a-f]{64}$/i.test(value) ? value : noteId(bytesToHex(randomBytes(32)))
+        )
+      }
       return get(url)
     }
     const spelt = spelling => (spelling === 'comment' ? 'a LUD-12 comment' : 'an h parameter')
@@ -538,7 +550,9 @@ export const gradeMint = async (payUrl, report) => {
     // 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']
+    // Probe h even when it was not advertised: a quote echoing mintToHash
+    // is itself a claim, and is otherwise impossible to discover.
+    const probed = [...new Set([...claimed, 'h'])]
     const named = Object.fromEntries(
       probed.map(spelling => {
         const secret = bytesToHex(randomBytes(32))
@@ -548,15 +562,7 @@ export const gradeMint = async (payUrl, report) => {
     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(
-        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 hClaimed = claimed.includes('h') || echoedIn.includes('h')
 
     const problems = []
     const claimedBy = [
@@ -609,6 +615,7 @@ export const gradeMint = async (payUrl, report) => {
       for (const [what, value] of malformed) {
         const body = await quoteAt(spelling, value)
         if (spelling === 'h') {
+          if (!hClaimed) continue
           // A wallet that pays a quote the mint was always going to reject
           // has bought nothing, and the mint keeps the sats.
           assert(
@@ -617,30 +624,48 @@ export const gradeMint = async (payUrl, report) => {
           )
           continue
         }
-        // The comment spelling, where the draft says the opposite.
+        // The normative comment spelling. A malformed commitment is refused
+        // before invoice creation; there is no preimage-backed fallback.
         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`
+          body.status === 'ERROR' && !body.pr,
+          `issued an invoice for a comment that is ${what} - current LUD-25 requires a well-formed wallet commitment before invoice creation`
         )
       }
     }
 
+    // The malformed loop can only probe values; explicitly cover absence.
+    const bare = new URL(pay.callback)
+    bare.searchParams.set('amount', String(amount))
+    const unnamed = await get(bare)
+    assert(
+      unnamed.status === 'ERROR' && !unnamed.pr,
+      'issued an invoice for a quote carrying no comment - current LUD-25 requires rejection before invoicing'
+    )
+
+    if (hClaimed) {
+      const mismatch = new URL(pay.callback)
+      mismatch.searchParams.set('amount', String(amount))
+      mismatch.searchParams.set('comment', noteId(bytesToHex(randomBytes(32))))
+      mismatch.searchParams.set('h', noteId(bytesToHex(randomBytes(32))))
+      const body = await get(mismatch)
+      assert(
+        body.status === 'ERROR' && !body.pr,
+        'issued an invoice when h and the mandatory comment named different outputs'
+      )
+    }
+
     // 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) {
+    if (advertised.includes('h') && !echoedIn.includes('h')) {
       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 (echoedIn.length > 0 && advertised.length === 0) {
+    if (echoedIn.includes('h') && !advertised.includes('h')) {
       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'
       )
@@ -662,6 +687,7 @@ export const gradeMint = async (payUrl, report) => {
     const otherAmount = Math.min(pay.maxSendable, amount * 2)
     if (otherAmount !== amount) {
       for (const spelling of probed) {
+        if (spelling === 'h' && !hClaimed) continue
         const twice = await quoteAt(spelling, named[spelling].h, otherAmount)
         if (twice.status !== 'ERROR') {
           problems.push(
@@ -779,6 +805,7 @@ export const gradeBoundMint = async (noteUrl, report, {preimage, payCallback = n
     if (payCallback) {
       const quote = new URL(payCallback)
       quote.searchParams.set('amount', '1000')
+      quote.searchParams.set('comment', noteId(k1))
       quote.searchParams.set('h', noteId(k1))
       const body = await get(quote)
       assert(
@@ -854,6 +881,72 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return 'maxWithdrawable is authoritative'
   })
 
+  // LUD-25 "Checking a note without exposing it". Optional, and detected
+  // rather than announced: the draft deliberately gives an unrecognized `h`
+  // 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.
+  await report.check('answers a note lookup by hash without the secret (optional)', async () => {
+    const byHash = new URL(url)
+    byHash.searchParams.delete('k1')
+    byHash.searchParams.delete('amount')
+    byHash.searchParams.set('h', noteId(k1))
+    const body = await get(byHash)
+    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'
+    }
+    // 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
+    // wire this lookup exists to keep it off.
+    assert(
+      body.k1 === undefined,
+      'the response carried a k1 - a lookup by hash must omit it, or it puts the bearer secret back in the reply the wallet asked by hash to avoid'
+    )
+    assert(
+      body.maxWithdrawable === info.maxWithdrawable,
+      `the same note is worth ${body.maxWithdrawable} by hash and ${info.maxWithdrawable} by k1`
+    )
+    // 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 nobody = new URL(url)
+    nobody.searchParams.delete('k1')
+    nobody.searchParams.delete('amount')
+    nobody.searchParams.set('h', noteId(bytesToHex(randomBytes(32))))
+    const invented = await get(nobody)
+    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'
+  })
+
+  // The merge cap. LUD-25 bounds a merge by URL length rather than by the
+  // protocol, and a request past that is truncated somewhere upstream into
+  // a malformed one. Probed with fabricated inputs: nothing here is a real
+  // note, so a compliant SERVICE has two acceptable answers and no third.
+  await report.check('refuses an oversized merge cleanly (optional cap)', async () => {
+    const cb = new URL(info.callback)
+    // Enough repeated k1 to carry the whole URL past the ~2000 characters
+    // browsers, servers and proxies commonly stop at.
+    const many = Math.ceil((2400 - cb.href.length) / 68)
+    for (let i = 0; i < many; i++) {
+      cb.searchParams.append('k1', bytesToHex(randomBytes(32)))
+    }
+    cb.searchParams.append('h', noteId(bytesToHex(randomBytes(32))))
+    const body = await get(cb)
+    // Whatever else it does, it must not say yes. Every input was invented
+    // by this runner and names no note anywhere.
+    assert(
+      body.status !== 'OK',
+      `answered OK to a merge of ${many} notes it has never held - a truncated k1 list read as a shorter merge mints an output against inputs the SERVICE never saw`
+    )
+    return /too many k1/i.test(body.reason ?? '')
+      ? `capped: "${body.reason}"`
+      : `no explicit cap - refused as "${body.reason}", so an oversized merge is indistinguishable from an invalid one and a wallet must batch by URL length`
+  })
+
   await report.check('refuses a rotate with no h', async () => {
     const cb = new URL(info.callback)
     cb.searchParams.append('k1', k1)

package/vectors/lifecycle.json

@@ -9,13 +9,14 @@
   ],
   "scenarios": [
     {
-      "name": "mint then rotate",
+      "name": "mint to a wallet-generated secret",
       "steps": [
-        "pay the payRequest invoice",
-        "the preimage is the k1",
-        "rotate immediately"
+        "persist a fresh secret",
+        "send its hash as the LUD-12 comment",
+        "pay the invoice",
+        "claim with the persisted secret"
       ],
-      "requirement": "a WALLET MUST rotate straight after claiming a minted note: the SERVICE generated that preimage and is a permanent prior holder of it. Anyone who saw the unpaid invoice can poll LUD-21 verify and race for it."
+      "requirement": "a SERVICE MUST reject a missing or malformed comment before invoicing. The payment preimage is only settlement proof; the freshly minted bearer k1 is the WALLET-generated secret whose hash was carried in comment."
     },
     {
       "name": "melt is not settlement",

package/vectors/mint-to-hash.json

@@ -1,17 +1,17 @@
 {
   "version": 1,
-  "spec": "LUD-06, LUD-21, LUD-25",
-  "description": "Naming the note you are buying. A WALLET MAY add `h` to the LUD-06 pay callback when minting: the sha256 of a secret it chose, 32 bytes as 64 lowercase hex, exactly what `h` means on the withdraw callback. The SERVICE then credits the minted note at that id on settlement, and the payment preimage is NOT a valid k1 for it. That is the whole point: in LUD-25 a minted note's k1 is the payment preimage, so the preimage is the money, and two sets of people learn it without being trusted with it - every routing node on the payment path, and anyone who merely saw the invoice and polled LUD-21 verify with its payment hash. Without `h` nothing changes and the preimage is still the secret, so this is purely additive: a SERVICE that has not implemented it is not broken, it simply does not offer the capability. This file fixes the parameter name, what counts as well-formed, and both refusal reasons, so implementations in different languages answer the same wallet the same way.",
+  "spec": "LUD-06, LUD-21, LUD-25 plus ForgeSworn mintToHash extension",
+  "description": "ForgeSworn compatibility profile layered on current LUD-25 minting. The normative output commitment is always `comment=hex(sha256(secret))`. A WALLET MAY repeat that same 64-hex hash as `h` for services and sealed-signer receipts that shipped before the comment spelling. `h` never replaces comment; if present it must be well formed and identify the same output. With or without the extension, the payment preimage is settlement proof and never a valid bearer k1.",
   "parameter": {
     "name": "h",
-    "on": "the LUD-06 pay callback, alongside amount",
-    "value": "sha256 of a WALLET-chosen secret, 32 bytes as 64 lowercase hex",
+    "on": "the LUD-06 pay callback, alongside amount and the mandatory identical comment",
+    "value": "the same sha256 commitment already carried in comment, 32 bytes as 64 lowercase hex",
     "optional": true,
-    "absent": "today's behaviour, unchanged: the note is credited at the payment hash and its k1 is the payment preimage"
+    "absent": "current LUD-25 behaviour: comment alone names the wallet-generated bearer secret"
   },
   "caseRule": {
-    "wallet": "A WALLET MUST send `h` as 64 lowercase hex. Strict on the producer side costs nothing and is what every implementation here does.",
-    "service": "A SERVICE SHOULD normalise case before comparing, and MUST NOT treat an otherwise well-formed upper-case `h` as a different output from its lowercase form. Hex is case-insensitive: both spellings are the same 32 bytes, so they name one output, not two.",
+    "wallet": "A WALLET using this extension MUST send the same commitment in `comment` and `h`, each as 64 lowercase hex.",
+    "service": "A SERVICE MUST require the normative comment, SHOULD normalise hex case before comparing, MUST reject a mismatched h, and MUST NOT treat upper- and lower-case spellings as different outputs.",
     "whyItMatters": "A SERVICE that keys the string it was handed files the note under the upper-case spelling, and then cannot find it when the wallet asks the withdraw endpoint for its own lowercase secret. The money is not stolen, it is simply lost, and nobody is told. A SERVICE that instead refuses an upper-case `h` outright is being strict rather than wrong, and loses nobody anything - the wallet learns before it pays.",
     "comparedAs": "Every case below carries `comparedAs`: the value a SERVICE compares and keys by, which is `h` lowercased, or null when `h` is absent or malformed."
   },
@@ -46,8 +46,8 @@
     "collision": "Invalid or already spent k1."
   },
   "outcomes": {
-    "bound": "an invoice is issued carrying `mintToHash: true`, and on settlement the note is credited at `comparedAs` - `h` lowercased, which for a WALLET following the rule is `h` itself. The payment preimage names nothing",
-    "unbound": "no `h` was sent: an invoice is issued and on settlement the note is credited at the payment hash, whose k1 is the payment preimage",
+    "extension-bound": "comment and h name the same output; an invoice is issued carrying `mintToHash: true`, and settlement credits that committed hash. The payment preimage names nothing",
+    "comment-only": "no h was sent: the mandatory comment still names the output, and the payment preimage names nothing",
     "malformed-h": "not 32 bytes of hex in any casing: refused before any invoice exists, so a wallet never pays for a quote the SERVICE was always going to reject",
     "collision": "refused before any invoice exists, with the same reason a colliding output hash gets on the withdraw callback, so a probe learns nothing about which ids exist"
   },
@@ -61,21 +61,23 @@
     {
       "name": "no h at all",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": null,
       "comparedAs": null,
-      "outcome": "unbound",
+      "outcome": "comment-only",
       "invoiced": true,
       "echo": false,
-      "noteId": "e802086ad6a1e16b78352ad7296d2aabd835b1b16dbe951e1135b97c68e29d81",
+      "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "reason": null,
-      "why": "the LUD-25 flow as it stands: nothing here is a change"
+      "why": "the current LUD-25 flow: the mandatory comment names the output without the extension"
     },
     {
       "name": "a well-formed h",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "comparedAs": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
-      "outcome": "bound",
+      "outcome": "extension-bound",
       "invoiced": true,
       "echo": true,
       "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
@@ -84,6 +86,7 @@
     {
       "name": "an h that is not hex",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
       "comparedAs": null,
       "outcome": "malformed-h",
@@ -96,6 +99,7 @@
     {
       "name": "an h one character short",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "000000000000000000000000000000000000000000000000000000000000000",
       "comparedAs": null,
       "outcome": "malformed-h",
@@ -107,6 +111,7 @@
     {
       "name": "an h one character long",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "00000000000000000000000000000000000000000000000000000000000000000",
       "comparedAs": null,
       "outcome": "malformed-h",
@@ -118,6 +123,7 @@
     {
       "name": "an empty h",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "",
       "comparedAs": null,
       "outcome": "malformed-h",
@@ -130,9 +136,10 @@
     {
       "name": "an h in upper case hex",
       "amountMsat": 21000,
+      "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "h": "F849D67325FACF04177BC663B2DC544051831C589EF581D412F2EBA44834E77C",
       "comparedAs": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
-      "outcome": "bound",
+      "outcome": "extension-bound",
       "invoiced": true,
       "echo": true,
       "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
@@ -142,6 +149,7 @@
     {
       "name": "an h that already names a note",
       "amountMsat": 21000,
+      "comment": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
       "h": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
       "comparedAs": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
       "outcome": "collision",
@@ -154,6 +162,7 @@
     {
       "name": "an h in upper case hex that already names a note",
       "amountMsat": 21000,
+      "comment": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
       "h": "E0E77A507412B120F6EDE61F62295B1A7B2FF19D3DCC8F7253E51663470C888E",
       "comparedAs": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
       "outcome": "collision",
@@ -166,6 +175,7 @@
     {
       "name": "an h that already names an invoice this SERVICE issued",
       "amountMsat": 21000,
+      "comment": "4bb06f8e4e3a7715d201d573d0aa423762e55dabd61a2c02278fa56cc6d294e0",
       "h": "4bb06f8e4e3a7715d201d573d0aa423762e55dabd61a2c02278fa56cc6d294e0",
       "comparedAs": "4bb06f8e4e3a7715d201d573d0aa423762e55dabd61a2c02278fa56cc6d294e0",
       "outcome": "collision",
@@ -178,6 +188,7 @@
     {
       "name": "an h another quote is already waiting to credit",
       "amountMsat": 21000,
+      "comment": "2578ccf8645b2d1dc10c465eff843585970f3a7e22296a92cad55d489a272072",
       "h": "2578ccf8645b2d1dc10c465eff843585970f3a7e22296a92cad55d489a272072",
       "comparedAs": "2578ccf8645b2d1dc10c465eff843585970f3a7e22296a92cad55d489a272072",
       "outcome": "collision",
@@ -191,20 +202,21 @@
   "settlement": {
     "description": "One worked settlement, both ways round, so an implementation can check where the note landed rather than only that an invoice came back.",
     "walletSecret": "0505050505050505050505050505050505050505050505050505050505050505",
+    "comment": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
     "h": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
     "preimage": "0606060606060606060606060606060606060606060606060606060606060606",
     "paymentHash": "e802086ad6a1e16b78352ad7296d2aabd835b1b16dbe951e1135b97c68e29d81",
-    "bound": {
+    "extensionBound": {
       "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
       "k1": "0505050505050505050505050505050505050505050505050505050505050505",
       "preimageIsAValidK1": false,
       "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",
-      "k1": "0606060606060606060606060606060606060606060606060606060606060606",
-      "preimageIsAValidK1": true,
-      "note": "the wallet must poll verify for the preimage, and rotate the instant it has it"
+    "commentOnly": {
+      "noteId": "f849d67325facf04177bc663b2dc544051831c589ef581d412f2eba44834e77c",
+      "k1": "0505050505050505050505050505050505050505050505050505050505050505",
+      "preimageIsAValidK1": false,
+      "note": "without h, the mandatory comment still binds the freshly minted note to the wallet secret"
     }
   },
   "receipt": {
@@ -214,6 +226,7 @@
     "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": {
+        "commentAllowed": 64,
         "mintToHash": true,
         "mintPubkey": "034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa"
       }
@@ -257,7 +270,7 @@
       "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."
+      "Absence of quote.mint means the optional receipt is not offered. A software wallet still claims the comment-bound note with its own k1; a sealed signer must use another authenticated confirmation path or decline before payment."
     ],
     "invalid": [
       {
@@ -328,6 +341,7 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w",
         "mintToHash": true
       },
@@ -342,6 +356,7 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w"
       },
       "offered": false,
@@ -356,6 +371,7 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w",
         "mintToHash": false
       },
@@ -370,6 +386,7 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w",
         "mintToHash": "true"
       },
@@ -385,6 +402,7 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w",
         "mintToHash": 1
       },
@@ -521,29 +539,29 @@
   "contradictions": [
     {
       "name": "claims the capability and does not bind",
-      "what": "any of the three says `mintToHash: true`, and the minted note is still opened by the payment preimage",
+      "what": "any of the three says `mintToHash: true`, but the service ignores h or lets it disagree with the mandatory comment",
       "verdict": "broken",
-      "why": "the wallet was told it need not race the preimage, so it did not. The quote echo is the worst version of it, because the wallet was told at the very moment it decided to pay."
+      "why": "the extension claim is false and any receipt commitment may authenticate a different output from the mandatory comment."
     },
     {
       "name": "binds and says nothing on the quote",
       "what": "the payRequest advertises it, the quote carries `h`, and the response omits `mintToHash`",
       "verdict": "safe but unconfirmable",
-      "why": "a wallet reading a missing field as false falls back to the preimage flow, which is safe. It simply cannot confirm at the one moment confirmation is worth anything."
+      "why": "the comment-bound note remains safe, but the wallet cannot rely on extension-specific receipt semantics for this quote."
     },
     {
       "name": "says nothing anywhere and ignores `h`",
-      "what": "no advertisement, no echo, and the note is the preimage's",
+      "what": "no extension advertisement or echo; the mandatory comment still names the note",
       "verdict": "not implemented",
-      "why": "every mint today. Nothing about this is a defect."
+      "why": "the additive extension is absent; current LUD-25 comment minting remains fully implemented."
     }
   ],
   "walletRules": [
-    "A WALLET MUST persist its chosen secret BEFORE asking for the invoice. Paying and then losing the secret is the one way this makes things worse than the preimage scheme, and persisting first removes it.",
-    "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 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."
+    "A WALLET MUST persist its chosen secret BEFORE asking for the invoice, then send its hash in the mandatory comment.",
+    "A WALLET using the extension MUST repeat that same hash as 64 lowercase hex in h; it MUST NOT send two different output commitments.",
+    "A WALLET decides whether the additive h and receipt fields are supported from mintToHash on the payRequest; absence affects only the extension, never the mandatory comment-bound note.",
+    "A WALLET requiring a bound receipt MUST check the pay callback's own mintToHash and mint commitment before paying. If absent, it declines or uses another authenticated confirmation path; it never falls back to a preimage-backed mint.",
+    "A software WALLET needs no verify preimage to claim a comment-bound note: it already knows its secret. A sealed signer MAY require the optional receipt and use verify as authenticated settlement evidence.",
+    "A comment-bound note belongs to the WALLET from birth. Seed-derived secrets make it recoverable without relying on payment history."
   ]
 }

package/vectors/pay-request.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-06, LUD-11, LUD-16, LUD-21, LUD-25",
-  "description": "Minting. A LUD-06 payRequest MAY advertise `withdrawLink`, the raw LUD-17 URL of the withdraw endpoint: the payment preimage of its paid invoice becomes a valid k1 there. A WALLET MUST rotate immediately after claiming, because the SERVICE necessarily saw that preimage.",
+  "description": "Minting. A LUD-06 payRequest MAY advertise `withdrawLink`, the raw LUD-17 URL of the withdraw endpoint, and MUST then advertise `commentAllowed: 64`. Before paying, WALLET generates and persists a 32-byte secret and sends `comment=hex(sha256(secret))`; SERVICE rejects a missing or malformed comment before issuing an invoice. The payment preimage is settlement proof, never the bearer k1.",
   "accepted": [
     {
       "name": "a minting payRequest",
@@ -11,9 +11,11 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"],[\"text/identifier\",\"mint@mint.example\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "lnurlw://mint.example/w"
       },
       "withdrawLink": "lnurlw://mint.example/w",
+      "commentAllowed": 64,
       "mintFee": null
     },
     {
@@ -24,9 +26,11 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"],[\"text/identifier\",\"mint@mint.example\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "https://mint.example/w"
       },
       "withdrawLink": "https://mint.example/w",
+      "commentAllowed": 64,
       "mintFee": null,
       "why": "LUD-25 says a raw, non-bech32 URL \"as described in LUD-17\", and LUD-17 describes both the lnurlw:// scheme and the plain URL it stands for. lnurl-mint, and the spec diagram, use this form; moneyer uses lnurlw://. A WALLET MUST accept either, unchanged, and resolve it through the same LUD-17 rule as any other input"
     },
@@ -38,9 +42,11 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "lnurlw://mintmintmintmintmintmintmintmintmintmintmintmintmintmi.onion/w"
       },
       "withdrawLink": "lnurlw://mintmintmintmintmintmintmintmintmintmintmintmintmintmi.onion/w",
+      "commentAllowed": 64,
       "mintFee": null,
       "why": "the parser passes the link through; resolution to http:// happens when a note is built from it (see note-url.json build)"
     },
@@ -52,9 +58,11 @@
         "minSendable": 1000,
         "maxSendable": 100000000,
         "metadata": "[[\"text/plain\",\"a mint\"],[\"text/plain\",\"Mint fees: 1000,2000\"]]",
+        "commentAllowed": 64,
         "withdrawLink": "lnurlw://mint.example/w"
       },
       "withdrawLink": "lnurlw://mint.example/w",
+      "commentAllowed": 64,
       "mintFee": {
         "baseFeeMsat": 1000,
         "feePpm": 2000
@@ -88,8 +96,49 @@
         "minSendable": 1000,
         "maxSendable": 1000
       }
+    },
+    {
+      "name": "minting payRequest without room for the required hash comment",
+      "body": {
+        "tag": "payRequest",
+        "callback": "https://mint.example/p/cb",
+        "minSendable": 1000,
+        "maxSendable": 100000000,
+        "metadata": "[[\"text/plain\",\"a broken mint\"]]",
+        "withdrawLink": "lnurlw://mint.example/w"
+      },
+      "why": "current LUD-25 draft: minting is unavailable unless commentAllowed can carry exactly the 64-character hash commitment"
     }
   ],
+  "mintCallback": {
+    "accepted": [
+      {
+        "name": "wallet names the freshly minted note before invoice creation",
+        "amountMsat": 21000,
+        "comment": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
+        "result": "invoice",
+        "noteId": "e0e77a507412b120f6ede61f62295b1a7b2ff19d3dcc8f7253e51663470c888e",
+        "bearerK1": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "paymentPreimageIsBearerK1": false
+      }
+    ],
+    "rejected": [
+      {
+        "name": "missing comment",
+        "amountMsat": 21000,
+        "comment": null,
+        "result": "error-before-invoice",
+        "why": "an unnamed mint would make the payment preimage the money, which the current draft no longer permits"
+      },
+      {
+        "name": "malformed comment",
+        "amountMsat": 21000,
+        "comment": "not-a-32-byte-hash",
+        "result": "error-before-invoice",
+        "why": "comment must be bare hex encoding of a 32-byte SHA-256 output"
+      }
+    ]
+  },
   "invoice": {
     "accepted": [
       {
@@ -158,7 +207,7 @@
         },
         "settled": true,
         "preimage": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-        "why": "for LNURLcash this preimage IS the bearer secret - rotate immediately, and never treat verify as having closed the exposure"
+        "why": "the payment preimage proves settlement but cannot redeem the comment-bound bearer note"
       },
       {
         "name": "settled, preimage withheld",