@forgesworn/moneyer 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.17.0 - 2026-09-26
+
+LUD-25's unified taproot model (lnurl/luds 6e865b1). Every note is now a
+BIP-341 taproot output key Q, and that is what the mint stores, burns and
+certifies.
+
+Also LUD-25's derivation purposes and renames (lnurl/luds 1286380..50d740a),
+which change every key a `cx1` derives:
+
+- **Lightning Address payments land on purpose 2.** A name's zaps are
+  credited at `tagged_hash("LNURLcash/derive", P || chaincode || ser32(2) ||
+  ser32(i))`, a counter of their own, and every name's counter restarts at 0
+  once on upgrade. The internal-transfer hint counts the same purpose.
+- **The address proof is by the purpose-0 index-0 key.** A `sig` made with
+  the old unpurposed index-0 key no longer verifies, so a wallet must be
+  upgraded before it can set or clear a name's `cx1`.
+- **`c` and `c2`.** Certificates go out as `c`/`c2`, with the older
+  `sig`/`sig2` alongside carrying the same value for now. A key wrap's
+  lookup URL carries `&c=`.
+- **`text/cpub`, not `text/xpub`.** The payRequest's internal-transfer hint
+  is renamed, and the old name is dropped rather than doubled: a wallet
+  reading `text/xpub` derives without a purpose and would transfer to a key
+  the payee never scans. It pays by Lightning instead.
+- The older `ck1` shapes are still accepted although the reference mint has
+  dropped them: Heartwood firmware still signs the 65-byte one.
+
+- **Notes are keyed by Q.** A comment, `p`, `p1` or `p2` of 64 hex is a
+  bearer note's h, credited at the Q of its `OP_SHA256 <h> OP_EQUAL` leaf
+  under the NUMS key; a `cp1` is Q itself, and is refused unless Q is on the
+  curve. A 64-hex value there never names a key note any more: that is how
+  the spec reads it now.
+- **`ck1` is bound to this mint.** Its signature is over the key-path
+  sighash of the canonical spend transaction, whose prevout commits to the
+  domain, so a `ck1` seen by one mint cannot be spent at another. Any of the
+  mint's own hosts counts: `MONEYER_PUBLIC_ORIGIN`'s and
+  `MONEYER_ONION_URL`'s. The older `ck1`s (Schnorr over `sha256("LNURLcash")`
+  or the raw string, and the 65-byte recoverable shape) are still accepted,
+  as the reference mint accepts them, so notes already handed out stay
+  redeemable.
+- **`cw1` script-path spends.** A bearer note's full `cw1` is the same note
+  as its preimage. Leaf versions other than `0xc0` and `OP_SUCCESSx` leaves
+  are refused, and time claims are checked against the mint's clock: Unix
+  times only, relative locks counted from when the note was credited.
+  Bearer hashlock leaves are evaluated here. Any other leaf goes to Bitcoin
+  Core's interpreter when `MONEYER_SCRIPT_VERIFIER` runs
+  `scripts/kernel-verifier.py` (lnurlcash-kernel, the reference mint's
+  verifier) or a `scriptVerifier` is passed to `createMoneyer`; without one
+  it is refused with a reason and the note left outstanding. A verifier
+  that crashes, errors or stalls refuses, never accepts.
+- **Every note is certified.** The callback's `c`/`c2` and the
+  informational GET's `c` are a `cs1` over hex(Q) for bearer notes as well
+  as key notes, reversing 0.14.0's "a plain note is unsigned". The LUD-21
+  bound receipt still signs exactly the `h` it repeats.
+- **The informational GET verifies the spend in full.** A `ck1` whose
+  signature does not open its note gets `Unknown note.`, and a `cw1`'s own
+  failure reason is passed on. The `k1` is echoed exactly as sent.
+- **`already in use`.** An output, or a mint comment, naming a note that is
+  outstanding, burned, or awaited by an invoice gets LUD-25's exact reason.
+- **Retries match on Q.** A completed rotate, split or merge retried with a
+  different spelling of the same spend (a preimage for its `cw1`, say) is
+  answered as the replay it is. Mutations completed before the upgrade
+  still match under their old fingerprint.
+- **Setting a name's `cx1` needs the address proof.** `POST /names` now
+  requires `sig`, a BIP-340 signature by the branch's index-0 key over
+  `sha256("LNURLcash:register:<domain>:<name>")`, whenever a `cx1` is set,
+  or `:unregister:` whenever one is cleared. The branch on file proves any
+  change to it. NIP-98 still decides who owns the name.
+- A payment hash whose preimage would open a note, this quote's own or any
+  other, is refused before an invoice is handed out, now that notes are
+  keyed by Q rather than by h.
+- **Upgrading.** Rows written before this release keep their old ids.
+  On first start the store records, once, the Q each old id would have as a
+  bearer note (`legacy_ids`), so an old bearer note is found by its
+  preimage, `cw1`, h or `cp1`, and no new note can be credited over it.
+  Nothing is rewritten, and key notes were keyed by Q already.
+
+## 0.16.2 - 2026-09-24
+
+Documentation only; no code changes.
+
+- `llms.txt` notes that `verifyStatsSnapshot` returns `stats: null` when the
+  content is not JSON or carries no signature, and returns the parsed stats
+  with `valid: false` for a bad signature, so check `valid` first.
+
 ## 0.16.1 - 2026-09-24
 
 Documentation only; no code changes.

