@forgesworn/moneyer 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.6.1] - 2026-08-24
+
+- The bundled web wallet now accepts a bound mint quote anywhere inside
+  the mint's advertised fee band, then uses the committed amount for the
+  signed receipt and note. A mint that rounds its fee up to a whole sat -
+  including moneyer's production default - no longer makes the page
+  silently abandon the sealed-signer receipt path for a legacy invoice.
+  Browser coverage uses the production `5000 msat + 1000 ppm`, sat-rounded
+  policy and proves the staged quote survives through settlement.
+- A resumable real-node bound-mint release check persists its bearer secret
+  with mode `0600` before requesting a quote, treats payer command output as
+  opaque, validates the settlement preimage and signed receipt, then melts
+  the whole test note to a fresh amountless refund invoice. Interrupted runs
+  resume from the same state file; successful runs scrub the secret and leave
+  no test-note liability behind.
+
+## [0.6.0] - 2026-08-24
+
+- **Bound mint settlement receipts.** A pay callback asked to mint at a
+  wallet-chosen `h` now commits the quote to `mint: {h, amount}` whenever
+  signing and LUD-21 verification are available. Before settlement the
+  response is unsigned; after settlement `/verify` repeats the commitment
+  and adds the ordinary LUD-25 note `sig`. This lets a sealed signer promote
+  a staged output without exporting its secret. No-`h`, unsigned and
+  verify-disabled deployments retain their previous response shapes.
+- The payRequest publishes `mintPubkey` when note signing is enabled, so a
+  receipt-aware wallet can establish the verification key before paying.
+- The bundled web client stages a wallet-chosen secret before requesting the
+  invoice, validates the quote and settled receipt, and falls back before
+  payment to the existing preimage-import-and-rotate flow when the optional
+  receipt is unavailable.
+
+- **A standing proof-of-concept disclaimer.** moneyer is an evaluation
+  implementation of a draft spec, its funding backends are beta, and a
+  note is bearer value with no recovery - so the site now says so at the
+  top, before anyone pays, rather than leaving it to a threat model
+  nobody opens. A prominent banner on the home page and the mint flow,
+  and on the fallback landing page: "Proof of concept · for developers …
+  assume you can lose anything you put in", with a link to the operator's
+  terms when `tosUrl` is set. Always on, because it is true of every
+  moneyer deployment as the spec stands. The per-step `warn` notes and
+  the operator MOTD are unchanged and sit alongside it.
+- **The fee says its own units.** `Mint fees: 5000,1000` is the shape
+  LUD-25 wallets parse - lnurlcash-kit matches it anchored and
+  digits-only, so it cannot carry units - and testers were reading both
+  numbers as satoshis. On a 10k sat mint that reads as a 5000 sat fee,
+  which is alarming and false. The prose beside it now spells the pair
+  out: `fee 5 sat + 0.1% (5000 msat + 1000 ppm), rounded up to the sat`.
+  The wire format is untouched.
+- The fee prose moves to `src/fee-words.ts`, the way `privacy.ts` already
+  holds the privacy statement, so the payRequest metadata and the
+  landing page cannot drift apart on it. The landing page had grown its
+  own second version reading `5000 msat flat + 0.1%`; it now uses the
+  shared one. `describeFee` is still exported from `server.ts`.
+- **Operator guidance on the custodial position.** `DEPLOY.md` gains a
+  "Before you run this" section: the regulatory perimeter follows the
+  operator rather than the code, how to configure an evaluation mint so
+  it reads as one, why **not** to zero the fee to make that point (a
+  fee-free mint pays the melt routing floor out of its own balance and is
+  griefable by mint-and-melt cycling - see `THREAT-MODEL.md`), and the
+  no-fiat invariant. moneyer is millisatoshis throughout, and that is
+  load-bearing rather than incidental.
+- `TERMS-TEMPLATE.md`, a starting point for `MONEYER_TOS_URL`. It defers
+  to the mint's own "what the mint knows" statement rather than restating
+  it, for the same no-drift reason.
+- **The regulatory guidance grows its missing teeth.** `DEPLOY.md`'s
+  "Before you run this" covered the payments perimeter and stopped there;
+  it now walks the UK regimes that actually bear on a custodial mint:
+  FCA registration under the Money Laundering Regulations 2017 (custody
+  is the live limb, and the travel rule the structural one - an anonymous
+  bearer instrument cannot carry originator and beneficiary information),
+  the financial promotion rules that gate marketing for an unregistered
+  operator (`MONEYER_ANNOUNCE` and the site copy both), sanctions, which
+  bind regardless of classification, and the cryptoasset custody regime
+  the 2025 draft legislation is bringing. `TERMS-TEMPLATE.md` gains the
+  liability floor consumer law insists on, a sanctions prohibited-use
+  clause, and a privacy notice in outline.
+
 ## [0.5.0] - 2026-08-23
 
 - **Both doors, named.** With `MONEYER_ONION_URL` and

package/README.md

@@ -66,6 +66,19 @@ node dist/cli.js
 The mint is then payable at `mint@mint.example` (and the bare-domain `_`
 alias).
 
+**Before you point one at mainnet**, read [Before you run this](DEPLOY.md)
+in the deployment guide. A mint holds other people's bitcoin as bearer
+liabilities, and it is the custody rather than the code that a regulator
+has a view on. In the UK that view is specific: the Money Laundering
+Regulations 2017 gate the custody of cryptoassets, by way of business, on
+FCA registration; the financial promotion rules gate how a mint may be
+marketed; sanctions law binds regardless. DEPLOY.md walks through all
+three. Two things carry most of the weight on the payments side: an
+evaluation mint should be configured as one (a fee kept at or below cost recovery rather
+than zeroed, no priced names, a small cap, a MOTD that says so - or
+better, a test network), and **no mint should ever touch fiat**. moneyer is millisatoshis throughout, deliberately, and that
+boundary is what keeps a mint clear of the payments and e-money regimes.
+
 ## Configuration
 
 Environment only. Every variable is `MONEYER_*`; anything unset takes the
