@forgesworn/moneyer 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,98 @@
 # Changelog
 
-## Unreleased
+## 0.11.0 - 2026-09-06
+
+**Three fields the reference mint publishes and moneyer did not.** Each
+answers a question a wallet had no way to ask.
+
+- `nodeUris` - every address the funding node announces, not just the first.
+  A node reachable over Tor as well as clearnet announces both, and `nodeUri`
+  alone told a peer about a door it may not be able to open. `nodeUri` is
+  unchanged and stays the first of the list. lnd already fetched all of them;
+  cln now builds the list the same way instead of taking `address[0]`.
+- `sunsetDate` - `MONEYER_SUNSET_DATE`, an ISO-8601 day, published so a wallet
+  can warn its holder while spending is still possible. Deliberately separate
+  from `MONEYER_SUNSET`, which stops minting: by the time that flag goes on,
+  a holder who was going to be told has already not been told. The value is
+  validated at boot, so a typo fails loudly rather than putting a wrong date
+  in front of a holder. It also shows on the mint's own landing page.
+- `outstandingNotesMsat` - what the mint owes, in msat. A fact about its own
+  database, so it survives an unreachable funding source, but it is the same
+  disclosure `/stats` makes and answers to the same two switches:
+  `MONEYER_STATS=false` or `MONEYER_STATS_RATIO_ONLY=true` leaves it off.
+
+- Graded against `lnurlcash-conformance` 0.7.0. Its one addition is
+  `cash-derivation.json`, LUD-25's own seed-recoverable note secrets, which is
+  a wallet-side vector - a mint never sees a derivation, only `sha256(k1)`. So
+  nothing here changes; the pin moves so the grade names the current suite.
+
+## 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
 

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 |
@@ -109,6 +114,7 @@ default, and a variable set to an empty string counts as unset.
 | `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 |
 | `MONEYER_SUNSET` | `false` | wind down: refuse anything that grows liabilities, keep every way out open |
+| `MONEYER_SUNSET_DATE` | | the day this mint plans to close, ISO-8601 (`2026-12-31`). Published so a wallet can warn its holder while spending is still possible |
 | `MONEYER_STATS` | `true` | the `/stats` endpoint. Off means 404 |
 | `MONEYER_STATS_RATIO_ONLY` | `false` | publish the coverage ratio alone, without the size of the book |
 | `MONEYER_STATS_PUBLISH` | `false` | publish a signed hourly snapshot of `/stats` to Nostr |
@@ -234,6 +240,13 @@ endpoint is public by design. `MONEYER_STATS=false` switches it off;
 `MONEYER_STATS_RATIO_ONLY=true` publishes the ratio without the size of
 the book.
 
+The discovery document carries the same number as `outstandingNotesMsat`,
+so a wallet reading a mint address learns what it owes without a second
+request. Both switches govern it: an operator who has turned `/stats` off,
+or down to the ratio, has already said not to publish the size of the
+book, and a second endpoint doing it anyway would make those switches a
+lie.
+
 ### Signed snapshots
 
 With `MONEYER_STATS_PUBLISH=true`, and the Nostr identity that

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)),
@@ -122,8 +126,15 @@ export const createClnBackend = (config) => {
         async nodeInfo() {
             const info = await mustCall('/v1/getinfo', {});
             const id = info?.id;
-            const address = (info?.address ?? [])[0];
-            const uri = id && address?.address && address?.port ? `${id}@${address.address}:${address.port}` : id;
+            // Every announced address, not just the first: a node reachable over
+            // both Tor and clearnet announces both, and a peer that can only use
+            // one of them needs to be told about it.
+            const uris = id
+                ? (info?.address ?? [])
+                    .filter((entry) => entry?.address && entry?.port)
+                    .map((entry) => `${id}@${entry.address}:${entry.port}`)
+                : [];
+            const uri = uris[0] ?? id;
             const color = typeof info?.color === 'string' ? `#${info.color.replace(/^#/, '')}` : undefined;
             const numChannels = Number(info?.num_active_channels);
             const numPeers = Number(info?.num_peers);
