@forgesworn/moneyer 0.1.2 → 0.2.0

package/dist/server.js

@@ -1,8 +1,9 @@
 import { createServer } from 'node:http';
-import { bytesToHex, randomBytes } from '@noble/hashes/utils.js';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+import { finalizeEvent } from 'nostr-tools/pure';
 import { applyMintFee, grossUpForMintFee, hashK1 } from 'lnurlcash-kit';
 import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
-import { NotePendingError, NoteStore, NoteUnavailableError } from "./store.js";
+import { NotePendingError, NoteStore, NoteUnavailableError, OutputCollisionError, swapFingerprint } from "./store.js";
 import { createNoteSigner } from "./signing.js";
 import { createFakeBackend } from "./backends/fake.js";
 import { createClnBackend } from "./backends/cln.js";
@@ -10,12 +11,45 @@ import { createLndBackend } from "./backends/lnd.js";
 import { PaymentPendingError } from "./backends/types.js";
 import { reconcilePendingMelts, runMelt } from "./melt.js";
 import { landingPage } from "./landing.js";
+import { packageVersion } from "./version.js";
+import { createZapBridge, poolTransport } from "./zap.js";
+import { STATS_D_TAG, STATS_KIND, buildStats, statsSnapshotContent } from "./stats.js";
+import { ANNOUNCE_D_TAG, ANNOUNCE_KIND, announcementContent } from "./announce.js";
+import { isRefusal, registerName, validateNip98 } from "./names.js";
 import { CONFIG_TOKEN, loadWebAssets } from "./web-assets.js";
 const HEX32 = /^[0-9a-f]{64}$/;