@@ -327,7 +340,9 @@ 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, and the LUD-25 draft needs no change to allow it.
+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.
 
 The rules:
 
@@ -348,6 +363,13 @@ The rules:
 - The payRequest and the discovery document both advertise `mintToHash:
   true`, so a wallet knows this mint takes the parameter before it asks
   rather than after it pays.
+- When signing and LUD-21 verification are enabled, the quote also carries
+  `mint: {h, amount}`. This is the exact output and net millisatoshi value
+  the invoice will mint; it never carries `sig` before settlement.
+- Once settled, `/verify` repeats the same `h` and `amount` and adds `sig`,
+  the ordinary LUD-25 signature over `LNURLcash:<amount>:<h>`. A sealed
+  signer can verify that receipt against the pre-payment commitment and
+  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
@@ -360,6 +382,10 @@ A named 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.
 
+The proposed normative wire text, invalid cases and compatibility matrix are
+kept executable in
+[`lnurlcash-conformance`](https://github.com/TheCryptoDonkey/lnurlcash-conformance/blob/main/docs/BOUND-MINT-RECEIPTS.md).
+
 ## A retried mutation is answered, not refused
 
 Rotate, split and merge are GETs, and transports retry GETs. Go's

package/TERMS-TEMPLATE.md

@@ -0,0 +1,132 @@
+# Terms template
+
+A starting point for `MONEYER_TOS_URL`. Adapt it, host it, point the
+variable at it. Angle brackets mark what an operator must fill in; the
+rest is written to be true of any moneyer mint and should only change if
+your deployment makes it untrue.
+
+This is a template, not legal advice. If your mint holds value that would
+matter to the person who lost it, have someone qualified in your
+jurisdiction read this before you publish it.
+
+---
+
+## Terms for <mint.example>
+
+Last updated: <date>
+
+### What this is
+
+<mint.example> is an evaluation mint for the
+[LUD-25 draft](https://github.com/lnurl/luds/pull/301), running
+[moneyer](https://github.com/forgesworn/moneyer). It exists to
+demonstrate the protocol and to give wallet and mint implementers
+something to grade against.
+
+It is not a place to keep money. Notes on this mint are for testing the
+protocol, and you should not hold value here that you would mind losing.
+
+### What a note is
+
+A note is a bearer instrument. Whoever holds its secret can spend it, and
+the mint cannot tell one holder from another - there are no accounts, no
+passwords and no recovery. In particular:
+
+- **Lose the secret and the value is gone.** Nobody can restore it, this
+  mint included.
+- **Disclose the secret and whoever sees it can spend the note.** Treat it
+  the way you would treat cash.
+- A note is a claim on this mint and nothing else. It is not backed by any
+  third party, and it is not a claim on the Bitcoin network.
+
+### No guarantee of redemption
+
+This mint will try to honour every note it has struck. It does not
+promise to, and you should not rely on it doing so. Redemption can fail
+for reasons inside the operator's control and outside it: insufficient
+channel liquidity, a funding source that is down, a host that is gone, or
+the operator winding the mint down.
+
+The mint publishes what it owes and what it holds at `/stats`, updated
+continuously and signed hourly. Read it before you trust the mint with
+anything. A `coverage` figure below 1 means the mint could not pay every
+note out today.
+
+The service is provided as is, without warranty of any kind. To the
+fullest extent the law allows, the operator accepts no liability for any
+loss arising from its use. That sentence has a floor: nothing in these
+terms limits a liability the law does not allow to be limited, and if you
+use this mint as a consumer, the statutory rights your law does not let
+you sign away - in the UK, those the Consumer Rights Act 2015 implies -
+are unaffected.
+
+### Wind-down
+
+If this mint is retired, it will be put into sunset mode: it will refuse
+anything that grows what it owes, and keep every way out open, so
+outstanding notes can be melted. <Notice will be given through the mint's
+MOTD and at <contact> at least <n> days beforehand.> Notes not melted by
+then may not be redeemable.
+
+### Limits and fees
+
+- Smallest note: <n> sats. Largest note: <n> sats.
+- The mint fee is `<base> msat + <ppm> ppm`, published in the payRequest
+  metadata and on the discovery endpoint before you pay.
+
+The fee is set to recover the routing cost the mint commits to when it
+pays a note out, and is not priced to make a margin. The melt routing
+budget is `max(0.5% of the amount, 5000 msat, the mint fee)`, so above
+roughly 1,250 sats the fee does not cover it.
+
+### What the mint knows
+
+This mint is not blind, and that is a property of LUD-25 rather than a
+choice this deployment made. See
+[What the mint knows](<mint.example>) - published on the mint's own site
+and in its discovery document - for the full statement. In short: it
+knows every note it issued, what each is worth, the links between them,
+and the address each request came from. It does not know who holds a note
+between operations.
+
+Do not use this mint for anything where that matters to you.
+
+That statement is also the privacy notice in outline. The personal data
+are the network addresses requests arrive from and any zap names bound to
+pubkeys; the operator holds them to run the mint and for nothing else,
+keeps them for <retention period>, and does not sell or share them except
+under compulsion of law. Where your law gives you rights over your data -
+in the UK, the UK GDPR rights of access, correction and deletion -
+contact <contact> to exercise them.
+
+### What this mint is not
+
+- **Not a bank, and not a deposit-taker.** A note is not a deposit. There
+  is no depositor protection scheme behind it, in any jurisdiction.
+- **Not a payment or e-money service.** This mint accepts and pays out
+  bitcoin only. It does not accept, hold, or pay out any national
+  currency, and no note is denominated in one.
+- **Not a regulated financial service**, and not offered as one.
+  <The operator is not authorised or registered by <regulator>.>
+
+### Use
+
+Use this mint lawfully. Do not use it if you are designated under UK, UN,
+EU or US sanctions lists (or those of <jurisdiction>), and do not use it
+to move value to or for anyone who is: a bearer mint cannot screen its
+holders, so that duty sits with you. The operator may refuse or reverse
+service, and may cooperate with lawful requests from authorities in
+<jurisdiction>.
+
+### Operator and contact
+
+<Operated by <name>, <jurisdiction>. Reach the operator at <contact>.>
+
+### Changes
+
+These terms may change. The current version is always the one at this
+URL, and material changes will be flagged through the mint's MOTD.
+
+### Governing law
+
+<These terms are governed by the law of <jurisdiction>.>

package/dist/fee-words.d.ts

@@ -0,0 +1,6 @@
+export type MintFeeLike = {
+    baseFeeMsat: number;
+    feePpm: number;
+};
+export declare const feeInUnits: (fee: MintFeeLike | null, roundedToSat: boolean) => string;
+export declare const describeFee: (fee: MintFeeLike, roundedToSat: boolean) => string;

package/dist/fee-words.js

@@ -0,0 +1,37 @@
+// The mint fee as a person reads it, in one place so the payRequest
+// metadata, the landing page and the mint's own site cannot drift apart
+// on it - the same reason `privacy.ts` exists.
+//
+// The raw pair is spelled out deliberately. The machine-readable line
+// beside it in the payRequest metadata is "Mint fees: 5000,1000" - the
+// shape lnurlcash-kit parses, anchored and digits-only, so it cannot
+// carry its own units - and a reader who has not parsed LUD-25 reads
+// both numbers as satoshis. A tester who thinks the fee is 5000 sats on
+// a 10k sat mint has been told something alarming and false, so the
+// prose says msat and ppm where the wire cannot.
+// "5 sat + 0.1% (5000 msat + 1000 ppm), rounded up to the sat", or
+// "none". Bare, for a page that supplies its own "mint fee" label.
+export const feeInUnits = (fee, roundedToSat) => {
+    if (!fee)
+        return 'none';
+    const shown = [];
+    const raw = [];
+    if (fee.baseFeeMsat > 0) {
+        shown.push(`${fee.baseFeeMsat % 1000 === 0 ? fee.baseFeeMsat / 1000 : (fee.baseFeeMsat / 1000).toFixed(3)} sat`);
+        raw.push(`${fee.baseFeeMsat} msat`);
+    }
+    if (fee.feePpm > 0) {
+        shown.push(`${fee.feePpm / 10_000}%`);
+        raw.push(`${fee.feePpm} ppm`);
+    }
+    if (!shown.length)
+        return 'none';
+    const body = `${shown.join(' + ')} (${raw.join(' + ')})`;
+    return roundedToSat ? `${body}, rounded up to the sat` : body;
+};
+// The same fee prefixed for prose: "fee 5 sat + 0.1% (5000 msat + 1000
+// ppm)" - what a payer sees inside their wallet's description.
+export const describeFee = (fee, roundedToSat) => {
+    const words = feeInUnits(fee, roundedToSat);
+    return words === 'none' ? 'no fee' : `fee ${words}`;
+};

package/dist/landing.js

@@ -1,4 +1,5 @@
 import { MINT_KNOWS, MINT_KNOWS_HEADING } from "./privacy.js";
+import { feeInUnits } from "./fee-words.js";
 import { applyMintFee } from 'lnurlcash-kit';
 // The mint's face: one self-contained page at GET /, no build step, no
 // external assets. It states what a visitor needs before trusting a mint
@@ -11,9 +12,7 @@ export const landingPage = (args) => {
     const stats = args.stats ?? null;
     const address = `${config.username}@${host}`;
     const fee = config.mintFee;
-    const feeLine = fee
-        ? `${fee.baseFeeMsat > 0 ? `${fee.baseFeeMsat} msat flat` : ''}${fee.baseFeeMsat > 0 && fee.feePpm > 0 ? ' + ' : ''}${fee.feePpm > 0 ? `${fee.feePpm / 10_000}%` : ''}`
-        : 'none';
+    const feeLine = feeInUnits(fee, config.roundFeeToSat !== false);
     const maxNet = fee ? applyMintFee(config.maxSendableMsat, fee) : config.maxSendableMsat;
     const sats = (msat) => `${(msat / 1000).toLocaleString('en-GB')} sat`;
     const title = config.name ?? nodeInfo.alias ?? 'moneyer';
@@ -72,12 +71,17 @@ p.small{color:var(--dim);font-size:13.5px;line-height:1.65;text-align:center}
 .knows p{font-size:14px;line-height:1.65}
 .motd{background:var(--raise);border:1px solid var(--line);border-left:3px solid var(--accent);border-radius:14px;padding:14px 18px;font-size:14.5px;line-height:1.6}
 .motd b{display:block;font-size:12px;letter-spacing:.09em;text-transform:uppercase;color:var(--dim);margin-bottom:4px}
+.disclaimer{background:color-mix(in srgb,var(--warn,#c4a35e) 12%,var(--raise));border:1px solid color-mix(in srgb,var(--warn,#c4a35e) 50%,transparent);border-left:3px solid var(--warn,#c4a35e);border-radius:14px;padding:14px 18px;font-size:14.5px;line-height:1.55}
+.disclaimer b{display:block;font-size:11px;font-weight:700;letter-spacing:.13em;text-transform:uppercase;color:var(--warn,#c4a35e);margin-bottom:5px}
+.disclaimer strong{color:var(--warn,#c4a35e)}
+.disclaimer a{color:var(--ink);text-decoration:underline;text-underline-offset:2px}
 a{color:var(--accent)}
 </style>
 </head>
 <body>
 <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>
 ${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>

package/dist/live-check.d.ts

@@ -0,0 +1,48 @@
+import { type InvoiceResult } from 'lnurlcash-kit';
+export type LiveCheckStage = 'prepared' | 'quoted' | 'settled' | 'claimed' | 'retiring' | 'retired';
+export type LiveCheckState = {
+    version: 1;
+    stage: LiveCheckStage;
+    payUrl: string;
+    grossMsat: number;
+    h: string;
+    secret?: string;
+    netMsat?: number;
+    mintPubkey?: string;
+    payCallback?: string;
+    withdrawLink?: string;
+    quote?: InvoiceResult;
+    noteCallback?: string;
+    refundPr?: string;
+    refundPaymentHash?: string;
+    meltVerify?: string;
+    paymentPreimageValidated?: true;
+    receiptSignatureValidated?: true;
+    refundSettled?: true;
+    completedAt?: string;
+};
+export type LiveBoundMintCheckOptions = {
+    payUrl: string;
+    grossMsat: number;
+    statePath: string;
+    payInvoice: (pr: string) => Promise<void>;
+    createRefundInvoice: () => Promise<string>;
+    timeoutMs?: number;
+    pollMs?: number;
+    log?: (message: string) => void;
+};
+export type LiveBoundMintCheckResult = {
+    stage: 'retired';
+    payUrl: string;
+    grossMsat: number;
+    netMsat: number;
+    h: string;
+    mintPubkey: string;
+    paymentPreimageValidated: true;
+    receiptSignatureValidated: true;
+    refundSettled: true;
+    completedAt: string;
+};
+export declare const readLiveCheckState: (path: string) => Promise<LiveCheckState>;
+export declare const extractBolt11: (output: string) => string | null;
+export declare const runLiveBoundMintCheck: (options: LiveBoundMintCheckOptions) => Promise<LiveBoundMintCheckResult>;

package/dist/live-check.js

@@ -0,0 +1,378 @@
+import { randomBytes } from 'node:crypto';
+import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
+import { decodeBolt11 } from 'farrier-kit/bolt11';
+import { NoteSpentError, PendingNoteError, buildNoteUrl, claimMintedNote, decodeBolt11AmountMsat, fetchInvoiceVerification, fetchPayRequest, hashK1, isBolt11Invoice, isPreimage, meltNote, probeBurnedNote, requestInvoice, requireBoundMintQuote, validateBoundMintReceipt, withinMintFeeBand } from 'lnurlcash-kit';
+const stages = new Set(['prepared', 'quoted', 'settled', 'claimed', 'retiring', 'retired']);
+const errno = (error) => error && typeof error === 'object' && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
+const serialise = (state) => `${JSON.stringify(state, null, 2)}\n`;
+const writeNewState = async (path, state) => {
+    const handle = await open(path, 'wx', 0o600);
+    try {
+        await handle.writeFile(serialise(state), 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const assertSecureStateFile = async (path) => {
+    const stat = await lstat(path);
+    if (!stat.isFile())
+        throw new Error(`Live-check state is not a regular file: ${path}`);
+    if (typeof process.getuid === 'function') {
+        if (stat.uid !== process.getuid())
+            throw new Error(`Live-check state is not owned by this user: ${path}`);
+        if ((stat.mode & 0o077) !== 0)
+            throw new Error(`Live-check state must have mode 0600: ${path}`);
+    }
+};
+const replaceState = async (path, state) => {
+    await assertSecureStateFile(path);
+    const temporary = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+        await writeNewState(temporary, state);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+};
+const validateState = (value) => {
+    if (!value || typeof value !== 'object')
+        throw new Error('Live-check state is not an object.');
+    const state = value;
+    if (state.version !== 1 || !state.stage || !stages.has(state.stage))
+        throw new Error('Unsupported live-check state.');
+    if (typeof state.payUrl !== 'string' ||
+        typeof state.grossMsat !== 'number' ||
+        !Number.isSafeInteger(state.grossMsat) ||
+        state.grossMsat <= 0 ||
+        typeof state.h !== 'string' ||
+        !/^[0-9a-f]{64}$/.test(state.h)) {
+        throw new Error('Live-check state is incomplete.');
+    }
+    if (state.stage !== 'retired') {
+        if (typeof state.secret !== 'string' || !isPreimage(state.secret) || hashK1(state.secret) !== state.h) {
+            throw new Error('Live-check state does not contain the secret committed by h.');
+        }
+    }
+    return state;
+};
+export const readLiveCheckState = async (path) => {
+    await assertSecureStateFile(path);
+    return validateState(JSON.parse(await readFile(path, 'utf8')));
+};
+const loadOrCreateState = async (options) => {
+    let state;
+    try {
+        state = await readLiveCheckState(options.statePath);
+    }
+    catch (error) {
+        if (errno(error) !== 'ENOENT')
+            throw error;
+        const secret = randomBytes(32).toString('hex');
+        state = {
+            version: 1,
+            stage: 'prepared',
+            payUrl: options.payUrl,
+            grossMsat: options.grossMsat,
+            secret,
+            h: hashK1(secret)
+        };
+        try {
+            // This fsync completes before a quote exists. A crash from here on
+            // can lose an index or an unpaid invoice, never the bearer secret.
+            await writeNewState(options.statePath, state);
+        }
+        catch (writeError) {
+            if (errno(writeError) !== 'EEXIST')
+                throw writeError;
+            state = await readLiveCheckState(options.statePath);
+        }
+    }
+    if (state.payUrl !== options.payUrl || state.grossMsat !== options.grossMsat) {
+        throw new Error('Existing live-check state belongs to a different mint or amount.');
+    }
+    return state;
+};
+const stringsIn = (value) => {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(stringsIn);
+    if (value && typeof value === 'object')
+        return Object.values(value).flatMap(stringsIn);
+    return [];
+};
+// `lncli` has emitted JSON in some versions and a display table in others.
+// The release check only needs an invoice from the refund command; it does
+// not treat either presentation as an API contract.
+export const extractBolt11 = (output) => {
+    const trimmed = output.trim();
+    if (isBolt11Invoice(trimmed))
+        return trimmed;
+    try {
+        for (const candidate of stringsIn(JSON.parse(trimmed))) {
+            if (isBolt11Invoice(candidate))
+                return candidate.trim();
+        }
+    }
+    catch {
+        // Human-readable output is handled below.
+    }
+    for (const match of output.matchAll(/ln(?:bc|tb|bcrt|tbs|sb)[0-9]*[munp]?1[a-z0-9]+/gi)) {
+        if (isBolt11Invoice(match[0]))
+            return match[0].trim();
+    }
+    return null;
+};
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const waitForSettled = async (verifyUrl, timeoutMs, pollMs) => {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() <= deadline) {
+        try {
+            const verification = await fetchInvoiceVerification(verifyUrl);
+            if (verification.settled)
+                return verification;
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await sleep(pollMs);
+    }
+    const detail = lastError instanceof Error ? ` Last response: ${lastError.message}` : '';
+    throw new Error(`Timed out waiting for settlement.${detail}`);
+};
+const existingVerification = async (verifyUrl) => {
+    try {
+        return await fetchInvoiceVerification(verifyUrl);
+    }
+    catch {
+        return null;
+    }
+};
+const requireQuotedState = (state) => {
+    if (!state.secret ||
+        state.netMsat === undefined ||
+        !state.mintPubkey ||
+        !state.payCallback ||
+        !state.withdrawLink ||
+        !state.quote?.verify) {
+        throw new Error('Quoted live-check state is incomplete.');
+    }
+    const commitment = requireBoundMintQuote(state.quote, state.h, state.netMsat);
+    if (commitment.signature !== undefined)
+        throw new Error('The pre-payment commitment unexpectedly carries a signature.');
+    return {
+        secret: state.secret,
+        netMsat: state.netMsat,
+        mintPubkey: state.mintPubkey,
+        payCallback: state.payCallback,
+        withdrawLink: state.withdrawLink,
+        quote: state.quote
+    };
+};
+const retiredResult = (state) => {
+    if (state.stage !== 'retired' ||
+        state.netMsat === undefined ||
+        !state.mintPubkey ||
+        !state.completedAt ||
+        state.paymentPreimageValidated !== true ||
+        state.receiptSignatureValidated !== true ||
+        state.refundSettled !== true) {
+        throw new Error('Retired live-check state is incomplete.');
+    }
+    return {
+        stage: 'retired',
+        payUrl: state.payUrl,
+        grossMsat: state.grossMsat,
+        netMsat: state.netMsat,
+        h: state.h,
+        mintPubkey: state.mintPubkey,
+        paymentPreimageValidated: true,
+        receiptSignatureValidated: true,
+        refundSettled: true,
+        completedAt: state.completedAt
+    };
+};
+export const runLiveBoundMintCheck = async (options) => {
+    if (!Number.isSafeInteger(options.grossMsat) || options.grossMsat <= 0)
+        throw new Error('grossMsat must be a positive integer.');
+    new URL(options.payUrl);
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const pollMs = options.pollMs ?? 500;
+    const log = options.log ?? (() => { });
+    let state = await loadOrCreateState(options);
+    if (state.stage === 'retired')
+        return retiredResult(state);
+    if (state.stage === 'prepared') {
+        const pay = await fetchPayRequest(state.payUrl);
+        if (!pay.mintToHash || !pay.mintPubkey || !pay.withdrawLink) {
+            throw new Error('Mint does not advertise the bound-mint receipt capabilities required by this check.');
+        }
+        if (state.grossMsat < pay.minSendable || state.grossMsat > pay.maxSendable) {
+            throw new Error(`Test amount is outside the mint range ${pay.minSendable}-${pay.maxSendable} msat.`);
+        }
+        const quote = await requestInvoice(pay.callback, state.grossMsat, { h: state.h });
+        if (!quote.verify || !quote.mint)
+            throw new Error('Mint did not bind this quote to h and a verification URL.');
+        const netMsat = quote.mint.amountMsat;
+        if (!Number.isSafeInteger(netMsat) || netMsat <= 0)
+            throw new Error('Mint committed an invalid net note amount.');
+        const feeAccepted = pay.mintFee
+            ? withinMintFeeBand(state.grossMsat, netMsat, pay.mintFee)
+            : netMsat === state.grossMsat;
+        if (!feeAccepted)
+            throw new Error('Mint committed a net amount outside its advertised fee band.');
+        const commitment = requireBoundMintQuote(quote, state.h, netMsat);
+        if (commitment.signature !== undefined)
+            throw new Error('The pre-payment commitment unexpectedly carries a signature.');
+        state = {
+            ...state,
+            stage: 'quoted',
+            netMsat,
+            mintPubkey: pay.mintPubkey,
+            payCallback: pay.callback,
+            withdrawLink: pay.withdrawLink,
+            quote
+        };
+        await replaceState(options.statePath, state);
+        log(`quote committed ${netMsat} msat at the staged note hash`);
+    }
+    const quoted = requireQuotedState(state);
+    if (state.stage === 'quoted') {
+        let verification = await fetchInvoiceVerification(quoted.quote.verify);
+        if (!verification.settled) {
+            let payerError;
+            try {
+                // Stdout is deliberately outside this interface. Exit status says
+                // whether the command believes it paid; /verify supplies the proof.
+                await options.payInvoice(quoted.quote.pr);
+            }
+            catch (error) {
+                payerError = error;
+            }
+            try {
+                verification = await waitForSettled(quoted.quote.verify, timeoutMs, pollMs);
+            }
+            catch (error) {
+                if (payerError instanceof Error) {
+                    throw new Error(`${error instanceof Error ? error.message : String(error)} Payer command: ${payerError.message}`);
+                }
+                throw error;
+            }
+        }
+        const receipt = validateBoundMintReceipt(quoted.quote, verification, state.h, quoted.netMsat, quoted.mintPubkey);
+        const paymentHash = decodeBolt11(quoted.quote.pr).paymentHashHex;
+        if (!verification.preimage || hashK1(verification.preimage) !== paymentHash) {
+            throw new Error('The settlement preimage does not prove the quoted invoice.');
+        }
+        if (!receipt.signature)
+            throw new Error('The settled receipt has no signature.');
+        state = { ...state, stage: 'settled' };
+        await replaceState(options.statePath, state);
+        log('settlement preimage and bound receipt signature validated');
+    }
+    if (state.stage === 'settled') {
+        const claim = await claimMintedNote(quoted.withdrawLink, quoted.secret);
+        if (claim.state !== 'minted' || claim.amountMsat !== quoted.netMsat || !claim.callback) {
+            throw new Error('The staged secret did not claim the committed note.');
+        }
+        state = { ...state, stage: 'claimed', noteCallback: claim.callback };
+        await replaceState(options.statePath, state);
+        log('the staged secret claimed the committed note');
+    }
+    if (state.stage === 'claimed') {
+        if (!state.noteCallback)
+            throw new Error('Claimed live-check state has no note callback.');
+        const refundOutput = await options.createRefundInvoice();
+        const refundPr = extractBolt11(refundOutput);
+        if (!refundPr)
+            throw new Error('Refund command did not emit a BOLT11 invoice.');
+        if (decodeBolt11AmountMsat(refundPr) !== null) {
+            throw new Error('Refund invoice must be amountless so the mint retires the entire test note.');
+        }
+        const refundPaymentHash = decodeBolt11(refundPr).paymentHashHex;
+        const meltVerify = new URL(`/verify/${refundPaymentHash}`, quoted.withdrawLink).toString();
+        // Persist the exact refund invoice before asking the mint to pay it.
+        // A crash after the callback can therefore resume without inventing a
+        // second payment target or losing the note secret.
+        state = { ...state, stage: 'retiring', refundPr, refundPaymentHash, meltVerify };
+        await replaceState(options.statePath, state);
+    }
+    if (state.stage === 'retiring') {
+        if (!state.noteCallback || !state.refundPr || !state.meltVerify) {
+            throw new Error('Retiring live-check state is incomplete.');
+        }
+        let verification = await existingVerification(state.meltVerify);
+        if (verification === null) {
+            try {
+                const result = await meltNote(state.noteCallback, quoted.secret, state.refundPr);
+                if (result.verify && result.verify !== state.meltVerify) {
+                    throw new Error('Mint returned a different verification URL for the refund melt.');
+                }
+            }
+            catch (error) {
+                if (!(error instanceof PendingNoteError) && !(error instanceof NoteSpentError))
+                    throw error;
+            }
+            verification = await existingVerification(state.meltVerify);
+        }
+        if (!verification?.settled) {
+            try {
+                verification = await waitForSettled(state.meltVerify, timeoutMs, pollMs);
+            }
+            catch (error) {
+                // A cleanly failed melt restores the note. Clear the used refund
+                // invoice but retain the secret, so the same command can retry with
+                // a fresh amountless invoice rather than stranding value.
+                const claim = await claimMintedNote(quoted.withdrawLink, quoted.secret).catch(() => null);
+                if (claim?.state === 'minted' && claim.callback) {
+                    state = {
+                        version: 1,
+                        stage: 'claimed',
+                        payUrl: state.payUrl,
+                        grossMsat: state.grossMsat,
+                        h: state.h,
+                        secret: quoted.secret,
+                        netMsat: quoted.netMsat,
+                        mintPubkey: quoted.mintPubkey,
+                        payCallback: quoted.payCallback,
+                        withdrawLink: quoted.withdrawLink,
+                        quote: quoted.quote,
+                        noteCallback: claim.callback
+                    };
+                    await replaceState(options.statePath, state);
+                    throw new Error(`Refund melt failed cleanly and the note was restored; rerun to use a fresh invoice. ${error instanceof Error ? error.message : ''}`);
+                }
+                throw error;
+            }
+        }
+        const noteUrl = buildNoteUrl(quoted.withdrawLink, quoted.secret, quoted.netMsat);
+        const deadline = Date.now() + timeoutMs;
+        while ((await probeBurnedNote(noteUrl)) !== 'gone') {
+            if (Date.now() > deadline)
+                throw new Error('Refund settled but the test note is not yet recorded as burned.');
+            await sleep(pollMs);
+        }
+        const completedAt = new Date().toISOString();
+        state = {
+            version: 1,
+            stage: 'retired',
+            payUrl: state.payUrl,
+            grossMsat: state.grossMsat,
+            netMsat: quoted.netMsat,
+            h: state.h,
+            mintPubkey: quoted.mintPubkey,
+            paymentPreimageValidated: true,
+            receiptSignatureValidated: true,
+            refundSettled: true,
+            completedAt
+        };
+        await replaceState(options.statePath, state);
+        log('refund settled and the test note was burned; bearer secret scrubbed from state');
+    }
+    return retiredResult(state);
+};

package/dist/server.d.ts

@@ -29,9 +29,6 @@ export type MoneyerDeps = {
     zapPollMs?: number;
     statsPublishMs?: number;
 };
-export declare const describeFee: (fee: {
-    baseFeeMsat: number;
-    feePpm: number;
-}, roundedToSat: boolean) => string;
+export { describeFee } from './fee-words.ts';
 export declare const createMoneyer: (config: MoneyerConfig, deps?: MoneyerDeps) => Promise<Moneyer>;
 export declare const sweepExpiredMintInvoices: (store: NoteStore, nowMs?: number) => number;

package/dist/server.js

@@ -5,6 +5,7 @@ import { applyMintFee, grossUpForMintFee, hashK1 } from 'lnurlcash-kit';
 import { tryDecodeBolt11 } from 'farrier-kit/bolt11';
 import { NotePendingError, NoteStore, NoteUnavailableError, OutputCollisionError, swapFingerprint } from "./store.js";
 import { createNoteSigner } from "./signing.js";
+import { describeFee } from "./fee-words.js";
 import { createFakeBackend } from "./backends/fake.js";
 import { createClnBackend } from "./backends/cln.js";
 import { createLndBackend } from "./backends/lnd.js";
@@ -34,16 +35,7 @@ const readBody = async (req, limit = MAX_BODY_BYTES) => {
     }
     return Buffer.concat(chunks).toString('utf8');
 };
-// "fee 5 sat + 0.1%" - what a payer sees in their wallet's description.
-export const describeFee = (fee, roundedToSat) => {
-    const parts = [];
-    if (fee.baseFeeMsat > 0)
-        parts.push(`${fee.baseFeeMsat % 1000 === 0 ? fee.baseFeeMsat / 1000 : (fee.baseFeeMsat / 1000).toFixed(3)} sat`);
-    if (fee.feePpm > 0)
-        parts.push(`${(fee.feePpm / 10_000).toString()}%`);
-    const base = parts.length ? `fee ${parts.join(' + ')}` : 'no fee';
-    return roundedToSat && parts.length ? `${base}, rounded up to the sat` : base;
-};
+export { describeFee } from "./fee-words.js";
 // A note's value rounded down to a whole sat; unchanged when already whole.
 const wholeSatFloor = (msat) => Math.floor(msat / 1000) * 1000;
 const backendFor = (config) => {
@@ -550,6 +542,9 @@ export const createMoneyer = async (config, deps = {}) => {
                 // LUD-17's lnurlw:// is the scheme a wallet puts on a QR, not a
                 // field in a JSON body; every other URL here is directly fetchable.
                 withdrawLink: `${origin}/w`,
+                // Receipt-aware wallets need the note-signing key before they pay,
+                // so they can authenticate the later LUD-21 mint receipt.
+                ...(signer ? { mintPubkey: signer.pubkey } : {}),
                 // This mint takes `h` on the callback below, so a wallet can name
                 // the note it is buying. Advertised here as well as on the
                 // discovery document because a wallet handed nothing but a
@@ -659,6 +654,12 @@ export const createMoneyer = async (config, deps = {}) => {
                 // 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 } : {}),
+                // 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
+                    ? { mint: { h: outputId, amount: net } }
+                    : {}),
                 ...(config.verify ? { verify: `${origin}/verify/${paymentHash}` } : {})
             });
         }
@@ -673,11 +674,30 @@ export const createMoneyer = async (config, deps = {}) => {
                 if (!invoice.settled && (await backend.isInvoiceSettled(paymentHash))) {
                     store.settleMintInvoice(paymentHash);
                 }
-                const settled = store.mintInvoiceByHash(paymentHash).settled;
+                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.
                 const preimageHex = settled ? await backend.invoicePreimage(paymentHash) : null;
-                return send({ status: 'OK', settled, preimage: preimageHex, pr: invoice.pr });
+                return send({
+                    status: 'OK',
+                    settled,
+                    preimage: preimageHex,
+                    pr: invoice.pr,
+                    // Repeating h and amount binds this response to the quote. The
+                    // ordinary note signature appears only once value exists at h.
+                    ...(currentInvoice.outputId !== null && signer
+                        ? {
+                            mint: {
+                                h: currentInvoice.outputId,
+                                amount: currentInvoice.netMsat,
+                                ...(settled
+                                    ? { sig: signer.sign(currentInvoice.outputId, currentInvoice.netMsat) }
+                                    : {})
+                            }
+                        }
+                        : {})
+                });
             }
             const melt = store.meltByHash(paymentHash);
             if (melt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "An LNURLcash (LUD-25) mint - strikes Lightning bearer notes. Independent implementation, cln/lnd funding sources, SQLite, zero HTTP framework.",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -32,11 +32,13 @@
   "files": [
     "dist",
     "web/dist",
+    "scripts/live-bound-mint-check.mjs",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
     "THREAT-MODEL.md",
+    "TERMS-TEMPLATE.md",
     "llms.txt"
   ],
   "scripts": {
@@ -50,14 +52,15 @@
     "web:dev": "vite web",
     "web:build": "vite build web",
     "web:preview": "vite preview web",
-    "typecheck:web": "tsc -p web"
+    "typecheck:web": "tsc -p web",
+    "live:bound-mint": "npm run build && node scripts/live-bound-mint-check.mjs"
   },
   "dependencies": {
     "@noble/curves": "^2.3.0",
     "@noble/hashes": "^2.3.0",
     "@scure/base": "^1.2.4",
     "farrier-kit": "^1.1.3",
-    "lnurlcash-kit": "^0.2.0",
+    "lnurlcash-kit": "^0.3.0",
     "nostr-tools": "2.24.1"
   },
   "devDependencies": {
@@ -67,7 +70,7 @@
     "@types/node": "^24.0.0",
     "animejs": "^4.0.0",
     "happy-dom": "^20.0.0",
-    "lnurlcash-conformance": "^0.2.1",
+    "lnurlcash-conformance": "^0.3.0",
     "playwright": "^1.62.1",
     "typescript": "^5.7.0",
     "uqr": "^0.1.2",

package/scripts/live-bound-mint-check.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// A resumable, real-sats bound-mint release check.
+//
+// The payer command receives the mint invoice as its final argument. Its
+// stdout is intentionally ignored: lnd has emitted JSON and tables across
+// versions, while Moneyer's /verify response is the settlement proof that
+// matters. The refund command receives no added arguments and must print an
+// amountless BOLT11 invoice; Moneyer melts the whole test note back to it.
+import {spawnSync} from 'node:child_process'
+import {resolve} from 'node:path'
+import {runLiveBoundMintCheck} from '../dist/live-check.js'
+
+const usage = `usage:
+  npm run live:bound-mint -- \\
+    --pay-url https://mint.example/.well-known/lnurlp/mint \\
+    --amount-sat 56 \\
+    --state /secure/path/moneyer-live-check.json \\
+    --payer <command...> \\
+    --refund <command...>
+
+The payer command gets the BOLT11 invoice as its final argument. The refund
+command must emit a fresh amountless BOLT11 invoice on stdout. State is mode
+0600 and resumable; rerun the exact command after any interruption.`
+
+const failUsage = message => {
+  if (message) console.error(message)
+  console.error(usage)
+  process.exit(2)
+}
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(usage)
+  process.exit(0)
+}
+
+const payerAt = args.indexOf('--payer')
+const refundAt = args.indexOf('--refund')
+if (payerAt < 0 || refundAt < 0 || refundAt <= payerAt) failUsage('Both --payer and --refund commands are required.')
+
+const optionArgs = args.slice(0, payerAt)
+const payerArgv = args.slice(payerAt + 1, refundAt)
+const refundArgv = args.slice(refundAt + 1)
+if (payerArgv.length === 0 || refundArgv.length === 0) failUsage('Command markers may not be empty.')
+
+const values = new Map()
+for (let index = 0; index < optionArgs.length; index += 2) {
+  const name = optionArgs[index]
+  const value = optionArgs[index + 1]
+  if (!name?.startsWith('--') || value === undefined) failUsage(`Invalid option near ${name ?? '(end)'}.`)
+  if (!['--pay-url', '--amount-sat', '--state', '--timeout-seconds'].includes(name)) failUsage(`Unknown option ${name}.`)
+  values.set(name, value)
+}
+
+const payUrl = values.get('--pay-url')
+const amountSat = Number(values.get('--amount-sat'))
+const stateValue = values.get('--state')
+const timeoutSeconds = values.has('--timeout-seconds') ? Number(values.get('--timeout-seconds')) : 60
+if (!payUrl || !stateValue) failUsage('--pay-url, --amount-sat and --state are required.')
+if (!Number.isSafeInteger(amountSat) || amountSat <= 0) failUsage('--amount-sat must be a positive whole number.')
+if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) failUsage('--timeout-seconds must be positive.')
+
+const runCommand = (argv, appended = []) => {
+  const [program, ...commandArgs] = argv
+  const result = spawnSync(program, [...commandArgs, ...appended], {
+    encoding: 'utf8',
+    maxBuffer: 4 * 1024 * 1024,
+    timeout: timeoutSeconds * 1000
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    const detail = result.stderr.trim().slice(0, 500)
+    throw new Error(`command exited ${result.status}${detail ? `: ${detail}` : ''}`)
+  }
+  return result.stdout
+}
+
+const statePath = resolve(stateValue)
+try {
+  const result = await runLiveBoundMintCheck({
+    payUrl,
+    grossMsat: amountSat * 1000,
+    statePath,
+    timeoutMs: timeoutSeconds * 1000,
+    payInvoice: async pr => {
+      // Deliberately do not parse or print this output. Settlement is proved
+      // independently by the invoice preimage and signed mint receipt.
+      runCommand(payerArgv, [pr])
+    },
+    createRefundInvoice: async () => runCommand(refundArgv),
+    log: message => console.error(`[live-check] ${message}`)
+  })
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) {
+  console.error(`[live-check] ${error instanceof Error ? error.message : String(error)}`)
+  console.error(`[live-check] state retained at ${statePath}; rerun the exact command to resume`)
+  process.exitCode = 1
+}