@forgesworn/moneyer 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [0.7.0] - 2026-08-26
+
+- **The published node capacity is the announced one.** `nodeCapacity` in
+  the discovery document was summed from lnd's `/v1/channels`, which is an
+  authenticated view of the node and counts private channels. That figure is
+  served to every visitor and goes out in the mint's announcement, so a
+  channel the operator chose not to announce was being sized in public
+  anyway. It now comes from this node's own entry in the public graph -
+  `total_capacity`, the same number any stranger on the network already
+  reads, converted from sats. A node with nothing announced reports zero
+  rather than omitting the field, because zero is the true answer there;
+  only a node that cannot be asked leaves it off. cln never reported
+  capacity and is unaffected.
+
+  Operators should expect the number to fall, and to fall to zero on a mint
+  running entirely on private channels. It was never the figure it claimed
+  to be.
+
+- The web wallet prints a note to a PNG you can send. The plate existed only
+  as HTML over the artwork, which is no use in a message; the same portrait
+  plate composites onto a canvas and comes back as a file - the share sheet
+  where the browser offers one, a download everywhere else. The travelling
+  plate carries the bech32 LNURL rather than the claim link, because a note
+  that leaves in a message is scanned by whatever the recipient already has,
+  and that is usually a Lightning wallet.
+
+- The bundled web wallet names its note on the plain path too, not only when
+  a signed receipt is on offer. It previously fell back to an unnamed mint
+  and then required `verify` to read the preimage - which, with the rule
+  above, a signer-less mint no longer answers. Naming needs no receipt, and
+  the page then claims the secret it chose rather than one the mint
+  publishes.
+
+- **No LUD-21 `verify` on a mint payment that named no output.** LUD-25
+  forbids it, and the reason is concrete: on that path the note's `k1` IS the
+  payment preimage, and `verify` publishes the preimage at a URL anyone who
+  has seen the invoice can build from its payment hash. The note was only as
+  private as the QR it was paid from.
+
+  Both halves are needed. New unnamed invoices get no `verify` field, and
+  `/verify/<hash>` refuses them outright - not advertising a URL does not
+  stop anyone constructing it. A payer on this path still learns the preimage
+  the way any Lightning wallet does, by paying.
+
+  **Invoices quoted before this mint adopted the rule keep their `verify`.**
+  A wallet polling one of those did not pay the invoice itself - that is why
+  it is polling - so the preimage this mint holds is its only route to a note
+  it already owns. Refusing them would not close a hole, it would burn
+  somebody's money. The cutover is written to a new `meta` table the first
+  time a build carrying this code opens the database, and never moves after;
+  persisted rather than taken from process start, or a restart would walk the
+  line forward and strand a quote made minutes earlier under the same build.
+  Old rows drain and the hole closes for everything new.
+
+- The mint accepts a LUD-12 `comment` carrying `hex(h)` as the name of the
+  note being bought, and advertises `commentAllowed: 64` on the payRequest.
+  This is how LUD-25 specifies it; `h` was this mint's own earlier spelling
+  and both are now honoured, so wallets on either keep working. A wallet
+  sending both must agree with itself - minting under one when the other is
+  being watched for would lose the note.
+
+  The two are deliberately not validated alike. Per LUD-25, a `comment` that
+  is not a bare 32-byte hex hash falls back to keying the note by the payment
+  preimage, exactly as no comment does, because a comment is free text in
+  LUD-12 and failing on every stray one would break ordinary payers. A
+  malformed `h` still fails loudly: that is a wallet that meant to name an
+  output and got it wrong.
+
+  This matters beyond conformance. A note minted with no named output has the
+  payment preimage as its spend secret, and until this release the mint
+  served that preimage on its LUD-21 `verify` URL, which anyone holding the
+  invoice can construct. Naming the output is what makes `verify` safe to
+  offer, and the entry above now gates it on exactly that.
+
 ## [0.6.1] - 2026-08-24
 
 - The bundled web wallet now accepts a bound mint quote anywhere inside

package/dist/backends/lnd.js

