@forgesworn/moneyer 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.0 - 2026-08-31
+
+**LUD-25 comment-bound minting is now unconditional.** Every mint quote must
+carry `comment=hex(sha256(secret))`; missing or malformed comments are
+rejected before invoice creation. The additive `h` field is accepted only
+alongside an identical comment. `MONEYER_REQUIRE_COMMENT` and the
+preimage-backed creation fallback have been removed. Existing notes and
+pre-upgrade database rows remain redeemable.
+
+## 0.8.1 - 2026-08-30
+
+**Fix: `requireComment` is optional on `MoneyerConfig`.** 0.8.0 added it as a
+required field, which is a breaking change for any consumer constructing a
+config by hand - their `tsc` fails on a flag they never asked for. Absent now
+means off, which is also what LUD-25 still asks for. Caught by notecase's
+typecheck; moneyer's own tests could not see it, since nothing here omits the
+field.
+
 ## 0.8.0 - 2026-08-30
 
 **`MONEYER_REQUIRE_COMMENT` (default off).** Refuses a mint quote that names

package/README.md

@@ -105,7 +105,6 @@ 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 |
@@ -318,38 +317,37 @@ non-payment, and the routing budget is still sized against the note.
 
 ## Name the note you are buying
 
-Paying a mint invoice mints a note, and by default that note's spend
-secret is the invoice's payment preimage. A payment preimage is not a
-private thing. The funding source has it, every node that forwarded the
-payment has it, and LUD-21 `verify` hands it to whoever asks with the
-payment hash, which is written inside the invoice on the payer's screen.
-The draft's answer is for the wallet to claim and rotate the instant the
-invoice settles, which is a foot race the wallet has to keep winning.
-
-So a wallet may name the note instead. It chooses the secret first, writes
-it down, and sends `h`, the sha256 of that secret, on the pay callback:
+Paying a mint invoice always mints to a wallet-generated secret. The wallet
+chooses and persists that secret first, then sends its SHA-256 commitment in
+the mandatory LUD-12 comment:
 
 ```
-GET /p/cb?amount=21000&h=<64 hex>
+GET /p/cb?amount=21000&comment=<64 hex>
 ```
 
-The mint credits the note at `h` when the invoice settles. The payment
+The mint credits the note at that commitment when the invoice settles. The payment
 preimage then buys nothing: it is an ordinary payment proof, which is why
 `verify` goes on serving it. Nobody but the buyer ever knew the secret, so
 there is no race left to run, and no window in which holding the invoice
 is nearly holding the money.
 
-`h` is optional and additive. A wallet that sends none gets exactly the
-behaviour it always got, so upgrading this mint breaks nothing that works
-today. The wire fields are an implementation proposal for eventual LUD-25
-adoption; current wallets and dni/reference mints keep using the original
-preimage-and-rotate flow unchanged.
+Moneyer's earlier `mintToHash` extension remains additive. A compatible
+wallet repeats the same commitment as `h`; it does not replace `comment`:
+
+```
+GET /p/cb?amount=21000&comment=<64 hex>&h=<same 64 hex>
+```
 
 The rules:
 
-- `h` is 64 hex characters, the sha256 of a 32-byte secret: the same
+- `comment` is mandatory and is exactly 64 hex characters, the SHA-256 of
+  a 32-byte secret. Missing or malformed comments are refused before an
+  invoice exists.
+- When supplied, `h` has the same
   meaning `h` carries on the withdraw callback. Upper case is accepted and
   read as lower case, there too.
+- `comment` and `h` must match. A disagreement is refused rather than
+  guessing which output the wallet is watching.
 - A malformed `h` is refused before the mint asks its funding source for
   anything, so a wallet is never left holding a quote the mint was always
   going to reject.
@@ -373,13 +371,12 @@ The rules:
   pinned `mintPubkey`, then confirm its staged note without exporting `k1`.
 - Claiming needs nothing else. `GET /w?k1=<the secret>` brings the note
   into existence as soon as the invoice has settled, with no `verify` poll
-  and no preimage involved. The poll is still the way to claim from a mint
-  that does not advertise `mintToHash`.
+  and no preimage involved. LUD-21 remains useful settlement evidence.
 - **Persist the secret before asking for the invoice.** Paying and then
   losing the secret is the one way this is worse than the old arrangement,
   and writing it down first removes it entirely.
 