@@ -142,6 +153,7 @@ export const createClnBackend = (config) => {
             return {
                 ...(info?.alias ? { alias: info.alias } : {}),
                 ...(uri ? { uri } : {}),
+                ...(uris.length ? { uris } : {}),
                 ...(color && /^#[0-9a-fA-F]{6}$/.test(color) ? { color } : {}),
                 ...(Number.isSafeInteger(numChannels) ? { numChannels } : {}),
                 ...(Number.isSafeInteger(numPeers) ? { numPeers } : {}),

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: {
@@ -220,6 +224,10 @@ export const createLndBackend = (config) => {
             return {
                 ...(res.json?.alias ? { alias: res.json.alias } : {}),
                 ...(uris[0] || res.json?.identity_pubkey ? { uri: uris[0] ?? res.json.identity_pubkey } : {}),
+                // getinfo already hands back every announced address; `uri` only
+                // ever carried the first. A node with nothing announced falls back
+                // to the bare pubkey above and has no list to publish.
+                ...(uris.length ? { uris } : {}),
                 ...(color && /^#[0-9a-fA-F]{6}$/.test(color) ? { color } : {}),
                 // !== undefined narrows for exactOptionalPropertyTypes; the isFinite
                 // half keeps a NaN from an unparseable channel capacity out.

package/dist/backends/types.d.ts

@@ -1,6 +1,7 @@
 export type NodeInfo = {
     alias?: string;
     uri?: string;
+    uris?: string[];
     color?: string;
     capacityMsat?: number;
     numChannels?: number;
@@ -19,9 +20,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/config.d.ts

@@ -46,6 +46,7 @@ export type MoneyerConfig = {
     announce?: boolean;
     metrics?: boolean;
     sunset: boolean;
+    sunsetDate?: string;
     zap?: ZapConfig;
     namePriceMsat?: number;
 };

package/dist/config.js

@@ -94,6 +94,7 @@ export const configFromEnv = (env = process.env) => {
         throw new Error('MONEYER_SIGNING_KEY must be 32 bytes of hex.');
     }
     const previousSigningPubkeys = previousPubkeysFromEnv(env, signingKey);
+    const sunsetDate = sunsetDateFromEnv(env);
     const kind = env.MONEYER_BACKEND ?? 'fake';
     let backend;
     if (kind === 'fake') {
@@ -225,10 +226,33 @@ export const configFromEnv = (env = process.env) => {
         ...(env.MONEYER_WALLET_URL ? { walletUrl: env.MONEYER_WALLET_URL.replace(/\/+$/, '') } : {}),
         maxK1s: int(env.MONEYER_MAX_K1S, DEFAULTS.maxK1s),
         sunset: flag(env.MONEYER_SUNSET, DEFAULTS.sunset),
+        ...(sunsetDate ? { sunsetDate } : {}),
         ...(zap ? { zap } : {}),
         ...(namePriceMsat !== undefined ? { namePriceMsat } : {})
     };
 };
+// MONEYER_SUNSET_DATE="2026-12-31" - the day this mint plans to stop.
+// Validated rather than passed through, because a wallet showing a holder
+// "this mint closes on 31/12/2026" off a string nobody checked is worse
+// than showing nothing: a typo that parses as a date in 2027 buys the
+// holder confidence they have not earned, and one that parses as nothing
+// silently disables the warning the operator thought they had switched on.
+// Whole days only - an hour of notice is not notice.
+const sunsetDateFromEnv = (env) => {
+    const raw = env.MONEYER_SUNSET_DATE?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        throw new Error('MONEYER_SUNSET_DATE must be an ISO-8601 date, e.g. 2026-12-31.');
+    }
+    // Round-tripped, so 2026-02-31 is caught: Date accepts it and rolls it
+    // forward to 3 March, which is not the day the operator typed.
+    const parsed = new Date(`${raw}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== raw) {
+        throw new Error(`MONEYER_SUNSET_DATE is not a real date: ${JSON.stringify(raw)}.`);
+    }
+    return raw;
+};
 // MONEYER_PREVIOUS_SIGNING_PUBKEYS="02ab...,03cd..." - the keys this mint
 // signed under before the current one. Every entry must be a point the
 // curve accepts, because a typo here would quietly tell wallets to accept

package/dist/landing.js

@@ -93,6 +93,7 @@ ${mintPubkey ? `<div class="kv"><span>notes signed by</span><code>${escapeHtml(m
 ${nodeInfo.uri ? `<div class="kv"><span>node</span><code>${escapeHtml(nodeInfo.uri)}</code></div>` : ''}
 ${coverageLine ? `<div class="kv"><span>coverage</span><b>${escapeHtml(coverageLine)}</b></div>` : ''}
 ${config.sunset ? '<div class="kv"><span>status</span><b>sunsetting - redeem only</b></div>' : ''}
+${!config.sunset && config.sunsetDate ? `<div class="kv"><span>closing</span><b>${escapeHtml(config.sunsetDate)} - spend or move notes before then</b></div>` : ''}
 ${contacts.map(entry => `<div class="kv"><span>${entry.label}</span><code>${escapeHtml(entry.value)}</code></div>`).join('\n')}
 ${config.tosUrl ? `<div class="kv"><span>terms</span><a href="${escapeHtml(config.tosUrl)}" rel="noopener noreferrer">${escapeHtml(config.tosUrl)}</a></div>` : ''}
 </div>

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.
@@ -246,7 +249,25 @@ export const createMoneyer = async (config, deps = {}) => {
             ? { nodeCapacity: nodeInfo.capacityMsat, nodeCapacityMsat: nodeInfo.capacityMsat }
             : {}),
         ...(nodeInfo.numChannels !== undefined ? { nodeNumChannels: nodeInfo.numChannels } : {}),
-        ...(nodeInfo.numPeers !== undefined ? { nodeNumPeers: nodeInfo.numPeers } : {})
+        ...(nodeInfo.numPeers !== undefined ? { nodeNumPeers: nodeInfo.numPeers } : {}),
+        // Every address the node announces. nodeUri stays, and stays the
+        // first of these: a wallet that only reads the singular field must
+        // keep working, and the reference mint publishes both for the same
+        // reason.
+        ...(nodeInfo.uris?.length ? { nodeUris: nodeInfo.uris } : {}),
+        // Advance warning of a planned shutdown, so a wallet can tell its
+        // holder while spending is still possible.
+        ...(config.sunsetDate ? { sunsetDate: config.sunsetDate } : {}),
+        // What this mint owes, in msat: the combined value of every note it
+        // has issued and not burned. A fact about its own database, so it
+        // survives an unreachable funding source - but it is the same
+        // disclosure /stats makes, so it answers to the same two switches. An
+        // operator who has turned stats off, or down to the coverage ratio
+        // alone, has already said not to put the size of the book on the
+        // internet, and this endpoint is not a way around that.
+        ...(config.stats !== false && config.statsRatioOnly !== true
+            ? { outstandingNotesMsat: store.liabilities().outstandingMsat }
+            : {})
     });
     // An hourly signed snapshot, so the coverage history can be checked
     // after the fact rather than taken on the operator's word for it today.
@@ -629,19 +650,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 +681,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);
             }
@@ -758,22 +826,23 @@ export const createMoneyer = async (config, deps = {}) => {
             const hasH = q.has('h');
             const k1 = q.get('k1')?.toLowerCase();
             const h = q.get('h')?.toLowerCase();
-            if ((!hasK1 && !hasH) ||
+            if (hasK1 === hasH ||
                 (hasK1 && (!k1 || !HEX32.test(k1))) ||
                 (hasH && (!h || !HEX32.test(h)))) {
                 return fail('Unknown note.');
             }
             // 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. If both spellings are present, they must name the same
-            // note; choosing one would make a malformed URL an ownership oracle.
-            if (k1 && h && hashK1(k1) !== h)
-                return fail('Unknown note.');
+            // 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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.9.1",
+  "version": "0.11.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.7.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",