@@ -183,12 +183,27 @@ export const createLndBackend = (config) => {
             const color = typeof res.json?.color === 'string' ? `#${res.json.color.replace(/^#/, '')}` : undefined;
             const numChannels = Number(res.json?.num_active_channels);
             const numPeers = Number(res.json?.num_peers);
-            // Total public capacity, best-effort: the macaroon may not carry
-            // offchain:read, and the discovery endpoint works fine without it.
+            // Announced capacity, read from this node's own entry in the public
+            // graph rather than from its channel list. `/v1/channels` is an
+            // authenticated view and counts private channels too; this figure is
+            // published in the discovery document, so summing that would tell the
+            // world what only the operator can see. The graph self-lookup returns
+            // the same `total_capacity` any stranger on the network already
+            // reads, in sats, so it is converted here to keep NodeInfo msat.
+            //
+            // Best-effort, in two flavours: a 404 is a node with nothing
+            // announced, which is a public capacity of zero rather than an
+            // unknown one, while any other failure leaves the field off - the
+            // macaroon may not carry info:read, and the discovery endpoint works
+            // fine without it.
             let capacityMsat;
-            const channels = await json('/v1/channels');
-            if (channels.ok && Array.isArray(channels.json?.channels)) {
-                capacityMsat = channels.json.channels.reduce((sum, channel) => sum + Number(channel.capacity ?? 0) * 1000, 0);
+            const pubkey = res.json?.identity_pubkey;
+            if (typeof pubkey === 'string' && pubkey) {
+                const node = await json(`/v1/graph/node/${pubkey}`);
+                if (node.ok)
+                    capacityMsat = Number(node.json?.total_capacity ?? 0) * 1000;
+                else if (node.status === 404)
+                    capacityMsat = 0;
             }
             // Outbound liquidity, best-effort for the same reason as capacity:
             // the macaroon may not carry offchain:read.

package/dist/server.js

@@ -551,6 +551,12 @@ export const createMoneyer = async (config, deps = {}) => {
                 // lightning address never reads that document, and this has to be
                 // known BEFORE paying, not after.
                 mintToHash: true,
+                // The same capability in the spelling LUD-25 specifies: the output
+                // hash rides in a LUD-12 comment, so 64 characters is exactly what
+                // a hex-encoded 32-byte hash needs. Advertised alongside
+                // `mintToHash` rather than instead of it, so wallets on either
+                // spelling can name a note.
+                commentAllowed: 64,
                 disposable: false
             });
         }
@@ -596,13 +602,33 @@ export const createMoneyer = async (config, deps = {}) => {
             // collision gets the same reason a colliding output gets on the
             // withdraw callback: which table an id already sits in is an oracle
             // nobody is owed.
-            const askedOutputId = q.get('h');
-            const outputId = askedOutputId === null ? null : askedOutputId.toLowerCase();
-            if (outputId !== null) {
-                if (!HEX32.test(outputId))
-                    return fail('missing h');
-                if (store.outputIdInUse(outputId))
-                    return fail('Invalid or already spent k1.');
+            // Two spellings of one thing. LUD-25 puts the output hash in a LUD-12
+            // `comment`; `h` is this mint's own earlier name for it, kept so the
+            // wallets that adopted it keep working.
+            //
+            // They are NOT validated the same way, and that asymmetry is the
+            // spec's. A malformed `comment` MUST fall back to keying the note by
+            // the preimage, exactly as no comment at all does - a comment is a
+            // free-text field in LUD-12 and a mint cannot treat every stray one
+            // as a failed mint. A malformed `h` is a wallet that meant to name an
+            // output and got it wrong, so it still fails loudly rather than
+            // quietly minting a note the wallet is not expecting.
+            const askedComment = q.get('comment')?.trim().toLowerCase() ?? null;
+            const commentOutputId = askedComment !== null && HEX32.test(askedComment) ? askedComment : null;
+            const askedOutputId = q.get('h')?.trim().toLowerCase() ?? null;
+            if (askedOutputId !== null && !HEX32.test(askedOutputId))
+                return fail('missing h');
+            // A wallet sending both should send the same hash in both; ours does.
+            // Disagreement is a bug in the caller, and picking a winner would
+            // mint a note under a hash one half of it is not watching for.
+            if (commentOutputId !== null &&
+                askedOutputId !== null &&
+                commentOutputId !== askedOutputId) {
+                return fail('comment and h name different outputs');
+            }
+            const outputId = commentOutputId ?? askedOutputId;
+            if (outputId !== null && store.outputIdInUse(outputId)) {
+                return fail('Invalid or already spent k1.');
             }
             // The preimage is the future note's spend secret unless `h` named
             // one; its hash is the invoice's payment hash either way. Generated
@@ -660,7 +686,15 @@ export const createMoneyer = async (config, deps = {}) => {
                 ...(outputId !== null && config.verify && signer
                     ? { mint: { h: outputId, amount: net } }
                     : {}),
-                ...(config.verify ? { verify: `${origin}/verify/${paymentHash}` } : {})
+                // LUD-25: a SERVICE MUST NOT offer verify on a mint payment that
+                // named no output. There the note's k1 IS the preimage, and verify
+                // hands it to whoever holds the URL - which anyone who has seen the
+                // invoice can build from its payment hash. A wallet on this path
+                // learns the preimage from paying the invoice, the way any Lightning
+                // wallet already keeps it.
+                ...(config.verify && outputId !== null
+                    ? { verify: `${origin}/verify/${paymentHash}` }
+                    : {})
             });
         }
         // ---- LUD-21 verify: mint invoices and melt payments ----
