@forgesworn/moneyer 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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

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/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

@@ -1298,7 +1298,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 +1335,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 +1419,7 @@ export const createMoneyer = async (config, deps = {}) => {
         publishStats,
         publishAnnouncement,
         close: async () => {
+            streamAbort.abort();
             clearInterval(housekeepingTimer);
             if (zapTimer)
                 clearInterval(zapTimer);
@@ -1370,6 +1428,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

@@ -48,6 +48,6 @@ export type ZapBridge = {
     callback(name: string, amountMsat: number, nostrParam: 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

@@ -325,7 +325,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 +337,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.19.0",
+  "version": "0.20.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",