@forgesworn/moneyer 0.20.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.20.1 - 2026-10-13
+
+- **A name with a cx1 issues invoices its payer's wallet will accept.** Its
+  payRequest metadata carries `text/cpub` with the next free index, but the
+  invoice's description hash was taken over the metadata without it, so it
+  never matched `sha256(metadata)` as LUD-06 requires. A wallet that checks
+  refused to pay the name by Lightning. The callback is now
+  `/z/cb/<name>/<index>`, the index the payRequest advertised, and the
+  invoice commits to exactly the metadata the payer read, even when a
+  settled payment has moved the next free index on in between. The index
+  feeds only the metadata: the note still lands on the next free key at
+  settlement. An index that is not a non-hardened one is refused. Zaps were
+  unaffected (their hash is over the zap request), and so is a name without
+  a cx1, whose callback stays `/z/cb/<name>`; that form still answers for
+  every name.
+- The derivation, address proof and auto-mint text moved from LUD-25 to
+  LUD-26 in the draft (lnurl/luds 2f17578, editorial); the README and
+  comments now point there.
+
 ## 0.20.0 - 2026-10-07
 
 - **A zap paid while the mint was down is no longer lost.** The expiry

package/README.md

@@ -584,7 +584,7 @@ A registered name resolves on both rails at once:
 The discovery endpoint advertises `namePriceMsat` while registration is
 open, so a wallet can offer the flow without asking.
 
-### A name that pays to your own keys (LUD-25 auto-mint)
+### A name that pays to your own keys (LUD-26 auto-mint)
 
 Add `"cx1": "cx1..."` to the registration body, or send `{"name", "cx1"}`
 again later from the key that owns the name, and payments to it stop being
@@ -592,7 +592,7 @@ custodial. A `cx1` is a watch-only branch: from it the mint can work out each
 of the holder's note keys in turn, but never spend one.
 
 A `cx1` is public, so pointing a name at one has to be proven by the branch
-itself, as LUD-25 requires: the body also carries `"sig"`, a BIP-340
+itself, as LUD-26 requires: the body also carries `"sig"`, a BIP-340
 signature by the branch's purpose-0 index-0 key over
 `sha256("LNURLcash:register:<domain>:<name>")`, `<domain>` being this mint's
 hostname. Changing the branch later is proven by the branch on file, not the
