@forgesworn/moneyer 0.1.2 → 0.2.0

package/THREAT-MODEL.md

@@ -26,11 +26,13 @@ parameters in one request are refused outright; they would otherwise count
 one note's value twice into the output.
 
 **A holder claiming an output id that already exists.** `h`/`h2` 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 a settled mint
-invoice's preimage to its payer, and that preimage is the k1 of whatever
-note carries the hash as its id - minting "over" such an id would point a
-future payer's money at a stranger's note.
+collide with any existing note, any mint invoice's payment hash, settled
+or not, or any note a payer has bought by naming it. The invoice cases are
+the subtle ones: `/verify` hands a settled mint invoice's preimage to its
+payer, and that preimage is the k1 of whatever note carries the hash as
+its id - minting "over" such an id would point a future payer's money at a
+stranger's note. A named note is the same hazard one step earlier, since
+it is spoken for before it exists.
 
 **A holder melting into the mint's own invoice.** Refused synchronously:
 paying it would route the funding source's money at itself, which real
@@ -70,12 +72,19 @@ runs at startup and on demand, resolving pending melts by asking the
 funding source, never by assumption.
 
 **The verify endpoint as an oracle.** `/verify` serves bearer material
-(the preimage). It is only served once the funding source reports
+(the preimage) whenever the note was minted the old way, at the invoice's
+payment hash. It is only served once the funding source reports
 settlement, is fetched live rather than cached, and has a real off switch
 (`MONEYER_VERIFY=0` makes it a 404). Anyone who saw the unpaid invoice can
 poll it, which is why wallets must rotate immediately on claim - stated in
 the spec and enforced by the companion wallet.
 
+The durable answer is for the wallet to name the note it is buying (`h` on
+the pay callback, see the README). The note is then credited at a secret
+only the buyer ever held, the preimage is bearer material for nothing, and
+what `/verify` serves is an ordinary payment proof. Wallets should prefer
+that path wherever a mint advertises `mintToHash`.
+
 ## Out of scope
 
 - Compromise of the host or the funding source credentials: at that point

package/dist/admin.d.ts

@@ -0,0 +1,12 @@
+import { NoteStore } from './store.ts';
+import type { LightningBackend } from './backends/types.ts';
+export type AdminDeps = {
+    env?: NodeJS.ProcessEnv;
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+    store?: NoteStore;
+    backend?: LightningBackend;
+    now?: () => number;
+};
+export declare const adminHelp: () => string;
+export declare const runAdmin: (argv: string[], deps?: AdminDeps) => Promise<number>;

package/dist/admin.js

