@forgesworn/moneyer 0.1.2 → 0.2.0

package/dist/signing.d.ts

@@ -1,4 +1,6 @@
 export declare const noteIdSignatureDigest: (noteId: string, amountMsat: number) => Uint8Array;
+export declare const signDigestRecoverable: (digest: Uint8Array, privateKeyHex: string) => string;
+export declare const recoversToPubkey: (digest: Uint8Array, signatureHex: string, pubkeyHex: string) => boolean;
 export type NoteSigner = {
     pubkey: string;
     sign: (noteId: string, amountMsat: number) => string;

package/dist/signing.js

@@ -12,6 +12,40 @@ import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
 // agree byte for byte; the test suite proves they do by verifying every
 // signature this module makes with the kit's verifyNoteSignature.
 export const noteIdSignatureDigest = (noteId, amountMsat) => sha256(sha256(utf8ToBytes(`Lightning Signed Message:LNURLcash:${amountMsat}:${noteId}`)));
+// A recoverable signature in the LUD-25 wire layout, r || s || recovery_id.
+// noble v2 emits recovery_id || r || s, so the leading byte moves to the
+// back. Anything this mint signs for a third party to check goes through
+// here.
+export const signDigestRecoverable = (digest, privateKeyHex) => {
+    const lead = secp256k1.sign(digest, hexToBytes(privateKeyHex), { format: 'recovered', prehash: false });
+    return bytesToHex(new Uint8Array([...lead.subarray(1), lead[0]]));
+};
+// Does this signature recover to that public key? Both byte orders are
+// tried for the same reason lnurlcash-kit tries both: recovery-id-first is
+// what noble emits, recovery-id-last is what the wire carries.
+export const recoversToPubkey = (digest, signatureHex, pubkeyHex) => {
+    let wireSig;
+    try {
+        wireSig = hexToBytes(signatureHex);
+    }
+    catch {
+        return false;
+    }
+    if (wireSig.length !== 65)
+        return false;
+    const target = pubkeyHex.trim().toLowerCase();
+    const recoveryIdFirst = new Uint8Array([wireSig[64], ...wireSig.subarray(0, 64)]);
+    for (const candidate of [recoveryIdFirst, wireSig]) {
+        try {
+            if (bytesToHex(secp256k1.recoverPublicKey(candidate, digest, { prehash: false })) === target)
+                return true;
+        }
+        catch {
+            // wrong recovery id for this order - try the other
+        }
+    }
+    return false;
+};
 // Signs with the mint's own dedicated key, in process. The reference mint
 // signs via its node's signmessage RPC instead; either is valid, since the
 // only key a wallet ever checks against is the mintPubkey the SERVICE

package/dist/stats.d.ts

@@ -0,0 +1,31 @@
+import type { Liabilities } from './store.ts';
+export declare const STATS_KIND = 30078;
+export declare const STATS_D_TAG = "lnurlcash-liabilities";
+export declare const STATS_MESSAGE_PREFIX = "LNURLcash-stats:";
+export type MintStats = {
+    at: number;
+    outstandingMsat?: number;
+    outstandingNotes?: number;
+    pendingMsat?: number;
+    pendingMelts?: number;
+    oldestPendingMeltAgeSecs?: number;
+    localBalanceMsat?: number;
+    coverage?: number;
+    reconciledAt?: number;
+};
+export declare const buildStats: (args: {
+    liabilities: Liabilities;
+    localBalanceMsat?: number | undefined;
+    reconciledAt?: number | undefined;
+    at?: number;
+    ratioOnly?: boolean;
+}) => MintStats;
+export declare const canonicalJson: (value: Record<string, number | string>) => string;
+export declare const statsDigest: (stats: MintStats) => Uint8Array;
+export declare const signStats: (stats: MintStats, privateKeyHex: string) => string;
+export declare const verifyStatsSignature: (stats: MintStats, signatureHex: string, mintPubkeyHex: string) => boolean;
+export declare const statsSnapshotContent: (stats: MintStats, privateKeyHex: string) => string;
+export declare const verifyStatsSnapshot: (content: string, mintPubkeyHex: string) => {
+    valid: boolean;
+    stats: MintStats | null;
+};

package/dist/stats.js

@@ -0,0 +1,115 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+// What the mint owes, what its node holds, and the ratio between the two.
+//
+// Because LNURLcash notes are not blinded, a mint can state its
+// liabilities exactly: no epochs, no blinded sums, no proof ceremony. The
+// numbers below are the whole of it, and none of them is per-note - a
+// stats endpoint that leaked which notes exist would be worse than no
+// stats endpoint at all.
+export const STATS_KIND = 30078;
+export const STATS_D_TAG = 'lnurlcash-liabilities';
+export const STATS_MESSAGE_PREFIX = 'LNURLcash-stats:';
+export const buildStats = (args) => {
+    const { liabilities, localBalanceMsat } = args;
+    const at = args.at ?? Date.now();
+    // Nothing outstanding means nothing to cover: any ratio would be
+    // infinite, and "infinitely covered" is not a claim worth making.
+    const coverage = localBalanceMsat !== undefined && liabilities.outstandingMsat > 0
+        ? Math.round((localBalanceMsat / liabilities.outstandingMsat) * 10_000) / 10_000
+        : undefined;
+    if (args.ratioOnly === true) {
+        return { at, ...(coverage !== undefined ? { coverage } : {}) };
+    }
+    return {
+        at,
+        ...liabilities,
+        ...(localBalanceMsat !== undefined ? { localBalanceMsat } : {}),
+        ...(coverage !== undefined ? { coverage } : {}),
+        ...(args.reconciledAt !== undefined ? { reconciledAt: args.reconciledAt } : {})
+    };
+};
+// RFC 8785 canonical JSON, for the flat object of numbers this module
+// signs: keys sorted by code unit, no whitespace, and ECMAScript's own
+// number-to-string, which is what the RFC specifies. Anything nested or
+// non-finite is refused rather than serialised a way a verifier might not
+// reproduce.
+export const canonicalJson = (value) => {
+    const parts = Object.keys(value)
+        .sort()
+        .map(key => {
+        const item = value[key];
+        if (typeof item === 'string')
+            return `${JSON.stringify(key)}:${JSON.stringify(item)}`;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return `${JSON.stringify(key)}:${item}`;
+        throw new Error(`Cannot canonicalise ${key}: only finite numbers and strings are signed.`);
+    });
+    return `{${parts.join(',')}}`;
+};
+// The same "Lightning Signed Message" wrapping the notes themselves use,
+// over a different message, so a stats signature can never be replayed as
+// a note signature or the other way round.
+export const statsDigest = (stats) => sha256(sha256(utf8ToBytes(`Lightning Signed Message:${STATS_MESSAGE_PREFIX}${canonicalJson(stats)}`)));
+// Signed with the NOTE signing key, deliberately: a holder already checks
+// their notes against that key, so the liabilities history checks against
+// the same one with nothing new to trust.
+export const signStats = (stats, privateKeyHex) => {
+    const priv = hexToBytes(privateKeyHex);
+    const lead = secp256k1.sign(statsDigest(stats), priv, { format: 'recovered', prehash: false });
+    // r || s || recovery_id, the LUD-25 wire layout.
+    return bytesToHex(new Uint8Array([...lead.subarray(1), lead[0]]));
+};
+export const verifyStatsSignature = (stats, signatureHex, mintPubkeyHex) => {
+    let wireSig;
+    try {
+        wireSig = hexToBytes(signatureHex);
+    }
+    catch {
+        return false;
+    }
+    if (wireSig.length !== 65)
+        return false;
+    let digest;
+    try {
+        digest = statsDigest(stats);
+    }
+    catch {
+        return false;
+    }
+    const target = mintPubkeyHex.trim().toLowerCase();
+    // Both byte orders are tried for the same reason lnurlcash-kit tries
+    // both: recovery-id-first is what noble emits, recovery-id-last is what
+    // the wire carries.
+    const recoveryIdFirst = new Uint8Array([wireSig[64], ...wireSig.subarray(0, 64)]);
+    for (const candidate of [recoveryIdFirst, wireSig]) {
+        try {
+            if (bytesToHex(secp256k1.recoverPublicKey(candidate, digest, { prehash: false })) === target)
+                return true;
+        }
+        catch {
+            // wrong recovery id for this order - try the other
+        }
+    }
+    return false;
+};
+// The published snapshot's content: the stats exactly as signed, plus the
+// signature. A verifier strips `sig` and canonicalises what is left.
+export const statsSnapshotContent = (stats, privateKeyHex) => JSON.stringify({ ...stats, sig: signStats(stats, privateKeyHex) });
+// The reverse: parse a published snapshot and check it against the mint's
+// advertised note-signing pubkey.
+export const verifyStatsSnapshot = (content, mintPubkeyHex) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return { valid: false, stats: null };
+    }
+    const { sig, ...stats } = parsed;
+    if (typeof sig !== 'string')
+        return { valid: false, stats: null };
+    const asStats = stats;
+    return { valid: verifyStatsSignature(asStats, sig, mintPubkeyHex), stats: asStats };
+};

