@forgesworn/moneyer 0.1.0-next.0

package/dist/store.d.ts

@@ -0,0 +1,53 @@
+export type NoteState = 'outstanding' | 'pending' | 'burned';
+export type NoteRow = {
+    id: string;
+    amountMsat: number;
+    state: NoteState;
+};
+export type MintInvoiceRow = {
+    paymentHash: string;
+    pr: string;
+    grossMsat: number;
+    netMsat: number;
+    settled: boolean;
+};
+export type MeltRow = {
+    paymentHash: string;
+    noteId: string;
+    pr: string;
+    amountMsat: number;
+    outcome: 'paid' | 'restored' | null;
+};
+export declare class NotePendingError extends Error {
+}
+export declare class NoteUnavailableError extends Error {
+}
+export declare class OutputCollisionError extends Error {
+}
+export declare class NoteStore {
+    private db;
+    constructor(path: string);
+    private tx;
+    noteById(id: string): NoteRow | null;
+    private insertNote;
+    private setNoteState;
+    private assertOutputIdFree;
+    private assertOutstanding;
+    swap(inputIds: string[], outputs: Array<{
+        id: string;
+        amountMsat: number;
+    }>): void;
+    markPending(noteId: string, paymentHash: string, pr: string, amountMsat: number): void;
+    finalizeMelt(paymentHash: string): void;
+    restoreMelt(paymentHash: string): void;
+    meltByHash(paymentHash: string): MeltRow | null;
+    pendingMelts(): MeltRow[];
+    recordMintInvoice(paymentHash: string, pr: string, grossMsat: number, netMsat: number): void;
+    mintInvoiceByHash(paymentHash: string): MintInvoiceRow | null;
+    unsettledMintInvoices(): MintInvoiceRow[];
+    deleteUnsettledMintInvoice(paymentHash: string): void;
+    settleMintInvoice(paymentHash: string): void;
+    creditNote(id: string, amountMsat: number): void;
+    outstandingLiabilityMsat(): number;
+    close(): void;
+}

package/dist/store.js

