@forgesworn/moneyer 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.18.0 - 2026-10-07
+
+- **A melt that cannot leave is answered with its reason.** The callback
+  used to reply `OK` the moment the note was reserved, so a melt with no
+  route looked like success until the wallet checked again. It now waits up
+  to two seconds for the payment: if the funding source confirms nothing
+  went out, the note is restored first and the answer is `ERROR` with the
+  reason (for lnd, "Could not find a route to pay this invoice."). A
+  payment still in flight, or one that settles, is `OK` as before. The
+  hodl-invoice rule stands: a failure report is acted on only once the
+  funding source confirms it. The invoice itself is still refused if tried
+  again, as it was after a background restore.
+
+## 0.17.1 - 2026-10-06
+
+- **The expiry sweep no longer deletes paid mint invoices.** A mint invoice
+  was recorded as paid only when a wallet came back to `/verify` or to
+  claim its note, and the sweep deleted every unrecorded one an hour past
+  its expiry. A payer whose wallet never came back lost the payment: the
+  funding source kept the money and the note's id went with the row. The
+  sweep, and `moneyer admin sweep`, now ask the funding source first. Paid,
+  the invoice is settled and its note minted; unpaid, the row goes; no
+  answer, the row stays.
+- **lnd: a refused invoice lookup is no longer read as unpaid.** Only a 404
+  (an invoice lnd does not hold) now means unpaid; any other non-2xx throws.
+  A transient lnd error on `/verify` now returns an error instead of "not
+  paid yet".
+
 ## 0.17.0 - 2026-09-26
 
 LUD-25's unified taproot model (lnurl/luds 6e865b1). Every note is now a

package/README.md

@@ -37,10 +37,13 @@ lesson, that behaviour is kept deliberately and tested.
   from the start.
 - Signs every note it mints with its own mint key (secp256k1, the standard
   `Lightning Signed Message` construction) for LUD-25 offline verification.
-- The melt discipline: reply OK when the note is reserved, pay in the
-  background, burn only on confirmed payment, restore only on confirmed
-  non-payment, and park everything else as pending for reconciliation -
-  which also runs at startup, so a crash mid-melt never guesses.
+- The melt discipline: reserve the note, then give the payment up to two
+  seconds. A payment the funding source confirms never left (no route, say)
+  is answered `ERROR` with its reason and the note is outstanding again;
+  anything else is answered `OK` and finishes in the background. Burn only
+  on confirmed payment, restore only on confirmed non-payment, and park
+  everything else as pending for reconciliation - which also runs at
+  startup, so a crash mid-melt never guesses.
 
 ## Run
 
@@ -703,7 +706,7 @@ path should not silently create an empty database to answer from.
 | `note <id\|k1>` | one note; 64 hex that names no note is hashed and looked up as the secret |
 | `melts [--pending]` | list melts |
 | `reconcile` | one pending-melt reconcile pass, printing what changed |
-| `sweep` | delete mint invoices whose expiry is provably past |
+| `sweep` | delete expired mint invoices the funding source confirms unpaid, and mint the notes of any it finds paid |
 | `snapshot <path>` | a consistent copy of the database, taken live, refusing to overwrite |
 | `names list\|add <name> <npub>\|rm <name>` | the lightning addresses this mint pays out as notes |
 | `keys rotate` | generate a signing key and print the two environment lines; writes nothing |
@@ -735,8 +738,9 @@ is not.
   Whether that is a channel imbalance or something worse, it is the one
   number a custodial mint must never be relaxed about.
 - **unsettled invoices growing.** Invoices are issued and never paid all
-  day, and the sweep clears the expired ones. A count that climbs through
-  a sweep means invoices are being issued that nobody can pay.
+  day, and the sweep clears the expired ones the funding source confirms
+  unpaid. A count that climbs through a sweep means invoices are being
+  issued that nobody can pay, or that the funding source is not answering.
 
 ## Testing
 

package/THREAT-MODEL.md

@@ -147,9 +147,9 @@ is what notecase and lnurl-wallet do.
 - No rate limiting is built in; put it at the proxy. This matters most for
   `/p/cb`: each unauthenticated call creates a real invoice at the funding
   source. moneyer sweeps its own unsettled invoices once their bolt11