-A named note is also derived-secret friendly: a wallet whose secrets come
+A comment-bound note is also derived-secret friendly: a wallet whose secrets come
 from its seed can restore a note it bought but never claimed, which a note
 whose secret was a preimage could never offer.
 
@@ -443,16 +440,15 @@ that is worth saying plainly.
 
 ## Zap-to-note: a lightning address that pays out as a note
 
-A Nostr zap is an ordinary LNURL-pay. Paid to the mint's own address it
-would mint a note, but to the payer: the invoice preimage is the secret
-and on Lightning the payer always learns it. So moneyer can also serve
-names that work the other way round. A zap to `alice@<host>` gets an
-invoice with a throwaway preimage; when it settles, the mint creates a
-note with a fresh secret, seals it in a NIP-59 gift wrap (a kind 2525
-rumor, the shape heartwood-esp32 and notecase read) to alice's pubkey,
-leaves it on her NIP-17 inbox relays, and publishes the kind 9735 receipt
-so the zap shows up in her client like any other. A hardware wallet that
-catches up on its inbox when it powers on will find the note waiting.
+A Nostr zap is an ordinary LNURL-pay and carries no current-LUD-25 output
+commitment. Moneyer therefore serves zap names in the recipient direction.
+A zap to `alice@<host>` gets an invoice with a throwaway preimage; when it
+settles, the mint creates a note with a fresh secret, seals it in a NIP-59
+gift wrap (a kind 2525 rumor, the shape heartwood-esp32 and notecase read)
+to alice's pubkey, leaves it on her NIP-17 inbox relays, and publishes the
+kind 9735 receipt so the zap shows up in her client like any other. A
+hardware wallet that catches up on its inbox when it powers on will find
+the note waiting.
 
 Until alice rotates the note, the mint knows its secret. That is the
 position every freshly minted note is in, and it is why wallets rotate on
@@ -672,30 +668,21 @@ MIT.
 
 ## Comment protection
 
-A LUD-25 mint quote may carry a LUD-12 `comment` holding
+A current LUD-25 mint quote must 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:
+Moneyer unconditionally refuses a missing or malformed comment before any
+invoice is issued. The former `MONEYER_REQUIRE_COMMENT` switch has been
+removed: allowing the preimage-backed fallback would now violate the draft
+and expose a bearer secret to every routing hop.
 
-- 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 rule also supports funding sources that settle without returning a
+preimage. There is no bearer credential to recover from the payment path;
+the wallet already persisted it before asking for the invoice.
 
