lnurlcash-conformance 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,7 +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.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
+
+**`cash-derivation.json`: LUD-25's own seed-recoverable note secrets.** The
+draft specifies a BIP-32 scheme under `m/139'` and the reference wallet
+implements it; `derivation.json` remains, unchanged, as the pre-spec HMAC
+scheme that notes are still outstanding under.
+
+Every case carries `cashRoot`, the four `domainIndices`, a `hardened` flag per
+index, the `domainNode` and the resulting `k1`. The flags are the point of the
+file. `d1..d4` are raw uint32 and BIP-32 reads any index `>= 2^31` as hardened,
+so which levels are hardened is decided by the mint's own host name - an
+implementation that masks the top bit, or hardens all four, derives a
+different tree and restores nothing, silently. Both hosts in the vector land
+on a mix, so an implementation that gets it wrong cannot pass by luck.
+
+`bip32Vector1` carries BIP-32's own published test vector 1, so a port can
+prove its CKDpriv before blaming the LUD-25 path above it. The generator
+implements BIP-32 from `@noble` primitives rather than importing a BIP-32
+library, for the reason at the top of `tools/generate.mjs`: a vector produced
+by the library under test proves nothing.
 
 ## 0.6.0 - 2026-09-03
 

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.6.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 () => {

package/vectors/cash-derivation.json

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

package/vectors/index.json

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