@forgesworn/moneyer 0.1.2 → 0.2.0

package/dist/zap.js

@@ -0,0 +1,294 @@
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+import { hashK1 } from 'lnurlcash-kit';
+import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { SimplePool } from 'nostr-tools/pool';
+import { makeZapReceipt, validateZapRequest } from 'nostr-tools/nip57';
+import { wrapEvent } from 'nostr-tools/nip59';
+// Zap-to-note: a lightning address on this host that pays out as an
+// LNURLcash note delivered over Nostr.
+//
+// A NIP-57 zap is an ordinary LNURL-pay. Paying the mint's own address
+// would mint a note, but to the PAYER: LUD-25 makes the invoice preimage
+// the secret, and on Lightning the payer always learns the preimage. So a
+// zap name works the other way round. The invoice gets a throwaway
+// preimage; on settlement the mint creates a note with a fresh secret of
+// its own, gift-wraps it (NIP-59, kind 2525 rumor) to the name's pubkey,
+// leaves it on their NIP-17 inbox relays, and publishes the kind 9735
+// receipt that makes the zap show up in clients.
+//
+// Until the recipient rotates the note, the mint knows its secret. That is
+// exactly the position a freshly minted note is in anyway, and it is why
+// wallets rotate on receipt. What is new is that the mint learns who was
+// paid, which a lightning address always did.
+export const NOTE_KIND = 2525;
+export const INBOX_RELAYS_KIND = 10050;
+export const ZAP_REQUEST_KIND = 9734;
+// Where a recipient's kind 10050 is looked for, beyond the mint's own relays.
+export const INDEXER_RELAYS = ['wss://purplepag.es', 'wss://relay.damus.io', 'wss://nos.lol'];
+// How long a settled zap keeps retrying the recipient's inbox relays
+// before it settles for whichever took the wrap. The receiver reads ONE
+// of its inbox relays, so a wrap that reached three others is still
+// undelivered. Seen live: a long-lived pool's dead socket to the device's
+// relay failed silently for hours while the other relays said OK.
+export const INBOX_RETRY_MS = 10 * 60_000;
+export const poolTransport = () => {
+    const pool = new SimplePool();
+    const used = new Set();
+    return {
+        async publish(relays, event) {
+            for (const r of relays)
+                used.add(r);
+            // A relay whose socket died reports failure forever on a pool that
+            // keeps the stale Relay object; drop it so the next publish dials
+            // afresh.
+            const results = await Promise.allSettled(pool.publish(relays, event));
+            results.forEach((r, i) => {
+                if (r.status === 'rejected') {
+                    try {
+                        pool.close([relays[i]]);
+                    }
+                    catch {
+                        // nothing to close
+                    }
+                }
+            });
+            const ok = [];
+            const failed = [];
+            results.forEach((r, i) => (r.status === 'fulfilled' ? ok : failed).push(relays[i]));
+            return { ok, failed };
+        },
+        async query(relays, filter) {
+            for (const r of relays)
+                used.add(r);
+            try {
+                return await pool.querySync(relays, filter, { maxWait: 6_000 });
+            }
+            catch {
+                return [];
+            }
+        },
+        close() {
+            pool.close([...used]);
+        }
+    };
+};
+export const inboxRelays = async (transport, pubkey, lookOn) => {
+    const events = await transport.query(lookOn, { kinds: [INBOX_RELAYS_KIND], authors: [pubkey], limit: 3 });
+    const latest = events.sort((a, b) => b.created_at - a.created_at)[0];
+    if (!latest)
+        return [];
+    return [...new Set(latest.tags.filter(t => t[0] === 'relay' && t[1]).map(t => t[1]))];
+};
+const metadataFor = (name, host, mintFeeLine, feeInWords = null) => {
+    const metadata = [
+        ['text/plain', `Zap ${name}@${host}: arrives as a Lightning bearer note${feeInWords ? ` (${feeInWords})` : ''}`],
+        ['text/identifier', `${name}@${host}`]
+    ];
+    if (mintFeeLine)
+        metadata.push(['text/plain', mintFeeLine]);
+    return JSON.stringify(metadata);
+};
+const tagValues = (event, name) => event.tags.filter(t => t[0] === name && t[1]).map(t => t[1]);
+export const createZapBridge = (deps) => {
+    const { config, store, backend, transport } = deps;
+    const log = deps.log ?? (() => { });
+    const now = deps.now ?? (() => Date.now());
+    const secret = hexToBytes(config.nostrKey);
+    const pubkey = getPublicKey(secret);
+    const origin = deps.origin;
+    const host = new URL(origin).host;
+    // Names live in the store, not in the configuration: the operator's own
+    // are loaded there at startup and self-service registrations land in
+    // the same table, so one lookup serves both.
+    const isZapName = (name) => store.zapName(name.toLowerCase()) !== null;
+    const payRequest = (name) => {
+        const lowered = name.toLowerCase();
+        if (!isZapName(lowered))
+            return null;
+        return {
+            tag: 'payRequest',
+            callback: `${origin}/z/cb/${lowered}`,
+            minSendable: deps.minSendableMsat,
+            maxSendable: deps.maxSendableMsat,
+            metadata: metadataFor(lowered, host, deps.mintFeeLine, deps.feeInWords),
+            allowsNostr: true,
+            nostrPubkey: pubkey
+            // Deliberately no withdrawLink: the preimage of this invoice is NOT
+            // a note, and an LNURLcash wallet that paid this must not think it
+            // is one.
+        };
+    };
+    const callback = async (name, amountMsat, nostrParam) => {
+        const lowered = name.toLowerCase();
+        const recipient = store.zapName(lowered)?.pubkey;
+        if (!recipient)
+            return { reason: 'Unknown user.' };
+        if (!Number.isSafeInteger(amountMsat) || amountMsat <= 0)
+            return { reason: 'Invalid amount.' };
+        if (amountMsat < deps.minSendableMsat || amountMsat > deps.maxSendableMsat)
+            return { reason: 'Amount out of range.' };
+        const net = deps.netAfterMintFee(amountMsat);
+        if (net < deps.minMintMsat)
+            return { reason: 'Amount too small to mint a note.' };
+        let zapRequest = null;
+        if (nostrParam !== null && nostrParam !== '') {
+            const problem = validateZapRequest(nostrParam);
+            if (problem)
+                return { reason: problem };
+            const parsed = JSON.parse(nostrParam);
+            if (parsed.kind !== ZAP_REQUEST_KIND)
+                return { reason: 'Zap request is not kind 9734.' };
+            const p = tagValues(parsed, 'p');
+            if (p.length !== 1 || p[0] !== recipient)
+                return { reason: `Zap request is not for ${lowered}@${host}.` };
+            const amountTag = tagValues(parsed, 'amount')[0];
+            if (amountTag !== undefined && Number(amountTag) !== amountMsat) {
+                return { reason: 'Zap request amount does not match.' };
+            }
+            zapRequest = nostrParam;
+        }
+        // A throwaway preimage: the payer will learn it, and it must be worth
+        // nothing to them. The note's secret is minted at settlement.
+        const preimage = bytesToHex(randomBytes(32));
+        const paymentHash = hashK1(preimage);
+        let pr;
+        try {
+            pr = (await backend.createInvoice({
+                amountMsat,
+                preimageHex: preimage,
+                memo: `Zap ${lowered}@${host}`,
+                descriptionForHash: zapRequest ?? metadataFor(lowered, host, deps.mintFeeLine, deps.feeInWords)
+            })).pr;
+        }
+        catch (err) {
+            log(`zap: create invoice failed: ${err.message}`);
+            return { reason: 'Temporarily unable to issue an invoice.' };
+        }
+        const decoded = tryDecodeBolt11(pr);
+        if (!decoded || decoded.paymentHashHex !== paymentHash || decoded.amountMsats !== BigInt(amountMsat)) {
+            log('zap: funding source returned an invoice that does not match the requested preimage/amount');
+            return { reason: 'Temporarily unable to issue an invoice.' };
+        }
+        store.recordZapInvoice({ paymentHash, name: lowered, recipient, pr, grossMsat: amountMsat, netMsat: net, zapRequest });
+        return { pr, ...(deps.verify ? { verify: `${origin}/verify/${paymentHash}` } : {}) };
+    };
+    // The note as the recipient's wallet will paste it, wrapped to them.
+    const buildWrap = (row, k1) => {
+        const tags = [
+            ['p', row.recipient],
+            ['amount', String(row.netMsat)],
+            ['u', `${host}/w`]
+        ];
+        if (row.zapRequest) {
+            const zr = JSON.parse(row.zapRequest);
+            // Who zapped, and what they zapped, so a receiver can say so.
+            tags.push(['P', zr.pubkey]);
+            for (const e of tagValues(zr, 'e'))
+                tags.push(['e', e]);
+            for (const a of tagValues(zr, 'a'))
+                tags.push(['a', a]);
+            // The zap request itself, the same content the kind 9735 receipt
+            // carries, so a wallet can show who zapped and what they wrote
+            // without going to a relay for it. Readers take tags by name, so an
+            // older one simply does not see this.
+            tags.push(['description', row.zapRequest]);
+        }
+        const rumor = {
+            kind: NOTE_KIND,
+            pubkey,
+            created_at: Math.floor(now() / 1000),
+            tags,
+            content: `${origin}/w?k1=${k1}&amount=${row.netMsat}`
+        };
+        return wrapEvent(rumor, secret, row.recipient);
+    };
+    // NIP-57 receipt, without the preimage tag: it is optional there, and
+    // here it would only invite someone to mistake it for the note.
+    const buildReceipt = (row) => {
+        if (!row.zapRequest)
+            return null;
+        const unsigned = makeZapReceipt({ zapRequest: row.zapRequest, bolt11: row.pr, paidAt: new Date(now()) });
+        return finalizeEvent(unsigned, secret);
+    };
+    const settle = async () => {
+        let minted = 0;
+        for (const row of store.unsettledZapInvoices()) {
+            let paid;
+            try {
+                paid = await backend.isInvoiceSettled(row.paymentHash);
+            }
+            catch (err) {
+                log(`zap: settlement check failed for ${row.paymentHash.slice(0, 8)}: ${err.message}`);
+                continue;
+            }
+            if (!paid)
+                continue;
+            const k1 = bytesToHex(randomBytes(32));
+            const noteId = hashK1(k1);
+            const wrap = buildWrap(row, k1);
+            const receipt = buildReceipt(row);
+            if (store.settleZapInvoice(row.paymentHash, noteId, JSON.stringify(wrap), receipt ? JSON.stringify(receipt) : null)) {
+                minted += 1;
+                log(`zap: ${row.name} received ${row.netMsat} msat; note ${noteId.slice(0, 8)} minted, wrap parked`);
+            }
+        }
+        return minted;
+    };
+    const publish = async () => {
+        let published = 0;
+        for (const row of store.unpublishedZaps()) {
+            if (!row.wrapJson) {
+                store.markZapPublished(row.paymentHash);
+                continue;
+            }
+            const wrap = JSON.parse(row.wrapJson);
+            const lookOn = [...new Set([...config.relays, ...INDEXER_RELAYS])];
+            const inbox = await inboxRelays(transport, row.recipient, lookOn);
+            const wrapRelays = [...new Set([...inbox, ...config.relays])];
+            const result = await transport.publish(wrapRelays, wrap);
+            if (!result.ok.length) {
+                log(`zap: wrap for ${row.name} reached no relay (${result.failed.join(', ')}); will retry`);
+                continue;
+            }
+            const missedInbox = result.failed.filter(r => inbox.includes(r));
+            if (missedInbox.length) {
+                const age = now() - (row.settledAt ?? now());
+                if (age < INBOX_RETRY_MS) {
+                    log(`zap: wrap for ${row.name} missed inbox relay(s) ${missedInbox.join(', ')}; parked for another try`);
+                    continue;
+                }
+                log(`zap: wrap for ${row.name} never reached ${missedInbox.join(', ')} in ${Math.round(age / 60_000)} min; left on ${result.ok.join(', ')}`);
+            }
+            if (!inbox.length)
+                log(`zap: ${row.name} publishes no inbox list; wrap left on the mint's relays`);
+            if (row.receiptJson) {
+                const receipt = JSON.parse(row.receiptJson);
+                // NIP-57 puts every relay in ONE tag: ["relays", url, url, ...].
+                const zr = JSON.parse(row.zapRequest ?? '{"tags":[]}');
+                const fromRequest = zr.tags.find(t => t[0] === 'relays')?.slice(1) ?? [];
+                const receiptRelays = [...new Set([...fromRequest, ...config.relays])].filter(r => /^wss?:\/\//.test(r));
+                const sent = await transport.publish(receiptRelays, receipt);
+                if (!sent.ok.length)
+                    log(`zap: receipt for ${row.name} reached no relay; the note still went out`);
+            }
+            store.markZapPublished(row.paymentHash);
+            published += 1;
+        }
+        return published;
+    };
+    const sweep = (nowMs = now()) => {
+        const stale = [];
+        for (const row of store.unsettledZapInvoices()) {
+            const decoded = tryDecodeBolt11(row.pr);
+            if (!decoded)
+                continue;
+            if (nowMs > (decoded.timestamp + decoded.expirySeconds) * 1000 + 3_600_000)
+                stale.push(row.paymentHash);
+        }
+        for (const hash of stale)
+            store.deleteUnsettledZapInvoice(hash);
+        return stale.length;
+    };
+    return { pubkey, isZapName, payRequest, callback, settle, publish, sweep };
+};

package/llms.txt

@@ -1,8 +1,9 @@
 # moneyer
 
 LNURLcash (LUD-25) mint for Node 24+. Strikes Lightning bearer notes:
-paying an invoice it issues mints a note whose spend secret IS the
-invoice's payment preimage. ESM-only. MIT.
+paying an invoice it issues mints a note whose spend secret is the
+invoice's payment preimage, or a secret the buyer named with `h` on the
+pay callback. ESM-only. MIT.
 
 Install: not yet on npm - build from source (see README)
 Run: node dist/cli.js --dev   (fake funding source, prints a funded note)
@@ -16,17 +17,29 @@ Client library to build against a mint: lnurlcash-kit
 
 1. A mint invoice's preimage is the note secret - the funding source must
    accept a caller-supplied preimage (cln and lnd do; phoenixd and NIP-47
-   make_invoice do not, and cannot back a mint).
+   make_invoice do not, and cannot back a mint). UNLESS the payer sent
+   `h` on the pay callback: then the note is credited at `h`, the payer's
+   own secret, and the preimage is only a payment proof. Prefer that: a
+   preimage is known to the funding source, to every node on the route,
+   and to anyone who polls verify with the payment hash in the invoice.
 2. Mutations are atomic: all named k1 burn and all outputs mint, or
    nothing happens. Duplicate k1 in one request is refused.
 3. h/h2 are WALLET-supplied hashes; the mint never generates a
