@forgesworn/moneyer 0.16.2 → 0.17.0

package/dist/store.js

@@ -1,6 +1,7 @@
 import { DatabaseSync } from 'node:sqlite';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
+import { bearerNoteId } from "./spend.js";
 // What identifies one mutation request, so a retry of it can be answered
 // with the same reply instead of "already spent". Everything the WALLET
 // chose goes in: the notes it named (by id, never by secret - the store
@@ -123,6 +124,16 @@ export class NoteStore {
         if (!nameColumns.includes('next_index')) {
             this.db.exec('ALTER TABLE zap_names ADD COLUMN next_index INTEGER NOT NULL DEFAULT 0');
         }
+        if (!invoiceColumns.includes('output_named')) {
+            this.db.exec('ALTER TABLE mint_invoices ADD COLUMN output_named TEXT');
+        }
+        // The Q of the bearer note the invoice's payment preimage would open.
+        // That preimage reaches the funding source, every hop, and /verify, so
+        // no note may ever be credited there. See outputIdInUse.
+        if (!invoiceColumns.includes('payment_q')) {
+            this.db.exec('ALTER TABLE mint_invoices ADD COLUMN payment_q TEXT');
+        }
+        this.db.exec('CREATE INDEX IF NOT EXISTS mint_invoices_payment_q ON mint_invoices (payment_q)');
         this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);');
         // The moment this mint stopped publishing preimages for notes nobody
         // named. Written once, the first time a build carrying this code opens
