@forgesworn/moneyer 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 0.8.0 - 2026-08-30
+
+**`MONEYER_REQUIRE_COMMENT` (default off).** Refuses a mint quote that names
+no output, rather than falling back to a note keyed by the payment preimage.
+Off by default because LUD-25 line 80 still asks for that fallback; on, the
+refusal happens before any invoice is issued, so a wallet never pays for a
+quote the mint was always going to reject. A quote naming its output by
+either spelling (`comment` or `h`) is unaffected.
+
+Worth knowing: `lnurlcash-conformance` now grades the mandate as required, so
+moneyer fails that suite in its default configuration and passes with the
+flag on. See that repo's `docs/COMMENT-IS-MANDATORY.md`.
+
+## [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/README.md

@@ -105,6 +105,7 @@ default, and a variable set to an empty string counts as unset.
 | `MONEYER_MIN_SENDABLE_MSAT` | `1000` | smallest payment the mint advertises |
 | `MONEYER_MAX_SENDABLE_MSAT` | `100000000` | largest payment the mint advertises |
 | `MONEYER_MIN_MINT_MSAT` | `1000` | dust floor: the smallest note the mint will strike |
+| `MONEYER_REQUIRE_COMMENT` | `false` | refuse a mint quote that names no output, instead of falling back to a note keyed by the payment preimage. See [comment protection](#comment-protection) |
 | `MONEYER_MAX_K1S` | `21` | most notes one callback may name |
 | `MONEYER_VERIFY` | `true` | the LUD-21 `verify` endpoint. Off means 404 |
 | `MONEYER_WALLET_URL` | | a companion web wallet the mint's site links notes into |
@@ -667,3 +668,34 @@ in [awesome-lnurlcash](https://github.com/TheCryptoDonkey/awesome-lnurlcash).
 ## Licence
 
 MIT.
+
+
+## Comment protection
+
+A LUD-25 mint quote may carry a LUD-12 `comment` holding
+`hex(sha256(secret))`, naming the note the payment will mint. The note is
+then keyed by the wallet's own `secret`, and the payment preimage redeems
+nothing.
+
+With no such comment, LUD-25 line 80 says the mint MUST fall back to keying
+the note by the payment preimage itself. That fallback is the default here,
+and it is what the draft currently requires.
+
+`MONEYER_REQUIRE_COMMENT=true` refuses an unnamed quote instead, before any
+invoice is issued. Two reasons to want it:
+
+- A preimage-keyed note is only as safe as the discretion of every routing
+  hop on the payment. Each one learns the preimage as it settles its own
+  HTLC, often before the payer has finished processing the payment.
+- A funding source that settles without producing a preimage - a Spark
+  backend, say - has nothing to key a fallback note by at all.
+
+The cost is backward compatibility: a wallet that has never heard of
+LNURLcash sends a bare LUD-06 request and gets an error rather than an
+invoice. `dni/lnurl-mint` made this behaviour unconditional in `b257d58`;
+the draft has not yet followed, which is why it is opt-in here. See
+`lnurlcash-conformance/docs/COMMENT-IS-MANDATORY.md`.
+
+Note that `lnurlcash-conformance` now grades the mandate as required, so
+this mint **fails that suite in its default configuration** and passes with
+`MONEYER_REQUIRE_COMMENT=true`.

package/dist/backends/lnd.js

@@ -6,8 +6,11 @@ import { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } fro
 // one (r_preimage), which is what lets it back a mint. Payment send/track
 // are chunked NDJSON streams read line by line to a terminal status.
 //
-// Not yet exercised against a live node - the semantics are a direct port
-// of the reference mint's lnd backend, which is.
+// This is what backs the public mint, so the invoice and payment paths run
+// against a live node continuously; the semantics started as a direct port
+// of the reference mint's lnd backend. The exception is nodeInfo's graph
+// self-lookup, which is newer than the running deployment - it is covered
+// by test/lnd-node-info.test.ts and by nothing else yet.
 //
 // TLS: for lnd's self-signed cert, point NODE_EXTRA_CA_CERTS at it.
 const FAILURE_REASONS = {
@@ -183,12 +186,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/config.d.ts

@@ -32,6 +32,7 @@ export type MoneyerConfig = {
     maxSendableMsat: number;
     minMintMsat: number;
     mintFee: MintFee | null;
+    requireComment: boolean;
     roundFeeToSat?: boolean;
     signingKey?: string;
     previousSigningPubkeys?: string[];

package/dist/config.js

@@ -84,6 +84,7 @@ const contactFromEnv = (env) => {
 // that starts with a half-understood configuration is holding other
 // people's money on a misunderstanding.
 export const configFromEnv = (env = process.env) => {
+    const requireComment = flag(env.MONEYER_REQUIRE_COMMENT, false);
     const baseFeeMsat = int(env.MONEYER_BASE_FEE_MSAT, 0);
     const feePpm = int(env.MONEYER_FEE_PPM, 0);
     if (feePpm >= 1_000_000) {
@@ -211,6 +212,7 @@ export const configFromEnv = (env = process.env) => {
         maxSendableMsat,
         minMintMsat: int(env.MONEYER_MIN_MINT_MSAT, DEFAULTS.minMintMsat),
         mintFee: baseFeeMsat === 0 && feePpm === 0 ? null : { baseFeeMsat, feePpm },
+        requireComment,
         roundFeeToSat: flag(env.MONEYER_ROUND_FEE_TO_SAT, DEFAULTS.roundFeeToSat),
         ...(signingKey ? { signingKey: signingKey.toLowerCase() } : {}),
         ...(previousSigningPubkeys.length ? { previousSigningPubkeys } : {}),

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,43 @@ 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;
+            // MONEYER_REQUIRE_COMMENT: refuse a quote that names no output at all,
+            // rather than minting a note keyed by the payment preimage. Off by
+            // default - LUD-25 line 80 still asks for that fallback - but the
+            // fallback note is only as safe as every routing hop's discretion, and
+            // a funding source that settles without a preimage has nothing to key
+            // one by. Refused here, before any invoice exists, so a wallet never
+            // pays for a quote this mint was always going to reject.
+            if (config.requireComment && outputId === null) {
+                return fail('a mint quote must name its output with a LUD-12 comment carrying hex(sha256(secret))');
+            }
+            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 +696,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 +715,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.8.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",