-The cost is backward compatibility: a wallet that has never heard of
+The compatibility boundary is explicit: 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`.
+invoice. Existing notes remain ordinary LUD-03 withdraw links and continue
+to redeem normally.

package/dist/backends/types.js

@@ -1,10 +1,9 @@
 // The funding source. Every amount is integer milli-satoshis.
 //
-// The one non-negotiable capability is createInvoice with a CALLER-SUPPLIED
-// preimage: a LUD-25 mint invoice's preimage IS the bearer note's spend
-// secret, so the mint must know it for certain before the invoice exists.
-// lnd (r_preimage) and cln (invoice preimage=) support this; phoenixd and
-// NIP-47 make_invoice do not, which is why neither can back a mint.
+// createInvoice currently takes a caller-supplied preimage so Moneyer can
+// verify that the returned BOLT-11 commits to the invoice it records and can
+// later provide ordinary LUD-21 settlement proof. The bearer note itself is
+// always keyed by the wallet's mandatory comment commitment.
 // The funding source's immediate answer to the payment attempt was a clean,
 // terminal failure - no route, rejected, expired. Distinct from a dropped
 // connection or timeout, where the payment may still have gone out. Even

package/dist/config.d.ts

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

package/dist/config.js

@@ -84,7 +84,6 @@ 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) {
@@ -212,7 +211,6 @@ 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/landing.js

@@ -46,7 +46,7 @@ export const landingPage = (args) => {
 <meta charset="utf-8"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>${escapeHtml(title)} - an LNURLcash mint</title>
-<meta name="description" content="A moneyer strikes Lightning bearer notes. Pay ${escapeHtml(address)} and the invoice's preimage becomes your note."/>
+<meta name="description" content="A moneyer strikes Lightning bearer notes bound to a secret generated by your wallet."/>
 <style>
 :root{--bg:#0e0f12;--raise:#16181d;--line:rgba(226,233,242,.09);--ink:#eef1f6;--dim:#98a0ac;--accent:#c9ced8;--accent-deep:#8f97a4}
 @media(prefers-color-scheme:light){:root{--bg:#f3f4f6;--raise:#fff;--line:rgba(30,38,50,.12);--ink:#1c2027;--dim:#6b7380;--accent:#6f7784;--accent-deep:#4d545f}}
@@ -82,7 +82,7 @@ a{color:var(--accent)}
 <main>
 <svg class="mark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 7.6v8.8"/><path d="M15.4 9.4c-.7-1.1-1.9-1.8-3.4-1.8-2 0-3.6 1.1-3.6 2.7 0 3.4 7.2 1.8 7.2 5 0 1.6-1.6 2.7-3.6 2.7-1.5 0-2.7-.7-3.4-1.8"/></svg>
 <div class="disclaimer" role="note"><b>Proof of concept · for developers</b><span>An evaluation mint for the <a href="https://github.com/lnurl/luds/pull/301" rel="noopener noreferrer">draft LNURLcash spec</a>. A note is real bearer value with no protection, no recovery and no guaranteed redemption - <strong>assume you can lose anything you put in.</strong>${config.tosUrl ? ` <a href="${escapeHtml(config.tosUrl)}" rel="noopener noreferrer">Terms</a>` : ''}</span></div>
-<h1>${escapeHtml(title)}<small>An LNURLcash mint. Pay the address below and the invoice's payment preimage <em>is</em> your bearer note - money as a secret you hold.</small></h1>
+<h1>${escapeHtml(title)}<small>An LNURLcash mint. Your wallet commits to its own bearer secret before payment; the Lightning preimage remains payment proof.</small></h1>
 ${config.motd ? `<div class="motd"><b>notice</b>${escapeHtml(config.motd)}</div>` : ''}
 <div class="addr"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 4.5 13.5H11L9.5 22 18 10.5h-6.5L13 2z"/></svg>${escapeHtml(address)}</div>
 <div class="card">

package/dist/server.js

@@ -231,10 +231,9 @@ export const createMoneyer = async (config, deps = {}) => {
         // present, empty included: "never rotated" and "does not
         // implement the field" are different answers.
         previousPubkeys: config.previousSigningPubkeys ?? [],
-        // This mint accepts `h` on the pay callback: the payer's wallet may
-        // name the note it is buying, and then the payment preimage is not
-        // a spend secret for it. A wallet learns this before it asks for an
-        // invoice rather than after it has paid one.
+        // Additive compatibility signal: this mint accepts `h` alongside the
+        // identical mandatory LUD-12 comment, including the receipt vocabulary
+        // used by sealed signers. The comment remains the baseline commitment.
         mintToHash: true,
         ...(nodeInfo.alias ? { nodeAlias: nodeInfo.alias } : {}),
         ...(nodeInfo.uri ? { nodeUri: nodeInfo.uri } : {}),
@@ -606,43 +605,31 @@ export const createMoneyer = async (config, deps = {}) => {
             // `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.
+            // Current LUD-25 makes the LUD-12 comment the mandatory mint output
+            // commitment. Missing or malformed input is refused before asking the
+            // funding source for an invoice. `h` remains an additive compatibility
+            // field, but it never substitutes for comment.
             const askedComment = q.get('comment')?.trim().toLowerCase() ?? null;
-            const commentOutputId = askedComment !== null && HEX32.test(askedComment) ? askedComment : null;
+            if (askedComment === null || !HEX32.test(askedComment)) {
+                return fail('a mint quote must name its output with a LUD-12 comment carrying hex(sha256(secret))');
+            }
+            const commentOutputId = askedComment;
             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 &&
