@forgesworn/moneyer 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-09-04
+
+Two changes here are breaking for an existing deployment, and both are
+deliberate.
+
+**An operator upgrading must set `MONEYER_SIGNING_KEY` before the mint will
+start.** LUD-25 makes offline-verifiable note signatures mandatory for a
+SERVICE, so issuing unsigned notes is no longer an allowed operating mode and
+failing loudly at boot beats doing it quietly. `moneyer admin keys rotate`
+bootstraps a persistent key; `--dev` still generates an ephemeral one for a
+valueless mint.
+
+**A custom `LightningBackend` must declare `acceptsInvoicePreimage`.** The
+bundled cln, lnd and fake backends declare `true` and behave exactly as
+before.
+
+**Graded against conformance 0.6.0, and the stale-probe exception is gone.**
+The suite now enforces the LUD-25 MUSTs moneyer already implements: every
+rotate, split and merge must return a signature, a retried mutation must be
+answered as a replay of its original success, and a hash lookup must not
+distinguish a burned note id from an unknown one. Moneyer passes all of them
+unchanged - the work landed in 0.9.1 and this is the first suite that checks
+it.
+
+`test/conformance-compat.ts` carried an allowlist for two probes that
+conformance 0.4.0 sent without the then-new mandatory comment, so a correct
+refusal looked like a failure. 0.6.0 sends the comment on both, so the
+allowlist is deleted and the test asserts no failures at all.
+
+**`lnurlcash-kit` moves to 0.7.0**, which refuses a mint publishing no
+`mintPubkey`, raises `UnverifiableNoteError` for a mutation it confirms
+without signing, and re-sends a mutation whose answer the transport lost.
+Moneyer is on the SERVICE side of all three, so nothing here changes - but
+the kit is also what its own tests drive the mint with, and they pass against
+the stricter client.
+
+**A caller-supplied invoice preimage is no longer required of a funding
+source.** It was, and the README said so: "the capability a LUD-25 mint
+cannot exist without". That was true of the draft that keyed a bearer note by
+the payment preimage, and stopped being true in 0.9.0, when comment-bound
+minting became unconditional. A note is bound to the buyer's commitment,
+which the funding source never sees, so a node that mints its own preimages
+can back a mint.
+
+`LightningBackend` gains `acceptsInvoicePreimage`, and `createInvoice`'s
+`preimageHex` is optional. cln, lnd and fake declare `true` and are unchanged:
+knowing the payment hash before the invoice exists lets the mint refuse an
+invoice that does not commit to it, which is still the stronger position. A
+backend declaring `false` gets the hash off the returned invoice and the same
+collision checks after the fact, plus two the pre-chosen path never needed - a
+payment hash this mint has already issued or melted, and an invoice the node
+had already settled, are both refused rather than quoted.
+
+No phoenixd or NIP-47 backend ships yet; what changed is that one is now
+possible. An operator writing one should know that phoenixd invoices are
+denominated in whole sats and that `payinvoice` takes no fee limit, so a mint
+on it cannot cap the routing cost of a melt the way cln and lnd can.
+
+- Moneyer now refuses to start without `MONEYER_SIGNING_KEY`. LUD-25 makes
+  offline-verifiable note signatures mandatory for a SERVICE; silently
+  issuing unsigned notes is no longer an allowed operating mode. `--dev`
+  still creates an ephemeral key, and `moneyer admin keys rotate` can
+  bootstrap a persistent one.
+- A hash-only informational lookup now treats a burned note id exactly like
+  an unknown one and refuses requests carrying both `k1` and `h`, matching
+  LUD-25's non-disclosing `h` lookup. Secret-bearing `k1` lookups retain the
+  useful `already spent` answer.
+
+## 0.9.1 - 2026-09-01
+
+**Fix: the LUD-25 informational GET now accepts `h=sha256(k1)`.** A
+receipt-aware wallet can verify that a bound mint payment created its note
+without disclosing the bearer secret. The hash-only reply deliberately omits
+`k1`; lazy settlement works on this path as it does on the secret-bearing
+path, and conflicting `k1` and `h` parameters are refused.
+
 ## 0.9.0 - 2026-08-31
 
 **LUD-25 comment-bound minting is now unconditional.** Every mint quote must

package/README.md

@@ -6,8 +6,9 @@
 moneyer is an independent implementation of the LUD-25 draft: paying an
 invoice it issues mints a bearer note, and a note's holder can rotate,
 split, merge and melt it against the withdraw callback. The note's spend