package/README.md

@@ -31,9 +31,10 @@ lesson, that behaviour is kept deliberately and tested.
   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. The buyer names the note they are buying with a mandatory LUD-12
-  comment, so the secret is theirs alone from the start.
+- Notes are stored by their taproot output key Q, as LUD-25 now defines
+  every note - the store never holds a spend. The buyer names the note they
+  are buying with a mandatory LUD-12 comment, so the spend 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
@@ -95,6 +96,7 @@ default, and a variable set to an empty string counts as unset.
 | `MONEYER_PORT` | `3737` | listen port |
 | `MONEYER_PUBLIC_ORIGIN` | derived from `Host` | the origin wallets are told to call back on. Required behind a reverse proxy, and required for zap-to-note |
 | `MONEYER_ONION_URL` | | this mint as a Tor hidden service, e.g. `http://<v3>.onion`. A request arriving on that host gets its URLs built from it (see below) |
+| `MONEYER_SCRIPT_VERIFIER` | | a command that judges script-path spends moneyer cannot evaluate itself, e.g. `python3 /opt/moneyer/kernel-verifier.py` (see DEPLOY.md). Unset, such spends are refused and their notes wait |
 | `MONEYER_USERNAME` | `mint` | the local part of the mint's own lightning address |
 | `MONEYER_DESCRIPTION` | `an LNURLcash note` | what a note is called on the wire (`defaultDescription`, and `description` on discovery) |
 | `MONEYER_DB` | `moneyer.sqlite` | SQLite path; `:memory:` allowed |
@@ -344,21 +346,44 @@ preimage then buys nothing: it is an ordinary payment proof, which is why
 there is no race left to run, and no window in which holding the invoice
 is nearly holding the money.
 