@@ -0,0 +1,410 @@
+import { existsSync } from 'node:fs';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { hashK1, noteDeclaredAmount, noteK1, noteSignature, verifyNoteSignature } from 'lnurlcash-kit';
+import { configFromEnv, pubkeyHex } from "./config.js";
+import { NoteStore } from "./store.js";
+import { buildStats } from "./stats.js";
+import { reconcilePendingMelts } from "./melt.js";
+import { sweepExpiredMintInvoices } from "./server.js";
+import { createFakeBackend } from "./backends/fake.js";
+import { createClnBackend } from "./backends/cln.js";
+import { createLndBackend } from "./backends/lnd.js";
+import { packageVersion } from "./version.js";
+const COMMANDS = [
+    ['status', 'liabilities, melts in flight, node balance, coverage, keys'],
+    ['notes [--state s] [--limit n]', 'list notes; state is outstanding, pending or burned'],
+    ['note <id|k1>', 'one note, by id or by the secret itself'],
+    ['melts [--pending]', 'list melts, newest first'],
+    ['reconcile', 'resolve melts left in flight, and say what changed'],
+    ['sweep', 'delete mint invoices whose expiry is provably past'],
+    ['snapshot <path>', 'a consistent copy of the database, taken live'],
+    ['names list|add <name> <npub>|rm <name>', 'the lightning addresses this mint pays out as notes'],
+    ['keys rotate', 'generate a signing key and print the two env lines'],
+    ['verify-note <url>', 'check a note offline, then say what the mint holds']
+];
+export const adminHelp = () => [
+    'moneyer admin - operate a running mint',
+    '',
+    'Usage: moneyer admin <command> [options]',
+    '',
+    ...COMMANDS.map(([name, what]) => `  ${name.padEnd(30)} ${what}`),
+    '',
+    'Reads the same MONEYER_* environment as the mint itself, so run it',
+    'with that environment loaded. Read-only unless the command says',
+    'otherwise (reconcile, sweep and snapshot are the only ones that are not).'
+].join('\n');
+const sats = (msat) => `${(msat / 1000).toLocaleString('en-GB')} sat`;
+const age = (fromMs, nowMs) => {
+    const seconds = Math.max(0, Math.floor((nowMs - fromMs) / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m`;
+    if (seconds < 86_400)
+        return `${Math.floor(seconds / 3600)}h`;
+    return `${Math.floor(seconds / 86_400)}d`;
+};
+const backendFor = (config) => {
+    switch (config.backend.kind) {
+        case 'fake':
+            return createFakeBackend();
+        case 'cln':
+            return createClnBackend(config.backend);
+        case 'lnd':
+            return createLndBackend(config.backend);
+    }
+};
+const signingPubkey = (config) => config.signingKey ? bytesToHex(secp256k1.getPublicKey(hexToBytes(config.signingKey), true)) : null;
+// Options are parsed here rather than in the CLI so a test can drive a
+// command with the same argv an operator would type.
+const parse = (argv) => {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const [name, inline] = arg.slice(2).split('=', 2);
+        if (inline !== undefined) {
+            flags.set(name, inline);
+        }
+        else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) {
+            flags.set(name, argv[++i]);
+        }
+        else {
+            flags.set(name, true);
+        }
+    }
+    return { positionals, flags };
+};
+export const runAdmin = async (argv, deps = {}) => {
+    const env = deps.env ?? process.env;
+    const out = deps.out ?? ((line) => console.log(line));
+    const err = deps.err ?? ((line) => console.error(line));
+    const now = deps.now ?? (() => Date.now());
+    const { positionals, flags } = parse(argv);
+    const command = positionals[0];
+    if (command === undefined || command === 'help' || flags.has('help')) {
+        out(adminHelp());
+        return command === undefined ? 2 : 0;
+    }
+    const known = new Set(['status', 'notes', 'note', 'melts', 'reconcile', 'sweep', 'snapshot', 'names', 'keys', 'verify-note']);
+    if (!known.has(command)) {
+        err(`Unknown command ${JSON.stringify(command)}. Try: moneyer admin help`);
+        return 2;
+    }
+    let config;
+    try {
+        config = configFromEnv(env);
+    }
+    catch (error) {
+        err(`Configuration: ${error.message}`);
+        return 1;
+    }
+    // `keys rotate` writes nothing and reads nothing: it generates a key
+    // and prints two lines for the operator to paste. No database needed,
+    // which also means it works before a mint has ever run.
+    if (command === 'keys') {
+        if (positionals[1] !== 'rotate') {
+            err('Usage: moneyer admin keys rotate');
+            return 2;
+        }
+        const fresh = bytesToHex(randomBytes(32));
+        const previous = signingPubkey(config);
+        const history = [...(previous ? [previous] : []), ...(config.previousSigningPubkeys ?? [])];
+        out('# A new signing key. Nothing has been written - paste these into the');
+        out('# mint environment and restart. Keep the OLD PUBLIC key in the list');
+        out('# below or every note already issued stops verifying.');
+        out(`MONEYER_SIGNING_KEY=${fresh}`);
+        if (history.length)
+            out(`MONEYER_PREVIOUS_SIGNING_PUBKEYS=${history.join(',')}`);
+        out('');
+        out(`# the new mint pubkey will be ${bytesToHex(secp256k1.getPublicKey(hexToBytes(fresh), true))}`);
+        if (!previous)
+            out('# this mint has no signing key configured yet, so there is no history to keep');
+        return 0;
+    }
+    const mutates = command === 'reconcile' ||
+        command === 'sweep' ||
+        command === 'snapshot' ||
+        (command === 'names' && positionals[1] !== undefined && positionals[1] !== 'list');
+    let store;
+    const ownsStore = deps.store === undefined;
+    if (deps.store) {
+        store = deps.store;
+    }
+    else {
+        try {
+            store = new NoteStore(config.dbPath, { readOnly: !mutates });
+        }
+        catch (error) {
+            err(`Cannot open ${config.dbPath}: ${error.message}`);
+            return 1;
+        }
+    }
+    // Opened lazily: most commands never touch the funding source, and a
+    // node that is down should not stop `notes` from listing.
+    const held = {};
+    const fundingSource = () => {
+        held.backend ??= deps.backend ?? backendFor(config);
+        return held.backend;
+    };
+    try {
+        switch (command) {
+            case 'status': {
+                const liabilities = store.liabilities(now());
+                const totals = store.totals();
+                let localBalanceMsat;
+                try {
+                    localBalanceMsat = (await fundingSource().nodeInfo?.())?.localBalanceMsat;
+                }
+                catch (error) {
+                    err(`funding source unreachable: ${error.message}`);
+                }
+                const stats = buildStats({ liabilities, localBalanceMsat, at: now() });
+                const previous = config.previousSigningPubkeys ?? [];
+                out(`moneyer ${packageVersion ?? 'unknown version'} at ${config.dbPath}`);
+                out(`  outstanding        ${sats(liabilities.outstandingMsat)} over ${liabilities.outstandingNotes} note${liabilities.outstandingNotes === 1 ? '' : 's'}`);
+                out(`  melts in flight    ${liabilities.pendingMelts}${liabilities.pendingMelts ? ` (${sats(liabilities.pendingMsat)}, oldest ${liabilities.oldestPendingMeltAgeSecs}s)` : ''}`);
+                out(`  unsettled invoices ${totals.unsettledMintInvoices}`);
+                out(`  node balance       ${localBalanceMsat === undefined ? 'not reported' : sats(localBalanceMsat)}`);
+                out(`  coverage           ${stats.coverage === undefined ? (liabilities.outstandingMsat === 0 ? 'nothing outstanding' : 'unknown') : stats.coverage}`);
+                out(`  lifetime           ${totals.mints} mints, ${totals.melts.paid} melts paid, ${totals.melts.restored} restored, ${totals.zaps} zaps`);
+                out(`  signing key        ${signingPubkey(config) ?? 'none - notes go out unsigned'}`);
+                out(`  previous keys      ${previous.length ? previous.join(', ') : 'none'}`);
+                out(`  funding source     ${config.backend.kind}`);
+                return 0;
+            }
+            case 'notes': {
+                const state = flags.get('state');
+                if (state !== undefined && (state === true || !['outstanding', 'pending', 'burned'].includes(state))) {
+                    err('--state must be outstanding, pending or burned.');
+                    return 2;
+                }
+                const limitRaw = flags.get('limit');
+                const limit = limitRaw === undefined || limitRaw === true ? 20 : Number(limitRaw);
+                if (!Number.isSafeInteger(limit) || limit < 1) {
+                    err('--limit must be a positive whole number.');
+                    return 2;
+                }
+                const rows = store.notes({ ...(state ? { state: state } : {}), limit });
+                if (!rows.length) {
+                    out('no notes');
+                    return 0;
+                }
+                for (const row of rows) {
+                    out(`${row.id}  ${sats(row.amountMsat).padStart(14)}  ${row.state.padEnd(11)}  ${age(row.createdAt, now())} old`);
+                }
+                return 0;
+            }
+            case 'note': {
+                const wanted = positionals[1];
+                if (!wanted) {
+                    err('Usage: moneyer admin note <id|k1>');
+                    return 2;
+                }
+                const asked = wanted.toLowerCase();
+                let note = store.noteById(asked);
+                let id = asked;
+                // 64 hex that names no note is very likely the secret itself,
+                // which an operator has in front of them far more often than an
+                // id. Hash it and look again rather than say "unknown".
+                if (!note && /^[0-9a-f]{64}$/.test(asked)) {
+                    id = hashK1(asked);
+                    note = store.noteById(id);
+                    if (note)
+                        out(`(that is a secret; its note id is ${id})`);
+                }
+                if (!note) {
+                    const invoice = store.mintInvoiceByHash(asked);
+                    if (invoice) {
+                        out(`${asked} is a mint invoice for ${sats(invoice.grossMsat)}, netting ${sats(invoice.netMsat)}`);
+                        out(`  ${invoice.settled ? 'settled - the note exists at this id' : 'unsettled - no note yet'}`);
+                        return 0;
+                    }
+                    out(`no note, and no mint invoice, at ${asked}`);
+                    return 1;
+                }
+                out(`${id}`);
+                out(`  value    ${sats(note.amountMsat)}`);
+                out(`  state    ${note.state}`);
+                const melt = store.melts({ limit: 1000 }).find(row => row.noteId === id);
+                if (melt) {
+                    out(`  melt     ${melt.outcome ?? 'in flight'} for ${sats(melt.amountMsat)}, ${age(melt.createdAt, now())} ago`);
+                    out(`  hash     ${melt.paymentHash}`);
+                }
+                return 0;
+            }
+            case 'melts': {
+                const rows = store.melts({ pendingOnly: flags.has('pending'), limit: 50 });
+                if (!rows.length) {
+                    out(flags.has('pending') ? 'no melts in flight' : 'no melts');
+                    return 0;
+                }
+                for (const row of rows) {
+                    out(`${row.paymentHash}  ${sats(row.amountMsat).padStart(14)}  ${(row.outcome ?? 'in flight').padEnd(9)}  ${age(row.createdAt, now())} ago  note ${row.noteId.slice(0, 12)}`);
+                }
+                return 0;
+            }
+            case 'reconcile': {
+                const before = new Map(store.melts({ pendingOnly: true, limit: 1000 }).map(row => [row.paymentHash, row]));
+                if (!before.size) {
+                    out('nothing in flight');
+                    return 0;
+                }
+                await reconcilePendingMelts(store, fundingSource(), new Set());
+                let changed = 0;
+                for (const paymentHash of before.keys()) {
+                    const after = store.meltByHash(paymentHash);
+                    if (after?.outcome) {
+                        changed++;
+                        out(`${paymentHash} ${after.outcome === 'paid' ? 'confirmed paid - note burned' : 'confirmed unpaid - note restored'}`);
+                    }
+                }
+                out(`${changed} of ${before.size} resolved${changed === before.size ? '' : ', the rest still have no terminal answer'}`);
+                return 0;
+            }
+            case 'sweep': {
+                const swept = sweepExpiredMintInvoices(store, now());
+                out(`swept ${swept} expired mint invoice${swept === 1 ? '' : 's'}`);
+                return 0;
+            }
+            case 'snapshot': {
+                const path = positionals[1];
+                if (!path) {
+                    err('Usage: moneyer admin snapshot <path>');
+                    return 2;
+                }
+                if (existsSync(path)) {
+                    err(`${path} already exists - refusing to overwrite a snapshot.`);
+                    return 1;
+                }
+                store.snapshot(path);
+                out(`snapshot written to ${path}`);
+                return 0;
+            }
+            case 'names': {
+                const sub = positionals[1] ?? 'list';
+                if (sub === 'list') {
+                    const names = store.zapNames();
+                    // A name in the environment that the mint has not started with
+                    // yet is not in the table. Showing it as missing would be a lie
+                    // about the configuration, so it is shown as waiting.
+                    const known = new Set(names.map(row => row.name));
+                    const waiting = Object.entries(config.zap?.names ?? {}).filter(([name]) => !known.has(name));
+                    if (!names.length && !waiting.length) {
+                        out('no lightning addresses');
+                        return 0;
+                    }
+                    for (const row of names) {
+                        out(`${row.name.padEnd(20)} ${row.pubkey}  ${row.source}${row.paidMsat ? ` (paid ${sats(row.paidMsat)})` : ''}`);
+                    }
+                    for (const [name, pubkey] of waiting)
+                        out(`${name.padEnd(20)} ${pubkey}  env (waiting for a restart)`);
+                    return 0;
+                }
+                if (sub === 'add') {
+                    const [, , name, key] = positionals;
+                    if (!name || !key) {
+                        err('Usage: moneyer admin names add <name> <npub|hex>');
+                        return 2;
+                    }
+                    let hex;
+                    try {
+                        hex = pubkeyHex(key);
+                    }
+                    catch (error) {
+                        err(error.message);
+                        return 2;
+                    }
+                    // An operator-granted name is recorded the same way an
+                    // environment one is: the operator IS the environment here, and
+                    // a name they grant should not look like one somebody bought.
+                    store.putOperatorZapName(name.toLowerCase(), hex);
+                    out(`${name.toLowerCase()} now pays out to ${hex}`);
+                    return 0;
+                }
+                if (sub === 'rm') {
+                    const name = positionals[2];
+                    if (!name) {
+                        err('Usage: moneyer admin names rm <name>');
+                        return 2;
+                    }
+                    const removed = store.removeZapName(name);
+                    out(removed ? `${name.toLowerCase()} removed` : `no such name: ${name}`);
+                    // A name in MONEYER_ZAP_NAMES comes back at the next restart,
+                    // and an operator deleting one should know that now.
+                    if (removed && config.zap?.names[name.toLowerCase()]) {
+                        out('(it is still in MONEYER_ZAP_NAMES and will return on the next restart)');
+                    }
+                    return removed ? 0 : 1;
+                }
+                err('Usage: moneyer admin names list|add <name> <npub>|rm <name>');
+                return 2;
+            }
+            case 'verify-note': {
+                const url = positionals[1];
+                if (!url) {
+                    err('Usage: moneyer admin verify-note <url>');
+                    return 2;
+                }
+                let k1;
+                try {
+                    k1 = noteK1(url) ?? '';
+                }
+                catch {
+                    k1 = '';
+                }
+                if (!k1) {
+                    err('That is not a note URL - no k1 in it.');
+                    return 2;
+                }
+                const id = hashK1(k1);
+                const declared = noteDeclaredAmount(url);
+                const signature = noteSignature(url);
+                const current = signingPubkey(config);
+                const keys = [...(current ? [current] : []), ...(config.previousSigningPubkeys ?? [])];
+                out(`note id  ${id}`);
+                if (declared !== null)
+                    out(`declared ${sats(declared)}`);
+                if (!signature) {
+                    out('signature none on the URL');
+                }
+                else if (declared === null) {
+                    out('signature present, but the URL declares no amount to check it against');
+                }
+                else {
+                    const signedBy = keys.find(pubkey => verifyNoteSignature(k1, declared, signature, pubkey));
+                    out(signedBy === undefined
+                        ? 'signature DOES NOT verify against this mint'
+                        : `signature verifies against ${signedBy === current ? 'the current key' : `a previous key (${signedBy})`}`);
+                }
+                const note = store.noteById(id);
+                out(`mint     ${note ? `holds ${sats(note.amountMsat)}, state ${note.state}` : 'has no note at this id'}`);
+                // A note the mint does not know, or one already burned, is the
+                // answer the operator came for; say it in the exit code too.
+                return note && note.state !== 'burned' ? 0 : 1;
+            }
+            default:
+                return 2;
+        }
+    }
+    catch (error) {
+        const message = error.message;
+        // A database with no tables is a path that has never held a mint -
+        // far more likely a typo than a corrupt file, and worth saying so.
+        err(/no such table/.test(message)
+            ? `${config.dbPath} does not look like a moneyer database - has the mint ever run against it?`
+            : message);
+        return 1;
+    }
+    finally {
+        if (ownsStore)
+            store.close();
+        if (deps.backend === undefined && held.backend)
+            await held.backend.close?.();
+    }
+};

package/dist/announce.d.ts

@@ -0,0 +1,12 @@
+export declare const ANNOUNCE_KIND = 30078;
+export declare const ANNOUNCE_D_TAG = "lnurlcash-mint";
+export declare const ANNOUNCE_MESSAGE_PREFIX = "LNURLcash-mint:";
+export type MintAddressDocument = Record<string, unknown>;
+export declare const canonicalise: (value: unknown) => string;
+export declare const announcementDigest: (document: MintAddressDocument) => Uint8Array;
+export declare const signAnnouncement: (document: MintAddressDocument, privateKeyHex: string) => string;
+export declare const announcementContent: (document: MintAddressDocument, privateKeyHex?: string | undefined) => string;
+export declare const verifyAnnouncement: (content: string, mintPubkeyHex: string) => {
+    valid: boolean;
+    document: MintAddressDocument | null;
+};

package/dist/announce.js

@@ -0,0 +1,82 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+import { recoversToPubkey, signDigestRecoverable } from "./signing.js";
+// The mint announcing itself.
+//
+// A wallet only ever learns of a mint by being told its address; there is
+// no way to find one. Cashu has NIP-87 for this, and its kinds are not
+// ours to take. A new kind of our own is a protocol decision that belongs
+// with the NIPs, so this uses what already exists: the same NIP-78
+// replaceable kind the hourly liabilities snapshot goes out under, with a
+// `d` tag of its own.
+//
+// The content is the mint's own discovery document, unchanged, so there is
+// one description of a mint and not two. It carries a signature by the
+// NOTE signing key as well, which is the key a holder already checks their
+// notes against: an announcement that verifies against `mintPubkey` is the
+// mint speaking, whoever the Nostr identity publishing it belongs to.
+export const ANNOUNCE_KIND = 30078;
+export const ANNOUNCE_D_TAG = 'lnurlcash-mint';
+export const ANNOUNCE_MESSAGE_PREFIX = 'LNURLcash-mint:';
+// RFC 8785 canonical JSON, over the shapes a mint address document holds:
+// strings, finite numbers, booleans, arrays, and nested objects. Keys sort
+// by UTF-16 code unit, which is what JavaScript's own string comparison
+// does, and numbers serialise the ECMAScript way, which is what the RFC
+// specifies. `undefined` members are dropped exactly as JSON.stringify
+// drops them, so what is signed matches what goes on the wire.
+export const canonicalise = (value) => {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('Only a finite number can be signed.');
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalise).join(',')}]`;
+    if (typeof value === 'object') {
+        const members = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalise(item)}`);
+        return `{${members.join(',')}}`;
+    }
+    throw new Error(`A ${typeof value} cannot be signed.`);
+};
+// The same "Lightning Signed Message" wrapping the notes use, over a
+// prefix of its own, so an announcement signature can never be replayed as
+// a note signature or as a liabilities signature.
+export const announcementDigest = (document) => sha256(sha256(utf8ToBytes(`Lightning Signed Message:${ANNOUNCE_MESSAGE_PREFIX}${canonicalise(document)}`)));
+export const signAnnouncement = (document, privateKeyHex) => signDigestRecoverable(announcementDigest(document), privateKeyHex);
+// What goes in the event: the document as the endpoint serves it, plus
+// `sig`. A mint with no note signing key has no `mintPubkey` to verify
+// against either, so it announces the document alone.
+export const announcementContent = (document, privateKeyHex) => JSON.stringify(privateKeyHex ? { ...document, sig: signAnnouncement(document, privateKeyHex) } : document);
+// The reverse: read an announcement and check it against the note-signing
+// key it claims. `mintPubkey` inside the document is what a wallet holding
+// a note of this mint already knows, so an announcement that recovers to
+// it needs nothing else trusted.
+export const verifyAnnouncement = (content, mintPubkeyHex) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return { valid: false, document: null };
+    }
+    const { sig, ...document } = parsed;
+    if (typeof sig !== 'string')
+        return { valid: false, document: null };
+    let digest;
+    try {
+        digest = announcementDigest(document);
+    }
+    catch {
+        return { valid: false, document: null };
+    }
+    return { valid: recoversToPubkey(digest, sig, mintPubkeyHex), document };
+};

