lnurlcash-conformance 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,7 +4,32 @@ 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.8.0 - 2026-09-09
+
+**A spent note must say so.** LUD-25 [#307][307] settled the hash lookup's
+status contract the other way round from 0.7.0: a retained burned hash returns
+a spent error, an unregistered hash stays unknown, and the two must be
+distinguishable. A holder who kept only the hash can then learn a note was
+redeemed without putting its bearer secret on the wire, which is the whole
+point of the lookup. Mints passing 0.7.0's privacy check fail this one, and the
+change is deliberate.
+
+[307]: https://github.com/lnurl/luds/pull/307
+
+- Revise spent-hash grading to match the proposed LUD-25 status contract:
+  a retained burned hash must return a spent error, while an unregistered
+  hash remains unknown. Add the adversarial `hidesSpent` fixture; retain
+  `revealsSpent` as a compliant compatibility alias. This reverses the
+  0.7.0 privacy check and requires corresponding mint changes.
+
+- Documentation only, no grade changes. `previousPubkeys` is no longer a
+  LUD-25 field: the spec carried it briefly and dropped it on 2026-09-04,
+  replacing it with "`SERVICE` SHOULD NOT rotate `mintPubkey`" plus a
+  `WALLET`-side MUST to pin per origin and require explicit holder approval
+  for any replacement. The runner already graded it for shape only and never
+  for presence, which is the right posture for a convention; the comments and
+  the flag table now say that is what it is, and that a wallet must not read
+  it as permission to move a pin by itself.
 
 ## 0.7.0 - 2026-09-04
 

package/README.md

@@ -104,7 +104,7 @@ must survive:
 | `--retriedMutation=refuse` | deliberately answers an identical mutation retry as already spent instead of replaying its original success |
 | `--hashLookup=echoesK1` | offers hash lookup but puts a `k1` back in the response |
 | `--hashLookup=answersUnknown` | offers hash lookup but invents a note for an unknown hash |
-| `--hashLookup=revealsSpent` | offers hash lookup but distinguishes a burned hash from an unknown note |
+| `--hashLookup=hidesSpent` | incorrectly reports a retained spent hash as unknown |
 | `--hashLookup=acceptsBoth` | offers hash lookup but accepts `k1` and `h` together |
 | `--mintToHashAcceptsMalformedH` | claims `mintToHash` and invoices an `h` that is not 64 lowercase hex, so a wallet pays for a quote the mint will refuse |
 | `--mintToHashAcceptsUsedH` | claims it and invoices an `h` that already names a note, an invoice or another quote's output |
@@ -114,6 +114,10 @@ The three `mintToHash*` misbehaviours need `--mintToHash` alongside them;
 on their own they do nothing, because a mint that never offered the
 capability cannot misuse it.
 
+Hash lookup keeps the spending secret off the wire but reports spent state:
+`--hashLookup=true` distinguishes a burned hash from an unknown hash. The older
+`--hashLookup=revealsSpent` spelling remains an alias for this compliant behaviour.
+
 The remaining flags enable optional features, legal wire variants, or make a
 conforming default explicit. Optional fields stay absent unless requested:
 
@@ -125,7 +129,7 @@ conforming default explicit. Optional fields stay absent unless requested:
 | `--baseFeeMsat --feePpm` | also publishes `fees: {baseFeeMsat, feePpm}` on that endpoint, the structured twin of the fee line in the payRequest metadata |
 | `--stats` | serves `GET /stats`: what the mint owes, what is in flight, what the node holds, and the coverage between them |
 | `--localBalanceMsat=N` | what the node behind a stats-publishing mock claims to hold, so a mock can be told to look under-covered |
-| `--previousPubkeys=a,b` | keys this mint has signed under before, so notes issued before a rotation still verify |
+| `--previousPubkeys=a,b` | keys this mint has signed under before, so notes issued before a rotation still verify. Not a LUD-25 field: the spec carried it briefly and dropped it on 2026-09-04. Graded for shape where a mint offers it, never asked for |
 | `--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. This is the conforming default; use `refuse` only as an adversarial fixture |
@@ -268,7 +272,7 @@ Spec and reference implementations, all by dni, all MIT:
 - [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
 
 Implementations to run these vectors against are indexed in
-[awesome-lnurlcash](https://github.com/TheCryptoDonkey/awesome-lnurlcash).
+[awesome-lnurlcash](https://github.com/lnurlcash/awesome-lnurlcash).
 
 Contributions of vectors are welcome, particularly from implementers who
 found a case these missed. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/mock-mint/index.d.ts

@@ -14,6 +14,8 @@ export type HashLookup =
   | boolean
   | 'echoesK1'
   | 'answersUnknown'
+  | 'hidesSpent'
+  /** Legacy alias for true: spent hashes are now distinguishable. */
   | 'revealsSpent'
   | 'acceptsBoth'
 

package/mock-mint/index.mjs

@@ -190,8 +190,8 @@ const DEFAULTS = {
   //                      on the wire the lookup existed to keep it off
   //   'answersUnknown' - non-compliant: answers for a hash it never
   //                      registered, instead of the unknown-note refusal
-  //   'revealsSpent'   - non-compliant: distinguishes a burned h from an
-  //                      unknown note
+  //   'hidesSpent'     - non-compliant: hides a retained burned h as unknown
+  //   'revealsSpent'   - legacy alias for the now-compliant true behaviour
   //   'acceptsBoth'    - non-compliant: accepts k1 and h together
   hashLookup: false,
   // LUD-25 lets a SERVICE refuse an oversized merge outright rather than
@@ -813,8 +813,9 @@ export const createMockMint = async (options = {}) => {
         if (!invent) {
           if (!held) return fail('Unknown note.')
           if (held.state === 'burned') {
-            return fail(opts.hashLookup === 'revealsSpent' ? 'Note already spent.' : 'Unknown note.')
+            return fail(opts.hashLookup === 'hidesSpent' ? 'Unknown note.' : 'Note already spent.')
           }
+          if (held.state === 'pending') return fail('pending')
         }
         return send({
           tag: 'withdrawRequest',
@@ -833,6 +834,7 @@ export const createMockMint = async (options = {}) => {
       const note = notes.get(noteId(k1))
       if (!note) return fail('Unknown note.')
       if (note.state === 'burned') return fail('Note already spent.')
+      if (note.state === 'pending') return fail('pending')
       return send({
         tag: 'withdrawRequest',
         callback: `${origin}/w/cb`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Language-neutral conformance vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25) implementations",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -9,11 +9,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/TheCryptoDonkey/lnurlcash-conformance.git"
+    "url": "git+https://github.com/lnurlcash/lnurlcash-conformance.git"
   },
-  "homepage": "https://github.com/TheCryptoDonkey/lnurlcash-conformance#readme",
+  "homepage": "https://github.com/lnurlcash/lnurlcash-conformance#readme",
   "bugs": {
-    "url": "https://github.com/TheCryptoDonkey/lnurlcash-conformance/issues"
+    "url": "https://github.com/lnurlcash/lnurlcash-conformance/issues"
   },
   "type": "module",
   "keywords": [

package/runner/index.mjs

@@ -364,6 +364,15 @@ export const gradeMint = async (payUrl, report) => {
     // absence is never a failure - but a field that IS published and is
     // the wrong shape is worth saying out loud, because a wallet will try
     // to render it. Malformed means a warning, not a fail.
+    //
+    // previousPubkeys in particular: LUD-25 carried it briefly and dropped
+    // it on 2026-09-04, replacing it with "SERVICE SHOULD NOT rotate
+    // mintPubkey" plus a WALLET-side MUST to pin per origin and require
+    // explicit holder approval for any replacement. So it is now purely a
+    // convention between the implementations that already emit and read it,
+    // and it is graded here as one: shape only, never presence. Nothing in
+    // this suite asks a SERVICE to publish it, and a wallet must not treat
+    // it as permission to move a pin by itself.
     const problems = []
     for (const key of ['name', 'description', 'tosUrl', 'motd', 'version']) {
       const value = body[key]
@@ -833,7 +842,10 @@ export const gradeBoundMint = async (noteUrl, report, {preimage, payCallback = n
 // options.previousPubkeys: keys this mint has signed under before, from
 // the discovery endpoint. A note issued before a signing-key rotation
 // still verifies against one of them, and grading that as a bad signature
-// would punish a mint for rotating properly.
+// would punish a mint for rotating properly. Not a LUD-25 field - the spec
+// dropped it on 2026-09-04 and now says a SERVICE SHOULD NOT rotate at all
+// - so this is a convention the grader honours where a mint offers it,
+// never something it asks for.
 export const gradeNote = async (noteUrl, report, options = {}) => {
   const knownBaseFee = 'mintFee' in options ? (options.mintFee?.baseFeeMsat ?? 0) : null
   const previousPubkeys = Array.isArray(options.previousPubkeys)
@@ -1038,9 +1050,12 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     assert(info.mintPubkey, 'no mintPubkey advertised - offline verification is mandatory')
     assert(isCompressedPubkey(info.mintPubkey), 'mintPubkey is not a 33-byte compressed secp256k1 key')
     assert(currentSig, 'the rotate returned no sig - offline verification is mandatory')
-    // A mint that has rotated its signing key publishes the old ones as
+    // A mint that has rotated its signing key may publish the old ones as
     // previousPubkeys, so notes it issued before the rotation still
-    // verify. Any key it currently stands behind is an acceptable signer.
+    // verify. Any key it currently stands behind is an acceptable signer
+    // for grading purposes. That is a narrower claim than it looks: it
+    // says the signature is genuine, not that a wallet should accept the
+    // new key - LUD-25 puts that decision with the holder.
     const signedBy = [info.mintPubkey, ...previousPubkeys].find(key =>
       verifySignature(current, info.maxWithdrawable, currentSig, key)
     )
@@ -1055,26 +1070,28 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
       : `verified offline against a previous signing key (${signedBy.slice(0, 16)}...)`
   })
 
-  await report.check('does not reveal a burned note through hash lookup', async () => {
+  await report.check('reports a spent hash distinguishably from an unknown hash', async () => {
     if (!hashLookupOffered) throw soft('hash lookup is not offered')
     const burned = new URL(url)
     burned.searchParams.delete('k1')
     burned.searchParams.delete('amount')
     burned.searchParams.set('h', noteId(k1))
     const burnedResponse = await get(burned)
+    assert(
+      burnedResponse.status === 'ERROR' && typeof burnedResponse.reason === 'string' &&
+        /spent/i.test(burnedResponse.reason) && !/unknown|not found/i.test(burnedResponse.reason),
+      `a spent hash must be identified as spent, got ${JSON.stringify(burnedResponse)}`
+    )
 
-    const unknown = new URL(url)
-    unknown.searchParams.set('k1', bytesToHex(randomBytes(32)))
-    unknown.searchParams.delete('h')
-    unknown.searchParams.delete('amount')
+    const unknown = new URL(burned)
+    unknown.searchParams.set('h', noteId(bytesToHex(randomBytes(32))))
     const unknownResponse = await get(unknown)
-
     assert(
-      burnedResponse.status === unknownResponse.status &&
-        burnedResponse.reason === unknownResponse.reason,
-      `a burned h answered ${JSON.stringify(burnedResponse)} but an unknown k1 answered ${JSON.stringify(unknownResponse)}`
+      unknownResponse.status === 'ERROR' && typeof unknownResponse.reason === 'string' &&
+        /unknown|not found/i.test(unknownResponse.reason) && !/spent/i.test(unknownResponse.reason),
+      `an unregistered hash must be identified as unknown, got ${JSON.stringify(unknownResponse)}`
     )
-    return 'burned h is indistinguishable from an unknown note'
+    return 'spent and unknown hashes are distinguishable without disclosing k1'
   })
 
   await report.check('keeps signatures off the informational endpoint', async () => {