-### Or name it by a key (LUD-25 Part 2)
-
-The comment can instead be `cp1<pk>`, a public key. The note is keyed by
-that key and spent with `ck1`, a recoverable signature by its private key,
-so the mint never sees anything that could spend it. Everywhere a note is
-named or spent, the two kinds mix freely:
-
-- `GET /w?k1=<ck1>` or `GET /w?p=<cp1>` looks a Part 2 note up, and the
-  answer carries `sig`, the mint's certificate for it as `cs1`.
-- `p1`/`p2` on the callback may be `cp1` keys, and the matching `sig`/`sig2`
-  come back as amount-bearing `cs1`. A legacy hash output instead receives
-  the raw 65-byte Part 1 signature used by the reference mint.
-- A merge may combine Part 1 secrets and Part 2 `ck1`s in one request.
-
-A recipient checks a Part 2 note offline from its `ck1` and `cs1` alone.
+### Every note is a taproot output key
+
+LUD-25 makes every note a BIP-341 output key Q, written `cp1<Q>`, and that
+is what this mint stores, burns and certifies. The 64-hex secret above is
+the short form of the simplest kind, a bearer note: an
+`OP_SHA256 <h> OP_EQUAL` leaf under BIP-341's NUMS key, so its Q follows
+from h alone. Wherever a note is named (a comment, `p`, `p1`, `p2`), 64 hex
+is that h, and `cp1<Q>` names any note directly. Wherever one is spent
+(`k1`), it can be:
+
+- the 64-hex preimage of a bearer note;
+- `ck1<Q || sig>`, a key-path spend: a BIP-340 signature by Q over the
+  sighash of LUD-25's canonical spend transaction, whose prevout commits to
+  this mint's domain, so it cannot be replayed at another mint. Any of the
+  mint's own hosts counts, clearnet or onion. The older `ck1` shapes are
+  still accepted, as the reference mint accepts them;
+- `cw1<...>`, a script-path spend: a leaf of Q's tree, its control block and
+  the witness that satisfies it. A bearer note's full `cw1` is the same note
+  as its preimage. Leaf versions other than `0xc0` and `OP_SUCCESSx` leaves
+  are refused, and time claims are checked against the mint's own clock:
+  Unix times only, relative locks counted from when the note was credited.
+  That is the mint asserting its clock, a custodial policy and not a
+  consensus proof.
+
+Bearer hashlock leaves are evaluated in process. LUD-25 has a mint accept
+any consensus-valid leaf, and moneyer is not a tapscript interpreter, so
+any other leaf goes to Bitcoin Core's own, the one the reference mint uses:
+set `MONEYER_SCRIPT_VERIFIER` to run `scripts/kernel-verifier.py` beside the
+mint (or pass a `scriptVerifier` to `createMoneyer`). Without one such a
+spend is refused with a reason and the note stays outstanding; a verifier
+that crashes, errors or stalls refuses too, and never accepts.
+
+Every note gets a certificate, `cs1` over hex(Q) and its amount: `c` on
+the informational GET, `c`/`c2` on every rotate, split and merge. The same
+value also goes out as the older `sig`/`sig2` until wallets reading only
+those have moved on. The
+informational GET verifies a `k1` in full before answering, so a wallet
+checking a note it was handed learns whether its spend really opens it.
 
 Moneyer's earlier `mintToHash` extension remains additive. A compatible
 wallet repeats the same commitment as `h`; it does not replace `comment`:
@@ -543,19 +568,29 @@ A registered name resolves on both rails at once:
 The discovery endpoint advertises `namePriceMsat` while registration is
 open, so a wallet can offer the flow without asking.
 
-### A name that pays to your own keys (LUD-25 Part 2)
+### A name that pays to your own keys (LUD-25 auto-mint)
 
 Add `"cx1": "cx1..."` to the registration body, or send `{"name", "cx1"}`
 again later from the key that owns the name, and payments to it stop being
 custodial. A `cx1` is a watch-only branch: from it the mint can work out each
 of the holder's note keys in turn, but never spend one.
 
-When a zap to the name settles, the mint takes the next index on the branch
-and credits the note to that key. It skips any key already holding a note,
+A `cx1` is public, so pointing a name at one has to be proven by the branch
+itself, as LUD-25 requires: the body also carries `"sig"`, a BIP-340
+signature by the branch's purpose-0 index-0 key over
+`sha256("LNURLcash:register:<domain>:<name>")`, `<domain>` being this mint's
+hostname. Changing the branch later is proven by the branch on file, not the
+new one, and clearing it takes the same signature over
+`LNURLcash:unregister:...` instead. The NIP-98 key still decides who owns
+the name; the proof decides where it may pay.
+
+When a zap to the name settles, the mint takes the next index on the
+branch's Lightning Address purpose (LUD-25's purpose 2, a counter of its
+own) and credits the note to that key. It skips any key already holding a note,
 and an invoice nobody pays takes no index at all, so a wallet scanning its
 branch never meets a gap it did not make. The gift wrap still goes to the
 owner's npub, but it carries no secret: a lookup URL,
-`https://mint.example/w?p=<cp1>&sig=<amount-bearing-cs1>&i=<index>`, plus an
+`https://mint.example/w?p=<cp1>&c=<amount-bearing-cs1>&i=<index>`, plus an
 `i` tag. The wallet derives the key at that index, checks the certificate,
 and spends with its own `ck1`. A wallet that only knows note URLs sees no
 `k1` and passes the wrap by, and the note waits at the mint for a scan of the
@@ -568,12 +603,14 @@ in `MONEYER_ZAP_NAMES`.
 Sending a new branch starts it at index 0; sending the same one again keeps
 its place. Zap receipts are unchanged.
 