-secret is the invoice's payment preimage, or, better, a secret the buyer
-chose and named on the way in. It passes the full
+secret is chosen by the buyer, before the invoice exists, and named to the
+mint only as a hash - so the mint never holds it, and neither does any node
+that forwards the payment. It passes the full
 [lnurlcash-conformance](https://github.com/TheCryptoDonkey/lnurlcash-conformance)
 grader, including the spending checks, and the grader runs in this repo's
 own test suite.
@@ -21,14 +22,18 @@ lesson, that behaviour is kept deliberately and tested.
 
 - TypeScript, ESM, Node 24+. `node:http` and `node:sqlite`; no web
   framework, no ORM.
-- Funding sources: **cln** (clnrest) and **lnd** (REST), both of which
-  accept a caller-supplied invoice preimage - the capability a LUD-25 mint
-  cannot exist without. phoenixd and NIP-47 `make_invoice` do not offer it,
-  which is why neither can back a mint. A **fake** backend exists for
+- Funding sources: **cln** (clnrest) and **lnd** (REST). Both accept a
+  caller-supplied invoice preimage, so the mint knows the payment hash
+  before the invoice exists and can refuse an invoice that does not commit
+  to it. That is a nicety, not a requirement: a note is keyed by the buyer's
+  comment commitment, which the funding source never sees, so a node that
+  mints its own preimages (phoenixd, NIP-47 `make_invoice`) can back a mint
+  too - it just gets the after-the-fact checks instead. A backend declares
+  which it is with `acceptsInvoicePreimage`. A **fake** backend exists for
   development and tests and refuses to run outside `--dev`.
 - Notes are stored by id, `sha256(k1)` - the store never holds a spend
-  secret. A buyer may name the note they are buying, in which case the
-  secret is theirs alone from the start.
+  secret. The buyer names the note they are buying with a mandatory LUD-12
+  comment, so the secret is theirs alone from the start.
 - Signs every note it mints with its own mint key (secp256k1, the standard
   `Lightning Signed Message` construction) for LUD-25 offline verification.
 - The melt discipline: reply OK when the note is reserved, pay in the
@@ -97,7 +102,7 @@ default, and a variable set to an empty string counts as unset.
 | `MONEYER_BACKEND_URL` | | the funding source's REST endpoint |
 | `MONEYER_BACKEND_RUNE` | | cln authentication |
 | `MONEYER_BACKEND_MACAROON` | | lnd authentication, hex |
-| `MONEYER_SIGNING_KEY` | | 32 bytes of hex. Unset means notes go out unsigned, which holders will notice |
+| `MONEYER_SIGNING_KEY` | required | Persistent 32-byte hex note-signing key. The service refuses to start without it; use `moneyer admin keys rotate` to generate one |
 | `MONEYER_PREVIOUS_SIGNING_PUBKEYS` | | compressed pubkeys this mint signed under before, comma separated (see below) |
 | `MONEYER_BASE_FEE_MSAT` | `0` | flat mint fee |
 | `MONEYER_FEE_PPM` | `0` | proportional mint fee, parts per million |
@@ -576,7 +581,7 @@ clearnet.
 | `/p/cb` | LUD-06 pay callback; issues the mint invoice, and takes an optional `h` naming the note |
 | `/z/cb/<zap name>` | the zap callback; validates the kind 9734 and issues the invoice |
 | `/verify/<hash>` | LUD-21 verify, for mint invoices and melt payments |
-| `/w` | LUD-03 informational GET; a live note also carries `payLink`, the route back to this mint's discovery document |
+| `/w` | LUD-03 informational GET; accepts `k1` or the non-disclosing LUD-25 `h=sha256(k1)` check; a live note also carries `payLink` |
 | `/w/cb` | the mutating callback: melt, rotate, split, merge |
 | `POST /names` | claim a lightning address, authenticated by NIP-98 |
 | `/.well-known/nostr.json` | NIP-05 for the names this mint serves |

package/dist/admin.js

@@ -173,7 +173,7 @@ export const runAdmin = async (argv, deps = {}) => {
                 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(`  signing key        ${signingPubkey(config) ?? 'none - service will refuse to start'}`);
                 out(`  previous keys      ${previous.length ? previous.join(', ') : 'none'}`);
                 out(`  funding source     ${config.backend.kind}`);
                 return 0;

package/dist/backends/cln.js

@@ -36,7 +36,11 @@ export const createClnBackend = (config) => {
     };
     return {
         name: 'cln',
+        acceptsInvoicePreimage: true,
         async createInvoice({ amountMsat, preimageHex, memo, descriptionForHash }) {
+            if (preimageHex === undefined) {
+                throw new Error('cln accepts a caller-supplied invoice preimage and was given none.');
+            }
             const result = await mustCall('/v1/invoice', {
                 amount_msat: amountMsat,
                 label: bytesToHex(randomBytes(16)),

package/dist/backends/fake.d.ts

@@ -3,6 +3,7 @@ export type FakePayMode = 'succeed' | 'fail-clean' | 'fail-then-paid' | 'ambiguo
 export declare const DEFAULT_AUTO_SETTLE_AFTER_MS = 1500;
 export type FakeBackendOptions = {
     autoSettle?: boolean;
+    nodeChoosesPreimage?: boolean;
     autoSettleAfterMs?: number;
 };
 export type FakeBackend = LightningBackend & {
@@ -12,6 +13,7 @@ export type FakeBackend = LightningBackend & {
         resolvePayment(paymentHashHex: string, status: 'complete' | 'failed'): void;
         registerPaymentPreimage(paymentHashHex: string, preimageHex: string): void;
         seedForeignPayment(paymentHashHex: string, status?: 'complete' | 'pending'): void;
+        reuseNextInvoiceHash(paymentHashHex: string): void;
         invoiceByHash(paymentHashHex: string): {
             preimageHex: string;
             amountMsat: number;

package/dist/backends/fake.js

@@ -1,4 +1,4 @@
-import { bytesToHex } from '@noble/hashes/utils.js';
+import { bytesToHex, randomBytes } from '@noble/hashes/utils.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { hexToBytes } from '@noble/hashes/utils.js';
 import { bolt11PaymentHash } from 'farrier-kit/bolt11';
@@ -22,6 +22,8 @@ const isSettled = (invoice) => {
 export const FAKE_LOCAL_BALANCE_MSAT = 100_000_000_000;
 export const createFakeBackend = (options = {}) => {
     const autoSettle = options.autoSettle === true;
+    const nodeChoosesPreimage = options.nodeChoosesPreimage === true;
+    let reusedInvoiceHash = null;
     const autoSettleAfterMs = options.autoSettleAfterMs ?? DEFAULT_AUTO_SETTLE_AFTER_MS;
     // `settleAt` is when autoSettle starts calling this invoice paid; null
     // for an invoice only control.settleInvoice can settle, which is every
@@ -33,11 +35,25 @@ export const createFakeBackend = (options = {}) => {
     let payMode = 'succeed';
     return {
         name: 'fake',
+        acceptsInvoicePreimage: !nodeChoosesPreimage,
         async createInvoice({ amountMsat, preimageHex, memo }) {
-            const paymentHashHex = bytesToHex(sha256(hexToBytes(preimageHex)));
+            // A node that mints its own preimages never sees the caller's.
+            const chosen = nodeChoosesPreimage ? bytesToHex(randomBytes(32)) : preimageHex;
+            if (chosen === undefined) {
+                throw new Error('the fake backend accepts a caller-supplied invoice preimage and was given none.');
+            }
+            // A funding source handing back an invoice that is not the fresh one
+            // it was asked for. Nothing is recorded under the reused hash: the
+            // point is precisely that this invoice is somebody else's.
+            if (reusedInvoiceHash !== null) {
+                const paymentHashHex = reusedInvoiceHash;
+                reusedInvoiceHash = null;
+                return { pr: fakeBolt11({ amountMsat, paymentHashHex, memo }) };
+            }
+            const paymentHashHex = bytesToHex(sha256(hexToBytes(chosen)));
             const pr = fakeBolt11({ amountMsat, paymentHashHex, memo });
             invoices.set(paymentHashHex, {
-                preimageHex,
+                preimageHex: chosen,
                 amountMsat,
                 settled: false,
                 settleAt: autoSettle ? Date.now() + autoSettleAfterMs : null
@@ -128,6 +144,9 @@ export const createFakeBackend = (options = {}) => {
             seedForeignPayment(paymentHashHex, status = 'complete') {
                 payments.set(paymentHashHex, { status, preimageHex: null, amountMsat: null });
             },
+            reuseNextInvoiceHash(paymentHashHex) {
+                reusedInvoiceHash = paymentHashHex;
+            },
             sentAmountMsat(paymentHashHex) {
                 const payment = payments.get(paymentHashHex);
                 return payment ? payment.amountMsat : undefined;

package/dist/backends/lnd.js

@@ -85,7 +85,11 @@ export const createLndBackend = (config) => {
     };
     return {
         name: 'lnd',
+        acceptsInvoicePreimage: true,
         async createInvoice({ amountMsat, preimageHex, memo, descriptionForHash }) {
+            if (preimageHex === undefined) {
+                throw new Error('lnd accepts a caller-supplied invoice preimage and was given none.');
+            }
             const res = await json('/v1/invoices', {
                 method: 'POST',
                 body: {

package/dist/backends/types.d.ts

@@ -19,9 +19,10 @@ export declare class PaymentAlreadyKnownError extends Error {
 }
 export interface LightningBackend {
     readonly name: string;
+    readonly acceptsInvoicePreimage: boolean;
     createInvoice(args: {
         amountMsat: number;
-        preimageHex: string;
+        preimageHex?: string;
         memo: string;
         descriptionForHash?: string;
     }): Promise<{

package/dist/backends/types.js

@@ -1,9 +1,12 @@
 // The funding source. Every amount is integer milli-satoshis.
 //
-// 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.
+// A backend MAY accept a caller-supplied invoice preimage, and Moneyer uses
+// one where it can: knowing the payment hash before the invoice exists lets it
+// prove the BOLT-11 it got back is the one it asked for. That is a nicety, not
+// a requirement. The bearer note is keyed by the wallet's mandatory comment
+// commitment, never by the payment preimage, so a funding source whose node
+// chooses its own preimages can back a mint perfectly well - see
+// `acceptsInvoicePreimage`.
 // 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/cli.js

@@ -67,8 +67,7 @@ const log = (message) => console.error(`[moneyer] ${message}`);
 const moneyer = await createMoneyer(config, { log });
 console.log(`moneyer listening on ${moneyer.url}`);
 console.log(`  lightning address: ${config.username}@${new URL(config.publicOrigin ?? moneyer.url).host}`);
-if (moneyer.signer)
-    console.log(`  mint pubkey:       ${moneyer.signer.pubkey}`);
+console.log(`  mint pubkey:       ${moneyer.signer.pubkey}`);
 console.log(`  funding source:    ${moneyer.backend.name}`);
 if (values.dev) {
     const k1 = bytesToHex(randomBytes(32));

package/dist/server.d.ts

@@ -11,7 +11,7 @@ export type Moneyer = {
     config: MoneyerConfig;
     store: NoteStore;
     backend: LightningBackend;
-    signer: NoteSigner | null;
+    signer: NoteSigner;
     zap: ZapBridge | null;
     reconcile: () => Promise<void>;
     stats: () => Promise<MintStats>;

package/dist/server.js

@@ -54,10 +54,13 @@ const backendFor = (config) => {
     }
 };
 export const createMoneyer = async (config, deps = {}) => {
+    if (!config.signingKey) {
+        throw new Error('MONEYER_SIGNING_KEY is required: LUD-25 requires every SERVICE to sign its notes. Run `moneyer admin keys rotate` to generate one.');
+    }
     const log = deps.log ?? (() => { });
     const store = deps.store ?? new NoteStore(config.dbPath);
     const backend = deps.backend ?? backendFor(config);
-    const signer = config.signingKey ? createNoteSigner(config.signingKey) : null;
+    const signer = createNoteSigner(config.signingKey);
     const webAssets = deps.webAssets === undefined ? loadWebAssets() : deps.webAssets;
     // Node identity for the discovery endpoint, fetched once, best-effort: a
     // funding source that cannot answer does not stop the mint serving.
@@ -140,8 +143,7 @@ export const createMoneyer = async (config, deps = {}) => {
     // A note whose id we do not know yet may be a settled mint invoice whose
     // claim simply has not been observed: settle it lazily against the
     // funding source, which is what makes paying an invoice mint the note.
-    const resolveNote = async (k1) => {
-        const id = hashK1(k1);
+    const resolveNoteId = async (id) => {
         const note = store.noteById(id);
         if (note)
             return note;
@@ -161,6 +163,7 @@ export const createMoneyer = async (config, deps = {}) => {
         }
         return null;
     };
+    const resolveNote = async (k1) => resolveNoteId(hashK1(k1));
     // ---- transparency: what the mint owes, and what the node holds ----
     //
     // Cached for 30 seconds so a public endpoint cannot be turned into a
@@ -629,19 +632,30 @@ export const createMoneyer = async (config, deps = {}) => {
                 return fail('Invalid or already spent k1.');
             }
             // 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);
-            while (store.outputIdInUse(paymentHash) || paymentHash === outputId) {
-                preimage = bytesToHex(randomBytes(32));
-                paymentHash = hashK1(preimage);
+            //
+            // Where the funding source lets Moneyer choose it, choosing means the
+            // payment hash is known before the invoice exists, and the invoice that
+            // comes back can be held to it. Where the node mints its own preimages,
+            // the hash arrives with the invoice and the same collisions are checked
+            // after the fact instead. Either way the preimage is never persisted -
+            // the store keeps hashes only - and either way the bearer note is keyed
+            // by the wallet's comment commitment, which is why a node that will not
+            // take a preimage can still back a mint.
+            let chosen = null;
+            if (backend.acceptsInvoicePreimage) {
+                let preimageHex = bytesToHex(randomBytes(32));
+                let paymentHash = hashK1(preimageHex);
+                while (store.outputIdInUse(paymentHash) || paymentHash === outputId) {
+                    preimageHex = bytesToHex(randomBytes(32));
+                    paymentHash = hashK1(preimageHex);
+                }
+                chosen = { preimageHex, paymentHash };
             }
             let pr;
             try {
                 pr = (await backend.createInvoice({
                     amountMsat: amount,
-                    preimageHex: preimage,
+                    ...(chosen === null ? {} : { preimageHex: chosen.preimageHex }),
                     memo: `LNURLcash mint at ${host}`
                 })).pr;
             }
@@ -649,14 +663,50 @@ export const createMoneyer = async (config, deps = {}) => {
                 log(`create invoice failed: ${err.message}`);
                 return fail('Temporarily unable to issue an invoice.');
             }
-            // Trust but verify: an invoice that does not commit to OUR payment
-            // hash would take the payer's money and mint a note they can never
-            // claim. Refuse to hand it out.
+            // Trust but verify: an invoice for the wrong amount would take the
+            // payer's money and mint a note worth something else.
             const decoded = tryDecodeBolt11(pr);
-            if (!decoded || decoded.paymentHashHex !== paymentHash || decoded.amountMsats !== BigInt(amount)) {
-                log('funding source returned an invoice that does not match the requested preimage/amount');
+            if (!decoded || decoded.amountMsats !== BigInt(amount)) {
+                log('funding source returned an invoice that does not match the requested amount');
                 return fail('Temporarily unable to issue an invoice.');
             }
+            const paymentHash = decoded.paymentHashHex;
+            if (chosen !== null) {
+                // An invoice that does not commit to OUR payment hash is not the one
+                // that was asked for, and paying it would mint nothing claimable.
+                if (paymentHash !== chosen.paymentHash) {
+                    log('funding source returned an invoice that does not match the requested preimage');
+                    return fail('Temporarily unable to issue an invoice.');
+                }
+            }
+            else {
+                // The node chose the preimage, so every check the pre-chosen path got
+                // for free has to be made now - plus one it never needed. A hash this
+                // mint has already seen, or an invoice the node settled before handing
+                // it over, would credit a note against money that never moved on this
+                // quote's behalf.
+                if (paymentHash === outputId ||
+                    store.outputIdInUse(paymentHash) ||
+                    store.mintInvoiceByHash(paymentHash) ||
+                    store.meltByHash(paymentHash)) {
+                    log('funding source returned an invoice whose payment hash is already in use');
+                    return fail('Temporarily unable to issue an invoice.');
+                }
+                let alreadySettled;
+                try {
+                    alreadySettled = await backend.isInvoiceSettled(paymentHash);
+                }
+                catch (err) {
+                    // Unconfirmable is not "fresh". Handing out an invoice that might
+                    // already be paid is the whole risk this check exists to close.
+                    log(`could not confirm a fresh invoice is unsettled: ${err.message}`);
+                    return fail('Temporarily unable to issue an invoice.');
+                }
+                if (alreadySettled) {
+                    log('funding source returned an invoice that was already settled');
+                    return fail('Temporarily unable to issue an invoice.');
+                }
+            }
             try {
                 store.recordMintInvoice(paymentHash, pr, amount, net, outputId);
             }
@@ -754,14 +804,27 @@ export const createMoneyer = async (config, deps = {}) => {
         }
         // ---- LUD-03 informational GET ----
         if (requestUrl.pathname === '/w') {
+            const hasK1 = q.has('k1');
+            const hasH = q.has('h');
             const k1 = q.get('k1')?.toLowerCase();
-            if (!k1 || !HEX32.test(k1))
+            const h = q.get('h')?.toLowerCase();
+            if (hasK1 === hasH ||
+                (hasK1 && (!k1 || !HEX32.test(k1))) ||
+                (hasH && (!h || !HEX32.test(h)))) {
                 return fail('Unknown note.');
-            const note = await resolveNote(k1);
+            }
+            // LUD-25's hash-only check lets a wallet prove that the note it just
+            // bought exists without sending the bearer secret to the service a
+            // second time. `h` is accepted in place of `k1`, never alongside it.
+            const note = h ? await resolveNoteId(h) : await resolveNote(k1);
             if (!note)
                 return fail('Unknown note.');
+            // A hash-only lookup must not disclose whether a note id once existed:
+            // LUD-25 gives a never-registered and an already-spent h the same
+            // response as an unknown k1. A caller presenting the bearer k1 still
+            // receives the useful already-spent distinction.
             if (note.state === 'burned')
-                return fail('Note already spent.');
+                return fail(h ? 'Unknown note.' : 'Note already spent.');
             // A note reserved by an in-flight melt is not withdrawable, and must
             // not be advertised as though it were. LUD-25 makes this GET the way
             // anyone checks what a note is worth, so answering "live, worth all
@@ -780,7 +843,10 @@ export const createMoneyer = async (config, deps = {}) => {
             return send({
                 tag: 'withdrawRequest',
                 callback: `${origin}/w/cb`,
-                k1,
+                // A hash-only query deliberately does not echo or invent k1. The
+                // wallet already has the secret; this endpoint only confirms the
+                // mint's record at sha256(k1).
+                ...(k1 ? { k1 } : {}),
                 minWithdrawable: wholeSatFloor(note.amountMsat),
                 maxWithdrawable: note.amountMsat,
                 defaultDescription: config.description,

package/llms.txt

@@ -15,13 +15,17 @@ Client library to build against a mint: lnurlcash-kit
 
 ## Rules this SERVICE follows (and any mint MUST)
 
-1. A mint invoice's preimage is the note secret - the funding source must
-   accept a caller-supplied preimage (cln and lnd do; phoenixd and NIP-47
-   make_invoice do not, and cannot back a mint). UNLESS the payer sent
-   `h` on the pay callback: then the note is credited at `h`, the payer's
-   own secret, and the preimage is only a payment proof. Prefer that: a
-   preimage is known to the funding source, to every node on the route,
-   and to anyone who polls verify with the payment hash in the invoice.
+1. A mint quote MUST be named. The payer sends `comment=hex(sha256(secret))`
+   on the pay callback (LUD-12, and the payRequest advertises
+   `commentAllowed: 64`); a missing or malformed comment is refused before
+   any invoice is issued. The note is credited at that hash, so the secret
+   is the payer's alone. The payment preimage is settlement proof and never
+   a bearer credential - it is known to the funding source, to every node on
+   the route, and to anyone who polls verify with the payment hash written
+   inside the invoice. `h` is an additive alias for the same commitment and
+   never replaces the comment. Because the note is not keyed by the
+   preimage, a funding source whose node chooses its own preimages
+   (phoenixd, NIP-47 make_invoice) can back a mint.
 2. Mutations are atomic: all named k1 burn and all outputs mint, or
    nothing happens. Duplicate k1 in one request is refused.
 3. h/h2 are WALLET-supplied hashes; the mint never generates a
@@ -82,5 +86,5 @@ NoteStore - SQLite store; notes by sha256(k1), never secrets
 /.well-known/lnurlw/{user}  LUD-25 mint address (experimental)
 /p/cb                       LUD-06 pay callback (optional h names the note)
 /verify/{payment_hash}      LUD-21 verify (mint invoices AND melt payments)
-/w                          LUD-03 informational GET
+/w                          LUD-03 informational GET by k1 or hash-only h
 /w/cb                       melt / rotate / split / merge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.9.0",
+  "version": "0.10.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.6.0",
+    "lnurlcash-kit": "^0.7.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.5.0",
+    "lnurlcash-conformance": "^0.6.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",