+// The one request body this mint reads. Capped hard: nothing here needs
+// 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;
+const readBody = async (req, limit = MAX_BODY_BYTES) => {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        size += buffer.length;
+        if (size > limit)
+            return null;
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+// "fee 5 sat + 0.1%" - what a payer sees in their wallet's description.
+export const describeFee = (fee, roundedToSat) => {
+    const parts = [];
+    if (fee.baseFeeMsat > 0)
+        parts.push(`${fee.baseFeeMsat % 1000 === 0 ? fee.baseFeeMsat / 1000 : (fee.baseFeeMsat / 1000).toFixed(3)} sat`);
+    if (fee.feePpm > 0)
+        parts.push(`${(fee.feePpm / 10_000).toString()}%`);
+    const base = parts.length ? `fee ${parts.join(' + ')}` : 'no fee';
+    return roundedToSat && parts.length ? `${base}, rounded up to the sat` : base;
+};
+// A note's value rounded down to a whole sat; unchanged when already whole.
+const wholeSatFloor = (msat) => Math.floor(msat / 1000) * 1000;
 const backendFor = (config) => {
     switch (config.backend.kind) {
         case 'fake':
-            return createFakeBackend();
+            return createFakeBackend({ autoSettle: config.backend.autoSettle === true });
         case 'cln':
             return createClnBackend(config.backend);
         case 'lnd':
@@ -37,6 +71,13 @@ export const createMoneyer = async (config, deps = {}) => {
     catch {
         log('could not fetch funding-source node info - discovery will omit it');
     }
+    // The operator's own lightning addresses, re-applied at every startup so
+    // the environment and the table cannot disagree. Self-service names
+    // live in the same table and are left alone.
+    if (config.zap) {
+        for (const [name, pubkey] of Object.entries(config.zap.names))
+            store.putOperatorZapName(name, pubkey);
+    }
     // Melt payment hashes with a live attempt in this process. Reconcile
     // skips these - see melt.ts.
     const inFlight = new Set();
@@ -53,13 +94,46 @@ export const createMoneyer = async (config, deps = {}) => {
     const netAfterMintFee = (grossMsat) => Math.max(0, grossMsat - mintFeeMsat(grossMsat));
     // What the mint advertises as its minimum must survive its own fee: a
     // payRequest whose minSendable nets below the dust floor invites a
-    // payment it would then refuse.
-    const effectiveMinSendableMsat = Math.max(config.minSendableMsat, config.mintFee ? grossUpForMintFee(config.minMintMsat, config.mintFee) : 0);
+    // payment it would then refuse. grossUpForMintFee inverts the exact
+    // formula; with the fee rounded up to the sat the net can land just
+    // under the floor, so walk up until it clears. At most a sat of steps.
+    const effectiveMinSendableMsat = (() => {
+        let min = Math.max(config.minSendableMsat, config.mintFee ? grossUpForMintFee(config.minMintMsat, config.mintFee) : 0);
+        while (config.mintFee && netAfterMintFee(min) < config.minMintMsat)
+            min += 1;
+        return min;
+    })();
     // The routing-fee budget for a melt. LUD-25 has the mint fee cover the
     // eventual payout's routing cost, so the budget follows what this mint
     // actually charges, floored at 0.5%-or-5000msat so fee-free mints still
     // route.
     const meltFeeLimitMsat = (amountMsat) => Math.max(Math.round(amountMsat * 0.005), 5_000, mintFeeMsat(amountMsat));
+    const mintFeeLine = config.mintFee ? `Mint fees: ${config.mintFee.baseFeeMsat},${config.mintFee.feePpm}` : null;
+    // The same fee for a person: "Mint fees: 5000,1000" is for wallets that
+    // parse LUD-25, and reads as nonsense to anyone who does not.
+    const feeInWords = config.mintFee ? describeFee(config.mintFee, config.roundFeeToSat === true) : null;
+    const nostr = config.zap ? (deps.nostr ?? poolTransport()) : null;
+    const zap = config.zap && nostr
+        ? createZapBridge({
+            config: config.zap,
+            store,
+            backend,
+            transport: nostr,
+            netAfterMintFee,
+            minSendableMsat: effectiveMinSendableMsat,
+            maxSendableMsat: config.maxSendableMsat,
+            minMintMsat: config.minMintMsat,
+            mintFeeLine,
+            feeInWords,
+            verify: config.verify,
+            // configFromEnv guarantees this when zap is set; a caller
+            // building the config by hand gets the same rule.
+            origin: config.publicOrigin ?? (() => {
+                throw new Error('Zap-to-note needs publicOrigin.');
+            })(),
+            log
+        })
+        : null;
     // A note whose id we do not know yet may be a settled mint invoice whose
     // claim simply has not been observed: settle it lazily against the
     // funding source, which is what makes paying an invoice mint the note.
@@ -68,13 +142,152 @@ export const createMoneyer = async (config, deps = {}) => {
         const note = store.noteById(id);
         if (note)
             return note;
-        const invoice = store.mintInvoiceByHash(id);
-        if (invoice && !invoice.settled && (await backend.isInvoiceSettled(id))) {
-            store.settleMintInvoice(id);
+        // Either the invoice whose payment hash is this id - the older
+        // arrangement, where the payment preimage is the spend secret - or the
+        // invoice a payer bound to this id by naming it with `h`. In the bound
+        // case the wallet needs nothing but its own secret to claim: no
+        // /verify poll, no preimage, and so no window in which knowing the
+        // invoice is knowing the money.
+        const invoice = store.mintInvoiceByHash(id) ?? store.mintInvoiceByOutputId(id);
+        if (invoice && !invoice.settled && (await backend.isInvoiceSettled(invoice.paymentHash))) {
+            store.settleMintInvoice(invoice.paymentHash);
+            // The note lands at the id its payer named. Looking it up by this id
+            // finds it when that id IS the name, and finds nothing when this is
+            // a bound invoice's payment hash - which is the point of binding.
             return store.noteById(id);
         }
         return null;
     };
+    // ---- transparency: what the mint owes, and what the node holds ----
+    //
+    // Cached for 30 seconds so a public endpoint cannot be turned into a
+    // load generator against the funding source, and so the landing page
+    // and /stats never disagree with each other by a request.
+    let localBalanceMsat = nodeInfo.localBalanceMsat;
+    let reconciledAt;
+    let statsCache = null;
+    const currentStats = async () => {
+        const now = Date.now();
+        if (statsCache && now - statsCache.builtAt < 30_000)
+            return statsCache.value;
+        try {
+            // An answer that omits the balance is the funding source saying it
+            // does not know, and coverage must disappear with it rather than be
+            // computed against a stale number. A THROWN error is different: the
+            // node is unreachable this minute, and the last known figure stands.
+            const fresh = await backend.nodeInfo?.();
+            if (fresh)
+                localBalanceMsat = fresh.localBalanceMsat;
+        }
+        catch {
+            // unreachable - keep the last figure
+        }
+        const value = buildStats({
+            liabilities: store.liabilities(now),
+            localBalanceMsat,
+            reconciledAt,
+            at: now,
+            ratioOnly: config.statsRatioOnly === true
+        });
+        statsCache = { builtAt: now, value };
+        return value;
+    };
+    // ---- the mint address document ----
+    //
+    // LUD-25 discovery, built here rather than inline in its route because
+    // the mint also announces itself with it, and there must be one
+    // description of a mint rather than two that can drift apart.
+    const mintAddressDocument = (origin, user) => ({
+        tag: 'withdrawRequest',
+        callback: `${origin}/w`,
+        minWithdrawable: config.minMintMsat,
+        maxWithdrawable: config.mintFee
+            ? netAfterMintFee(config.maxSendableMsat)
+            : config.maxSendableMsat,
+        defaultDescription: config.description,
+        payLink: `${origin}/.well-known/lnurlp/${user}`,
+        ...(signer ? { mintPubkey: signer.pubkey } : {}),
+        // The human layer: who runs this, how to reach them, the terms,
+        // and today's message. Absent unless the operator set it.
+        ...(config.name ? { name: config.name } : {}),
+        description: config.description,
+        ...(config.contact ? { contact: config.contact } : {}),
+        ...(config.tosUrl ? { tosUrl: config.tosUrl } : {}),
+        ...(config.motd ? { motd: config.motd } : {}),
+        // The structured twin of the payRequest metadata's fee prose. Both
+        // stay: one is for a wallet that parses LUD-25, the other for a
+        // wallet that only reads a payRequest.
+        ...(config.mintFee ? { fees: config.mintFee } : {}),
+        ...(packageVersion ? { version: packageVersion } : {}),
+        // What a lightning address at this mint costs, when anyone can
+        // claim one. Absent means registration is closed.
+        ...(config.namePriceMsat !== undefined ? { namePriceMsat: config.namePriceMsat } : {}),
+        // Keys this mint has signed under before, so a wallet pinned to an
+        // old one can tell a legitimate rotation from an impostor. Always
+        // present, empty included: "never rotated" and "does not
+        // implement the field" are different answers.
+        previousPubkeys: config.previousSigningPubkeys ?? [],
+        // This mint accepts `h` on the pay callback: the payer's wallet may
+        // name the note it is buying, and then the payment preimage is not
+        // a spend secret for it. A wallet learns this before it asks for an
+        // invoice rather than after it has paid one.
+        mintToHash: true,
+        ...(nodeInfo.alias ? { nodeAlias: nodeInfo.alias } : {}),
+        ...(nodeInfo.uri ? { nodeUri: nodeInfo.uri } : {}),
+        ...(nodeInfo.color ? { nodeColor: nodeInfo.color } : {}),
+        // nodeCapacity is the name the reference mint, the conformance
+        // mock and lnurlcash-kit all use; nodeCapacityMsat was ours alone
+        // and only survived a round trip through the kit's rest-spread.
+        // Both go out for one release, then the old name goes.
+        ...(nodeInfo.capacityMsat !== undefined
+            ? { nodeCapacity: nodeInfo.capacityMsat, nodeCapacityMsat: nodeInfo.capacityMsat }
+            : {}),
+        ...(nodeInfo.numChannels !== undefined ? { nodeNumChannels: nodeInfo.numChannels } : {}),
+        ...(nodeInfo.numPeers !== undefined ? { nodeNumPeers: nodeInfo.numPeers } : {})
+    });
+    // An hourly signed snapshot, so the coverage history can be checked
+    // after the fact rather than taken on the operator's word for it today.
+    // Signed with the NOTE key: a holder already trusts that key for their
+    // own notes, so this adds nothing new to trust.
+    const publishStats = async () => {
+        if (config.statsPublish !== true || !signer || !config.signingKey || !config.zap || !nostr)
+            return;
+        const stats = await currentStats();
+        const event = finalizeEvent({
+            kind: STATS_KIND,
+            created_at: Math.floor(Date.now() / 1000),
+            tags: [['d', STATS_D_TAG]],
+            content: statsSnapshotContent(stats, config.signingKey)
+        }, hexToBytes(config.zap.nostrKey));
+        const { ok, failed } = await nostr.publish(config.zap.relays, event);
+        log(`liabilities snapshot published to ${ok.length} relay${ok.length === 1 ? '' : 's'}${failed.length ? `, ${failed.length} refused` : ''}`);
+    };
+    // The mint saying where it is. A wallet otherwise only ever learns of a
+    // mint by being told its address, and nothing that might follow - a
+    // list, a recommendation, a review - can exist until a mint can be found
+    // at all.
+    //
+    // It reuses the replaceable kind the snapshot goes out under, with a `d`
+    // tag of its own: choosing a new event kind is a protocol decision, and
+    // Cashu's NIP-87 kinds are not ours to take. The content is the
+    // discovery document exactly as the endpoint serves it, plus a signature
+    // by the NOTE signing key, so a holder can check that the mint
+    // announcing itself is the mint their notes verify against.
+    //
+    // Off unless the operator asked for it: a mint that does not want to be
+    // listed says nothing.
+    const publishAnnouncement = async () => {
+        if (config.announce !== true || !config.zap || !nostr || !config.publicOrigin)
+            return;
+        const event = finalizeEvent({
+            kind: ANNOUNCE_KIND,
+            created_at: Math.floor(Date.now() / 1000),
+            tags: [['d', ANNOUNCE_D_TAG]],
+            content: announcementContent(mintAddressDocument(config.publicOrigin, config.username), config.signingKey)
+        }, hexToBytes(config.zap.nostrKey));
+        const { ok, failed } = await nostr.publish(config.zap.relays, event);
+        log(`mint announced to ${ok.length} relay${ok.length === 1 ? '' : 's'}${failed.length ? `, ${failed.length} refused` : ''}`);
+    };
     const handle = async (req, res) => {
         const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
         const q = requestUrl.searchParams;
@@ -118,7 +331,13 @@ export const createMoneyer = async (config, deps = {}) => {
                     'x-frame-options': 'DENY',
                     'referrer-policy': 'no-referrer'
                 });
-                res.end(landingPage({ config, host, mintPubkey: signer?.pubkey ?? null, nodeInfo }));
+                res.end(landingPage({
+                    config,
+                    host,
+                    mintPubkey: signer?.pubkey ?? null,
+                    nodeInfo,
+                    stats: config.stats === false ? null : await currentStats()
+                }));
             }
             return;
         }
@@ -134,18 +353,147 @@ export const createMoneyer = async (config, deps = {}) => {
                 return;
             }
         }
+        // ---- claiming a lightning address ----
+        //
+        // This sits ABOVE the GET-only gate on purpose. That gate protects
+        // the LNURL callbacks, where a retried GET carrying the same query
+        // string must never burn a note twice; this is not one of them. It is
+        // a POST because it creates something, and it is authenticated by
+        // NIP-98 rather than by anything this mint has to store.
+        if (requestUrl.pathname === '/names' && req.method === 'POST') {
+            if (config.namePriceMsat === undefined)
+                return fail('This mint is not registering names.', 404);
+            const body = await readBody(req);
+            if (body === null)
+                return fail('Request body too large.', 413);
+            const authorized = validateNip98(req.headers.authorization, {
+                url: `${origin}${requestUrl.pathname}`,
+                method: 'POST',
+                body
+            });
+            if ('reason' in authorized)
+                return fail(authorized.reason, 401);
+            let parsed;
+            try {
+                parsed = JSON.parse(body || '{}');
+            }
+            catch {
+                return fail('Body must be JSON.', 400);
+            }
+            const result = registerName({
+                store,
+                // The NIP-98 signer owns the name. No other identity is accepted:
+                // a pubkey in the body would let anyone register a name to
+                // somebody else's key.
+                pubkey: authorized.pubkey,
+                body: parsed,
+                priceMsat: config.namePriceMsat,
+                reserved: [config.username],
+                host
+            });
+            if (isRefusal(result))
+                return fail(result.reason, result.status);
+            log(`name ${result.name} registered to ${result.pubkey.slice(0, 8)} for ${result.paidMsat} msat`);
+            return send({
+                status: 'OK',
+                name: result.name,
+                pubkey: result.pubkey,
+                address: `${result.name}@${host}`,
+                priceMsat: config.namePriceMsat,
+                paidMsat: result.paidMsat
+            });
+        }
         // Every LNURL endpoint below is a GET. The method matters: /w/cb
         // mutates on whatever arrives, and an OPTIONS preflight or a stray
         // retry carrying the same query string must never burn a note.
         if (req.method !== 'GET')
             return fail('Not found.', 404);
-        // ---- LUD-16 payRequest: paying this mints a note ----
+        // ---- NIP-05 ----
+        // The same table, so a registered name resolves both as a lightning
+        // address and as a Nostr address. Only the name asked for is
+        // answered: the list of everyone here is not something to hand out.
+        if (requestUrl.pathname === '/.well-known/nostr.json') {
+            const wanted = q.get('name')?.toLowerCase();
+            const entry = wanted ? store.zapName(wanted) : null;
+            return send({ names: entry ? { [entry.name]: entry.pubkey } : {} });
+        }
+        // ---- machine-readable operating figures ----
+        // The OpenMetrics text format, for a scraper. Off unless asked for,
+        // and deliberately unauthenticated: the deployment notes restrict the
+        // path at the reverse proxy, which is where that decision belongs.
+        if (requestUrl.pathname === '/metrics') {
+            if (config.metrics !== true)
+                return fail('Not found.', 404);
+            const liabilities = store.liabilities();
+            const totals = store.totals();
+            // The balance rides along with the /stats cache rather than hitting
+            // the funding source on every scrape.
+            const snapshot = await currentStats();
+            const lines = [];
+            const metric = (name, help, type, samples) => {
+                lines.push(`# HELP ${name} ${help}`, `# TYPE ${name} ${type}`);
+                for (const [labels, value] of samples)
+                    lines.push(`${name}${labels} ${value}`);
+            };
+            metric('moneyer_outstanding_msat', 'Value of every note this mint still owes.', 'gauge', [['', liabilities.outstandingMsat]]);
+            metric('moneyer_outstanding_notes', 'Number of notes this mint still owes.', 'gauge', [['', liabilities.outstandingNotes]]);
+            metric('moneyer_pending_melts', 'Melts reserved against a note and not yet resolved.', 'gauge', [['', liabilities.pendingMelts]]);
+            metric('moneyer_oldest_pending_melt_seconds', 'Age of the oldest unresolved melt.', 'gauge', [
+                ['', liabilities.oldestPendingMeltAgeSecs]
+            ]);
+            if (snapshot.localBalanceMsat !== undefined) {
+                metric('moneyer_local_balance_msat', 'Outbound balance reported by the funding source.', 'gauge', [
+                    ['', snapshot.localBalanceMsat]
+                ]);
+            }
+            metric('moneyer_unsettled_mint_invoices', 'Mint invoices issued and not yet paid.', 'gauge', [
+                ['', totals.unsettledMintInvoices]
+            ]);
+            metric('moneyer_mints_total', 'Notes minted from a settled invoice.', 'counter', [['', totals.mints]]);
+            metric('moneyer_melts_total', 'Melts by outcome.', 'counter', [
+                ['{outcome="paid"}', totals.melts.paid],
+                ['{outcome="restored"}', totals.melts.restored],
+                ['{outcome="pending"}', totals.melts.pending]
+            ]);
+            metric('moneyer_zaps_total', 'Zaps that settled into a note.', 'counter', [['', totals.zaps]]);
+            res.writeHead(200, {
+                'content-type': 'text/plain; version=0.0.4; charset=utf-8',
+                'x-content-type-options': 'nosniff'
+            });
+            res.end(`${lines.join('\n')}\n`);
+            return;
+        }
+        // ---- what the mint owes ----
+        // Public by design, and never per-note: a mint that will not say its
+        // liabilities is asking for trust it has not earned, but a mint that
+        // listed its notes would be handing out an oracle.
+        if (requestUrl.pathname === '/stats') {
+            if (config.stats === false)
+                return fail('Not found.', 404);
+            return send(await currentStats());
+        }
+        // ---- Zap-to-note: a name that pays out as a note over Nostr ----
         const lnurlpMatch = requestUrl.pathname.match(/^\/\.well-known\/lnurlp\/(.+)$/);
+        if (lnurlpMatch && zap && zap.isZapName(lnurlpMatch[1])) {
+            return send(zap.payRequest(lnurlpMatch[1]));
+        }
+        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'));
+            if ('reason' in result)
+                return fail(result.reason);
+            return send({ ...result, disposable: false });
+        }
+        // ---- LUD-16 payRequest: paying this mints a note ----
         if (lnurlpMatch) {
             if (!knownUser(lnurlpMatch[1]))
                 return fail('Unknown user.', 404);
             const metadata = [
-                ['text/plain', `Mint an LNURLcash bearer note at ${config.username}@${host}`],
+                ['text/plain', `Mint an LNURLcash bearer note at ${config.username}@${host}${feeInWords ? ` (${feeInWords})` : ''}`],
                 ['text/identifier', `${lnurlpMatch[1]}@${host}`]
             ];
             if (config.mintFee) {
@@ -161,6 +509,12 @@ export const createMoneyer = async (config, deps = {}) => {
                 // LUD-17's lnurlw:// is the scheme a wallet puts on a QR, not a
                 // field in a JSON body; every other URL here is directly fetchable.
                 withdrawLink: `${origin}/w`,
+                // This mint takes `h` on the callback below, so a wallet can name
+                // the note it is buying. Advertised here as well as on the
+                // discovery document because a wallet handed nothing but a
+                // lightning address never reads that document, and this has to be
+                // known BEFORE paying, not after.
+                mintToHash: true,
                 disposable: false
             });
         }
@@ -169,23 +523,7 @@ export const createMoneyer = async (config, deps = {}) => {
         if (lnurlwMatch) {
             if (!knownUser(lnurlwMatch[1]))
                 return fail('Unknown user.', 404);
-            return send({
-                tag: 'withdrawRequest',
-                callback: `${origin}/w`,
-                minWithdrawable: config.minMintMsat,
-                maxWithdrawable: config.mintFee
-                    ? netAfterMintFee(config.maxSendableMsat)
-                    : config.maxSendableMsat,
-                defaultDescription: config.description,
-                payLink: `${origin}/.well-known/lnurlp/${lnurlwMatch[1]}`,
-                ...(signer ? { mintPubkey: signer.pubkey } : {}),
-                ...(nodeInfo.alias ? { nodeAlias: nodeInfo.alias } : {}),
-                ...(nodeInfo.uri ? { nodeUri: nodeInfo.uri } : {}),
-                ...(nodeInfo.color ? { nodeColor: nodeInfo.color } : {}),
-                ...(nodeInfo.capacityMsat !== undefined ? { nodeCapacityMsat: nodeInfo.capacityMsat } : {}),
-                ...(nodeInfo.numChannels !== undefined ? { nodeNumChannels: nodeInfo.numChannels } : {}),
-                ...(nodeInfo.numPeers !== undefined ? { nodeNumPeers: nodeInfo.numPeers } : {})
-            });
+            return send(mintAddressDocument(origin, lnurlwMatch[1]));
         }
         // ---- LUD-06 pay callback: issue a mint invoice ----
         if (requestUrl.pathname === '/p/cb') {
@@ -200,12 +538,43 @@ export const createMoneyer = async (config, deps = {}) => {
             const net = netAfterMintFee(amount);
             if (net < config.minMintMsat)
                 return fail('Amount too small to mint a note.');
-            // The preimage is the future note's spend secret; its hash is the
-            // note id AND the invoice's payment hash. Generated here, handed to
-            // the funding source, never persisted - the store keeps hashes only.
+            // ---- naming the note being bought ----
+            //
+            // Optionally the payer's wallet chooses the note's spend secret
+            // itself and sends `h`, the sha256 of it, exactly as `h` means on
+            // the withdraw callback. The mint then credits the note at `h` on
+            // settlement, and the invoice's payment preimage buys nothing.
+            //
+            // That matters because a payment preimage is not a secret between
+            // two parties. It is known to the funding source, it is known to
+            // every node that forwarded the payment, and /verify hands it to
+            // anyone who can name the payment hash - which is written inside the
+            // invoice itself, on the QR the payer was shown. Where the preimage
+            // is the money, holding the invoice is nearly holding the money, and
+            // the wallet's only defence is to claim and rotate faster than
+            // anybody else. Naming the note removes the race instead of running
+            // it: the buyer is the only party who ever knew the secret.
+            //
+            // Both checks happen before an invoice exists, so a wallet is never
+            // left holding a quote the mint was always going to refuse. A
+            // collision gets the same reason a colliding output gets on the
+            // withdraw callback: which table an id already sits in is an oracle
+            // nobody is owed.
+            const askedOutputId = q.get('h');
+            const outputId = askedOutputId === null ? null : askedOutputId.toLowerCase();
+            if (outputId !== null) {
+                if (!HEX32.test(outputId))
+                    return fail('missing h');
+                if (store.outputIdInUse(outputId))
+                    return fail('Invalid or already spent k1.');
+            }
+            // The preimage is the future note's spend secret unless `h` named
+            // one; its hash is the invoice's payment hash either way. Generated
+            // here, handed to the funding source, never persisted - the store
+            // keeps hashes only.
             let preimage = bytesToHex(randomBytes(32));
             let paymentHash = hashK1(preimage);
-            while (store.noteById(paymentHash) || store.mintInvoiceByHash(paymentHash)) {
+            while (store.outputIdInUse(paymentHash) || paymentHash === outputId) {
                 preimage = bytesToHex(randomBytes(32));
                 paymentHash = hashK1(preimage);
             }
@@ -229,10 +598,26 @@ export const createMoneyer = async (config, deps = {}) => {
                 log('funding source returned an invoice that does not match the requested preimage/amount');
                 return fail('Temporarily unable to issue an invoice.');
             }
-            store.recordMintInvoice(paymentHash, pr, amount, net);
+            try {
+                store.recordMintInvoice(paymentHash, pr, amount, net, outputId);
+            }
+            catch (err) {
+                // The read above already refused the collisions it could see; this
+                // closes the race where another request claimed the id in between.
+                // The invoice exists at the funding source but has been shown to
+                // nobody, so nothing can be paid against it.
+                if (err instanceof OutputCollisionError)
+                    return fail('Invalid or already spent k1.');
+                throw err;
+            }
             return send({
                 pr,
                 disposable: false,
+                // Confirmation that this invoice really is bound to the id the
+                // wallet named. A mint that ignored an unknown parameter would
+                // answer without it, and a wallet can tell the two apart before
+                // paying rather than by looking for a note afterwards.
+                ...(outputId !== null ? { mintToHash: true } : {}),
                 ...(config.verify ? { verify: `${origin}/verify/${paymentHash}` } : {})
             });
         }
@@ -259,6 +644,15 @@ export const createMoneyer = async (config, deps = {}) => {
                 const preimageHex = settled ? await backend.paymentPreimage(paymentHash) : null;
                 return send({ status: 'OK', settled, preimage: preimageHex, pr: melt.pr });
             }
+            // A zap invoice's preimage is a throwaway the payer already holds,
+            // so serving it is LUD-21 as written and leaks nothing: the note's
+            // secret is a different value, sealed to the recipient.
+            const zapInvoice = store.zapInvoiceByHash(paymentHash);
+            if (zapInvoice) {
+                const settled = zapInvoice.settled || (await backend.isInvoiceSettled(paymentHash));
+                const preimageHex = settled ? await backend.invoicePreimage(paymentHash) : null;
+                return send({ status: 'OK', settled, preimage: preimageHex, pr: zapInvoice.pr });
+            }
             return fail('Unknown payment hash.');
         }
         // ---- LUD-03 informational GET ----
@@ -271,13 +665,24 @@ export const createMoneyer = async (config, deps = {}) => {
                 return fail('Unknown note.');
             if (note.state === 'burned')
                 return fail('Note already spent.');
+            // maxWithdrawable states the note's value, as the reference does.
+            // minWithdrawable is that value floored to a whole sat: most Lightning
+            // wallets can only invoice whole sats, and a note of 94.9 sat that
+            // insists on exactly 94,900 msat cannot be withdrawn by any of them.
+            // The sub-sat remainder of such a melt is dust the mint keeps.
             return send({
                 tag: 'withdrawRequest',
                 callback: `${origin}/w/cb`,
                 k1,
-                minWithdrawable: 0,
+                minWithdrawable: wholeSatFloor(note.amountMsat),
                 maxWithdrawable: note.amountMsat,
                 defaultDescription: config.description,
+                // The way home. A payRequest advertises `withdrawLink`; this is the
+                // other direction, so a holder who has nothing but a note can still
+                // find the document that publishes this mint's terms and its retired
+                // signing keys. Without it a wallet that only ever received notes
+                // cannot tell an announced key rotation from a substituted key.
+                payLink: `${origin}/.well-known/lnurlp/${config.username}`,
                 ...(signer ? { mintPubkey: signer.pubkey } : {})
             });
         }
@@ -312,6 +717,49 @@ export const createMoneyer = async (config, deps = {}) => {
             // merge or split. Atomic refusal, same as an invalid one.
             if (new Set(k1s).size !== k1s.length)
                 return fail('Invalid or already spent k1.');
+            // ---- the retried mutation ----
+            //
+            // A rotate, split or merge is a GET, and transports retry GETs.
+            // Go's net/http retries one that failed on a reused idle
+            // connection; the JDK's HttpClient retries idempotent methods with
+            // no switch to turn it off. The retry is byte-identical and arrives
+            // after the inputs are burned, so the honest-looking answer -
+            // "already spent" - tells a wallet to drop the only copy of a
+            // secret this mint really did mint a note against.
+            //
+            // So a request that already minted its outputs is answered with the
+            // same reply. This branch burns nothing, mints nothing and moves no
+            // balance: it is a read. The signature is deterministic over the
+            // output id and its amount, so it is recomputed rather than stored.
+            // Anything else naming a burned input is a double-spend attempt and
+            // still gets today's reason string, unchanged.
+            // Every k1 has to be hex before it can be hashed into a
+            // fingerprint; a malformed one falls through to the loop below and
+            // gets the same refusal it always did.
+            const fingerprint = pr !== null || !k1s.every(k1 => HEX32.test(k1))
+                ? null
+                : swapFingerprint({
+                    inputIds: k1s.map(hashK1),
+                    h: h,
+                    h2,
+                    ...(amountRaw !== null ? { amountMsat: Number(amountRaw) } : {})
+                });
+            const alreadyMinted = fingerprint === null ? null : store.swapByFingerprint(fingerprint);
+            if (alreadyMinted) {
+                const first = alreadyMinted.find(output => output.id === h);
+                const second = h2 === undefined ? undefined : alreadyMinted.find(output => output.id === h2);
+                if (first) {
+                    return send({
+                        status: 'OK',
+                        ...(signer
+                            ? {
+                                sig: signer.sign(first.id, first.amountMsat),
+                                ...(second ? { sig2: signer.sign(second.id, second.amountMsat) } : {})
+                            }
+                            : {})
+                    });
+                }
+            }
             const found = [];
             for (const k1 of k1s) {
                 if (!HEX32.test(k1))
@@ -330,8 +778,26 @@ export const createMoneyer = async (config, deps = {}) => {
                 const decoded = tryDecodeBolt11(pr.trim());
                 if (!decoded)
                     return fail('Invalid invoice.');
-                if (decoded.amountMsats === null || decoded.amountMsats !== BigInt(totalMsat)) {
-                    return fail(`Invoice must be for exactly ${totalMsat} msat.`);
+                // Exactly the notes' value, or the whole-sat floor of it when the
+                // value is not a whole sat (see the informational GET above). Never
+                // less than the floor: that would let a holder leave real value on
+                // the table by accident, and never more.
+                const floorMsat = wholeSatFloor(totalMsat);
+                // An invoice that states no amount is the easiest case a bearer
+                // note has: the note's value IS the amount, so the mint fills it in
+                // rather than refusing. It sends the whole-sat floor, which is the
+                // arithmetic a whole-value melt already does, and keeps the sub-sat
+                // remainder as the same dust it keeps when a wallet invoices the
+                // floor itself. A note worth less than a single sat has nothing
+                // left once that applies, and is refused as it always was.
+                const payAmountMsat = decoded.amountMsats === null ? floorMsat : null;
+                if (payAmountMsat === 0)
+                    return fail('insufficient value');
+                if (decoded.amountMsats !== null &&
+                    (decoded.amountMsats > BigInt(totalMsat) || decoded.amountMsats < BigInt(floorMsat))) {
+                    return fail(floorMsat === totalMsat
+                        ? `Invoice must be for exactly ${totalMsat} msat.`
+                        : `Invoice must be for ${totalMsat} msat, or ${floorMsat} msat (the whole-sat floor).`);
                 }
                 const paymentHash = decoded.paymentHashHex;
                 // Paying an invoice this mint itself issued would route the funding
@@ -374,7 +840,13 @@ export const createMoneyer = async (config, deps = {}) => {
                     return fail('Invoice already used by an earlier melt - use a fresh one.');
                 }
                 inFlight.add(paymentHash);
-                void runMelt({ paymentHash, noteId: inputIds[0], pr: pr.trim(), amountMsat: totalMsat }, { store, backend, feeLimitMsat: meltFeeLimitMsat, log, ...(deps.confirmDelaysMs ? { confirmDelaysMs: deps.confirmDelaysMs } : {}) })
+                void 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}`))
                     .finally(() => inFlight.delete(paymentHash));
                 // Replied before the payment resolves, per LUD-03: OK means the
@@ -409,7 +881,7 @@ export const createMoneyer = async (config, deps = {}) => {
                     store.swap(inputIds, [
                         { id: h, amountMsat: amount },
                         { id: h2, amountMsat: changeMsat }
-                    ]);
+                    ], fingerprint ?? undefined);
                 }
                 catch (err) {
                     if (err instanceof NotePendingError)
@@ -429,7 +901,7 @@ export const createMoneyer = async (config, deps = {}) => {
             // of one - the refund is exactly 0.
             const mergedMsat = totalMsat + (inputIds.length - 1) * baseFeeMsat;
             try {
-                store.swap(inputIds, [{ id: h, amountMsat: mergedMsat }]);
+                store.swap(inputIds, [{ id: h, amountMsat: mergedMsat }], fingerprint ?? undefined);
             }
             catch (err) {
                 if (err instanceof NotePendingError)
@@ -465,16 +937,51 @@ 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);
+        const swept = sweepExpiredMintInvoices(store) + (zap?.sweep() ?? 0);
         if (swept > 0)
             log(`swept ${swept} expired mint invoice${swept === 1 ? '' : 's'}`);
         await reconcilePendingMelts(store, backend, inFlight, log);
+        reconciledAt = Date.now();
     };
     await housekeeping();
     const housekeepingTimer = setInterval(() => {
         housekeeping().catch(err => log(`housekeeping failed: ${err.message}`));
     }, 300_000);
     housekeepingTimer.unref();
+    // A zap settles on the funding source's clock, not ours, so look often.
+    // One pass at a time: a slow relay must not stack passes.
+    let zapPass = null;
+    const zapTick = () => {
+        if (!zap)
+            return Promise.resolve();
+        if (zapPass)
+            return zapPass;
+        zapPass = (async () => {
+            try {
+                await zap.settle();
+                await zap.publish();
+            }
+            catch (err) {
+                log(`zap pass failed: ${err.message}`);
+            }
+            finally {
+                zapPass = null;
+            }
+        })();
+        return zapPass;
+    };
+    const zapTimer = zap ? setInterval(() => void zapTick(), deps.zapPollMs ?? 5_000) : null;
+    zapTimer?.unref();
+    // 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.
+    const statsTimer = (config.statsPublish === true && signer && config.zap) || (config.announce === true && config.zap)
+        ? setInterval(() => {
+            publishStats().catch(err => log(`liabilities snapshot failed: ${err.message}`));
+            publishAnnouncement().catch(err => log(`mint announcement failed: ${err.message}`));
+        }, deps.statsPublishMs ?? 3_600_000)
+        : null;
+    statsTimer?.unref();
     return {
         url: `http://${config.host}:${port}`,
         port,
@@ -482,9 +989,22 @@ export const createMoneyer = async (config, deps = {}) => {
         store,
         backend,
         signer,
-        reconcile: () => reconcilePendingMelts(store, backend, inFlight, log),
+        zap,
+        reconcile: async () => {
+            await reconcilePendingMelts(store, backend, inFlight, log);
+            reconciledAt = Date.now();
+            await zapTick();
+        },
+        stats: currentStats,
+        publishStats,
+        publishAnnouncement,
         close: async () => {
             clearInterval(housekeepingTimer);
+            if (zapTimer)
+                clearInterval(zapTimer);
+            if (statsTimer)
+                clearInterval(statsTimer);
+            nostr?.close();
             await new Promise((resolve, reject) => server.close(err => (err ? reject(err) : resolve())));
             await backend.close?.();
             store.close();