@@ -0,0 +1,245 @@
+import { DatabaseSync } from 'node:sqlite';
+// A note named by the request is reserved by an in-flight melt. The wire
+// reply for this is the exact reason string "pending".
+export class NotePendingError extends Error {
+}
+// A note named by the request is burned or was never minted. The callback
+// cannot say which without leaking, so the wire reply is the atomic
+// "Invalid or already spent k1."
+export class NoteUnavailableError extends Error {
+}
+// A requested output id already names a note or a mint invoice. Refused
+// before anything burns: minting "over" an existing id would let whoever
+// can learn that id's preimage take the output.
+export class OutputCollisionError extends Error {
+}
+export class NoteStore {
+    db;
+    constructor(path) {
+        this.db = new DatabaseSync(path);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.db.exec('PRAGMA foreign_keys = ON');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS notes (
+        id TEXT PRIMARY KEY,
+        amount_msat INTEGER NOT NULL,
+        state TEXT NOT NULL CHECK (state IN ('outstanding','pending','burned')),
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS mint_invoices (
+        payment_hash TEXT PRIMARY KEY,
+        pr TEXT NOT NULL,
+        gross_msat INTEGER NOT NULL,
+        net_msat INTEGER NOT NULL,
+        settled INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS melts (
+        payment_hash TEXT PRIMARY KEY,
+        note_id TEXT NOT NULL,
+        pr TEXT NOT NULL,
+        amount_msat INTEGER NOT NULL,
+        outcome TEXT CHECK (outcome IN ('paid','restored')),
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER
+      );
+    `);
+    }
+    tx(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    noteById(id) {
+        const row = this.db
+            .prepare('SELECT id, amount_msat, state FROM notes WHERE id = ?')
+            .get(id);
+        return row ? { id: row.id, amountMsat: row.amount_msat, state: row.state } : null;
+    }
+    insertNote(id, amountMsat) {
+        const now = Date.now();
+        this.db
+            .prepare('INSERT INTO notes (id, amount_msat, state, created_at, updated_at) VALUES (?, ?, ?, ?, ?)')
+            .run(id, amountMsat, 'outstanding', now, now);
+    }
+    setNoteState(id, state) {
+        this.db.prepare('UPDATE notes SET state = ?, updated_at = ? WHERE id = ?').run(state, Date.now(), id);
+    }
+    // An output id may not collide with any existing note OR any mint
+    // invoice's payment hash, settled or not. The invoice case is the subtle
+    // one: /verify hands out a settled mint invoice's preimage, and that
+    // preimage is the k1 of whatever note carries the invoice's payment hash
+    // as its id - so letting a mutation claim such an id would point a future
+    // payer's money at a stranger's note.
+    assertOutputIdFree(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);
+        if (asNote || asInvoice)
+            throw new OutputCollisionError(`output id ${id} is already in use`);
+    }
+    assertOutstanding(id) {
+        const note = this.noteById(id);
+        if (!note)
+            throw new NoteUnavailableError(`no note ${id}`);
+        if (note.state === 'pending')
+            throw new NotePendingError(`note ${id} has a melt in flight`);
+        if (note.state !== 'outstanding')
+            throw new NoteUnavailableError(`note ${id} is ${note.state}`);
+        return note;
+    }
+    // The atomic mutation behind rotate, split and merge: burn every input,
+    // mint every output, or do nothing at all.
+    swap(inputIds, outputs) {
+        this.tx(() => {
+            for (const id of inputIds)
+                this.assertOutstanding(id);
+            for (const output of outputs)
+                this.assertOutputIdFree(output.id);
+            for (const id of inputIds)
+                this.setNoteState(id, 'burned');
+            for (const output of outputs)
+                this.insertNote(output.id, output.amountMsat);
+        });
+    }
+    // Reserves a note for a melt and records the melt, atomically. The melts
+    // row is keyed by the invoice's payment hash; a duplicate hash means an
+    // earlier melt already used this invoice and the INSERT itself refuses.
+    markPending(noteId, paymentHash, pr, amountMsat) {
+        this.tx(() => {
+            this.assertOutstanding(noteId);
+            this.db
+                .prepare('INSERT INTO melts (payment_hash, note_id, pr, amount_msat, outcome, created_at) VALUES (?, ?, ?, ?, NULL, ?)')
+                .run(paymentHash, noteId, pr, amountMsat, Date.now());
+            this.setNoteState(noteId, 'pending');
+        });
+    }
+    finalizeMelt(paymentHash) {
+        this.tx(() => {
+            const melt = this.meltByHash(paymentHash);
+            if (!melt || melt.outcome !== null)
+                return;
+            this.db
+                .prepare('UPDATE melts SET outcome = ?, resolved_at = ? WHERE payment_hash = ?')
+                .run('paid', Date.now(), paymentHash);
+            this.setNoteState(melt.noteId, 'burned');
+        });
+    }
+    restoreMelt(paymentHash) {
+        this.tx(() => {
+            const melt = this.meltByHash(paymentHash);
+            if (!melt || melt.outcome !== null)
+                return;
+            this.db
+                .prepare('UPDATE melts SET outcome = ?, resolved_at = ? WHERE payment_hash = ?')
+                .run('restored', Date.now(), paymentHash);
+            const note = this.noteById(melt.noteId);
+            if (note?.state === 'pending')
+                this.setNoteState(melt.noteId, 'outstanding');
+        });
+    }
+    meltByHash(paymentHash) {
+        const row = this.db
+            .prepare('SELECT payment_hash, note_id, pr, amount_msat, outcome FROM melts WHERE payment_hash = ?')
+            .get(paymentHash);
+        if (!row)
+            return null;
+        return {
+            paymentHash: row.payment_hash,
+            noteId: row.note_id,
+            pr: row.pr,
+            amountMsat: row.amount_msat,
+            outcome: row.outcome
+        };
+    }
+    pendingMelts() {
+        const rows = this.db
+            .prepare('SELECT payment_hash, note_id, pr, amount_msat, outcome FROM melts WHERE outcome IS NULL')
+            .all();
+        return rows.map(row => ({
+            paymentHash: row.payment_hash,
+            noteId: row.note_id,
+            pr: row.pr,
+            amountMsat: row.amount_msat,
+            outcome: row.outcome
+        }));
+    }
+    recordMintInvoice(paymentHash, pr, grossMsat, netMsat) {
+        this.tx(() => {
+            this.assertOutputIdFree(paymentHash);
+            this.db
+                .prepare('INSERT INTO mint_invoices (payment_hash, pr, gross_msat, net_msat, settled, created_at) VALUES (?, ?, ?, ?, 0, ?)')
+                .run(paymentHash, pr, grossMsat, netMsat, Date.now());
+        });
+    }
+    mintInvoiceByHash(paymentHash) {
+        const row = this.db
+            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled FROM mint_invoices WHERE payment_hash = ?')
+            .get(paymentHash);
+        if (!row)
+            return null;
+        return {
+            paymentHash: row.payment_hash,
+            pr: row.pr,
+            grossMsat: row.gross_msat,
+            netMsat: row.net_msat,
+            settled: row.settled === 1
+        };
+    }
+    // Every unsettled mint invoice, for the expiry sweep. An unsettled row
+    // past its bolt11 expiry can never settle - the funding source refuses
+    // 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 FROM mint_invoices WHERE settled = 0')
+            .all();
+        return rows.map(row => ({
+            paymentHash: row.payment_hash,
+            pr: row.pr,
+            grossMsat: row.gross_msat,
+            netMsat: row.net_msat,
+            settled: false
+        }));
+    }
+    // Conditional on STILL unsettled: a settle landing between the sweep's
+    // check and this delete must win, always.
+    deleteUnsettledMintInvoice(paymentHash) {
+        this.db.prepare('DELETE FROM mint_invoices WHERE payment_hash = ? AND settled = 0').run(paymentHash);
+    }
+    // Paying a mint invoice is what brings its note into existence. Safe to
+    // call twice: the second settle finds the note already minted.
+    settleMintInvoice(paymentHash) {
+        this.tx(() => {
+            const invoice = this.mintInvoiceByHash(paymentHash);
+            if (!invoice)
+                return;
+            this.db.prepare('UPDATE mint_invoices SET settled = 1 WHERE payment_hash = ?').run(paymentHash);
+            if (!this.noteById(paymentHash))
+                this.insertNote(paymentHash, invoice.netMsat);
+        });
+    }
+    // Operator/dev funding path: mint a note directly, bypassing Lightning.
+    // The fake backend's world only - the CLI never exposes it on a real one.
+    creditNote(id, amountMsat) {
+        this.tx(() => {
+            this.assertOutputIdFree(id);
+            this.insertNote(id, amountMsat);
+        });
+    }
+    outstandingLiabilityMsat() {
+        const row = this.db
+            .prepare("SELECT COALESCE(SUM(amount_msat), 0) AS total FROM notes WHERE state IN ('outstanding','pending')")
+            .get();
+        return row.total;
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/web-assets.d.ts

@@ -0,0 +1,12 @@
+export type WebAsset = {
+    body: Buffer;
+    type: string;
+    immutable: boolean;
+};
+export type WebAssets = {
+    indexHtml: string;
+    get(path: string): WebAsset | undefined;
+};
+export declare const CONFIG_TOKEN = "<!--#mint-config-->";
+export declare const defaultWebDist: () => string;
+export declare const loadWebAssets: (dir?: string) => WebAssets | null;

package/dist/web-assets.js

@@ -0,0 +1,51 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const CONFIG_TOKEN = '<!--#mint-config-->';
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.json': 'application/json',
+    '.webmanifest': 'application/manifest+json',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8'
+};
+export const defaultWebDist = () => fileURLToPath(new URL('../web/dist', import.meta.url));
+export const loadWebAssets = (dir = defaultWebDist()) => {
+    const files = new Map();
+    let indexHtml = null;
+    const walk = (current, prefix) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = `${prefix}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(join(current, entry.name), path);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const body = readFileSync(join(current, entry.name));
+            const type = TYPES[extname(entry.name).toLowerCase()] ?? 'application/octet-stream';
+            // vite content-hashes everything under /assets/, so those never change
+            // in place; everything else revalidates.
+            files.set(path, { body, type, immutable: path.startsWith('/assets/') });
+            if (path === '/index.html')
+                indexHtml = body.toString('utf8');
+        }
+    };
+    try {
+        walk(dir, '');
+    }
+    catch {
+        return null;
+    }
+    if (indexHtml === null)
+        return null;
+    return { indexHtml, get: path => files.get(path) };
+};

package/llms.txt

@@ -0,0 +1,64 @@
+# 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.
+
+Install: not yet on npm - build from source (see README)
+Run: node dist/cli.js --dev   (fake funding source, prints a funded note)
+
+Draft spec: https://github.com/lnurl/luds/pull/301
+Conformance: https://github.com/TheCryptoDonkey/lnurlcash-conformance
+Companion wallet: @forgesworn/notecase
+Client library to build against a mint: lnurlcash-kit
+
+## Rules this SERVICE follows (and any mint MUST)
+
+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).
+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.
+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.
+   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
+   distinct restorable outcome - never confirm a melt against a payment
+   this mint did not initiate.
+6. Fee algebra (LUD-25, when a fee is advertised): base_fee_msat comes
+   out of every split's CHANGE, never the requested amount; a merge of n
+   notes refunds (n-1) base fees; a change that cannot cover the fee or
+   would land at zero refuses with 'insufficient value'. The proportional
+   part applies at mint time only.
+7. Reason strings are protocol surface: 'pending',
+   'Invalid or already spent k1.', 'Unknown note.', 'Note already spent.',
+   'missing h', 'missing h2', 'insufficient value' - wallets classify on
+   them.
+8. minSendable must survive the mint's own fee (grossUpForMintFee of the
+   dust floor), or the mint advertises an amount it will refuse.
+
+## Library API
+
+createMoneyer(config, deps?) -> {url, port, store, backend, signer, reconcile, close}
+configFromEnv(env?) -> MoneyerConfig     MONEYER_* environment variables
+createFakeBackend() -> LightningBackend with .control test hooks
+createClnBackend({url, rune}) / createLndBackend({url, macaroon})
+createNoteSigner(privHex) -> {pubkey, sign(noteId, amountMsat)}
+fakeBolt11({amountMsat, paymentHashHex, memo?}) -> decodable, unpayable invoice
+NoteStore - SQLite store; notes by sha256(k1), never secrets
+
+## Endpoints
+
+/.well-known/lnurlp/{user}  LUD-16 payRequest (mints)
+/.well-known/lnurlw/{user}  LUD-25 mint address (experimental)
+/p/cb                       LUD-06 pay callback
+/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

