@forgesworn/moneyer 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # 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
+  sweep deleted any unsettled zap invoice an hour past expiry without
+  asking the funding source, so a zap paid while moneyer was down that long
+  stayed in the node and never became a note. It now asks first, as the
+  mint-invoice sweep has since 0.17.1: an unpaid one goes, a paid one stays
+  for the settle pass to mint, and no answer deletes nothing.
+- **A paid mint invoice is credited the moment it settles.** moneyer now
+  watches the funding source's settled invoices (lnd's
+  `/v1/invoices/subscribe`, cln's `waitanyinvoice`) and mints the note as
+  soon as the payment lands, instead of when the wallet comes back to claim
+  or poll `verify`, or when the expiry sweep finds it. Liabilities and
+  coverage are therefore right straight away. A report is only a hint: the
+  invoice is checked against the node and credited through the same call
+  `verify` and the sweep make, and those remain the fallback while the
+  stream is down. The stream reconnects with backoff and resumes from the
+  node's settle index, kept in the database, so settles during a restart
+  are caught up. A settled zap invoice brings the next zap pass forward.
+  The existing lnd macaroon (`invoices:read`) already covers the
+  subscription. lnd sends no headers on it until the first event, so on a
+  quiet node Node's fetch ends it after five minutes; that counts as a
+  normal end and the stream reconnects without logging. The cln side is untested against a live node, like the
+  rest of that backend.
+
 ## 0.19.0 - 2026-10-07
 
 - **A failed melt's invoice can be tried again.** Once the funding source

package/README.md

@@ -351,6 +351,15 @@ 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.
 
+On lnd and cln the mint watches the node's settled invoices (lnd's
+invoice subscription, cln's `waitanyinvoice`), so the note exists from
+the moment the invoice is paid, whether or not the wallet ever comes
+back. Each report is checked against the node before anything is
+credited, and the stream resumes from the last settle it handled after a
+drop or a restart. Without it, a paid invoice is credited when the wallet
+claims or polls `verify`, or at the latest when the expiry sweep finds it
+paid.
+
 ### Every note is a taproot output key
 
 LUD-25 makes every note a BIP-341 output key Q, written `cp1<Q>`, and that
@@ -575,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
@@ -583,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
@@ -681,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/backends/cln.js

@@ -100,6 +100,32 @@ export const createClnBackend = (config) => {
             }
             return pays.some(pay => pay?.status === 'complete');
         },
