@forgesworn/moneyer 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.12.0 - 2026-09-11
+
+- LUD-25's renamed parameters are accepted: `p` for the informational
+  GET's hash lookup, `p1`/`p2` for the callback's outputs. The old names
+  `h` and `h`/`h2` keep working, and a wallet may mix them in one request.
+  Sending both spellings of one value with different contents is refused.
+  A retry is matched on the outputs, not the spelling, so a split first
+  sent as `h`/`h2` and retried as `p1`/`p2` is answered as a replay.
+- The callback's missing-output reasons are now `missing p1` and
+  `missing p2` (were `missing h`/`missing h2`), and `p1 and p2 must
+  differ.` The pay callback's `missing h` is unchanged.
+- **LUD-25 Part 2 notes.** A note can be keyed by a public key and spent
+  with a recoverable signature, so the mint never holds anything that could
+  spend it. `comment=cp1…` mints one; `k1=ck1…` looks it up or spends it;
+  `p`, `p1` and `p2` take `cp1` keys; and a Part 2 note's certificate comes
+  back as `cs1`, on the lookup and on every rotate, split and merge. The two
+  kinds mix freely in one merge.
+- A note named twice in one request is now caught by the note each `k1`
+  spends rather than by the `k1` string, since one Part 2 note has many
+  valid `ck1` strings. The store refuses a repeated input as well.
+- Takes lnurlcash-kit 0.10.0.
+
 ## 0.11.1 - 2026-09-07
 
 - Hash lookups report `Note already spent.` for retained burned notes,
@@ -9,6 +31,9 @@
   burned rows are retained already; no database migration is required.
 - Test tooling uses an immutable conformance commit matching this response
   contract. It is a development dependency, not a runtime dependency.
+  Since 2026-09-09 that contract is released as `lnurlcash-conformance`
+  0.8.0 and the pin is the version rather than the commit; the graded bytes
+  are the same ones 0.11.1 shipped against.
 
 ## 0.11.0 - 2026-09-06
 

package/README.md

@@ -344,6 +344,21 @@ preimage then buys nothing: it is an ordinary payment proof, which is why
 there is no race left to run, and no window in which holding the invoice
 is nearly holding the money.
 
+### Or name it by a key (LUD-25 Part 2)
+
+The comment can instead be `cp1<pk>`, a public key. The note is keyed by
+that key and spent with `ck1`, a recoverable signature by its private key,
+so the mint never sees anything that could spend it. Everywhere a note is
+named or spent, the two kinds mix freely:
+
+- `GET /w?k1=<ck1>` or `GET /w?p=<cp1>` looks a Part 2 note up, and the
+  answer carries `sig`, the mint's certificate for it as `cs1`.
+- `p1`/`p2` on the callback may be `cp1` keys, and the matching `sig`/`sig2`
+  come back as `cs1`. A hash output still gets a plain hex signature.
+- A merge may combine Part 1 secrets and Part 2 `ck1`s in one request.
+
+A recipient checks a Part 2 note offline from its `ck1` and `cs1` alone.
+
 Moneyer's earlier `mintToHash` extension remains additive. A compatible
 wallet repeats the same commitment as `h`; it does not replace `comment`:
 
@@ -416,9 +431,10 @@ signatures, nothing burned, nothing minted, no balance moved. A retry is
 a read.
 
 A request is the same request when it names the same input notes and asks
-for the same outputs: the same `h`, the same `h2`, the same `amount`.
+for the same outputs: the same `p1`, the same `p2`, the same `amount`.
 Input order does not matter, because a reordered retry is the same
-operation. Anything else naming a burned note is a double-spend attempt
+operation, and nor does spelling: `h`/`h2`, the older names for
+`p1`/`p2`, name the same outputs. Anything else naming a burned note is a double-spend attempt
 and still gets `Invalid or already spent k1.`, unchanged. Provenance is
 recorded rather than inferred for that reason: matching on "a note exists
 at `h`" alone would let anyone holding a burned `k1` and any outstanding