@@ -0,0 +1,76 @@
+{
+  "name": "@forgesworn/moneyer",
+  "version": "0.1.0-next.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgesworn/moneyer.git"
+  },
+  "homepage": "https://github.com/forgesworn/moneyer#readme",
+  "bugs": {
+    "url": "https://github.com/forgesworn/moneyer/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "moneyer": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "web/dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "THREAT-MODEL.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "node --experimental-strip-types src/cli.ts --dev",
+    "conform": "node test/run-grader.mjs",
+    "check": "npm run typecheck && npm run typecheck:web && npm test && npm run build && npm run web:build && npm pack --dry-run",
+    "web:dev": "vite web",
+    "web:build": "vite build web",
+    "web:preview": "vite preview web",
+    "typecheck:web": "tsc -p web"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@scure/base": "^1.2.4",
+    "farrier-kit": "^1.1.3",
+    "lnurlcash-kit": "^0.1.0"
+  },
+  "devDependencies": {
+    "@fontsource/cinzel": "^5.3.0",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "@fontsource/spectral": "^5.3.0",
+    "@types/node": "^24.0.0",
+    "animejs": "^4.0.0",
+    "happy-dom": "^20.0.0",
+    "lnurlcash-conformance": "^0.1.0",
+    "playwright": "^1.62.1",
+    "typescript": "^5.7.0",
+    "uqr": "^0.1.2",
+    "vite": "^7.0.0",
+    "vitest": "^3.0.0"
+  }
+}