@forgesworn/moneyer 0.17.1 → 0.18.0

package/CHANGELOG.md

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

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
 

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;

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}` } : {})

package/package.json

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