+        // waitanyinvoice answers with the first invoice paid after
+        // `lastpay_index`, or the next one paid at all without it. Its timeout
+        // (904) just means nothing was paid meanwhile.
+        async watchSettledInvoices({ fromIndex, signal, onSettled }) {
+            let lastIndex = fromIndex;
+            while (!signal.aborted) {
+                const res = await fetch(`${config.url}/v1/waitanyinvoice`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', Rune: config.rune },
+                    body: JSON.stringify({ ...(lastIndex > 0 ? { lastpay_index: lastIndex } : {}), timeout: 60 }),
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(90_000)])
+                });
+                const invoice = await res.json().catch(() => null);
+                if (!res.ok) {
+                    if (invoice?.code === 904)
+                        continue;
+                    throw new Error(`cln waitanyinvoice failed (${res.status}).`);
+                }
+                const index = invoice?.pay_index;
+                if (invoice?.status !== 'paid' || typeof invoice.payment_hash !== 'string' || !Number.isSafeInteger(index)) {
+                    throw new Error('cln waitanyinvoice returned no paid invoice.');
+                }
+                await onSettled(invoice.payment_hash, index);
+                lastIndex = index;
+            }
+        },
         async isInvoiceSettled(paymentHashHex) {
             const result = await mustCall('/v1/listinvoices', { payment_hash: paymentHashHex });
             const invoices = result?.invoices ?? [];

package/dist/backends/fake.d.ts

@@ -5,6 +5,7 @@ export type FakeBackendOptions = {
     autoSettle?: boolean;
     nodeChoosesPreimage?: boolean;
     autoSettleAfterMs?: number;
+    streamsSettles?: boolean;
 };
 export type FakeBackend = LightningBackend & {
     control: {
@@ -21,6 +22,7 @@ export type FakeBackend = LightningBackend & {
         } | undefined;
         sentAmountMsat(paymentHashHex: string): number | null | undefined;
         setLocalBalanceMsat(msat: number | undefined): void;
+        dropInvoiceStreams(): void;
     };
 };
 export declare const FAKE_LOCAL_BALANCE_MSAT = 100000000000;

package/dist/backends/fake.js

@@ -33,9 +33,49 @@ export const createFakeBackend = (options = {}) => {
     const knownPreimages = new Map();
     let localBalanceMsat = FAKE_LOCAL_BALANCE_MSAT;
     let payMode = 'succeed';
+    const settleLog = [];
+    const watchers = new Set();
+    const watchSettledInvoices = async ({ fromIndex, signal, onSettled }) => {
+        const queue = settleLog.filter(entry => fromIndex > 0 && entry.index > fromIndex);
+        let wake = null;
+        let ended = false;
+        const watcher = {
+            push: (entry) => {
+                queue.push(entry);
+                wake?.();
+            },
+            end: () => {
+                ended = true;
+                wake?.();
+            }
+        };
+        const onAbort = () => watcher.end();
+        signal.addEventListener('abort', onAbort);
+        watchers.add(watcher);
+        try {
+            for (;;) {
+                const entry = queue.shift();
+                if (entry) {
+                    await onSettled(entry.paymentHashHex, entry.index);
+                    continue;
+                }
+                if (ended)
+                    return;
+                await new Promise(resolve => {
+                    wake = resolve;
+                });
+                wake = null;
+            }
+        }
+        finally {
+            watchers.delete(watcher);
+            signal.removeEventListener('abort', onAbort);
+        }
+    };
     return {
         name: 'fake',
         acceptsInvoicePreimage: !nodeChoosesPreimage,
+        ...(options.streamsSettles === true ? { watchSettledInvoices } : {}),
         async createInvoice({ amountMsat, preimageHex, memo }) {
             // A node that mints its own preimages never sees the caller's.
             const chosen = nodeChoosesPreimage ? bytesToHex(randomBytes(32)) : preimageHex;
@@ -126,7 +166,13 @@ export const createFakeBackend = (options = {}) => {
                 const invoice = invoices.get(paymentHashHex);
                 if (!invoice)
                     throw new Error(`no fake invoice for ${paymentHashHex}`);
+                if (invoice.settled)
+                    return;
                 invoice.settled = true;
+                const entry = { paymentHashHex, index: settleLog.length + 1 };
+                settleLog.push(entry);
+                for (const watcher of watchers)
+                    watcher.push(entry);
             },
             setPayMode(mode) {
                 payMode = mode;
@@ -156,6 +202,14 @@ export const createFakeBackend = (options = {}) => {
             setLocalBalanceMsat(msat) {
                 localBalanceMsat = msat;
             },
+            dropInvoiceStreams() {
+                // gone at once, as a dropped connection is: a settle after this
+                // reaches the watcher only by its resuming from the index
+                for (const watcher of [...watchers]) {
+                    watchers.delete(watcher);
+                    watcher.end();
+                }
+            },
             invoiceByHash(paymentHashHex) {
                 const invoice = invoices.get(paymentHashHex);
                 // `settled` here answers "is it paid now", so autoSettle's moment

package/dist/backends/lnd.js

@@ -19,6 +19,13 @@ const FAILURE_REASONS = {
     FAILURE_REASON_INSUFFICIENT_BALANCE: 'Insufficient balance to pay this invoice.',
     FAILURE_REASON_TIMEOUT: 'Timed out trying to find a route to pay this invoice.'
 };
+// Node's fetch gives up on a response idle for five minutes, headers or
+// body. lnd sends no headers on an invoice subscription until its first
+// event, so on a quiet node that is the normal end of one, not a fault.
+const isIdleTimeout = (err) => {
+    const code = err?.cause?.code ?? err?.code;
+    return code === 'UND_ERR_HEADERS_TIMEOUT' || code === 'UND_ERR_BODY_TIMEOUT';
+};
 const hexToBase64 = (hex) => Buffer.from(hexToBytes(hex)).toString('base64');
 const decodeHexOrBase64 = (value) => {
     if (/^[0-9a-fA-F]{64}$/.test(value))
@@ -83,6 +90,47 @@ export const createLndBackend = (config) => {
             reader.cancel().catch(() => { });
         }
     };
+    const readSettledInvoices = async ({ fromIndex, signal, onSettled }) => {
+        const res = await fetch(`${config.url}/v1/invoices/subscribe?settle_index=${fromIndex}`, { headers, signal });
+        if (!res.ok || !res.body)
+            throw new Error(`lnd refused the invoice subscription (${res.status}).`);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (event?.error)
+                        throw new Error(`lnd ended the invoice subscription: ${event.error.message ?? 'unknown'}`);
+                    const invoice = event?.result ?? event;
+                    if (invoice?.state !== 'SETTLED' || typeof invoice.r_hash !== 'string')
+                        continue;
+                    const index = Number(invoice.settle_index);
+                    if (!Number.isSafeInteger(index) || index <= 0)
+                        continue;
+                    await onSettled(decodeHexOrBase64(invoice.r_hash), index);
+                }
+            }
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+    };
     return {
         name: 'lnd',
         acceptsInvoicePreimage: true,
@@ -161,6 +209,18 @@ export const createLndBackend = (config) => {
                 throw new Error('lnd did not report a payment status.');
             return result;
         },
+        // lnd replays every settle after `settle_index` before going live, and
+        // none for 0. The stream is held open until lnd, the signal or Node's
+        // idle timeout ends it.
+        async watchSettledInvoices({ fromIndex, signal, onSettled }) {
+            try {
+                await readSettledInvoices({ fromIndex, signal, onSettled });
+            }
+            catch (err) {
+                if (!isIdleTimeout(err))
+                    throw err;
+            }
+        },
         // 404 is lnd's answer for an invoice it does not hold, which can never
         // settle. Any other refusal is no answer at all, and reading it as
         // "unpaid" would let the expiry sweep delete a paid invoice's row.

package/dist/backends/types.d.ts

@@ -39,5 +39,10 @@ export interface LightningBackend {
     invoicePreimage(paymentHashHex: string): Promise<string | null>;
     paymentPreimage(paymentHashHex: string): Promise<string | null>;
     nodeInfo?(): Promise<NodeInfo>;
+    watchSettledInvoices?(args: {
+        fromIndex: number;
+        signal: AbortSignal;
+        onSettled: (paymentHashHex: string, index: number) => Promise<void>;
+    }): Promise<void>;
     close?(): void | Promise<void>;
 }

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.d.ts

@@ -30,6 +30,7 @@ export type MoneyerDeps = {
     nostr?: NostrTransport;
     zapPollMs?: number;
     statsPublishMs?: number;
+    invoiceStreamRetryMs?: number;
     scriptVerifier?: ScriptVerifier;
 };
 export { describeFee } from './fee-words.ts';

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 });
@@ -1298,7 +1299,7 @@ export const createMoneyer = async (config, deps = {}) => {
     // unref'd so it never keeps the process alive.
     const housekeeping = async () => {
         const { swept: mintSwept, settled } = await sweepExpiredMintInvoices(store, backend);
-        const swept = mintSwept + (zap?.sweep() ?? 0);
+        const swept = mintSwept + (zap ? await zap.sweep() : 0);
         if (swept > 0)
             log(`swept ${swept} expired mint invoice${swept === 1 ? '' : 's'}`);
         if (settled > 0)
@@ -1335,6 +1336,63 @@ export const createMoneyer = async (config, deps = {}) => {
     };
     const zapTimer = zap ? setInterval(() => void zapTick(), deps.zapPollMs ?? 5_000) : null;
     zapTimer?.unref();
+    // A funding source that streams its settles lets a paid mint invoice be
+    // credited the moment it is paid, rather than when its wallet next asks
+    // or the expiry sweep finds it. A report is only a hint: the invoice is
+    // checked again and credited by the same call /verify and the sweep
+    // make, and those stay as the fallback whenever the stream is down. A
+    // settled zap invoice brings the next zap pass forward instead.
+    const streamAbort = new AbortController();
+    const streamIndexKey = `invoice_stream_index:${backend.name}`;
+    const onSettled = async (paymentHash, index) => {
+        try {
+            const invoice = store.mintInvoiceByHash(paymentHash);
+            if (invoice && !invoice.settled && (await backend.isInvoiceSettled(paymentHash))) {
+                if (streamAbort.signal.aborted)
+                    return;
+                store.settleMintInvoice(paymentHash);
+            }
+            else if (!invoice && zap && store.zapInvoiceByHash(paymentHash)) {
+                void zapTick();
+            }
+        }
+        catch (err) {
+            log(`invoice stream: could not settle a reported invoice (${err.message})`);
+        }
+        if (!streamAbort.signal.aborted)
+            store.setMetaValue(streamIndexKey, String(index));
+    };
+    const streamInvoices = async (watch) => {
+        const firstRetryMs = deps.invoiceStreamRetryMs ?? 1_000;
+        let retryMs = firstRetryMs;
+        while (!streamAbort.signal.aborted) {
+            const startedAt = Date.now();
+            try {
+                await watch({ fromIndex: Number(store.metaValue(streamIndexKey) ?? 0), signal: streamAbort.signal, onSettled });
+            }
+            catch (err) {
+                if (!streamAbort.signal.aborted)
+                    log(`invoice stream dropped: ${err.message}`);
+            }
+            if (streamAbort.signal.aborted)
+                return;
+            if (Date.now() - startedAt > 60_000)
+                retryMs = firstRetryMs;
+            await new Promise(resolve => {
+                const done = () => {
+                    clearTimeout(timer);
+                    streamAbort.signal.removeEventListener('abort', done);
+                    resolve();
+                };
+                const timer = setTimeout(done, retryMs);
+                streamAbort.signal.addEventListener('abort', done);
+            });
+            retryMs = Math.min(retryMs * 2, 60_000);
+        }
+    };
+    const invoiceStream = backend.watchSettledInvoices
+        ? streamInvoices(backend.watchSettledInvoices.bind(backend))
+        : Promise.resolve();
     // One hourly pass to Nostr carries both: the signed liabilities snapshot
     // and the mint's announcement of itself. Each re-checks its own switch,
     // so an operator can have either, both, or neither.
@@ -1362,6 +1420,7 @@ export const createMoneyer = async (config, deps = {}) => {
         publishStats,
         publishAnnouncement,
         close: async () => {
+            streamAbort.abort();
             clearInterval(housekeepingTimer);
             if (zapTimer)
                 clearInterval(zapTimer);
@@ -1370,6 +1429,7 @@ export const createMoneyer = async (config, deps = {}) => {
             nostr?.close();
             kernel?.close();
             await new Promise((resolve, reject) => server.close(err => (err ? reject(err) : resolve())));
+            await invoiceStream;
             await backend.close?.();
             store.close();
         }

package/dist/store.d.ts

@@ -93,6 +93,8 @@ export declare class NoteStore {
     private indexLegacyIds;
     legacyIdOf(q: string): string | null;
     noteByQ(q: string): NoteRow | null;
+    metaValue(key: string): string | null;
+    setMetaValue(key: string, value: string): void;
     unnamedVerifyCutover(): number;
     private tx;
     noteById(id: string): NoteRow | null;

package/dist/store.js

@@ -216,6 +216,15 @@ export class NoteStore {
     }
     // Invoices quoted at or after this instant get no verify if they named no
     // output. See the migration above for why it is not simply "now".
+    // Small operational values that must survive a restart, such as where
+    // the funding source's invoice stream should resume.
+    metaValue(key) {
+        const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+        return row?.value ?? null;
+    }
+    setMetaValue(key, value) {
+        this.db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value').run(key, value);
+    }
     unnamedVerifyCutover() {
         const row = this.db
             .prepare("SELECT value FROM meta WHERE key = 'unnamed_verify_cutover'")

package/dist/zap.d.ts

@@ -45,9 +45,9 @@ 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): number;
+    sweep(nowMs?: number): Promise<number>;
 };
 export declare const createZapBridge: (deps: ZapBridgeDeps) => ZapBridge;

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) {
@@ -325,7 +344,10 @@ export const createZapBridge = (deps) => {
         }
         return published;
     };
-    const sweep = (nowMs = now()) => {
+    // As the mint-invoice sweep: an expired row goes only once the funding
+    // source confirms it unpaid. One paid while the mint was down stays for
+    // the next settle pass to mint, and no answer deletes nothing.
+    const sweep = async (nowMs = now()) => {
         const stale = [];
         for (const row of store.unsettledZapInvoices()) {
             const decoded = tryDecodeBolt11(row.pr);
@@ -334,9 +356,21 @@ export const createZapBridge = (deps) => {
             if (nowMs > (decoded.timestamp + decoded.expirySeconds) * 1000 + 3_600_000)
                 stale.push(row.paymentHash);
         }
-        for (const hash of stale)
+        let swept = 0;
+        for (const hash of stale) {
+            let paid;
+            try {
+                paid = await backend.isInvoiceSettled(hash);
+            }
+            catch {
+                continue;
+            }
+            if (paid)
+                continue;
             store.deleteUnsettledZapInvoice(hash);
-        return stale.length;
+            swept++;
+        }
+        return swept;
     };
     return { pubkey, isZapName, payRequest, callback, settle, publish, sweep };
 };

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.19.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",