lnurlcash-conformance 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.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
@@ -461,7 +465,14 @@ 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} : {}),
+        // 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}
+          : {})
       })
     }
 
@@ -628,18 +639,28 @@ export const createMockMint = async (options = {}) => {
 
       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}
+      const body = {pr, disposable: false}
       if (opts.verify) 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 +673,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 +682,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 +807,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.3.0",
   "description": "Language-neutral conformance vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25) implementations",
   "author": "TheCryptoDonkey",
   "license": "MIT",

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."
   ]
 }