-  expiry has passed, but the node's side of that growth is the operator's
-  to bound (cln's autoclean, or an equivalent cron) - and a proxy limit is
-  what keeps the RPC pile-up and the node database from growing at all.
+  expiry has passed and the funding source confirms them unpaid, but the
+  node's side of that growth is the operator's to bound (cln's autoclean,
+  or an equivalent cron) - and a proxy limit is what keeps the RPC pile-up and the node database from growing at all.
 - A fee-free configuration pays the melt routing-fee floor (0.5% of the
   amount or 5000 msat) out of its own channel balance, and mint-and-melt
   cycling costs a griefer nothing. Set `MONEYER_BASE_FEE_MSAT` to cover the

package/dist/admin.js

@@ -18,7 +18,7 @@ const COMMANDS = [
     ['note <id|k1>', 'one note, by id or by the secret itself'],
     ['melts [--pending]', 'list melts, newest first'],
     ['reconcile', 'resolve melts left in flight, and say what changed'],
-    ['sweep', 'delete mint invoices whose expiry is provably past'],
+    ['sweep', 'delete expired mint invoices the funding source confirms unpaid'],
     ['snapshot <path>', 'a consistent copy of the database, taken live'],
     ['names list|add <name> <npub>|rm <name>', 'the lightning addresses this mint pays out as notes'],
     ['keys rotate', 'generate a signing key and print the two env lines'],
@@ -271,8 +271,10 @@ export const runAdmin = async (argv, deps = {}) => {
                 return 0;
             }
             case 'sweep': {
-                const swept = sweepExpiredMintInvoices(store, now());
+                const { swept, settled } = await sweepExpiredMintInvoices(store, fundingSource(), now());
                 out(`swept ${swept} expired mint invoice${swept === 1 ? '' : 's'}`);
+                if (settled > 0)
+                    out(`found ${settled} paid after all - note${settled === 1 ? '' : 's'} minted`);
                 return 0;
             }
             case 'snapshot': {

package/dist/backends/lnd.js

@@ -158,9 +158,16 @@ export const createLndBackend = (config) => {
                 throw new Error('lnd did not report a payment status.');
             return result;
         },
+        // 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.
         async isInvoiceSettled(paymentHashHex) {
             const res = await json(`/v1/invoice/${paymentHashHex}`);
-            return res.ok && Boolean(res.json?.settled);
+            if (res.status === 404)
+                return false;
+            if (!res.ok)
+                throw new Error(`lnd invoice lookup failed: HTTP ${res.status}`);
+            return Boolean(res.json?.settled);
         },
         async invoicePreimage(paymentHashHex) {
             const res = await json(`/v1/invoice/${paymentHashHex}`);

package/dist/melt.d.ts

@@ -7,6 +7,14 @@ export type MeltJob = {
     amountMsat: number;
     payAmountMsat?: number;
 };
+export type MeltOutcome = {
+    kind: 'paid';
+} | {
+    kind: 'restored';
+    reason: string;
+} | {
+    kind: 'unresolved';
+};
 export type MeltDeps = {
     store: NoteStore;
     backend: LightningBackend;
@@ -14,5 +22,5 @@ export type MeltDeps = {
     confirmDelaysMs?: number[];
     log?: (message: string) => void;
 };
-export declare const runMelt: (job: MeltJob, deps: MeltDeps) => Promise<void>;
+export declare const runMelt: (job: MeltJob, deps: MeltDeps) => Promise<MeltOutcome>;
 export declare const reconcilePendingMelts: (store: NoteStore, backend: LightningBackend, inFlight: ReadonlySet<string>, log?: (message: string) => void) => Promise<void>;

package/dist/melt.js

@@ -2,7 +2,7 @@ import { verifyPreimage } from 'farrier-kit/preimage';
 import { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } from "./backends/types.js";
 const DEFAULT_CONFIRM_DELAYS_MS = [0, 2_000, 4_000, 9_000, 16_000];
 const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-const confirmThenSettle = async (job, deps) => {
+const confirmThenSettle = async (job, deps, reason) => {
     const log = deps.log ?? (() => { });
     for (const delay of deps.confirmDelaysMs ?? DEFAULT_CONFIRM_DELAYS_MS) {
         if (delay > 0)
@@ -11,12 +11,11 @@ const confirmThenSettle = async (job, deps) => {
             const complete = await deps.backend.isPaymentComplete(job.paymentHash);
             if (complete) {
                 deps.store.finalizeMelt(job.paymentHash);
+                return { kind: 'paid' };
             }
-            else {
-                log(`melt ${job.noteId}: confirmed not paid - restoring`);
-                deps.store.restoreMelt(job.paymentHash);
-            }
-            return;
+            log(`melt ${job.noteId}: confirmed not paid - restoring`);
+            deps.store.restoreMelt(job.paymentHash);
+            return { kind: 'restored', reason };
         }
         catch (err) {
             if (!(err instanceof PaymentPendingError)) {
@@ -25,6 +24,7 @@ const confirmThenSettle = async (job, deps) => {
         }
     }
     log(`melt ${job.noteId}: payment status unconfirmable - note left pending for reconciliation`);
+    return { kind: 'unresolved' };
 };
 export const runMelt = async (job, deps) => {
     const log = deps.log ?? (() => { });
@@ -47,23 +47,26 @@ export const runMelt = async (job, deps) => {
             // lands between that check and the send.
             log(`melt ${job.noteId}: the funding source already knew this hash - restored (shared-node replay?)`);
             deps.store.restoreMelt(job.paymentHash);
-            return;
+            return { kind: 'restored', reason: 'Invoice already used by an earlier melt - use a fresh one.' };
         }
-        if (!(err instanceof PaymentFailedError)) {
+        // A clean failure's message is the backend's reason, written for a
+        // wallet ("Could not find a route..."); an ambiguous one is transport
+        // detail, so a wallet gets a plain sentence instead.
+        const clean = err instanceof PaymentFailedError;
+        if (!clean) {
             log(`melt ${job.noteId}: payment attempt failed ambiguously (${err.message})`);
         }
-        await confirmThenSettle(job, deps);
-        return;
+        return confirmThenSettle(job, deps, clean ? err.message : 'Payment failed.');
     }
     if (outcome.preimageHex !== null && !verifyPreimage(outcome.preimageHex, job.paymentHash)) {
         // The backend claims success with a preimage that does not settle this
         // invoice. That is a statement about the evidence, not the money - fall
         // back to the tracker rather than trusting either way.
         log(`melt ${job.noteId}: backend preimage does not settle this invoice - reconfirming`);
-        await confirmThenSettle(job, deps);
-        return;
+        return confirmThenSettle(job, deps, 'Payment failed.');
     }
     deps.store.finalizeMelt(job.paymentHash);
+    return { kind: 'paid' };
 };
 // Resolves melts an earlier process left pending - a crash mid-melt, or an
 // outcome that could not be confirmed at the time. Melts whose attempt is

package/dist/server.d.ts

@@ -25,6 +25,7 @@ export type MoneyerDeps = {
     store?: NoteStore;
     log?: (message: string) => void;
     confirmDelaysMs?: number[];
+    meltAnswerWindowMs?: number;
     webAssets?: WebAssets | null;
     nostr?: NostrTransport;
     zapPollMs?: number;
@@ -33,4 +34,7 @@ export type MoneyerDeps = {
 };
 export { describeFee } from './fee-words.ts';
 export declare const createMoneyer: (config: MoneyerConfig, deps?: MoneyerDeps) => Promise<Moneyer>;
-export declare const sweepExpiredMintInvoices: (store: NoteStore, nowMs?: number) => number;
+export declare const sweepExpiredMintInvoices: (store: NoteStore, backend: Pick<LightningBackend, "isInvoiceSettled">, nowMs?: number) => Promise<{
+    swept: number;
+    settled: number;
+}>;

package/dist/server.js

@@ -45,6 +45,9 @@ const renamedRef = (q, name, legacy) => {
 // 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.
 const MAX_BODY_BYTES = 8 * 1024;
+// How long a melt callback waits for the payment's outcome before answering
+// OK. Long enough for a no-route failure, short against a wallet's timeout.
+const MELT_ANSWER_WINDOW_MS = 2_000;
 const readBody = async (req, limit = MAX_BODY_BYTES) => {
     const chunks = [];
     let size = 0;
@@ -1161,17 +1164,34 @@ export const createMoneyer = async (config, deps = {}) => {
                     return fail('Invoice already used by an earlier melt - use a fresh one.');
                 }
                 inFlight.add(paymentHash);
-                void runMelt({
+                const melt = runMelt({
                     paymentHash,
                     noteId: inputIds[0],
                     pr: pr.trim(),
                     amountMsat: totalMsat,
                     ...(payAmountMsat !== null ? { payAmountMsat } : {})
                 }, { store, backend, feeLimitMsat: meltFeeLimitMsat, log, ...(deps.confirmDelaysMs ? { confirmDelaysMs: deps.confirmDelaysMs } : {}) })
-                    .catch(err => log(`melt ${inputIds[0]}: ${err.message}`))
+                    .catch((err) => {
+                    log(`melt ${inputIds[0]}: ${err.message}`);
+                    return { kind: 'unresolved' };
+                })
                     .finally(() => inFlight.delete(paymentHash));
-                // Replied before the payment resolves, per LUD-03: OK means the
-                // melt is requested and the note reserved, never that it settled.
+                // A payment that cannot leave usually says so within a second (lnd
+                // answers no-route before sending any HTLC), so wait briefly: a
+                // melt the funding source has confirmed never went out is answered
+                // with its reason, and the note is already outstanding again. Any
+                // other outcome, or none yet, is OK as LUD-03 has it: the melt is
+                // requested and the note reserved, never that it settled.
+                let windowTimer;
+                const outcome = await Promise.race([
+                    melt,
+                    new Promise(resolve => {
+                        windowTimer = setTimeout(() => resolve(null), deps.meltAnswerWindowMs ?? MELT_ANSWER_WINDOW_MS);
+                    })
+                ]);
+                clearTimeout(windowTimer);
+                if (outcome?.kind === 'restored')
+                    return fail(outcome.reason);
                 return send({
                     status: 'OK',
                     ...(config.verify ? { pr: pr.trim(), verify: `${origin}/verify/${paymentHash}` } : {})
@@ -1262,9 +1282,12 @@ export const createMoneyer = async (config, deps = {}) => {
     // otherwise grow by one dead row per /p/cb call forever. The timer is
     // unref'd so it never keeps the process alive.
     const housekeeping = async () => {
-        const swept = sweepExpiredMintInvoices(store) + (zap?.sweep() ?? 0);
+        const { swept: mintSwept, settled } = await sweepExpiredMintInvoices(store, backend);
+        const swept = mintSwept + (zap?.sweep() ?? 0);
         if (swept > 0)
             log(`swept ${swept} expired mint invoice${swept === 1 ? '' : 's'}`);
+        if (settled > 0)
+            log(`found ${settled} expired mint invoice${settled === 1 ? '' : 's'} paid after all - note${settled === 1 ? '' : 's'} minted`);
         await reconcilePendingMelts(store, backend, inFlight, log);
         reconciledAt = Date.now();
     };
@@ -1337,15 +1360,25 @@ export const createMoneyer = async (config, deps = {}) => {
         }
     };
 };
-// Deletes unsettled mint invoices whose bolt11 expiry is comfortably past,
-// returning the count swept. The invoice's own timestamp + expiry are the
-// proof - a funding source refuses to settle an expired invoice, so the
-// row can never mint a note again. The hour's margin keeps the delete
-// unambiguously behind every implementation's reading of that expiry, and
-// an undecodable invoice is kept: no proof, no delete. The delete itself is
-// conditional on the row still being unsettled, so a settle racing the
-// sweep always wins.
-export const sweepExpiredMintInvoices = (store, nowMs = Date.now()) => {
+// Clears mint invoices this mint has not seen paid once their bolt11 expiry
+// is comfortably past, returning how many it deleted and how many it found
+// paid after all.
+//
+// "Unsettled" here is only this mint's record. A payment is recorded when a
+// wallet comes back to /verify or to claim its note, so a payer whose wallet
+// never comes back - a closed tab, an invoice paid from another app - leaves
+// a row that reads unsettled while the funding source holds the money.
+// Deleting that row would strand the payment for good: the note's id lives
+// only here. So the funding source is asked first. Paid, the invoice is
+// settled and its note minted, exactly as a /verify would have. Unpaid, the
+// expiry is the proof it never can be, and the row goes. No answer, no
+// delete.
+//
+// The hour's margin keeps the delete unambiguously behind every
+// implementation's reading of that expiry, an undecodable invoice is kept,
+// and the delete is conditional on the row still being unsettled, so a
+// settle racing the sweep always wins.
+export const sweepExpiredMintInvoices = async (store, backend, nowMs = Date.now()) => {
     const stale = [];
     for (const invoice of store.unsettledMintInvoices()) {
         const decoded = tryDecodeBolt11(invoice.pr);
@@ -1355,7 +1388,24 @@ export const sweepExpiredMintInvoices = (store, nowMs = Date.now()) => {
         if (nowMs > expiresAtMs + 3_600_000)
             stale.push(invoice.paymentHash);
     }
-    for (const paymentHash of stale)
-        store.deleteUnsettledMintInvoice(paymentHash);
-    return stale.length;
+    let swept = 0;
+    let settled = 0;
+    for (const paymentHash of stale) {
+        let paid;
+        try {
+            paid = await backend.isInvoiceSettled(paymentHash);
+        }
+        catch {
+            continue;
+        }
+        if (paid) {
+            store.settleMintInvoice(paymentHash);
+            settled++;
+        }
+        else {
+            store.deleteUnsettledMintInvoice(paymentHash);
+            swept++;
+        }
+    }
+    return { swept, settled };
 };

package/package.json

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