@@ -586,11 +602,11 @@ clearnet.
 | `/.well-known/lnurlp/<user>` | LUD-16 payRequest; paying mints a note |
 | `/.well-known/lnurlp/<zap name>` | NIP-57 payRequest; paying mints a note *to the name's pubkey* |
 | `/.well-known/lnurlw/<user>` | LUD-25 mint address discovery (experimental) |
-| `/p/cb` | LUD-06 pay callback; issues the mint invoice, and takes an optional `h` naming the note |
+| `/p/cb` | LUD-06 pay callback; issues the mint invoice for the note the `comment` names, a hash or a `cp1` key (`h` is an older spelling for a hash) |
 | `/z/cb/<zap name>` | the zap callback; validates the kind 9734 and issues the invoice |
 | `/verify/<hash>` | LUD-21 verify, for mint invoices and melt payments |
-| `/w` | LUD-03 informational GET; accepts `k1` or the non-disclosing LUD-25 `h=sha256(k1)` check; a live note also carries `payLink` |
-| `/w/cb` | the mutating callback: melt, rotate, split, merge |
+| `/w` | LUD-03 informational GET; accepts `k1` (a secret or a `ck1`) or the non-disclosing LUD-25 `p` check (`sha256(k1)` or a `cp1` key; `h` is its older name, still accepted); a live note also carries `payLink`, and a Part 2 note its `cs1` as `sig` |
+| `/w/cb` | the mutating callback: melt, rotate, split, merge; inputs as secrets or `ck1`s, outputs as `p1`/`p2` hashes or `cp1` keys, or their older names `h`/`h2` |
 | `POST /names` | claim a lightning address, authenticated by NIP-98 |
 | `/.well-known/nostr.json` | NIP-05 for the names this mint serves |
 | `/stats` | what the mint owes, what the node holds, and the coverage between them |

package/THREAT-MODEL.md

@@ -23,7 +23,12 @@ request carrying a callback's query string cannot mutate anything.
 
 **A holder inflating a merge or split with a repeated k1.** Duplicated k1
 parameters in one request are refused outright; they would otherwise count