-   replacement secret, and refuses output ids that already exist as notes
-   or as mint-invoice payment hashes.
+   replacement secret, and refuses output ids that already exist as
+   notes, as mint-invoice payment hashes, or as a note another payer has
+   already bought with `h`. A malformed `h` on the pay callback is
+   refused BEFORE an invoice is issued; a colliding one gets the same
+   oracle-free refusal a colliding mutation output gets. The reply
+   carries mintToHash: true when the invoice was bound, and the
+   payRequest and mint address advertise mintToHash: true.
 4. Melt OK means IN FLIGHT. The note burns only on confirmed payment,
    restores only on confirmed non-payment, and stays pending otherwise.
    A clean failure REPORT is not confirmation (hodl invoices).
-5. A melt invoice must equal the note total exactly, must not be one this
-   mint issued, and must not repeat an earlier melt's payment hash.
+5. A melt invoice must equal the note total exactly, or state no amount
+   at all, in which case the mint sends the whole-sat floor of the note's
+   value and refuses with 'insufficient value' when that is zero. It must
+   not be one this mint issued, and must not repeat an earlier melt's
+   payment hash.
    On a SHARED funding source the node's own payment history is the only
    dedupe that spans every consumer: pre-check it before reserving the
    note, and treat the node's "payment already exists" refusal as a