@@ -671,6 +705,14 @@ export const createMoneyer = async (config, deps = {}) => {
             const paymentHash = verifyMatch[1].toLowerCase();
             const invoice = store.mintInvoiceByHash(paymentHash);
             if (invoice) {
+                // The other half of the rule above, and the half that matters: not
+                // advertising the URL does not stop anyone building it. Refused for
+                // an unnamed invoice quoted since this mint adopted the rule, and
+                // still honoured for one quoted before it, whose payer has no other
+                // way to reach a note they already own.
+                if (invoice.outputId === null && invoice.createdAt >= store.unnamedVerifyCutover()) {
+                    return fail('Not found.', 404);
+                }
                 if (!invoice.settled && (await backend.isInvoiceSettled(paymentHash))) {
                     store.settleMintInvoice(paymentHash);
                 }

package/dist/store.d.ts

@@ -11,6 +11,7 @@ export type MintInvoiceRow = {
     netMsat: number;
     settled: boolean;
     outputId: string | null;
+    createdAt: number;
 };
 export type MeltRow = {
     paymentHash: string;
@@ -83,6 +84,7 @@ export declare class NoteStore {
     constructor(path: string, options?: {
         readOnly?: boolean;
     });
+    unnamedVerifyCutover(): number;
     private tx;
     noteById(id: string): NoteRow | null;
     private insertNote;

package/dist/store.js

@@ -117,6 +117,29 @@ export class NoteStore {
         // Two invoices may not name the same note. SQLite counts NULLs as
         // distinct, so every unbound invoice still fits.
         this.db.exec('CREATE UNIQUE INDEX IF NOT EXISTS mint_invoices_output_id ON mint_invoices (output_id)');
+        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
+        // the database, and never moved after.
+        //
+        // It has to be persisted rather than taken from process start, or a
+        // restart would walk the line forward and strand a quote made minutes
+        // earlier under the same build. Invoices older than it keep their
+        // verify: a wallet polling one of those did not pay the invoice itself
+        // - that is why it is polling - so the preimage this mint holds is its
+        // only route to a note it already owns. Refusing those retroactively
+        // would not close a hole, it would burn somebody's money. They drain.
+        this.db
+            .prepare("INSERT OR IGNORE INTO meta (key, value) VALUES ('unnamed_verify_cutover', ?)")
+            .run(String(Date.now()));
+    }
+    // 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".
+    unnamedVerifyCutover() {
+        const row = this.db
+            .prepare("SELECT value FROM meta WHERE key = 'unnamed_verify_cutover'")
+            .get();
+        return row ? Number(row.value) : 0;
     }
     tx(fn) {
         this.db.exec('BEGIN IMMEDIATE');
@@ -294,7 +317,7 @@ export class NoteStore {
     }
     mintInvoiceByHash(paymentHash) {
         const row = this.db
-            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id FROM mint_invoices WHERE payment_hash = ?')
+            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, created_at FROM mint_invoices WHERE payment_hash = ?')
             .get(paymentHash);
         if (!row)
             return null;
@@ -304,7 +327,8 @@ export class NoteStore {
             grossMsat: row.gross_msat,
             netMsat: row.net_msat,
             settled: row.settled === 1,
-            outputId: row.output_id
+            outputId: row.output_id,
+            createdAt: row.created_at
         };
     }
     // The invoice a payer bound to this note id, if any. The lookup a claim
@@ -320,7 +344,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 FROM mint_invoices WHERE settled = 0')
+            .prepare('SELECT payment_hash, pr, gross_msat, net_msat, settled, output_id, created_at FROM mint_invoices WHERE settled = 0')
             .all();
         return rows.map(row => ({
             paymentHash: row.payment_hash,
@@ -328,7 +352,8 @@ export class NoteStore {
             grossMsat: row.gross_msat,
             netMsat: row.net_msat,
             settled: false,
-            outputId: row.output_id
+            outputId: row.output_id,
+            createdAt: row.created_at
         }));
     }
     // Conditional on STILL unsettled: a settle landing between the sweep's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.6.1",
+  "version": "0.7.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",