-one note's value twice into the output.
+one note's value twice into the output. The check is on the note each k1
+spends, not on the k1 string: a Part 2 note's `ck1` is a signature, and one
+note has many valid ones (anyone holding a `ck1` can flip it to `(r, n-s)`,
+and the key's owner can sign again). The store refuses a note named twice
+among a swap's inputs as well, so the rule does not rest on the handler
+alone.
 
 **A holder claiming an output id that already exists.** `h`/`h2` may not
 collide with any existing note, any mint invoice's payment hash, settled

package/dist/server.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http';
 import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
 import { finalizeEvent } from 'nostr-tools/pure';
-import { applyMintFee, grossUpForMintFee, hashK1 } from 'lnurlcash-kit';
+import { applyMintFee, decodeCk1, decodeCp1, encodeCs1, grossUpForMintFee, hashK1, recoverNoteOwnershipPubkey } from 'lnurlcash-kit';
 import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
 import { NotePendingError, NoteStore, NoteUnavailableError, OutputCollisionError, swapFingerprint } from "./store.js";
 import { createNoteSigner } from "./signing.js";
@@ -19,6 +19,36 @@ import { ANNOUNCE_D_TAG, ANNOUNCE_KIND, announcementContent } from "./announce.j
 import { isRefusal, registerName, validateNip98 } from "./names.js";
 import { CONFIG_TOKEN, loadWebAssets } from "./web-assets.js";
 const HEX32 = /^[0-9a-f]{64}$/;
+// An output or a lookup: a 64-hex hash, or a cp1 key.
+const namedRef = (value) => {
+    if (HEX32.test(value))
+        return { id: value, cp1: false };
+    const pubkey = decodeCp1(value);
+    return pubkey ? { id: bytesToHex(pubkey), cp1: true } : null;
+};
+// What a k1 spends: sha256(k1) for a Part 1 secret, and for a Part 2 ck1 the
+// key its ownership signature recovers to. Different ck1 strings can recover
+// to the same note, so inputs are compared by ref, never by k1 string.
+const spentRef = (k1) => {
+    if (HEX32.test(k1))
+        return { id: hashK1(k1), cp1: false };
+    const signature = decodeCk1(k1);
+    const pubkey = signature ? recoverNoteOwnershipPubkey(signature) : null;
+    return pubkey ? { id: bytesToHex(pubkey), cp1: true } : null;
+};
+// LUD-25 renamed `h` to `p` on the lookup and `h`/`h2` to `p1`/`p2` on the
+// callback. The old names stay accepted; sending both spellings must agree.
+const renamedRef = (q, name, legacy) => {
+    const current = q.get(name)?.toLowerCase();
+    const old = q.get(legacy)?.toLowerCase();
+    const fromCurrent = current === undefined ? undefined : namedRef(current);
+    const fromOld = old === undefined ? undefined : namedRef(old);
+    return {
+        present: current !== undefined || old !== undefined,
+        ref: (fromCurrent !== undefined ? fromCurrent : fromOld) ?? null,
+        conflict: fromCurrent !== undefined && fromOld !== undefined && fromCurrent?.id !== fromOld?.id
+    };
+};
 // The one request body this mint reads. Capped hard: nothing here needs
 // more than a name and a note, and an unbounded read on a public endpoint
 // is a way to run a mint out of memory.
@@ -61,6 +91,11 @@ export const createMoneyer = async (config, deps = {}) => {
     const store = deps.store ?? new NoteStore(config.dbPath);
     const backend = deps.backend ?? backendFor(config);
     const signer = createNoteSigner(config.signingKey);
+    // A cp1 note's certificate is the same signature, carried as cs1.
+    const certify = (ref, amountMsat) => {
+        const sig = signer.sign(ref.id, amountMsat);
+        return ref.cp1 ? encodeCs1(hexToBytes(sig)) : sig;
+    };
     const webAssets = deps.webAssets === undefined ? loadWebAssets() : deps.webAssets;
     // Node identity for the discovery endpoint, fetched once, best-effort: a
     // funding source that cannot answer does not stop the mint serving.
@@ -163,7 +198,6 @@ export const createMoneyer = async (config, deps = {}) => {
         }
         return null;
     };
-    const resolveNote = async (k1) => resolveNoteId(hashK1(k1));
     // ---- transparency: what the mint owes, and what the node holds ----
     //
     // Cached for 30 seconds so a public endpoint cannot be turned into a
@@ -630,11 +664,15 @@ export const createMoneyer = async (config, deps = {}) => {
             // commitment. Missing or malformed input is refused before asking the
             // funding source for an invoice. `h` remains an additive compatibility
             // field, but it never substitutes for comment.
+            //
+            // LUD-25 Part 2: the comment may instead be `cp1<pk>`, and the note is
+            // keyed by that key, spent later with a ck1 rather than a secret.
             const askedComment = q.get('comment')?.trim().toLowerCase() ?? null;
-            if (askedComment === null || !HEX32.test(askedComment)) {
-                return fail('a mint quote must name its output with a LUD-12 comment carrying hex(sha256(secret))');
+            const commentRef = askedComment === null ? null : namedRef(askedComment);
+            if (commentRef === null) {
+                return fail('a mint quote must name its output with a LUD-12 comment carrying hex(sha256(secret)) or a cp1 key');
             }
-            const commentOutputId = askedComment;
+            const commentOutputId = commentRef.id;
             const askedOutputId = q.get('h')?.trim().toLowerCase() ?? null;
             if (askedOutputId !== null && !HEX32.test(askedOutputId))
                 return fail('missing h');
@@ -823,18 +861,20 @@ export const createMoneyer = async (config, deps = {}) => {
         // ---- LUD-03 informational GET ----
         if (requestUrl.pathname === '/w') {
             const hasK1 = q.has('k1');
-            const hasH = q.has('h');
             const k1 = q.get('k1')?.toLowerCase();
-            const h = q.get('h')?.toLowerCase();
-            if (hasK1 === hasH ||
-                (hasK1 && (!k1 || !HEX32.test(k1))) ||
-                (hasH && (!h || !HEX32.test(h)))) {
+            const lookup = renamedRef(q, 'p', 'h');
+            if (lookup.conflict)
+                return fail('p and h name different notes');
+            if (hasK1 === lookup.present)
                 return fail('Unknown note.');
-            }
             // LUD-25's hash-only check lets a wallet prove that the note it just
             // bought exists without sending the bearer secret to the service a
-            // second time. `h` is accepted in place of `k1`, never alongside it.
-            const note = h ? await resolveNoteId(h) : await resolveNote(k1);
+            // second time. `p` (or `h`) is accepted in place of `k1`, never
+            // alongside it, and names a Part 2 note by its cp1 key.
+            const ref = hasK1 ? (k1 ? spentRef(k1) : null) : lookup.ref;
+            if (!ref)
+                return fail('Unknown note.');
+            const note = await resolveNoteId(ref.id);
             if (!note)
                 return fail('Unknown note.');
             // Hash lookups protect the secret, not the note's spent state.
@@ -876,7 +916,10 @@ export const createMoneyer = async (config, deps = {}) => {
                 // but a note learns from the note itself that the other door
                 // exists.
                 ...(mirrors.length ? { mirrors } : {}),
-                ...(signer ? { mintPubkey: signer.pubkey } : {})
+                ...(signer ? { mintPubkey: signer.pubkey } : {}),
+                // LUD-25 Part 2: a note named by cp1 or ck1 gets its certificate
+                // here, so a wallet need not rotate just to obtain one.
+                ...(ref.cp1 ? { sig: certify(ref, note.amountMsat) } : {})
             });
         }
         // ---- the mutating callback: melt / rotate / split / merge ----
@@ -884,8 +927,12 @@ export const createMoneyer = async (config, deps = {}) => {
             const k1s = q.getAll('k1').map(value => value.toLowerCase());
             const pr = q.get('pr');
             const amountRaw = q.get('amount');
-            const h = q.get('h')?.toLowerCase();
-            const h2 = q.get('h2')?.toLowerCase();
+            // One ref per output from here on, so the replay match below treats
+            // `p1=X` and `h=X` as the same request.
+            const out1 = renamedRef(q, 'p1', 'h');
+            const out2 = renamedRef(q, 'p2', 'h2');
+            const o1 = out1.ref;
+            const o2 = out2.ref;
             if (k1s.length === 0)
                 return fail('Missing k1.');
             if (k1s.length > config.maxK1s)
@@ -896,19 +943,29 @@ export const createMoneyer = async (config, deps = {}) => {
             // Hash parameters are checked before any note resolves, so an
             // invalid or missing hash can never burn anything.
             if (!pr) {
-                if (!h || !HEX32.test(h))
-                    return fail('missing h');
-                if (amountRaw !== null && (!h2 || !HEX32.test(h2)))
-                    return fail('missing h2');
-                if (h2 !== undefined && h2 === h)
-                    return fail('h and h2 must differ.');
+                if (out1.conflict)
+                    return fail('p1 and h name different outputs');
+                if (out2.conflict)
+                    return fail('p2 and h2 name different outputs');
+                if (!o1)
+                    return fail('missing p1');
+                if (amountRaw !== null && !o2)
+                    return fail('missing p2');
+                if (o2 && o2.id === o1.id)
+                    return fail('p1 and p2 must differ.');
             }
             if (config.sunset && amountRaw !== null) {
                 return fail('This mint is sunsetting - splitting is disabled.');
             }
-            // A repeated k1 would count one note's value twice on the way into a
-            // merge or split. Atomic refusal, same as an invalid one.
-            if (new Set(k1s).size !== k1s.length)
+            // A note named twice would count its value twice on the way into a
+            // merge or split. Compared by the note each k1 spends, since two
+            // different ck1 strings can spend the same one. Atomic refusal, same
+            // as an invalid k1.
+            const spent = k1s.map(spentRef);
+            if (spent.some(ref => ref === null))
+                return fail('Invalid or already spent k1.');
+            const spentIds = spent.map(ref => ref.id);
+            if (new Set(spentIds).size !== spentIds.length)
                 return fail('Invalid or already spent k1.');
             // ---- the retried mutation ----
             //
@@ -925,39 +982,36 @@ export const createMoneyer = async (config, deps = {}) => {
             // balance: it is a read. The signature is deterministic over the
             // output id and its amount, so it is recomputed rather than stored.
             // Anything else naming a burned input is a double-spend attempt and
-            // still gets today's reason string, unchanged.
-            // Every k1 has to be hex before it can be hashed into a
-            // fingerprint; a malformed one falls through to the loop below and
-            // gets the same refusal it always did.
-            const fingerprint = pr !== null || !k1s.every(k1 => HEX32.test(k1))
+            // still gets today's reason string, unchanged. The fingerprint is
+            // over note ids, so a hex request fingerprints exactly as it did
+            // before Part 2 and replays from before an upgrade still match.
+            const fingerprint = pr !== null
                 ? null
                 : swapFingerprint({
-                    inputIds: k1s.map(hashK1),
-                    h: h,
-                    h2,
+                    inputIds: spentIds,
+                    h: o1.id,
+                    h2: o2?.id,
                     ...(amountRaw !== null ? { amountMsat: Number(amountRaw) } : {})
                 });
             const alreadyMinted = fingerprint === null ? null : store.swapByFingerprint(fingerprint);
             if (alreadyMinted) {
-                const first = alreadyMinted.find(output => output.id === h);
-                const second = h2 === undefined ? undefined : alreadyMinted.find(output => output.id === h2);
+                const first = alreadyMinted.find(output => output.id === o1.id);
+                const second = o2 ? alreadyMinted.find(output => output.id === o2.id) : undefined;
                 if (first) {
                     return send({
                         status: 'OK',
                         ...(signer
                             ? {
-                                sig: signer.sign(first.id, first.amountMsat),
-                                ...(second ? { sig2: signer.sign(second.id, second.amountMsat) } : {})
+                                sig: certify(o1, first.amountMsat),
+                                ...(second ? { sig2: certify(o2, second.amountMsat) } : {})
                             }
                             : {})
                     });
                 }
             }
             const found = [];
-            for (const k1 of k1s) {
-                if (!HEX32.test(k1))
-                    return fail('Invalid or already spent k1.');
-                const note = await resolveNote(k1);
+            for (const id of spentIds) {
+                const note = await resolveNoteId(id);
                 if (!note || note.state === 'burned')
                     return fail('Invalid or already spent k1.');
                 if (note.state === 'pending')
@@ -1072,8 +1126,8 @@ export const createMoneyer = async (config, deps = {}) => {
                     return fail('insufficient value');
                 try {
                     store.swap(inputIds, [
-                        { id: h, amountMsat: amount },
-                        { id: h2, amountMsat: changeMsat }
+                        { id: o1.id, amountMsat: amount },
+                        { id: o2.id, amountMsat: changeMsat }
                     ], fingerprint ?? undefined);
                 }
                 catch (err) {
@@ -1085,7 +1139,7 @@ export const createMoneyer = async (config, deps = {}) => {
                 }
                 return send({
                     status: 'OK',
-                    ...(signer ? { sig: signer.sign(h, amount), sig2: signer.sign(h2, changeMsat) } : {})
+                    ...(signer ? { sig: certify(o1, amount), sig2: certify(o2, changeMsat) } : {})
                 });
             }
             // rotate (one k1) or merge (several) - the same swap either way.
@@ -1094,7 +1148,7 @@ export const createMoneyer = async (config, deps = {}) => {
             // of one - the refund is exactly 0.
             const mergedMsat = totalMsat + (inputIds.length - 1) * baseFeeMsat;
             try {
-                store.swap(inputIds, [{ id: h, amountMsat: mergedMsat }], fingerprint ?? undefined);
+                store.swap(inputIds, [{ id: o1.id, amountMsat: mergedMsat }], fingerprint ?? undefined);
             }
             catch (err) {
                 if (err instanceof NotePendingError)
@@ -1102,7 +1156,7 @@ export const createMoneyer = async (config, deps = {}) => {
                 // same oracle-free reason for a collision as for a dead k1
                 return fail('Invalid or already spent k1.');
             }
-            return send({ status: 'OK', ...(signer ? { sig: signer.sign(h, mergedMsat) } : {}) });
+            return send({ status: 'OK', ...(signer ? { sig: certify(o1, mergedMsat) } : {}) });
         }
         return fail('Not found.', 404);
     };

package/dist/store.js

@@ -214,6 +214,11 @@ export class NoteStore {
     // a secret the mint really did mint a note against.
     swap(inputIds, outputs, fingerprint) {
         this.tx(() => {
+            // Every input is checked before any is burned, so a note named twice
+            // would pass both checks and be counted twice by the caller.
+            if (new Set(inputIds).size !== inputIds.length) {
+                throw new NoteUnavailableError('a note is named twice among the inputs');
+            }
             for (const id of inputIds)
                 this.assertOutstanding(id);
             for (const output of outputs)

package/llms.txt

@@ -25,10 +25,13 @@ Client library to build against a mint: lnurlcash-kit
    inside the invoice. `h` is an additive alias for the same commitment and
    never replaces the comment. Because the note is not keyed by the
    preimage, a funding source whose node chooses its own preimages
-   (phoenixd, NIP-47 make_invoice) can back a mint.
+   (phoenixd, NIP-47 make_invoice) can back a mint. LUD-25 Part 2: the
+   comment may instead be `cp1<pk>`, and the note is keyed by that key.
 2. Mutations are atomic: all named k1 burn and all outputs mint, or
-   nothing happens. Duplicate k1 in one request is refused.
-3. h/h2 are WALLET-supplied hashes; the mint never generates a
+   nothing happens. A note named twice in one request is refused, compared
+   by the note each k1 spends: one Part 2 note has many valid ck1 strings.
+3. p1/p2 (older names h/h2, still accepted; both spellings of one output
+   must agree) are WALLET-supplied hashes or cp1 keys; the mint never generates a
    replacement secret, and refuses output ids that already exist as
    notes, as mint-invoice payment hashes, or as a note another payer has
    already bought with `h`. A malformed `h` on the pay callback is
@@ -56,8 +59,8 @@ Client library to build against a mint: lnurlcash-kit
    part applies at mint time only.
 7. Reason strings are protocol surface: 'pending',
    'Invalid or already spent k1.', 'Unknown note.', 'Note already spent.',
-   'missing h', 'missing h2', 'insufficient value' - wallets classify on
-   them.
+   'missing p1', 'missing p2' (withdraw callback), 'missing h' (pay
+   callback), 'insufficient value' - wallets classify on them.
 8. minSendable must survive the mint's own fee (grossUpForMintFee of the
    dust floor), or the mint advertises an amount it will refuse.
 
@@ -84,7 +87,7 @@ NoteStore - SQLite store; notes by sha256(k1), never secrets
 
 /.well-known/lnurlp/{user}  LUD-16 payRequest (mints)
 /.well-known/lnurlw/{user}  LUD-25 mint address (experimental)
-/p/cb                       LUD-06 pay callback (optional h names the note)
+/p/cb                       LUD-06 pay callback (comment names the note: hash or cp1)
 /verify/{payment_hash}      LUD-21 verify (mint invoices AND melt payments)
-/w                          LUD-03 informational GET by k1 or hash-only h
-/w/cb                       melt / rotate / split / merge
+/w                          LUD-03 informational GET by k1 (secret or ck1) or p (hash or cp1, older h); a cp1 note carries its cs1 as sig
+/w/cb                       melt / rotate / split / merge; inputs secrets or ck1, outputs p1/p2 hashes or cp1 (or older h/h2); cp1 outputs certified as cs1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "An LNURLcash (LUD-25) mint - strikes Lightning bearer notes. Independent implementation, cln/lnd funding sources, SQLite, zero HTTP framework.",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -60,7 +60,7 @@
     "@noble/hashes": "^2.3.0",
     "@scure/base": "^1.2.4",
     "farrier-kit": "^1.1.3",
-    "lnurlcash-kit": "^0.7.0",
+    "lnurlcash-kit": "^0.10.0",
     "nostr-tools": "2.24.1"
   },
   "devDependencies": {
@@ -70,7 +70,7 @@
     "@types/node": "^24.0.0",
     "animejs": "^4.0.0",
     "happy-dom": "^20.0.0",
-    "lnurlcash-conformance": "https://codeload.github.com/lnurlcash/lnurlcash-conformance/tar.gz/6c6aee66cf1b6cba72a03af976ecec113f470c9e",
+    "lnurlcash-conformance": "^0.8.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",