@@ -47,6 +60,10 @@ Client library to build against a mint: lnurlcash-kit
 ## Library API
 
 createMoneyer(config, deps?) -> {url, port, store, backend, signer, reconcile, close}
+verifyAnnouncement(content, mintPubkey) -> {valid, document}
+  kind 30078 / d=lnurlcash-mint: a mint announcing itself, content = its
+  discovery document + sig by the note signing key. MONEYER_ANNOUNCE=true,
+  off by default.
 configFromEnv(env?) -> MoneyerConfig     MONEYER_* environment variables
 createFakeBackend() -> LightningBackend with .control test hooks
 createClnBackend({url, rune}) / createLndBackend({url, macaroon})
@@ -58,7 +75,7 @@ NoteStore - SQLite store; notes by sha256(k1), never secrets
 
 /.well-known/lnurlp/{user}  LUD-16 payRequest (mints)
 /.well-known/lnurlw/{user}  LUD-25 mint address (experimental)
-/p/cb                       LUD-06 pay callback
+/p/cb                       LUD-06 pay callback (optional h names the note)
 /verify/{payment_hash}      LUD-21 verify (mint invoices AND melt payments)
 /w                          LUD-03 informational GET
 /w/cb                       melt / rotate / split / merge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.1.2",
+  "version": "0.2.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",
@@ -57,7 +57,8 @@
     "@noble/hashes": "^2.3.0",
     "@scure/base": "^1.2.4",
     "farrier-kit": "^1.1.3",
-    "lnurlcash-kit": "^0.1.0"
+    "lnurlcash-kit": "^0.2.0",
+    "nostr-tools": "2.24.1"
   },
   "devDependencies": {
     "@fontsource/cinzel": "^5.3.0",
@@ -66,7 +67,7 @@
     "@types/node": "^24.0.0",
     "animejs": "^4.0.0",
     "happy-dom": "^20.0.0",
-    "lnurlcash-conformance": "^0.1.0",
+    "lnurlcash-conformance": "^0.2.1",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",