package/dist/store.d.ts

@@ -10,6 +10,7 @@ export type MintInvoiceRow = {
     grossMsat: number;
     netMsat: number;
     settled: boolean;
+    outputId: string | null;
 };
 export type MeltRow = {
     paymentHash: string;
@@ -18,6 +19,58 @@ export type MeltRow = {
     amountMsat: number;
     outcome: 'paid' | 'restored' | null;
 };
+export type ZapInvoiceRow = {
+    paymentHash: string;
+    name: string;
+    recipient: string;
+    pr: string;
+    grossMsat: number;
+    netMsat: number;
+    zapRequest: string | null;
+    settled: boolean;
+    noteId: string | null;
+    wrapJson: string | null;
+    receiptJson: string | null;
+    settledAt: number | null;
+};
+export declare const swapFingerprint: (args: {
+    inputIds: string[];
+    h: string;
+    h2?: string | undefined;
+    amountMsat?: number | undefined;
+}) => string;
+export type Liabilities = {
+    outstandingMsat: number;
+    outstandingNotes: number;
+    pendingMsat: number;
+    pendingMelts: number;
+    oldestPendingMeltAgeSecs: number;
+};
+export type ZapNameRow = {
+    name: string;
+    pubkey: string;
+    createdAt: number;
+    paidMsat: number;
+    source: 'env' | 'self';
+};
+export type NoteListRow = NoteRow & {
+    createdAt: number;
+    updatedAt: number;
+};
+export type MeltListRow = MeltRow & {
+    createdAt: number;
+    resolvedAt: number | null;
+};
+export type StoreTotals = {
+    mints: number;
+    unsettledMintInvoices: number;
+    zaps: number;
+    melts: {
+        paid: number;
+        restored: number;
+        pending: number;
+    };
+};
 export declare class NotePendingError extends Error {
 }
 export declare class NoteUnavailableError extends Error {
@@ -26,28 +79,77 @@ export declare class OutputCollisionError extends Error {
 }
 export declare class NoteStore {
     private db;
-    constructor(path: string);
+    readonly readOnly: boolean;
+    constructor(path: string, options?: {
+        readOnly?: boolean;
+    });
     private tx;
     noteById(id: string): NoteRow | null;
     private insertNote;
     private setNoteState;
+    outputIdInUse(id: string): boolean;
     private assertOutputIdFree;
     private assertOutstanding;
     swap(inputIds: string[], outputs: Array<{
         id: string;
         amountMsat: number;
-    }>): void;
+    }>, fingerprint?: string): void;
+    swapByFingerprint(fingerprint: string): Array<{
+        id: string;
+        amountMsat: number;
+    }> | null;
     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;
+    recordMintInvoice(paymentHash: string, pr: string, grossMsat: number, netMsat: number, outputId?: string | null): void;
     mintInvoiceByHash(paymentHash: string): MintInvoiceRow | null;
+    mintInvoiceByOutputId(outputId: string): MintInvoiceRow | null;
     unsettledMintInvoices(): MintInvoiceRow[];
     deleteUnsettledMintInvoice(paymentHash: string): void;
     settleMintInvoice(paymentHash: string): void;
+    recordZapInvoice(row: {
+        paymentHash: string;
+        name: string;
+        recipient: string;
+        pr: string;
+        grossMsat: number;
+        netMsat: number;
+        zapRequest: string | null;
+    }): void;
+    private zapRow;
+    private static readonly ZAP_COLUMNS;
+    zapInvoiceByHash(paymentHash: string): ZapInvoiceRow | null;
+    unsettledZapInvoices(): ZapInvoiceRow[];
+    deleteUnsettledZapInvoice(paymentHash: string): void;
+    settleZapInvoice(paymentHash: string, noteId: string, wrapJson: string, receiptJson: string | null): boolean;
+    unpublishedZaps(): ZapInvoiceRow[];
+    markZapPublished(paymentHash: string): void;
+    zapName(name: string): ZapNameRow | null;
+    zapNames(): ZapNameRow[];
+    putOperatorZapName(name: string, pubkey: string): void;
+    buyZapName(args: {
+        name: string;
+        pubkey: string;
+        noteId?: string;
+        paidMsat: number;
+    }): void;
+    removeZapName(name: string): boolean;
+    zapNameCountFor(pubkey: string): number;
     creditNote(id: string, amountMsat: number): void;
+    liabilities(nowMs?: number): Liabilities;
+    notes(filter?: {
+        state?: NoteState;
+        limit?: number;
+    }): NoteListRow[];
+    melts(filter?: {
+        pendingOnly?: boolean;
+        limit?: number;
+    }): MeltListRow[];
+    totals(): StoreTotals;
+    snapshot(path: string): void;
     outstandingLiabilityMsat(): number;
+    busyTimeoutMs(): number;
     close(): void;
 }