@@ -690,7 +690,7 @@ clearnet.
 | `/.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 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 |
+| `/z/cb/<zap name>` | the zap callback; validates the kind 9734 and issues the invoice. A name with a `cx1` calls back at `/z/cb/<zap name>/<index>`, the index its payRequest advertised, so the invoice commits to exactly the metadata the payer was shown |
 | `/verify/<hash>` | LUD-21 verify, for mint invoices and melt payments |
 | `/w` | LUD-03 informational GET; accepts `k1` (a preimage, `ck1` or `cw1`, verified in full) or the non-disclosing LUD-25 `p` check (a bearer note's h or any `cp1`; `h` is its older name, still accepted); a live note carries `payLink` and its `cs1` as `sig` |
 | `/w/cb` | the mutating callback: melt, rotate, split, merge; inputs as preimages, `ck1`s or `cw1`s, outputs as `p1`/`p2` (a bearer note's h or a `cp1`), or their older names `h`/`h2` |

package/dist/names.js

@@ -87,7 +87,7 @@ export const validateNip98 = (authorization, request) => {
     }
     return { pubkey: event.pubkey };
 };
-// LUD-25's address proof. A cx1 is public, so pointing a name at one, or
+// LUD-26's address proof. A cx1 is public, so pointing a name at one, or
 // away from one, has to be proven by the branch itself: a BIP-340
 // signature by its index-0 key over sha256("LNURLcash:<action>:<domain>:
 // <name>"). The domain is this mint's own, so a proof one mint has seen
@@ -132,7 +132,7 @@ export const registerName = async (args) => {
     if ([...ALWAYS_RESERVED, ...args.reserved.map(name => name.toLowerCase())].includes(raw)) {
         return refuse('That name is reserved.', 403);
     }
-    // LUD-25 Part 2: a watch-only branch, so payments to the name are minted
+    // LUD-26 auto-mint: a watch-only branch, so payments to the name are minted
     // to the holder's own keys. Absent leaves it as it is; null clears it.
     let cx1;
     if (args.body.cx1 === null) {

package/dist/server.js

@@ -615,13 +615,14 @@ export const createMoneyer = async (config, deps = {}) => {
         if (lnurlpMatch && zap && zap.isZapName(lnurlpMatch[1])) {
             return send(zap.payRequest(lnurlpMatch[1]));
         }
-        const zapCbMatch = requestUrl.pathname.match(/^\/z\/cb\/(.+)$/);
+        // `/z/cb/<name>`, or `/z/cb/<name>/<index>` for a name advertising a cx1.
+        const zapCbMatch = requestUrl.pathname.match(/^\/z\/cb\/([^/]+)(?:\/([^/]+))?$/);
         if (zapCbMatch) {
             if (!zap || !zap.isZapName(zapCbMatch[1]))
                 return fail('Unknown user.', 404);
             if (config.sunset)
                 return fail('This mint is sunsetting - minting is disabled.');
-            const result = await zap.callback(zapCbMatch[1], Number(q.get('amount')), q.get('nostr'));
+            const result = await zap.callback(zapCbMatch[1], Number(q.get('amount')), q.get('nostr'), zapCbMatch[2] ?? null);
             if ('reason' in result)
                 return fail(result.reason);
             return send({ ...result, disposable: false });

package/dist/zap.d.ts

@@ -45,7 +45,7 @@ export type ZapBridge = {
     pubkey: string;
     isZapName(name: string): boolean;
     payRequest(name: string): Record<string, unknown> | null;
-    callback(name: string, amountMsat: number, nostrParam: string | null): Promise<ZapCallbackResult>;
+    callback(name: string, amountMsat: number, nostrParam: string | null, advertisedIndex?: string | null): Promise<ZapCallbackResult>;
     settle(): Promise<number>;
     publish(): Promise<number>;
     sweep(nowMs?: number): Promise<number>;

package/dist/zap.js

@@ -111,7 +111,7 @@ export const createZapBridge = (deps) => {
         const registered = store.zapName(lowered);
         if (!registered)
             return null;
-        let internalTransfer;
+        let advertisedIndex;
         const branch = decodeCx1(registered.cx1 ?? '');
         if (branch) {
             let index = registered.nextIndex;
@@ -119,7 +119,7 @@ export const createZapBridge = (deps) => {
                 try {
                     const noteId = bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, NOTE_PURPOSE_LIGHTNING_ADDRESS, index));
                     if (!store.outputIdInUse(noteId)) {
-                        internalTransfer = `${registered.cx1}:${index}`;
+                        advertisedIndex = index;
                         break;
                     }
                 }
@@ -128,9 +128,15 @@ export const createZapBridge = (deps) => {
                 }
             }
         }
+        const internalTransfer = advertisedIndex === undefined ? undefined : `${registered.cx1}:${advertisedIndex}`;
         return {
             tag: 'payRequest',
-            callback: `${origin}/z/cb/${lowered}`,
+            // The index rides in the callback path so the invoice can commit to
+            // this exact metadata (LUD-06): by the time the payer calls back, a
+            // settled payment may have moved the next unused index on. A path
+            // segment rather than a query parameter, because some zap clients
+            // append `?amount=` without looking for an existing query.
+            callback: `${origin}/z/cb/${lowered}${advertisedIndex === undefined ? '' : `/${advertisedIndex}`}`,
             minSendable: deps.minSendableMsat,
             maxSendable: deps.maxSendableMsat,
             metadata: metadataFor(lowered, host, deps.mintFeeLine, deps.feeInWords, internalTransfer),
@@ -141,11 +147,16 @@ export const createZapBridge = (deps) => {
             // is one.
         };
     };
-    const callback = async (name, amountMsat, nostrParam) => {
+    const callback = async (name, amountMsat, nostrParam, advertisedIndex = null) => {
         const lowered = name.toLowerCase();
-        const recipient = store.zapName(lowered)?.pubkey;
-        if (!recipient)
+        const registered = store.zapName(lowered);
+        const recipient = registered?.pubkey;
+        if (!registered || !recipient)
             return { reason: 'Unknown user.' };
+        // Below 2^31: a non-hardened index, as the derivation's ser32 needs.
+        if (advertisedIndex !== null && (!/^\d{1,10}$/.test(advertisedIndex) || Number(advertisedIndex) > 0x7fffffff)) {
+            return { reason: 'Invalid callback.' };
+        }
         if (!Number.isSafeInteger(amountMsat) || amountMsat <= 0)
             return { reason: 'Invalid amount.' };
         if (amountMsat < deps.minSendableMsat || amountMsat > deps.maxSendableMsat)
@@ -174,13 +185,21 @@ export const createZapBridge = (deps) => {
         // nothing to them. The note's secret is minted at settlement.
         const preimage = bytesToHex(randomBytes(32));
         const paymentHash = hashK1(preimage);
+        // A zap commits to its zap request (NIP-57); any other payment to the
+        // metadata the payer was shown (LUD-06), rebuilt from the index the
+        // payRequest advertised. That index is only a hint and feeds nothing
+        // but this string: settlement derives the note's key itself, so a
+        // forged one changes no more than the forger's own invoice. A cx1
+        // changed or cleared between the two requests still mismatches, and
+        // the payer's wallet fetches the payRequest again.
+        const internalTransfer = advertisedIndex !== null && registered.cx1 ? `${registered.cx1}:${Number(advertisedIndex)}` : undefined;
         let pr;
         try {
             pr = (await backend.createInvoice({
                 amountMsat,
                 preimageHex: preimage,
                 memo: `Zap ${lowered}@${host}`,
-                descriptionForHash: zapRequest ?? metadataFor(lowered, host, deps.mintFeeLine, deps.feeInWords)
+                descriptionForHash: zapRequest ?? metadataFor(lowered, host, deps.mintFeeLine, deps.feeInWords, internalTransfer)
             })).pr;
         }
         catch (err) {

package/llms.txt

@@ -131,4 +131,7 @@ POST /names                 claim a name (NIP-98; the signer owns it); body {nam
                             /w?p=<cp1>&c=<amount-bearing-cs1>&i=<index> plus an `i` tag. The index is
                             taken at settlement, never at the invoice, and occupied keys are skipped
                             Its payRequest metadata publishes text/cpub = cx1:<next-free-purpose-2-index> for
-                            same-mint rotate/split/merge transfers; a raced key returns "already in use"
+                            same-mint rotate/split/merge transfers; a raced key returns "already in use".
+                            Such a name's callback is /z/cb/{name}/{index}: the index it advertised, so a
+                            non-zap invoice's description hash is sha256 of that exact metadata (a zap's
+                            is of its kind 9734). The index feeds only the metadata, never the note's key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "An LNURLcash (LUD-25) mint - strikes Lightning bearer notes. Independent implementation, cln/lnd funding sources, SQLite, zero HTTP framework.",
   "author": "TheCryptoDonkey",
   "license": "MIT",