-The name's payRequest also publishes `['text/xpub', '<cx1>:<index>']`, where
-the index is the next key not already present in this mint's ledger. A payer
+The name's payRequest also publishes `['text/cpub', '<cx1>:<index>']`, where
+the index is the next purpose-2 key not already present in this mint's
+ledger. It never publishes the older `text/xpub`: a wallet reading that
+derives without a purpose, so it pays by Lightning instead. A payer
 already holding a note here can therefore rotate, split or merge straight to
 that `cp1` without creating or routing a Lightning invoice. The index is a
-hint: if another payment wins the key first, Moneyer returns `Output already
-in use.` so the reference kit advances and retries.
+hint: if another payment wins the key first, Moneyer returns LUD-25's
+`already in use`, so the reference kit advances and retries.
 
 ## Reaching the mint over Tor
 
@@ -594,9 +631,10 @@ 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
+Both doors serve the **same notes**. A note is keyed by its Q and not by
+host, so a k1 struck on the onion is valid at the clearnet host and the
+other way round. A `ck1` is bound to a domain, and both of this mint's
+domains are its own, so one signed for either host is accepted at both. 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.
@@ -638,8 +676,8 @@ clearnet.
 | `/p/cb` | LUD-06 pay callback; issues the mint invoice for the note the `comment` names, a hash or a `cp1` key (`h` is an older spelling for a hash) |
 | `/z/cb/<zap name>` | the zap callback; validates the kind 9734 and issues the invoice |
 | `/verify/<hash>` | LUD-21 verify, for mint invoices and melt payments |