@@ -138,6 +149,66 @@ export class NoteStore {
         this.db
             .prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('unnamed_verify_cutover', ?)")
             .run(String(Date.now()));
+        this.indexLegacyIds();
+        // Lightning Address payments now land on their own purpose of a name's
+        // branch, a counter that starts at 0. The indices on file counted the
+        // old single ladder, so restart them once rather than open a gap a
+        // wallet's scan could stop short of.
+        this.tx(() => {
+            const moved = this.db
+                .prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('address_purpose_counter', ?)")
+                .run(String(Date.now()));
+            if (moved.changes > 0)
+                this.db.exec('UPDATE zap_names SET next_index = 0');
+        });
+    }
+    // Once per database: the Q each id written before notes were keyed by Q
+    // would have as a bearer note (see the top of this file). Every note row,
+    // every note an invoice was told to credit, and every payment hash that
+    // is itself a note's id. Rows written after this run are keyed by Q
+    // already, apart from notes still to land from invoices indexed here.
+    indexLegacyIds() {
+        this.db.exec('CREATE TABLE IF NOT EXISTS legacy_ids (q TEXT PRIMARY KEY, id TEXT NOT NULL)');
+        const done = this.db.prepare("SELECT 1 FROM meta WHERE key = 'legacy_ids_indexed'").get();
+        if (done)
+            return;
+        this.tx(() => {
+            const ids = this.db
+                .prepare(`SELECT id FROM notes
+           UNION SELECT output_id FROM mint_invoices WHERE output_id IS NOT NULL
+           UNION SELECT payment_hash FROM mint_invoices WHERE output_id IS NULL`)
+                .all();
+            const insert = this.db.prepare('INSERT OR IGNORE INTO legacy_ids (q, id) VALUES (?, ?)');
+            for (const { id } of ids) {
+                if (/^[0-9a-f]{64}$/.test(id))
+                    insert.run(bearerNoteId(id), id);
+            }
+            const unmapped = this.db.prepare('SELECT payment_hash FROM mint_invoices WHERE payment_q IS NULL').all();
+            const setQ = this.db.prepare('UPDATE mint_invoices SET payment_q = ? WHERE payment_hash = ?');
+            for (const { payment_hash } of unmapped)
+                setQ.run(bearerNoteId(payment_hash), payment_hash);
+            this.db.prepare("INSERT INTO meta (key, value) VALUES ('legacy_ids_indexed', ?)").run(String(Date.now()));
+        });
+    }
+    // The old id a note named by `q` is stored under, if it predates Q ids.
+    // A read-only store opened on a database no upgraded mint has touched
+    // has no index yet, and so no old ids to find.
+    legacyIdOf(q) {
+        try {
+            const row = this.db.prepare('SELECT id FROM legacy_ids WHERE q = ?').get(q);
+            return row?.id ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // The note whose output key is `q`, wherever it is stored.
+    noteByQ(q) {
+        const note = this.noteById(q);
+        if (note)
+            return note;
+        const legacy = this.legacyIdOf(q);
+        return legacy ? this.noteById(legacy) : null;
     }
     // 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".
@@ -159,11 +230,12 @@ export class NoteStore {
             throw err;
         }
     }
+    // By the row's own key. A request names notes by Q: see noteByQ.
     noteById(id) {
         const row = this.db
-            .prepare('SELECT id, amount_msat, state FROM notes WHERE id = ?')
+            .prepare('SELECT id, amount_msat, state, created_at FROM notes WHERE id = ?')
             .get(id);
-        return row ? { id: row.id, amountMsat: row.amount_msat, state: row.state } : null;
+        return row ? { id: row.id, amountMsat: row.amount_msat, state: row.state, createdAt: row.created_at } : null;
     }
     insertNote(id, amountMsat) {
         const now = Date.now();
@@ -187,11 +259,16 @@ export class NoteStore {
     // Public because the pay callback has to answer this before it asks the
     // funding source for an invoice: a wallet must never pay for a quote the
     // mint was always going to refuse.
+    //
+    // A Q that an old id maps to is in use too, burned or not: crediting a
+    // new note there would give one secret two notes.
     outputIdInUse(id) {
         const asNote = this.db.prepare('SELECT 1 FROM notes WHERE id = ?').get(id);
         const asInvoice = this.db.prepare('SELECT 1 FROM mint_invoices WHERE payment_hash = ?').get(id);
         const asBoundOutput = this.db.prepare('SELECT 1 FROM mint_invoices WHERE output_id = ?').get(id);
-        return Boolean(asNote || asInvoice || asBoundOutput);
+        const asLegacy = this.db.prepare('SELECT 1 FROM legacy_ids WHERE q = ?').get(id);
+        const asPreimageNote = this.db.prepare('SELECT 1 FROM mint_invoices WHERE payment_q = ?').get(id);
+        return Boolean(asNote || asInvoice || asBoundOutput || asLegacy || asPreimageNote);
     }
     assertOutputIdFree(id) {
         if (this.outputIdInUse(id))
@@ -313,22 +390,23 @@ export class NoteStore {
             outcome: row.outcome
         }));
     }
-    // `outputId` is the note id the payer's wallet asked for with `h`. Both
-    // ids are checked in the same transaction that inserts the row, so two
-    // requests racing for one id cannot both be told yes.
-    recordMintInvoice(paymentHash, pr, grossMsat, netMsat, outputId = null) {
+    // `outputId` is hex(Q) of the note the payer's wallet named, and
+    // `outputNamed` the value it named it by. Both ids are checked in the
+    // same transaction that inserts the row, so two requests racing for one
+    // id cannot both be told yes.
+    recordMintInvoice(paymentHash, pr, grossMsat, netMsat, outputId = null, outputNamed = outputId) {
         this.tx(() => {
             this.assertOutputIdFree(paymentHash);
             if (outputId !== null)
                 this.assertOutputIdFree(outputId);
             this.db
-                .prepare('INSERT INTO mint_invoices (payment_hash, pr, gross_msat, net_msat, settled, created_at, output_id) VALUES (?, ?, ?, ?, 0, ?, ?)')
-                .run(paymentHash, pr, grossMsat, netMsat, Date.now(), outputId);
+                .prepare('INSERT INTO mint_invoices (payment_hash, pr, gross_msat, net_msat, settled, created_at, output_id, output_named, payment_q) VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?)')
+                .run(paymentHash, pr, grossMsat, netMsat, Date.now(), outputId, outputNamed, bearerNoteId(paymentHash));
         });
     }
     mintInvoiceByHash(paymentHash) {
         const row = this.db
-            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, created_at FROM mint_invoices WHERE payment_hash = ?')
+            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, output_named, created_at FROM mint_invoices WHERE payment_hash = ?')
             .get(paymentHash);
         if (!row)
             return null;
@@ -339,6 +417,7 @@ export class NoteStore {
             netMsat: row.net_msat,
             settled: row.settled === 1,
             outputId: row.output_id,
+            outputNamed: row.output_named,
             createdAt: row.created_at
         };
     }
@@ -355,7 +434,7 @@ export class NoteStore {
     // expired invoices - so it is dead weight, and every /p/cb call adds one.
     unsettledMintInvoices() {
         const rows = this.db
-            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, created_at FROM mint_invoices WHERE settled = 0')
+            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, output_named, created_at FROM mint_invoices WHERE settled = 0')
             .all();
         return rows.map(row => ({
             paymentHash: row.payment_hash,
@@ -364,6 +443,7 @@ export class NoteStore {
             netMsat: row.net_msat,
             settled: false,
             outputId: row.output_id,
+            outputNamed: row.output_named,
             createdAt: row.created_at
         }));
     }

package/dist/zap.js

@@ -1,5 +1,6 @@
 import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
-import { decodeCx1, deriveNotePubkey, encodeCp1, hashK1 } from '@lnurlcash/kit';
+import { decodeCx1, encodeCp1, hashK1 } from '@lnurlcash/kit';
+import { NOTE_PURPOSE_LIGHTNING_ADDRESS, bearerNoteIdOfPreimage, deriveNotePubkey } from "./spend.js";
 import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
 import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
 import { SimplePool } from 'nostr-tools/pool';
@@ -83,8 +84,11 @@ const metadataFor = (name, host, mintFeeLine, feeInWords = null, internalTransfe
         ['text/plain', `Zap ${name}@${host}: arrives as a Lightning bearer note${feeInWords ? ` (${feeInWords})` : ''}`],
         ['text/identifier', `${name}@${host}`]
     ];
+    // `text/cpub`, never the older `text/xpub` as well: a wallet that reads
+    // `text/xpub` derives the index without a purpose, and would transfer to
+    // a key the payee never scans. Without it that wallet pays by Lightning.
     if (internalTransfer)
-        metadata.push(['text/xpub', internalTransfer]);
+        metadata.push(['text/cpub', internalTransfer]);
     if (mintFeeLine)
         metadata.push(['text/plain', mintFeeLine]);
     return JSON.stringify(metadata);
@@ -113,7 +117,7 @@ export const createZapBridge = (deps) => {
             let index = registered.nextIndex;
             for (let tries = 0; tries < 1000; tries++, index++) {
                 try {
-                    const noteId = bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, index));
+                    const noteId = bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, NOTE_PURPOSE_LIGHTNING_ADDRESS, index));
                     if (!store.outputIdInUse(noteId)) {
                         internalTransfer = `${registered.cx1}:${index}`;
                         break;
@@ -224,7 +228,7 @@ export const createZapBridge = (deps) => {
     // the certificate, and the index `i` the holder derives the key at. A
     // reader that knows only note URLs sees no k1 and passes it by, and the
     // note waits at the mint for a scan to find it.
-    const buildKeyWrap = (row, noteId, index) => wrap(row, [...wrapTags(row), ['i', String(index)]], `${origin}/w?p=${encodeCp1(hexToBytes(noteId))}&sig=${deps.certify(noteId, row.netMsat)}&i=${index}`);
+    const buildKeyWrap = (row, noteId, index) => wrap(row, [...wrapTags(row), ['i', String(index)]], `${origin}/w?p=${encodeCp1(hexToBytes(noteId))}&c=${deps.certify(noteId, row.netMsat)}&i=${index}`);
     // 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) => {
@@ -251,7 +255,7 @@ export const createZapBridge = (deps) => {
                 const receipt = buildReceipt(row);
                 const keyAt = (index) => {
                     try {
-                        return bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, index));
+                        return bytesToHex(deriveNotePubkey(branch.pubkeyXOnly, branch.chainCode, NOTE_PURPOSE_LIGHTNING_ADDRESS, index));
                     }
                     catch {
                         return null;
@@ -268,7 +272,8 @@ export const createZapBridge = (deps) => {
                 continue;
             }
             const k1 = bytesToHex(randomBytes(32));
-            const noteId = hashK1(k1);
+            // The bearer note whose preimage is k1, stored under its Q.
+            const noteId = bearerNoteIdOfPreimage(k1);
             const wrap = buildWrap(row, k1);
             const receipt = buildReceipt(row);
             if (store.settleZapInvoice(row.paymentHash, noteId, JSON.stringify(wrap), receipt ? JSON.stringify(receipt) : null)) {

package/llms.txt

@@ -29,11 +29,16 @@ Client library to build against a mint: @lnurlcash/kit
    inside the invoice. `h` is an additive alias for the same commitment and
    never replaces the comment. Because the note is not keyed by the
    preimage, a funding source whose node chooses its own preimages
-   (phoenixd, NIP-47 make_invoice) can back a mint. LUD-25 Part 2: the
-   comment may instead be `cp1<pk>`, and the note is keyed by that key.
+   (phoenixd, NIP-47 make_invoice) can back a mint. Every note is a LUD-25
+   taproot output key Q: a 64-hex comment is a bearer note's h (Q follows
+   from it), and `cp1<Q>` names any note directly.
 2. Mutations are atomic: all named k1 burn and all outputs mint, or
    nothing happens. A note named twice in one request is refused, compared
-   by the note each k1 spends: one Part 2 note has many valid ck1 strings.
+   by the Q each k1 spends: one note has many valid spends (preimage, cw1,
+   ck1). Every k1 is verified first: a ck1 is bound to this mint's domains
+   (clearnet and onion), a cw1 is checked for leaf version, OP_SUCCESSx and
+   Unix-time claims, and only bearer hashlock leaves are evaluated in
+   process; other leaves need MoneyerDeps.scriptVerifier.
 3. p1/p2 (older names h/h2, still accepted; both spellings of one output
    must agree) are WALLET-supplied hashes or cp1 keys; the mint never generates a
    replacement secret, and refuses output ids that already exist as
@@ -84,10 +89,17 @@ configFromEnv(env?) -> MoneyerConfig     MONEYER_* environment variables
   operator configured - it never builds one.
 createFakeBackend() -> LightningBackend with .control test hooks
 createClnBackend({url, rune}) / createLndBackend({url, macaroon})
+decodeSpend(k1) -> Spend | null        a preimage, ck1 or cw1, with the Q it opens
+decodeNote(value) -> hex(Q) | null     a cp1, or a bearer note's 64-hex h
+verifySpend(spend, {outputKey, domains, now, lockedAt, scriptVerifier?}) -> Promise<SpendVerdict>
+bearerNoteId(hHex) / bearerNoteIdOfPreimage(k1Hex) -> hex(Q)
+keyPathSighash(Q, domain) / scriptPathSighash(Q, domain, leaf, locktime, sequence) -> 32 bytes
+ScriptVerifier = ({outputKey, domain, spend, now, lockedAt}) => Promise<reason | null>
+  pass as MoneyerDeps.scriptVerifier to judge leaves moneyer cannot evaluate itself
 createNoteSigner(privHex) -> {pubkey, sign(noteId, amountMsat)}
   privHex is a secp256k1 private key, as MONEYER_SIGNING_KEY; zero is rejected
 fakeBolt11({amountMsat, paymentHashHex, memo?}) -> decodable, unpayable invoice
-NoteStore - SQLite store; notes by sha256(k1), never secrets
+NoteStore - SQLite store; notes by hex(Q), never spends; pre-Q rows found via legacy_ids
 runMelt(job, deps) -> Promise<void> / reconcilePendingMelts(store, backend, inFlight, log?)
   the melt discipline: burn only on confirmed payment, restore only on confirmed
   non-payment. The /w/cb handler drives both; outcomes land in the store, not in a
@@ -108,15 +120,15 @@ signStats(stats, privHex) -> string   the signature alone, hex r || s || recover
 
 /.well-known/lnurlp/{user}  LUD-16 payRequest (mints)
 /.well-known/lnurlw/{user}  LUD-25 mint address (experimental)
-/p/cb                       LUD-06 pay callback (comment names the note: hash or cp1)
+/p/cb                       LUD-06 pay callback (comment names the note: a bearer h or a cp1)
 /verify/{payment_hash}      LUD-21 verify (mint invoices AND melt payments)
-/w                          LUD-03 informational GET by k1 (secret or ck1) or p (hash or cp1, older h); a cp1 note carries its cs1 as sig
-/w/cb                       melt / rotate / split / merge; inputs secrets or ck1, outputs p1/p2 hashes or cp1 (or older h/h2); cp1 outputs certified as cs1
+/w                          LUD-03 informational GET by k1 (preimage, ck1 or cw1, verified in full) or p (a bearer h or a cp1, older h); every note carries its cs1 over Q as sig
+/w/cb                       melt / rotate / split / merge; inputs preimages, ck1 or cw1, outputs p1/p2 as a bearer h or cp1 (or older h/h2); every output certified as cs1 over Q; a taken output is `already in use`
 POST /names                 claim a name (NIP-98; the signer owns it); body {name, note?, cx1?}.
                             The owner may resend {name, cx1} to set a branch, or cx1: null to clear it
 /z/cb/{name}                zap invoice for a name. With a cx1 the settled note is credited to the
-                            holder's next key, and the kind 2525 gift wrap carries no secret:
-                            /w?p=<cp1>&sig=<amount-bearing-cs1>&i=<index> plus an `i` tag. The index is
+                            holder's next key on the branch's Lightning Address purpose (2), and the kind 2525 gift wrap carries no secret:
+                            /w?p=<cp1>&c=<amount-bearing-cs1>&i=<index> plus an `i` tag. The index is
                             taken at settlement, never at the invoice, and occupied keys are skipped
-                            Its payRequest metadata publishes text/xpub = cx1:<next-free-index> for
+                            Its payRequest metadata publishes text/cpub = cx1:<next-free-purpose-2-index> for
                             same-mint rotate/split/merge transfers; a raced key returns "already in use"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.16.2",
+  "version": "0.17.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",
@@ -50,6 +50,7 @@
     "dist",
     "web/dist",
     "scripts/live-bound-mint-check.mjs",
+    "scripts/kernel-verifier.py",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
@@ -87,7 +88,7 @@
     "@types/node": "^24.0.0",
     "animejs": "^4.0.0",
     "happy-dom": "^20.0.0",
-    "lnurlcash-conformance": "0.13.1",
+    "lnurlcash-conformance": "0.15.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",

package/scripts/kernel-verifier.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""moneyer's tapscript verifier: Bitcoin Core's own script interpreter,
+through lnurlcash-kernel (pip install lnurlcash-kernel), the same verifier
+the reference mint uses.
+
+moneyer evaluates a bearer note's hashlock leaf itself and hands every other
+script-path spend here. One JSON request per line on stdin, one reply per
+line on stdout, matched by id:
+
+  -> {"id": 1, "q": "<hex Q>", "domain": "mint.example", "cw1": "cw1...",
+      "now": 1790000000, "locked_at": 1789990000}
+  <- {"id": 1, "ok": true}
+  <- {"id": 1, "reason": "bitcoin core rejected the spend"}
+
+`now` and `locked_at` are moneyer's clock, in Unix seconds: the kernel never
+reads one. A reply carrying "error" is a broken install or a bug, never a
+verdict, and moneyer refuses the spend.
+"""
+
+import json
+import sys
+
+import lnurlcashkernel as kernel
+
+
+def answer(request: dict) -> dict:
+    spend = kernel.decode_spend(request["cw1"])
+    if spend is None or spend.key_path:
+        return {"reason": "malformed cw1"}
+    try:
+        kernel.verify_spend(
+            output_key=bytes.fromhex(request["q"]),
+            domain=request["domain"],
+            spend=spend,
+            now=int(request["now"]),
+            locked_at=int(request["locked_at"]),
+        )
+    except kernel.SpendRejected as exc:
+        return {"reason": exc.reason}
+    return {"ok": True}
+
+
+def main() -> None:
+    for line in sys.stdin:
+        try:
+            request = json.loads(line)
+            request_id = request["id"]
+        except (ValueError, KeyError, TypeError):
+            continue
+        try:
+            reply = answer(request)
+        except Exception as exc:  # noqa: BLE001 - reported, never a verdict
+            reply = {"error": type(exc).__name__}
+        sys.stdout.write(json.dumps({"id": request_id, **reply}) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()