@forgesworn/moneyer 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## [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
+  `MONEYER_PUBLIC_ORIGIN` both set, `/w` and the mint address now carry
+  `mirrors`: this mint's other origin. Both serve the same notes - a note
+  is keyed by `sha256(k1)` and not by host - but a note travels as a URL,
+  and a URL names one host, so an onion note handed to somebody without
+  Tor is unspendable to them. Naming the other door is what lets a wallet
+  offer the holder a way across.
+- Absent rather than empty when there is only one door, because a wallet
+  reading `[]` would think it had been told something. The hourly Nostr
+  announcement carries it too.
+- Documented, because it is a real limit rather than a missing feature: a
+  wallet must **not** fail over to a mirror on its own. Every request that
+  identifies a note carries the k1, and nothing in LUD-25 lets a host
+  prove it is the same mint before receiving that secret - a hostile
+  discovery document can name any host and claim any `mintPubkey`, since
+  claiming is not proving. Closing it needs a signed challenge the spec
+  does not have.
+
 ## [0.4.0] - 2026-08-23
 
 - **Reaching the mint over Tor.** `MONEYER_ONION_URL` names this mint's

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
@@ -507,6 +533,37 @@ controlled, and that property is unchanged: the worst a forged Host can do
 is get back the onion URL instead of the clearnet one, and the operator
 configured both. Anything else falls through to `MONEYER_PUBLIC_ORIGIN`.
 
+### Serving both audiences at once
+
+Both doors serve the **same notes**. A note is keyed by `sha256(k1)` and
+not by host, so a k1 struck on the onion is valid at the clearnet host and
+the other way round. What is bound to a host is only the URL a note
+travels as - and an onion note handed to somebody without Tor is
+unspendable to them, while a clearnet note redeemed over Tor is private
+only if their wallet proxies.
+
+So when both are configured, `/w` and the mint address name the other one
+in `mirrors`:
+
+```json
+{"tag": "withdrawRequest", "callback": "http://<v3>.onion/w/cb",
+ "mirrors": ["https://mint.example"], "mintPubkey": "..."}
+```
+
+Absent when there is only one door, rather than an empty array - a wallet
+reading `[]` would think it had been told something. The hourly Nostr
+announcement carries it too, so a wallet that discovers this mint on a
+relay learns both doors before it holds anything.
+
+**A wallet must not fail over to a mirror on its own.** Every request that
+identifies a note carries the k1, so switching hosts discloses a bearer
+secret to the new one, and nothing in LUD-25 lets a host prove it is the
+same mint before receiving that secret - a hostile discovery document can
+name any host and claim any `mintPubkey`, because claiming is not proving.
+Show the holder the other door and let them choose it. Closing that
+properly needs a challenge the mint signs, which the spec does not have
+yet.
+
 Running the hidden service itself is not this mint's job. Point a Tor
 `HiddenServiceDir` (or a proxy that speaks onion) at whatever host and port
 it already listens on, the same way you would front it with Caddy for

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/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) => {
@@ -208,7 +200,7 @@ export const createMoneyer = async (config, deps = {}) => {
     // LUD-25 discovery, built here rather than inline in its route because
     // the mint also announces itself with it, and there must be one
     // description of a mint rather than two that can drift apart.
-    const mintAddressDocument = (origin, user) => ({
+    const mintAddressDocument = (origin, user, mirrors = []) => ({
         tag: 'withdrawRequest',
         callback: `${origin}/w`,
         minWithdrawable: config.minMintMsat,
@@ -217,6 +209,7 @@ export const createMoneyer = async (config, deps = {}) => {
             : config.maxSendableMsat,
         defaultDescription: config.description,
         payLink: `${origin}/.well-known/lnurlp/${user}`,
+        ...(mirrors.length ? { mirrors } : {}),
         ...(signer ? { mintPubkey: signer.pubkey } : {}),
         // The human layer: who runs this, how to reach them, the terms,
         // and today's message. Absent unless the operator set it.
@@ -294,7 +287,7 @@ export const createMoneyer = async (config, deps = {}) => {
             kind: ANNOUNCE_KIND,
             created_at: Math.floor(Date.now() / 1000),
             tags: [['d', ANNOUNCE_D_TAG]],
-            content: announcementContent(mintAddressDocument(config.publicOrigin, config.username), config.signingKey)
+            content: announcementContent(mintAddressDocument(config.publicOrigin, config.username, config.onionUrl ? [config.onionUrl] : []), config.signingKey)
         }, hexToBytes(config.zap.nostrKey));
         const { ok, failed } = await nostr.publish(config.zap.relays, event);
         log(`mint announced to ${ok.length} relay${ok.length === 1 ? '' : 's'}${failed.length ? `, ${failed.length} refused` : ''}`);
@@ -311,6 +304,14 @@ export const createMoneyer = async (config, deps = {}) => {
         const origin = onionHost && askedFor === onionHost
             ? config.onionUrl
             : (config.publicOrigin ?? `http://${req.headers.host ?? '127.0.0.1'}`);
+        // This mint's OTHER doors. A note is keyed by sha256(k1) and not by
+        // host, so every one of these serves the same notes - but a note
+        // travels as a URL, and a URL names one host. An onion note handed to
+        // somebody without Tor is unspendable to them, and a clearnet note
+        // redeemed over Tor is only private if their wallet proxies. Saying
+        // which other host answers is what lets a wallet move a note between
+        // them instead of the holder finding out it cannot.
+        const mirrors = [config.publicOrigin, config.onionUrl].filter((candidate) => Boolean(candidate) && candidate !== origin);
         const host = new URL(origin).host;
         const send = (body, status = 200) => {
             res.writeHead(status, {
@@ -541,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
@@ -555,7 +559,7 @@ export const createMoneyer = async (config, deps = {}) => {
         if (lnurlwMatch) {
             if (!knownUser(lnurlwMatch[1]))
                 return fail('Unknown user.', 404);
-            return send(mintAddressDocument(origin, lnurlwMatch[1]));
+            return send(mintAddressDocument(origin, lnurlwMatch[1], mirrors));
         }
         // ---- LUD-06 pay callback: issue a mint invoice ----
         if (requestUrl.pathname === '/p/cb') {
@@ -650,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}` } : {})
             });
         }
@@ -664,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) {
@@ -725,6 +754,10 @@ export const createMoneyer = async (config, deps = {}) => {
                 // signing keys. Without it a wallet that only ever received notes
                 // cannot tell an announced key rotation from a substituted key.
                 payLink: `${origin}/.well-known/lnurlp/${config.username}`,
+                // Where else this same note can be redeemed. A holder with nothing
+                // but a note learns from the note itself that the other door
+                // exists.
+                ...(mirrors.length ? { mirrors } : {}),
                 ...(signer ? { mintPubkey: signer.pubkey } : {})
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -37,6 +37,7 @@
     "CHANGELOG.md",
     "SECURITY.md",
     "THREAT-MODEL.md",
+    "TERMS-TEMPLATE.md",
     "llms.txt"
   ],
   "scripts": {
@@ -57,7 +58,7 @@
     "@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 +68,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",