-| `/w` | LUD-03 informational GET; accepts `k1` (a secret or a `ck1`) or the non-disclosing LUD-25 `p` check (`sha256(k1)` or a `cp1` key; `h` is its older name, still accepted); a live note also carries `payLink`, and a Part 2 note its `cs1` as `sig` |
-| `/w/cb` | the mutating callback: melt, rotate, split, merge; inputs as secrets or `ck1`s, outputs as `p1`/`p2` hashes or `cp1` keys, or their older names `h`/`h2` |
+| `/w` | LUD-03 informational GET; accepts `k1` (a preimage, `ck1` or `cw1`, verified in full) or the non-disclosing LUD-25 `p` check (a bearer note's h or any `cp1`; `h` is its older name, still accepted); a live note carries `payLink` and its `cs1` as `sig` |
+| `/w/cb` | the mutating callback: melt, rotate, split, merge; inputs as preimages, `ck1`s or `cw1`s, outputs as `p1`/`p2` (a bearer note's h or a `cp1`), or their older names `h`/`h2` |
 | `POST /names` | claim a lightning address, authenticated by NIP-98 |
 | `/.well-known/nostr.json` | NIP-05 for the names this mint serves |
 | `/stats` | what the mint owes, what the node holds, and the coverage between them |

package/TERMS-TEMPLATE.md

@@ -109,6 +109,20 @@ contact <contact> to exercise them.
 - **Not a regulated financial service**, and not offered as one.
   <The operator is not authorised or registered by <regulator>.>
 
+### Scripts and timelocks
+
+A note may be locked to a script, and this mint checks every script the
+same way: it verifies the spend it is shown and nothing about why the
+note was locked. It runs no oracle, offers no contracts, and takes no
+part in any arrangement between the people a script names. A timelock is
+judged against this mint's own clock: it is the mint's promise, not a
+guarantee enforced by the Bitcoin network.
+
+Do not use this mint to stake bets, run a lottery or offer any other
+gambling, whatever script expresses it. The operator may stop verifying
+script spends at any time; a note that needs one then waits, outstanding,
+until verification returns or the mint winds down.
+
 ### Use
 
 Use this mint lawfully. Do not use it if you are designated under UK, UN,

package/THREAT-MODEL.md

@@ -24,20 +24,47 @@ request carrying a callback's query string cannot mutate anything.
 **A holder inflating a merge or split with a repeated k1.** Duplicated k1
 parameters in one request are refused outright; they would otherwise count
 one note's value twice into the output. The check is on the note each k1
-spends, not on the k1 string: a Part 2 note's `ck1` is a signature, and one
-note has many valid ones (anyone holding a `ck1` can flip it to `(r, n-s)`,
-and the key's owner can sign again). The store refuses a note named twice
+spends, its Q, not on the k1 string: one note has many valid spends (a
+bearer note's preimage and its full `cw1`, the key owner's fresh `ck1`s,
+the deprecated `ck1` shapes a wallet may still hold). The store refuses a note named twice
 among a swap's inputs as well, so the rule does not rest on the handler
 alone.
 
-**A holder claiming an output id that already exists.** `h`/`h2` may not
-collide with any existing note, any mint invoice's payment hash, settled
-or not, or any note a payer has bought by naming it. The invoice cases are
-the subtle ones: `/verify` hands a settled mint invoice's preimage to its
-payer, and that preimage is the k1 of whatever note carries the hash as
-its id - minting "over" such an id would point a future payer's money at a
-stranger's note. A named note is the same hazard one step earlier, since
-it is spoken for before it exists.
+**A holder claiming an output id that already exists.** An output (`p1`,
+`p2`, or a mint comment) may not name a Q that is already a note, spent or
+not, or that a payer has bought by naming it, and gets LUD-25's
+`already in use`. Nor may it name the bearer note a mint invoice's payment
+preimage would open: `/verify` hands that preimage out, so minting there
+would point money at a note anyone who saw the invoice can spend. A note
+written before notes were keyed by Q is protected the same way through
+`legacy_ids`, so its preimage never opens two notes.
+
+**A payment preimage that opens a note.** Every preimage is also the spend
+of the bearer note whose h is its payment hash, and a preimage reaches the
+funding source, every hop and `/verify`. So a quote is refused, before any
+invoice is shown, if its payment hash is the h of this quote's own note or
+of any note on file, whoever chose the preimage.
+
+**A spend replayed at another mint.** A `ck1` signs the sighash of LUD-25's
+canonical spend transaction, whose prevout commits to the mint's domain,
+so a key-path spend one mint has seen cannot be used at another. Moneyer
+accepts a signature bound to any of its own hosts, clearnet or onion, and
+nothing else. The deprecated `ck1` shapes are not bound to any mint; they
+are still accepted, as the reference mint accepts them, so that notes
+already handed out stay redeemable, and they should be retired once none
+are expected to remain.
+
+**A leaf that succeeds for anyone.** Tapscript keeps upgrade hooks that
+consensus accepts unconditionally: unknown leaf versions and `OP_SUCCESSx`
+opcodes. A `cw1` using either is refused before anything runs, as LUD-25
+requires; otherwise a note locked to such a leaf would be spendable by
+whoever saw it.
+
+**Timelocks.** A `cw1` carries a signed `nLockTime`/`nSequence`, and the
+mint checks them against its own clock: Unix times only, relative locks
+counted from when it credited the note. That is the mint asserting its
+clock, a custodial policy and not a consensus guarantee, and must never be
+described as trustless.
 
 **A holder melting into the mint's own invoice.** Refused synchronously:
 paying it would route the funding source's money at itself, which real
@@ -109,6 +136,11 @@ is what notecase and lnurl-wallet do.
 
 ## Known limitations
 
+- A script-path spend whose leaf is not a bearer hashlock can only be
+  judged by a tapscript interpreter, which moneyer does not contain. Without
+  a `scriptVerifier` such spends are refused and the note waits; a mint
+  cannot tell a script note from a key note when it is credited, since Q
+  is opaque, so it cannot refuse one up front either.
 - The cln and lnd backends are unexercised against live nodes (direct
   ports of the reference mint's logic). Run `--dev` traffic and the
   conformance grader against a staging deployment before taking real money.

package/dist/admin.js

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
 import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils.js';
 import { secp256k1 } from '@noble/curves/secp256k1.js';
-import { hashK1, noteDeclaredAmount, noteK1, noteSignature, verifyNoteSignature } from '@lnurlcash/kit';
+import { noteDeclaredAmount, noteK1, noteSignature, verifyNoteSignature, verifyNoteSignatureHash } from '@lnurlcash/kit';
+import { decodeNote, decodeSpend } from "./spend.js";
 import { configFromEnv, pubkeyHex } from "./config.js";
 import { NoteStore } from "./store.js";
 import { buildStats } from "./stats.js";
@@ -206,17 +207,18 @@ export const runAdmin = async (argv, deps = {}) => {
                     err('Usage: moneyer admin note <id|k1>');
                     return 2;
                 }
-                const asked = wanted.toLowerCase();
-                let note = store.noteById(asked);
-                let id = asked;
-                // 64 hex that names no note is very likely the secret itself,
-                // which an operator has in front of them far more often than an
-                // id. Hash it and look again rather than say "unknown".
-                if (!note && /^[0-9a-f]{64}$/.test(asked)) {
-                    id = hashK1(asked);
-                    note = store.noteById(id);
+                const asked = wanted.trim().toLowerCase();
+                let note = store.noteById(asked) ?? store.noteByQ(asked);
+                // Whatever else an operator is likely to have in front of them: a
+                // bearer note's h or a cp1, or a spend - a preimage, a ck1, a cw1.
+                // Each names a Q; look again by it rather than say "unknown".
+                if (!note) {
+                    const named = decodeNote(asked);
+                    const spend = decodeSpend(asked);
+                    const q = named && store.noteByQ(named) ? named : spend ? bytesToHex(spend.outputKey) : null;
+                    note = q ? store.noteByQ(q) : null;
                     if (note)
-                        out(`(that is a secret; its note id is ${id})`);
+                        out(`(that ${named === q ? 'names' : 'spends'} the note at Q ${q}${note.id === q ? '' : `, stored under ${note.id}`})`);
                 }
                 if (!note) {
                     const invoice = store.mintInvoiceByHash(asked);
@@ -228,6 +230,7 @@ export const runAdmin = async (argv, deps = {}) => {
                     out(`no note, and no mint invoice, at ${asked}`);
                     return 1;
                 }
+                const id = note.id;
                 out(`${id}`);
                 out(`  value    ${sats(note.amountMsat)}`);
                 out(`  state    ${note.state}`);
@@ -362,7 +365,12 @@ export const runAdmin = async (argv, deps = {}) => {
                     err('That is not a note URL - no k1 in it.');
                     return 2;
                 }
-                const id = hashK1(k1);
+                const spend = decodeSpend(k1);
+                if (!spend) {
+                    err('That note URL carries no spend this mint could read.');
+                    return 2;
+                }
+                const id = bytesToHex(spend.outputKey);
                 const declared = noteDeclaredAmount(url);
                 const signature = noteSignature(url);
                 const current = signingPubkey(config);
@@ -377,12 +385,14 @@ export const runAdmin = async (argv, deps = {}) => {
                     out('signature present, but the URL declares no amount to check it against');
                 }
                 else {
-                    const signedBy = keys.find(pubkey => verifyNoteSignature(k1, declared, signature, pubkey));
+                    // Over Q, as LUD-25 certifies every note now, or over the note's
+                    // old id for a certificate issued before that.
+                    const signedBy = keys.find(pubkey => verifyNoteSignatureHash(id, declared, signature, pubkey) || verifyNoteSignature(k1, declared, signature, pubkey));
                     out(signedBy === undefined
                         ? 'signature DOES NOT verify against this mint'
                         : `signature verifies against ${signedBy === current ? 'the current key' : `a previous key (${signedBy})`}`);
                 }
-                const note = store.noteById(id);
+                const note = store.noteByQ(id);
                 out(`mint     ${note ? `holds ${sats(note.amountMsat)}, state ${note.state}` : 'has no note at this id'}`);
                 // A note the mint does not know, or one already burned, is the
                 // answer the operator came for; say it in the exit code too.

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { bytesToHex, randomBytes } from '@noble/hashes/utils.js';
-import { buildNoteUrl, hashK1 } from '@lnurlcash/kit';
+import { buildNoteUrl } from '@lnurlcash/kit';
+import { bearerNoteIdOfPreimage } from "./spend.js";
 import { configFromEnv } from "./config.js";
 import { createMoneyer } from "./server.js";
 // moneyer - strike LNURLcash bearer notes.
@@ -71,7 +72,7 @@ console.log(`  mint pubkey:       ${moneyer.signer.pubkey}`);
 console.log(`  funding source:    ${moneyer.backend.name}`);
 if (values.dev) {
     const k1 = bytesToHex(randomBytes(32));
-    moneyer.store.creditNote(hashK1(k1), 21_000);
+    moneyer.store.creditNote(bearerNoteIdOfPreimage(k1), 21_000);
     console.log(`  a 21 sat note:     ${buildNoteUrl(`${moneyer.url}/w`, k1, 21_000)}`);
     console.log('\nDEV MINT - the fake funding source invents its invoices and treats every one\nof them as paid the moment it is issued, so minting here costs nothing and\nthe notes it hands out are worth nothing. Melts always succeed and send no\nsats anywhere. Never point a wallet holding real money at this.');
 }

package/dist/config.d.ts

@@ -22,6 +22,7 @@ export type MoneyerConfig = {
     port: number;
     publicOrigin?: string;
     onionUrl?: string;
+    scriptVerifier?: string[];
     username: string;
     description: string;
     name?: string;

package/dist/config.js

@@ -197,11 +197,14 @@ export const configFromEnv = (env = process.env) => {
         // header from, and the note URL it wraps must be right first time.
         throw new Error('Zap-to-note needs MONEYER_PUBLIC_ORIGIN.');
     }
+    // Split on whitespace: a path with spaces in it belongs in a wrapper script.
+    const scriptVerifier = env.MONEYER_SCRIPT_VERIFIER?.trim().split(/\s+/).filter(Boolean);
     return {
         host: env.MONEYER_HOST ?? DEFAULTS.host,
         port: int(env.MONEYER_PORT, DEFAULTS.port),
         ...(publicOrigin ? { publicOrigin } : {}),
         ...(onionUrl ? { onionUrl } : {}),
+        ...(scriptVerifier?.length ? { scriptVerifier } : {}),
         username: env.MONEYER_USERNAME ?? DEFAULTS.username,
         description: env.MONEYER_DESCRIPTION ?? DEFAULTS.description,
         ...(name ? { name } : {}),

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { configFromEnv, DEFAULTS, type MoneyerConfig, type BackendConfig } from
 export { createMoneyer, type Moneyer, type MoneyerDeps } from './server.ts';
 export { NoteStore, NotePendingError, NoteUnavailableError, OutputCollisionError, type NoteRow, type NoteState, type MeltRow, type MintInvoiceRow, type Liabilities } from './store.ts';
 export { createNoteSigner, noteIdSignatureDigest, recoversToPubkey, signDigestRecoverable, type NoteSigner } from './signing.ts';
+export { bearerNoteId, bearerNoteIdOfPreimage, decodeNote, decodeSpend, deriveNotePubkey, keyPathSighash, NOTE_PURPOSE_CHANGE, NOTE_PURPOSE_LIGHTNING_ADDRESS, NOTE_PURPOSE_WALLET, scriptPathSighash, spendDomainOf, verifySpend, type ScriptSpend, type ScriptVerifier, type Spend, type SpendVerdict } from './spend.ts';
+export { createKernelVerifier, type KernelVerifier } from './kernel.ts';
 export { STATS_D_TAG, STATS_KIND, buildStats, canonicalJson, signStats, statsDigest, statsSnapshotContent, verifyStatsSignature, verifyStatsSnapshot, type MintStats } from './stats.ts';
 export { ANNOUNCE_D_TAG, ANNOUNCE_KIND, ANNOUNCE_MESSAGE_PREFIX, announcementContent, announcementDigest, canonicalise, signAnnouncement, verifyAnnouncement, type MintAddressDocument } from './announce.ts';
 export { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError, type LightningBackend, type NodeInfo, type PaymentOutcome } from './backends/types.ts';

package/dist/index.js

@@ -15,6 +15,8 @@ export { configFromEnv, DEFAULTS } from "./config.js";
 export { createMoneyer } from "./server.js";
 export { NoteStore, NotePendingError, NoteUnavailableError, OutputCollisionError } from "./store.js";
 export { createNoteSigner, noteIdSignatureDigest, recoversToPubkey, signDigestRecoverable } from "./signing.js";
+export { bearerNoteId, bearerNoteIdOfPreimage, decodeNote, decodeSpend, deriveNotePubkey, keyPathSighash, NOTE_PURPOSE_CHANGE, NOTE_PURPOSE_LIGHTNING_ADDRESS, NOTE_PURPOSE_WALLET, scriptPathSighash, spendDomainOf, verifySpend } from "./spend.js";
+export { createKernelVerifier } from "./kernel.js";
 export { STATS_D_TAG, STATS_KIND, buildStats, canonicalJson, signStats, statsDigest, statsSnapshotContent, verifyStatsSignature, verifyStatsSnapshot } from "./stats.js";
 export { ANNOUNCE_D_TAG, ANNOUNCE_KIND, ANNOUNCE_MESSAGE_PREFIX, announcementContent, announcementDigest, canonicalise, signAnnouncement, verifyAnnouncement } from "./announce.js";
 export { PaymentAlreadyKnownError, PaymentFailedError, PaymentPendingError } from "./backends/types.js";

package/dist/kernel.d.ts

@@ -0,0 +1,10 @@
+import { type ScriptVerifier } from './spend.ts';
+export declare const UNAVAILABLE = "script verification is unavailable - try again later";
+export type KernelVerifier = ScriptVerifier & {
+    close: () => void;
+};
+export declare const createKernelVerifier: (options: {
+    command: string[];
+    timeoutMs?: number;
+    log?: (message: string) => void;
+}) => KernelVerifier;

package/dist/kernel.js

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { encodeCw1 } from "./spend.js";
+// A ScriptVerifier backed by a long-lived child process speaking one JSON
+// request and one JSON reply per line: scripts/kernel-verifier.py, which
+// runs Bitcoin Core's own interpreter through lnurlcash-kernel.
+//
+// LUD-25 has a mint accept any consensus-valid tapscript, and moneyer is
+// not a tapscript interpreter. Rather than write one, it borrows the one
+// the reference mint uses, so the two mints accept and refuse exactly the
+// same spends.
+//
+// Anything short of a verdict - the process missing, crashing, answering
+// with an error, or too slowly - refuses the spend. The note is untouched
+// and the wallet can try again; accepting on a broken verifier would be
+// the one unrecoverable answer.
+export const UNAVAILABLE = 'script verification is unavailable - try again later';
+export const createKernelVerifier = (options) => {
+    const [program, ...args] = options.command;
+    if (!program)
+        throw new Error('The script verifier needs a command.');
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const log = options.log ?? (() => { });
+    let child = null;
+    let nextId = 1;
+    const pending = new Map();
+    const settle = (id, reason) => {
+        const waiting = pending.get(id);
+        if (!waiting)
+            return;
+        clearTimeout(waiting.timer);
+        pending.delete(id);
+        waiting.resolve(reason);
+    };
+    const refuseAll = () => {
+        for (const id of [...pending.keys()])
+            settle(id, UNAVAILABLE);
+    };
+    const running = () => {
+        if (child)
+            return child;
+        const started = spawn(program, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        started.on('error', err => {
+            log(`script verifier failed to start: ${err.message}`);
+            if (child === started)
+                child = null;
+            refuseAll();
+        });
+        started.on('exit', code => {
+            log(`script verifier exited (${code ?? 'signal'})`);
+            if (child === started)
+                child = null;
+            refuseAll();
+        });
+        // A write to a process that has just died fails asynchronously; the
+        // exit handler above has already refused whatever was waiting.
+        started.stdin.on('error', err => log(`script verifier stdin: ${err.message}`));
+        started.stderr.on('data', chunk => log(`script verifier: ${String(chunk).trim()}`));
+        createInterface({ input: started.stdout }).on('line', line => {
+            let reply;
+            try {
+                reply = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof reply.id !== 'number')
+                return;
+            if (reply.ok === true)
+                settle(reply.id, null);
+            else if (typeof reply.reason === 'string')
+                settle(reply.id, reply.reason);
+            else {
+                log(`script verifier error: ${String(reply.error)}`);
+                settle(reply.id, UNAVAILABLE);
+            }
+        });
+        child = started;
+        return started;
+    };
+    const verify = ({ outputKey, domain, spend, now, lockedAt }) => new Promise(resolve => {
+        const id = nextId++;
+        const timer = setTimeout(() => {
+            log('script verifier timed out');
+            settle(id, UNAVAILABLE);
+        }, timeoutMs);
+        pending.set(id, { resolve, timer });
+        const request = { id, q: bytesToHex(outputKey), domain, cw1: encodeCw1(spend), now, locked_at: lockedAt };
+        try {
+            running().stdin.write(`${JSON.stringify(request)}\n`);
+        }
+        catch (err) {
+            log(`script verifier unreachable: ${err.message}`);
+            settle(id, UNAVAILABLE);
+        }
+    });
+    return Object.assign(verify, {
+        close: () => {
+            refuseAll();
+            child?.kill();
+            child = null;
+        }
+    });
+};