+            if (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)) {
+            const outputId = commentOutputId;
+            if (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
-            // here, handed to the funding source, never persisted - the store
+            // The preimage is payment proof only; comment names the future note.
+            // Generated here, handed to the funding source, never persisted - the store
             // keeps hashes only.
             let preimage = bytesToHex(randomBytes(32));
             let paymentHash = hashK1(preimage);
@@ -689,22 +676,17 @@ export const createMoneyer = async (config, deps = {}) => {
                 // wallet named. A mint that ignored an unknown parameter would
                 // answer without it, and a wallet can tell the two apart before
                 // paying rather than by looking for a note afterwards.
-                ...(outputId !== null ? { mintToHash: true } : {}),
+                mintToHash: true,
                 // Optional bound-receipt commitment: the exact output and net note
                 // value this invoice will mint. It is only offered when /verify can
                 // later authenticate settlement with this mint's signing key.
-                ...(outputId !== null && config.verify && signer
+                ...(config.verify && signer
                     ? { mint: { h: outputId, amount: net } }
                     : {}),
-                // 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}` }
-                    : {})
+                // Every current-draft mint quote is comment-bound, so the LUD-21
+                // preimage is ordinary settlement proof and safe to disclose after
+                // settlement.
+                ...(config.verify ? { verify: `${origin}/verify/${paymentHash}` } : {})
             });
         }
         // ---- LUD-21 verify: mint invoices and melt payments ----
@@ -728,8 +710,10 @@ export const createMoneyer = async (config, deps = {}) => {
                 }
                 const currentInvoice = store.mintInvoiceByHash(paymentHash);
                 const settled = currentInvoice.settled;
-                // The preimage IS the bearer secret. Served only once settled, and
-                // fetched live from the funding source - it is never stored here.
+                // For current comment-bound quotes this is settlement proof only.
+                // Historical pre-cutover unnamed rows used it as the note secret;
+                // those already-issued invoices remain redeemable after upgrade.
+                // It is fetched live from the funding source and never stored here.
                 const preimageHex = settled ? await backend.invoicePreimage(paymentHash) : null;
                 return send({
                     status: 'OK',

package/dist/zap.js

@@ -8,19 +8,17 @@ import { wrapEvent } from 'nostr-tools/nip59';
 // Zap-to-note: a lightning address on this host that pays out as an
 // LNURLcash note delivered over Nostr.
 //
-// A NIP-57 zap is an ordinary LNURL-pay. Paying the mint's own address
-// would mint a note, but to the PAYER: LUD-25 makes the invoice preimage
-// the secret, and on Lightning the payer always learns the preimage. So a
-// zap name works the other way round. The invoice gets a throwaway
-// preimage; on settlement the mint creates a note with a fresh secret of
-// its own, gift-wraps it (NIP-59, kind 2525 rumor) to the name's pubkey,
-// leaves it on their NIP-17 inbox relays, and publishes the kind 9735
-// receipt that makes the zap show up in clients.
+// A NIP-57 zap is an ordinary LNURL-pay. Unlike current LUD-25 minting it
+// carries no wallet-chosen output commitment, so a zap name works in the
+// recipient direction instead: its invoice gets a throwaway preimage; on
+// settlement the mint creates a note with a fresh secret of its own,
+// gift-wraps it (NIP-59, kind 2525 rumor) to the name's pubkey, leaves it on
+// their NIP-17 inbox relays, and publishes the kind 9735 receipt that makes
+// the zap show up in clients.
 //
 // Until the recipient rotates the note, the mint knows its secret. That is
-// exactly the position a freshly minted note is in anyway, and it is why
-// wallets rotate on receipt. What is new is that the mint learns who was
-// paid, which a lightning address always did.
+// why wallets rotate on receipt. The mint also learns who was paid, which a
+// lightning address always did.
 export const NOTE_KIND = 2525;
 export const INBOX_RELAYS_KIND = 10050;
 export const ZAP_REQUEST_KIND = 9734;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -60,7 +60,7 @@
     "@noble/hashes": "^2.3.0",
     "@scure/base": "^1.2.4",
     "farrier-kit": "^1.1.3",
-    "lnurlcash-kit": "^0.3.0",
+    "lnurlcash-kit": "^0.6.0",
     "nostr-tools": "2.24.1"
   },
   "devDependencies": {
@@ -70,7 +70,7 @@
     "@types/node": "^24.0.0",
     "animejs": "^4.0.0",
     "happy-dom": "^20.0.0",
-    "lnurlcash-conformance": "^0.3.0",
+    "lnurlcash-conformance": "^0.5.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",