package/dist/backends/cln.js

@@ -36,24 +36,33 @@ export const createClnBackend = (config) => {
     };
     return {
         name: 'cln',
-        async createInvoice({ amountMsat, preimageHex, memo }) {
+        async createInvoice({ amountMsat, preimageHex, memo, descriptionForHash }) {
             const result = await mustCall('/v1/invoice', {
                 amount_msat: amountMsat,
                 label: bytesToHex(randomBytes(16)),
-                description: memo,
+                description: descriptionForHash ?? memo,
+                // Commit to the hash of the description rather than carry it: the
+                // zap request is far over bolt11's description limit.
+                ...(descriptionForHash === undefined ? {} : { deschashonly: true }),
                 preimage: preimageHex
             });
             if (typeof result?.bolt11 !== 'string')
                 throw new Error('cln did not return a bolt11 invoice.');
             return { pr: result.bolt11 };
         },
-        async payInvoice({ pr, feeLimitMsat }) {
+        async payInvoice({ pr, feeLimitMsat, amountMsat }) {
             // xpay resolves once it stops retrying, which is NOT proof that no
             // HTLC it already sent remains outstanding - the caller confirms via
             // isPaymentComplete before restoring anything either way. The
             // timeout sits above xpay's own default 60s retry_for so a clean
             // failure response is not turned into an ambiguous one at the wire.
-            const res = await call('/v1/xpay', { invstring: pr, maxfee: feeLimitMsat }, 90_000);
+            const res = await call('/v1/xpay', {
+                invstring: pr,
+                maxfee: feeLimitMsat,
+                // xpay wants amount_msat only for an invoice that states no
+                // amount, and refuses it for one that does.
+                ...(amountMsat !== undefined ? { amount_msat: amountMsat } : {})
+            }, 90_000);
             if (!res.ok) {
                 const code = res.json?.code;
                 // 219: this node already paid that hash. On a shared node that is
@@ -70,10 +79,10 @@ export const createClnBackend = (config) => {
             const preimageHex = res.json?.payment_preimage;
             if (typeof preimageHex !== 'string')
                 throw new Error('cln did not return a payment_preimage.');
-            const amountMsat = res.json?.amount_msat;
+            const deliveredMsat = res.json?.amount_msat;
             const amountSentMsat = res.json?.amount_sent_msat;
-            const feeMsat = typeof amountMsat === 'number' && typeof amountSentMsat === 'number'
-                ? amountSentMsat - amountMsat
+            const feeMsat = typeof deliveredMsat === 'number' && typeof amountSentMsat === 'number'
+                ? amountSentMsat - deliveredMsat
                 : null;
             return { preimageHex, feeMsat };
         },
@@ -118,12 +127,25 @@ export const createClnBackend = (config) => {
             const color = typeof info?.color === 'string' ? `#${info.color.replace(/^#/, '')}` : undefined;
             const numChannels = Number(info?.num_active_channels);
             const numPeers = Number(info?.num_peers);
+            // Outbound liquidity over channels that can actually route today.
+            // A channel still opening or already closing holds funds this mint
+            // cannot pay out with, so it is not counted.
+            let localBalanceMsat;
+            const funds = await call('/v1/listfunds', {});
+            if (funds.ok && Array.isArray(funds.json?.channels)) {
+                const total = funds.json.channels
+                    .filter((channel) => channel?.state === 'CHANNELD_NORMAL')
+                    .reduce((sum, channel) => sum + Number(channel.our_amount_msat ?? 0), 0);
+                if (Number.isSafeInteger(total))
+                    localBalanceMsat = total;
+            }
             return {
                 ...(info?.alias ? { alias: info.alias } : {}),
                 ...(uri ? { uri } : {}),
                 ...(color && /^#[0-9a-fA-F]{6}$/.test(color) ? { color } : {}),
                 ...(Number.isSafeInteger(numChannels) ? { numChannels } : {}),
-                ...(Number.isSafeInteger(numPeers) ? { numPeers } : {})
+                ...(Number.isSafeInteger(numPeers) ? { numPeers } : {}),
+                ...(localBalanceMsat !== undefined ? { localBalanceMsat } : {})
             };
         }
     };

package/dist/backends/fake-bolt11.d.ts

@@ -1,5 +1,5 @@
 export declare const fakeBolt11: (args: {
-    amountMsat: number;
+    amountMsat?: number;
     paymentHashHex: string;
     memo?: string;
     timestamp?: number;

package/dist/backends/fake-bolt11.js

@@ -37,8 +37,10 @@ const tagged = (type, data) => [
     ...data
 ];
 const amountHrp = (msat) => (msat % 100 === 0 ? `${msat / 100}n` : `${msat * 10}p`);
+// `amountMsat` omitted builds an invoice that states no amount, which is
+// the shape a payee uses when the payer decides what to send.
 export const fakeBolt11 = (args) => {
-    const hrp = `lnbc${amountHrp(args.amountMsat)}`;
+    const hrp = `lnbc${args.amountMsat === undefined ? '' : amountHrp(args.amountMsat)}`;
     const words = [];
     const timestamp = args.timestamp ?? Math.floor(Date.now() / 1000);
     for (let i = 6; i >= 0; i--)