lnurlcash-conformance 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,177 @@ Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may add or tighten checks that a previously-passing mint now fails; pin an
 exact version if you gate CI on the grade.
 
+## 0.14.0 - 2026-09-26
+
+**LUD-25's unified taproot model** (luds `6e865b1`, "unified taproot
+verification"). Every note is now a BIP-341 output key `Q`, named `cp1<Q>`,
+and every spend opens it by its key path (`ck1`) or a leaf of its script
+tree (`cw1`), with every signature over the sighash of one canonical,
+never-broadcast transaction whose prevout is bound to the mint's domain. A
+bearer note is the one-leaf hashlock case: its 64-hex preimage and its hex
+`h` are short forms, so the Part 1 wire keeps working unchanged, but the
+note is keyed by `Q` and certified over `hex(Q)`. A mint graded clean by
+0.13.x will fail several checks here; that is the spec moving, not the
+grader.
+
+**Derivation purposes and certificate names** (luds `50d740a`). A note key
+is now `t = tagged_hash("LNURLcash/derive", P || chaincode || ser32(purpose)
+|| ser32(i)) mod n`, with purpose 0 for the wallet's own notes (and a
+split's `p1`), 1 for a split's change `p2` and 2 for Lightning Address
+auto-mint and internal transfer, each with its own counter and recovery gap
+limit. The register/unregister proof signs with the purpose-0 index-0 key.
+Certificates travel as `c` and `c2` (JSON) and `&c=` (note URL) rather than
+`sig`, `sig2` and `&sig=`, and the internal-transfer hint is `text/cpub`
+rather than `text/xpub`, its index the purpose-2 counter.
+
+Vectors:
+
+- `spec-vectors.json` follows 25.md's published vectors exactly. Vector 2's
+  address proofs sign `sha256("LNURLcash:<action>:<domain>:<username>")`;
+  vector 3 is now the key-path `ck1`, with the prevout, every `SigMsg`
+  field, the sighash and the serialised canonical spend transaction;
+  vector 5 is new, a bearer note from preimage to `cw1` and its `cs1`, and
+  its certified note URL carries `&c=`. Every note in vectors 1 and 2 gains
+  `purpose`; vector 1 lists purpose 0 at i = 0, 1, 2 and 5 and index 0 on
+  purposes 1 and 2, vector 2 purpose 0 at i = 0, 1 and 2, and vectors 3
+  and 4 move to the purpose-0 key, so every derived value, proof, `ck1` and
+  `cs1` changes. The selfcheck now holds every value to a literal
+  transcribed from 25.md at `50d740a`, and recomputes each independently.
+- New `spends.json`: bearer notes of both parities, one key's `ck1` across
+  several domains (and the cross-domain spends that must not verify), a
+  three-leaf script tree with each leaf's control block, `cw1` and verdict
+  plus a key-path spend of the tweaked key, a `CHECKSIG` leaf's
+  script-path sighash, time-claim cases, leaf-policy cases (an `OP_SUCCESS`
+  byte inside pushed data is data), malformed `cw1`s, off-curve `cp1`s and
+  the short-form equivalences.
+- `part2.json` and `nostr-seed.json`: every `ck1` now signs the key-path
+  sighash for its host's domain (lowercase, no port), so each branch or case
+  gains `domain`, and each note gains `sighash` and `keyPathSignature` in
+  place of `ownershipSignature`. The address proofs gain `domain` and sign
+  the domain-bound message. `conventions` drops the fixed ownership message.
+  Consumers reading `ownershipSignature` break loudly, which is intended:
+  it no longer means what it did.
+- `part2.json` and `nostr-seed.json` derive by purpose. Every note gains
+  `purpose` beside `index`. Each `part2.json` branch lists purpose 0 at the
+  same indices as before, then indices 0 and 1 on purposes 1 and 2, so
+  `notes[0]` is still the purpose-0 index-0 key the address proofs sign
+  with; each `nostr-seed.json` case lists purpose 0 at 0, 1 and 7, then
+  index 0 on purposes 1 and 2. `conventions` gains `purposes` and
+  `purposeUse`. A new `prePurpose` record keeps the superseded tweak
+  (no `ser32(purpose)`) for one branch, marked `superseded`, only so a
+  wallet can recognise and sweep notes it derived under luds `6e865b1`.
+- `note-url.json`, `responses.json` and `withdraw-info.json` use `c`, `c2`
+  and `&c=`. `note-url.json` keeps one parse case reading a certificate from
+  an older note URL's `&sig=`, and drops a stale `sig` along with a stale
+  `c` when the `k1` changes; `responses.json` adds a mint sending the
+  certificate under both names. `withdraw-info.json`'s `requestMustNotSend`
+  lists both.
+- `spends.json`'s key-path cases sign with vector 1's purpose-0 `sk_0`, so
+  the `mint.example` `ck1` is still test vector 3's.
+- `part2.json`'s `noteTweak` says `t` is reduced mod n, as 25.md requires,
+  where it said `t >= n` is unusable. No vector reaches n, so no value
+  changes. The mock mint's auto-mint reduces rather than skipping the index.
+
+Grader, `gradeNote`:
+
+- The note given may be any spend of it: a 64-hex preimage, a `ck1` or a
+  `cw1`. Mutations name their outputs as `p1`/`p2` rather than `h`/`h2`,
+  and lookups use `?p=`.
+- `answers a note lookup by p without the spend` replaces the optional
+  hash lookup, and now fails a mint that refuses it: LUD-25 makes `?p=` a
+  MUST. It asks by the note's `cp1` and, for a bearer note, its hex `h`.
+- `certifies a bearer output over hex(Q)` replaces `a legacy hash mutation
+  signature verifies when present`. A missing certificate warns (a SHOULD);
+  one that does not verify over `hex(Q)` fails, and one over the bearer
+  note's `h` is named as the pre-taproot message.
+- `a certificate on the informational GET verifies over hex(Q)` replaces
+  `keeps signatures off the informational endpoint`: a `sig` there must be
+  a `cs1` for exactly the queried note.
+- `refuses a p1 naming a burned note, as "already in use"` replaces
+  `refuses an output hash that already names a note`, asks by `cp1` and by
+  hex `h`, and fails any reason but exactly `already in use`.
+- `refuses a duplicated k1` also sends one note as its preimage and its
+  full `cw1`; `refuses a split whose p1 equals p2` also names one note as its
+  `h` and its `cp1`; `refuses a replayed burn` also tries the full `cw1`.
+- `replays a retried mutation rather than refusing it` also retries a
+  completed rotate naming its note by the full `cw1` instead of the
+  preimage, and its output by `cp1` instead of `h`. Both must replay with
+  the same certificate: LUD-25 matches retries on decoded `Q`s.
+- New, on a three-leaf script tree the grader funds by a bearer note's full
+  `cw1` and holds itself (MUST, fail): `a bearer note's full cw1 is the
+  same spend as its preimage`, `refuses a leaf version other than 0xc0`,
+  `refuses a leaf carrying an OP_SUCCESS opcode`, `refuses a block-height
+  locktime`, `refuses a locktime still in the future`, `refuses a
+  block-count relative lock`, `refuses a relative lock that has not yet
+  run` and `accepts a locktime already past`. Each refusal is tried at the
+  informational GET as well as the callback.
+- New, on a key-path note (MUST, fail): `credits a key-path note named by
+  its cp1`, `the informational GET refuses a spend that does not verify`,
+  `refuses a ck1 bound to another domain` and `spends a key-path note by a
+  ck1 bound to its own domain`. They replace `certifies a cp1 note it
+  issues (Part 2)`, which warned when a mint took no `cp1`; LUD-25 no
+  longer has an optional part, so that now fails.
+- New: `every certificate verifies over hex(Q) and the note value`, over
+  every `cs1` the run collected. A wrong one fails; missing ones warn.
+- Certificates are read from `c` and `c2` only, on the informational GET
+  and every rotate, split and merge, and a retry must return the same `c`
+  and `c2`. A mint sending only the pre-`50d740a` `sig`/`sig2` is graded
+  uncertified, a warning that names the old spelling; a mint sending both
+  names, as one mid-transition does, is graded on `c` and not faulted for
+  the extra `sig`. The note URL a run ends with drops `c` and `sig` both.
+- Value is conserved on every path. A refusal is confirmed to have left the
+  value in place, a misbehaving mint's output is adopted rather than lost,
+  and the script tree has two ways home (its hashlock leaf, then its key
+  path). The grader's `ck1`s sign the domain-bound sighash for the note
+  URL's own hostname; the deprecated fixed-message `ck1` is tried only as a
+  last rescue of the value, and never graded.
+- `gradeNote` resolves to `{finalSecret, noteUrl}`, as it always did in
+  practice; the declarations now say so.
+
+Grader, `gradeMint`: under `--address`, the internal-transfer hint is read
+from `text/cpub`; one published only as `text/xpub` fails that check. The
+comment check also requires a `cp1<Q>` comment to
+be invoiced, and a `cp1` whose key is not a curve point to be refused before
+any invoice exists. That rule is probed only here: as a `p1` it would
+destroy the note under grade on a mint that got it wrong.
+
+API: `ownershipProof(secretKey)` is gone. `keyPathSpend(secretKey, domain)`
+replaces it, since a `ck1` without a domain no longer means anything.
+
+Mock mint: keys notes by `hex(Q)` and verifies every spend in full (a `ck1`
+against the hostname it was reached at, or `--domains`; a `cw1` by the leaf
+and time rules, then the script, of which it evaluates only a bearer
+hashlock). It certifies every note with a `cs1` over `hex(Q)`, answers
+`?p=` (`?h=` still read), reads `p1`/`p2` (and `h`/`h2`), and refuses a
+collision as `already in use`. `creditNote` takes any spend; `creditOutput`
+takes a `cp1` or hex `h`. New misbehaviours, each caught by the self-grade
+with the value brought home: `leafVersionUnchecked`, `opSuccessUnchecked`,
+`ignoresTimeClaims` (all rules or named ones), `refusesLocktimes`,
+`unverifiedCk1`, `infoSkipsVerification`, `replayMatchesStrings`,
+`alreadyInUseReason`, `certificateOverH`, `refusesCp1Outputs`,
+`acceptsOffCurveCp1`; `acceptsMissingP2` is the new name of
+`acceptsMissingH2`. The optional bound-mint receipt keeps signing its `h`.
+It sends certificates as `c` and `c2`, and its registered address auto-mints
+on purpose 2 and publishes `text/cpub`; `certificateNames` (`'sig'` or
+`'both'`) and `addressHintType` reproduce a mint still on the older names.
+It has no register/unregister endpoint, so the purpose-0 proof key is held
+to the vectors only.
+
+Not yet brought over: `signature.json`, `callbacks.json`,
+`retried-mutation.json` and the other Part 1 wire vectors still describe the
+`h`/`h2` spelling and the certificate over `h`. The wire they describe still
+works through the short forms, but their certificate cases are the
+pre-taproot message.
+
+## 0.13.1 - 2026-09-16
+
+- The grader's own `ck1` (the one the Part 2 certification check spends
+  with) now signs `sha256("LNURLcash")`, like the vectors. It still signed
+  the raw 9-byte message, so a mint that dropped that older form would have
+  failed the check, and a mint that only read the older form would have
+  passed it. `ownershipProof` is exported, and the selfcheck holds it to the
+  digest.
+
 ## 0.13.0 - 2026-09-16
 
 **`ck1` and the LN-address register/unregister proof now sign a sha256

package/README.md

@@ -48,7 +48,9 @@ for (const c of cases) {
 | `signature.json` | offline verification, both recovery-id orderings, malformed input |
 | `derivation.json` | deterministic note secrets from a BIP39 seed |
 | `cash-derivation.json` | LUD-25's seed-recoverable note secrets under `m/139'`, with BIP-32's own vector 1 |
-| `part2.json` | Part 2: `cp1`, 96-byte-payload Schnorr `ck1`, amount-bearing recoverable-ECDSA `cs1`, `cx1`, the per-note key tweak, ownership proofs and mint certificates, on the reference wallet's `m/139'/1'` address path |
+| `spec-vectors.json` | LUD-25's own published test vectors 1-5, transcribed: derivation, the domain-bound address proof, a key-path `ck1` with every `SigMsg` field, a mint certificate, and a bearer note from `h` to `cw1` |
+| `spends.json` | the unified taproot model: bearer notes, `ck1`s across domains, a three-leaf script tree with its control blocks and verdicts, a `CHECKSIG` leaf's script-path sighash, time claims, leaf policy, malformed `cw1`s and the short forms |
+| `part2.json` | key-path notes: `cp1`, the domain-bound `ck1`, amount-bearing `cs1` certificates over `hex(Q)`, `cx1`, the per-note key tweak and address proofs, on the `m/139'/d1..d4` address path |
 | `bech32.json` | LUD-01 encoding, round trips, corrupted checksums |
 | `url-admission.json` | which URLs may be fetched, and why `data:` must never be |
 | `input-resolution.json` | bech32, LUD-17, Lightning Addresses, bare domains |
@@ -63,13 +65,14 @@ for (const c of cases) {
 | `settle-for-value.json` | the decision table a server works through to take a note as payment |
 | `retried-mutation.json` | what makes a repeated mutation a retry rather than a double-spend |
 | `mint-to-hash.json` | additive `mintToHash` compatibility and optional bound LUD-21 receipts; not baseline LUD-25 |
-| `nostr-seed.json` | a Part 2 address branch rooted in a Nostr identity key, for a holder with no BIP39 words (heartwood-esp32, lnurlcash-kit); an extension, not LUD-25 |
+| `nostr-seed.json` | a key-path address branch rooted in a Nostr identity key, for a holder with no BIP39 words (heartwood-esp32, lnurlcash-kit), with domain-bound `ck1`s; an extension, not LUD-25 |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
 | `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
 Regenerate with `npm run generate`; check them with `npm test`, which
 verifies every digest recomputes, every declared signature really does
-verify, and every fee expectation follows from the formula.
+verify, every fee expectation follows from the formula, and every value in
+`spec-vectors.json` is the hex 25.md itself publishes.
 
 The upstreamable wire text and compatibility matrix for the optional receipt
 are in [`docs/BOUND-MINT-RECEIPTS.md`](docs/BOUND-MINT-RECEIPTS.md).
@@ -95,8 +98,9 @@ must survive:
 | `--echoWrongK1` | answers the informational GET with a different `k1` |
 | `--lieAboutValue=N` | reports a `maxWithdrawable` it never signed |
 | `--signatureLayout=leading` | emits the recovery id at the other end |
-| `--signatures=false` | issues no optional Part 1 signatures. Unsigned plain-hash outputs are conforming; Part 2 `cp1` outputs still require certificates |
-| `--serverGeneratedSecrets` | hands back a secret it generated — the exposure `h` exists to close |
+| `--signatures=false` | certifies nothing. LUD-25 has a mint certify every note with a `cs1` over `hex(Q)` as a SHOULD, so the grader warns |
+| `--certificateOverH` | certifies a bearer note over its `h`, the pre-taproot message, instead of `hex(Q)` |
+| `--serverGeneratedSecrets` | hands back a secret it generated: the exposure `p1`/`p2` exist to close |
 | `--meltNeverSettles` | holds every melt in flight, so notes stay `pending` |
 | `--meltAlwaysFails` | fails every payment, restoring the note |
 | `--slowMs=N` | delays every response |
@@ -105,10 +109,20 @@ must survive:
 | `--roundFeeToSat` | rounds the withheld fee up to a whole sat — the note mints short of the formula |
 | `--verifyLeaksEarly` | serves a preimage before settlement, falsely claiming payment proof before payment happened |
 | `--retriedMutation=refuse` | deliberately answers an identical mutation retry as already spent instead of replaying its original success |
-| `--hashLookup=echoesK1` | offers hash lookup but puts a `k1` back in the response |
-| `--hashLookup=answersUnknown` | offers hash lookup but invents a note for an unknown hash |
-| `--hashLookup=hidesSpent` | incorrectly reports a retained spent hash as unknown |
-| `--hashLookup=acceptsBoth` | offers hash lookup but accepts `k1` and `h` together |
+| `--replayMatchesStrings` | matches a retry on the raw `k1`/`p1`/`p2` strings, so the same spend spelt another way is refused as already spent |
+| `--alreadyInUseReason=<text>` | refuses a `p1`/`p2` naming a note already in use with some reason other than LUD-25's exact `already in use` |
+| `--leafVersionUnchecked` | accepts a leaf version other than `0xc0`, as consensus alone would |
+| `--opSuccessUnchecked` | accepts a leaf carrying an `OP_SUCCESSx` opcode |
+| `--ignoresTimeClaims[=rule,...]` | ignores a script path's time claim: every rule, or `blockHeight`, `future`, `blockCount`, `relative` |
+| `--refusesLocktimes` | over-strict: refuses every non-zero locktime, a past Unix time included |
+| `--unverifiedCk1` | accepts any `ck1` whose `Q` is outstanding without checking its signature, so one bound to another domain opens the note |
+| `--infoSkipsVerification` | answers the informational GET for a `k1` from its `Q` alone, never verifying the spend |
+| `--refusesCp1Outputs` | refuses a `cp1` wherever one may go, as a mint without key-path notes does |
+| `--acceptsOffCurveCp1` | accepts a `cp1` whose key is not a curve point |
+| `--hashLookup=echoesK1` | answers a lookup by `p` but puts a `k1` back in the response |
+| `--hashLookup=answersUnknown` | answers a lookup by `p` for a note it never registered |
+| `--hashLookup=hidesSpent` | incorrectly reports a retained spent note as unknown |
+| `--hashLookup=acceptsBoth` | accepts `k1` and `p` together |
 | `--mintToHashAcceptsMalformedH` | claims `mintToHash` and invoices an `h` that is not 64 lowercase hex, so a wallet pays for a quote the mint will refuse |
 | `--mintToHashAcceptsUsedH` | claims it and invoices an `h` that already names a note, an invoice or another quote's output |
 | `--mintToHashIgnoresH` | claims it but accepts `h` and mandatory `comment` naming different outputs |
@@ -117,10 +131,19 @@ The three `mintToHash*` misbehaviours need `--mintToHash` alongside them;
 on their own they do nothing, because a mint that never offered the
 capability cannot misuse it.
 
-Hash lookup keeps the spending secret off the wire but reports spent state:
-`--hashLookup=true` distinguishes a burned hash from an unknown hash. The older
+The lookup by `p` (a `cp1`, or a bearer note's hex `h`; `?h=` is still read as
+its older name) keeps the spend off the wire but reports spent state:
+`--hashLookup=true` distinguishes a burned note from an unknown one. The older
 `--hashLookup=revealsSpent` spelling remains an alias for this compliant behaviour.
 
+The mock keys every note by its taproot output key `Q` and verifies every
+spend it is handed: a `ck1` against the key-path sighash for the hostname it
+was reached at (or `--domains=a,b`), and a `cw1` by the leaf rules, the time
+rules against its own clock, and then the script. It has no script
+interpreter, so of the scripts themselves it judges only a bearer hashlock
+(under any internal key, at any depth) and refuses any other as one it
+cannot verify.
+
 The remaining flags enable optional features, legal wire variants, or make a
 conforming default explicit. Optional fields stay absent unless requested:
 
@@ -136,7 +159,7 @@ conforming default explicit. Optional fields stay absent unless requested:
 | `--previousPrivateKey=<hex>` | an old signing key the mock still holds. Its public half joins `previousPubkeys` on its own |
 | `--signWithPreviousKey` | issues every note under that old key while still advertising the new one: the mid-rotation state a mint passes through when the advertisement moves before the signer |
 | `--retriedMutation=replay` | answers a byte-identical repeat of a mutation with the original success. This is the conforming default; use `refuse` only as an adversarial fixture |
-| `--hashLookup=false` | models an older SERVICE with no secret-free informational lookup. The current reference mock accepts `h=sha256(k1)` by default |
+| `--hashLookup=false` | models an older SERVICE with no lookup by `p`, which LUD-25 now makes a MUST |
 | `--mintToHash` | accepts `h` alongside the mandatory identical comment and enables the additive quote/receipt fields. Off by default; baseline comment-bound minting remains on |
 | `--mintReceipt` | with `--mintToHash`, adds the optional quote commitment and signed LUD-21 settlement receipt |
 | `--mintToHashAdvertisedOn=quote` | narrows which of the three places claim it (`payRequest`, `mintAddress`, `quote`); all three by default. Changes only what is claimed, never what the mint does |
@@ -152,11 +175,14 @@ mint.state.creditNote(k1, 21000)
 await mint.close()
 ```
 
-`mint.state` exposes `creditNote`, `noteState`, `settleMelt`, `failMelt` and
-the raw note and invoice maps, so a test can assert what the SERVICE
-actually did rather than what it said. `creditNote(k1, amount, {previousKey:
-true})` signs that one note under `previousPrivateKey`, which is how a case
-puts one note under the old signing key and the rest under the new.
+`mint.state` exposes `creditNote`, `creditOutput`, `noteState`, `settleMelt`,
+`failMelt` and the raw note and invoice maps (notes keyed by `hex(Q)`), so a
+test can assert what the SERVICE actually did rather than what it said.
+`creditNote` takes any spend of the note (a 64-hex preimage, a `ck1` or a
+`cw1`); `creditOutput` takes what names it (a `cp1` or a bearer note's hex
+`h`). `creditNote(k1, amount, {previousKey: true})` certifies that one note
+under `previousPrivateKey`, which is how a case puts one note under the old
+signing key and the rest under the new.
 
 ## The grader
 
@@ -167,14 +193,14 @@ npx lnurlcash-conform mint@example.com
 Read-only by default: resolves the payRequest, checks the `withdrawLink`
 (either legal spelling, and the report says which one the mint uses),
 the fee advertisement, invoice amounts, mandatory `commentAllowed: 64`,
-pre-invoice rejection of missing or malformed mint comments, whether an
-unknown note is reported distinguishably from a spent one, and the
-experimental mint address.
+pre-invoice rejection of missing or malformed mint comments (a `cp1` whose
+key is not on the curve among them), whether an unknown note is reported
+distinguishably from a spent one, and the experimental mint address.
 
-Current LUD-25 minting is always comment-bound. The wallet persists a secret,
-sends `comment=hex(sha256(secret))`, and the payment preimage remains ordinary
-settlement proof. A mint that cannot accept the 64-character commitment, or
-that silently creates a preimage-backed note, fails grading.
+Current LUD-25 minting is always comment-bound. The wallet names the note it
+is buying as `comment=cp1<Q>`, or as a bearer note's hex `h`, and the payment
+preimage remains ordinary settlement proof. A mint that cannot accept either
+spelling, or that silently creates a preimage-backed note, fails grading.
 
 `mintToHash` is retained as an additive compatibility field. When advertised,
 the runner sends `h` alongside the mandatory comment and requires both to name
@@ -226,27 +252,52 @@ Both are still read-only. The full run spends:
 npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --spend
 ```
 
-It burns the note it is given and prints where the value ended up. It
-checks that the informational GET is idempotent and echoes the queried
-`k1`, that the URL's own `amount` is ignored, that a rotate with no `h` is
-refused, that a rotate returns no secret, that signatures verify against the
-advertised `mintPubkey` or any key the mint still publishes as a previous
-one, that split and merge conserve value - exactly,
-under LUD-25's fee algebra, when the mint's fee advertisement is known -
-that a byte-identical repeat of a mutation is answered with the original
-success rather than as an already-spent input, and that a
-burned secret cannot be replayed. It also probes three adversarial shapes a
-mint must refuse atomically: a duplicated `k1` (which a careless mint counts
-twice, minting money from nothing), an output hash that collides with an
-existing note id (minting over it hands the output to whoever already knows
-that id's preimage), a split whose `h` equals `h2` (one id cannot carry
-two notes), a split naming only one output hash (a mint that accepts it is
-generating the change secret itself), and a split leaving change one msat
-short of the advertised base fee (which LUD-25 says to refuse with
-`insufficient value`, not to serve at a loss). And it replays the callback as a POST and as an OPTIONS
-preflight - real HTTP stacks send both on their own initiative, so the
-mutating endpoint must answer GET only. After every refusal it confirms the refused note is still
-spendable. Use a small note. Exit code is non-zero if anything failed.
+It burns the note it is given and prints where the value ended up. The
+note's `k1` may be any spend of it: a bearer note's 64-hex preimage, a `ck1`
+or a `cw1`. It grades LUD-25 as of the unified taproot model (luds
+`6e865b1`), where every note is a taproot output key `Q`, with the
+derivation purposes and certificate names of luds `50d740a`: certificates
+are read from `c` and `c2`, and a mint that also sends the older `sig` and
+`sig2` is not faulted for it.
+
+On the note as given it checks that the informational GET is idempotent,
+echoes the queried `k1` and ignores the URL's own `amount`; that a lookup by
+`p` answers by the note's `cp1` and by its hex `h`, with no `k1` in the reply,
+and tells a spent note from an unknown one; that a rotate with no `p1` and a
+split with no `p2` are refused; that a rotate returns no secret; that split
+and merge conserve value, exactly under LUD-25's fee algebra when the fee is
+known; and that a retried mutation is answered with the original success,
+byte for byte and when the retry spells the same spend (preimage or full
+`cw1`) or the same output (`h` or `cp1`) another way, while a burned note
+cannot be spent again. It probes the shapes a mint must refuse atomically:
+one note named twice in a merge, in the same or two spellings (a careless mint
+counts it twice, minting money from nothing); a `p1` naming the burned note
+it was given, which must be refused as exactly `already in use`; a split
+whose `p1` and `p2` name one note; a split leaving change short of the base
+fee (`insufficient value`); and the callback replayed as a POST and as an
+OPTIONS preflight, since the mutating endpoint must answer GET only.
+
+Then it moves the value through two notes of its own. The first is a
+three-leaf script tree under an internal key it holds: a bearer hashlock at
+leaf version `0xc0`, the same shape at `0xc2`, and a hashlock followed by
+`OP_SUCCESS80`. It is funded by the full `cw1` of a bearer note, which must be
+the same spend as its preimage. On it the grader shows that a leaf version
+other than `0xc0` and an `OP_SUCCESS` leaf are refused, and that time claims
+are judged by the mint's own clock: a block-height locktime, a locktime in the
+future, a block-count relative lock and an unelapsed relative time lock are
+refused, and a locktime already past is accepted. The second is a key-path
+note, `cp1<Q>` with `Q` untweaked as a seeded wallet makes them: a `ck1`
+signed for another domain is refused at the callback, the informational GET
+refuses it and a `ck1` signed by another key, and the `ck1` bound to the note
+URL's own hostname spends it.
+
+Every refusal is confirmed to have left the value where it was, and every
+path has a way home (the tree's hashlock leaf, then its key path), so a
+compliant run ends holding a bearer note worth what it started with.
+Certificates are a SHOULD: a missing `cs1` warns, but every `cs1` returned,
+on a mutation or on the informational GET, must verify over `hex(Q)` and the
+note's value, and one over a bearer note's `h` (the pre-taproot message)
+fails. Use a small note. Exit code is non-zero if anything failed.
 
 **What the grader cannot reach.** It never melts. Melting spends real sats
 against a real mint, which is not something a grading tool may decide to do,

package/llms.txt

@@ -13,9 +13,12 @@ vectors/index.json:
 signature.json       offline verification, both recovery-id orderings
 derivation.json      deterministic note secrets from a BIP39 seed
 cash-derivation.json LUD-25 m/139' note secrets, plus BIP-32 vector 1
-part2.json           Part 2: cp1, ck1=pubkey||BIP340 Schnorr sig, cs1=recoverable ECDSA certificate,
-                     cx1, the note-key tweak, ownership proofs and certificates;
-                     address path is the reference wallet's m/139'/1'/d1..d4 (not the text's)
+spec-vectors.json    25.md's own test vectors 1-5, every value checked against the spec text
+spends.json          the taproot model: bearer notes, ck1 per domain, a 3-leaf tree and its
+                     verdicts, a CHECKSIG leaf's sighash, time claims, leaf policy, bad cw1s
+part2.json           key-path notes: cp1, ck1=Q||BIP340 sig over the domain-bound sighash,
+                     cs1 over hex(Q), cx1, the note-key tweak per purpose, address proofs;
+                     m/139'/d1..d4; prePurpose = the superseded tweak, for sweeping only
 bech32.json          LUD-01 encoding
 url-admission.json   which URLs may be fetched (https, or http to loopback/.onion)
 input-resolution.json bech32, LUD-17, Lightning Address, bare domain
@@ -30,7 +33,7 @@ payment-request.json lnurlcashreq1: asking another holder for value
 settle-for-value.json the decision table for taking a note as payment
 retried-mutation.json what makes a repeat a retry, not a double-spend
 mint-to-hash.json    naming the note you are buying: h on the pay callback
-nostr-seed.json      EXTENSION: Part 2 branch from a Nostr key, HMAC-SHA256(key, "LNURLcash/nostr-seed")
+nostr-seed.json      EXTENSION: key-path branch from a Nostr key, HMAC-SHA256(key, "LNURLcash/nostr-seed")
 lifecycle.json       behavioural scenarios
 threat-suite.json    transport/exposure scorecard, options vs attacks (non-normative)
 
@@ -38,18 +41,29 @@ threat-suite.json    transport/exposure scorecard, options vs attacks (non-norma
 
 import {createMockMint} from 'lnurlcash-conformance/mock-mint'
 const mint = await createMockMint({dropAfterMutation: true})
-mint.state.creditNote(k1, 21000)   // then drive your client at mint.url
+mint.state.creditNote(k1, 21000)   // k1: 64-hex preimage, ck1 or cw1
+mint.state.creditOutput(cp1, 21000) // or name it: a cp1 or a bearer note's hex h
 await mint.close()
 
+Notes are keyed by hex(Q), every spend is verified in full (a ck1 against the
+hostname the mock was reached at, or domains=a,b), and every note gets a cs1
+over hex(Q). The mock evaluates only a bearer hashlock leaf, under any
+internal key and depth; any other script is refused as unverifiable.
+
 Misbehaviour flags: dropAfterMutation, unconfirmedMutation, malformedJson,
 echoWrongK1, lieAboutValue, signatureLayout=leading, signatures=false,
-serverGeneratedSecrets, meltNeverSettles, meltAlwaysFails, slowMs, sunset,
-baseFeeMsat, feePpm, verify=false, withdrawLinkForm=lnurlw (the lnurlw://
-spelling of withdrawLink; default is the plain https://, as lnurl-mint).
-
-retriedMutation=replay (a byte-identical repeat of a mutation gets the
-original success back instead of "already spent"; the default 'refuse' is
-what the mock has always done).
+certificateOverH, serverGeneratedSecrets, meltNeverSettles, meltAlwaysFails,
+slowMs, sunset, baseFeeMsat, feePpm, verify=false, withdrawLinkForm=lnurlw
+(the lnurlw:// spelling of withdrawLink; default is the plain https://, as
+lnurl-mint). The taproot rules: leafVersionUnchecked, opSuccessUnchecked,
+ignoresTimeClaims (true, or blockHeight/future/blockCount/relative),
+refusesLocktimes, unverifiedCk1, infoSkipsVerification, replayMatchesStrings,
+alreadyInUseReason=<text>, refusesCp1Outputs, acceptsOffCurveCp1,
+acceptsMissingP2.
+
+retriedMutation=replay is the default (a repeat of a mutation, matched on the
+notes it names, gets the original success back instead of "already spent");
+'refuse' is the non-compliant fixture.
 
 mintToHash=true (the pay callback takes an optional h - 64 lowercase hex,
 sha256 of a WALLET-chosen secret, the same thing h means on the withdraw
@@ -87,13 +101,63 @@ softly: a mint publishing none of them loses nothing, a published field of
 the wrong shape warns, and a signature under a key the mint publishes in
 previousPubkeys is accepted as its own.
 
-## The signature scheme, canonically
-
-note_id = hex(sha256(k1))
-message = "LNURLcash:" + amount_msat + ":" + note_id
+--spend grades LUD-25 as of luds 50d740a. Besides the rotate, split, merge,
+retry and refusal checks it moves the value through a three-leaf script tree
+(a hashlock at leaf version 0xc0, the same at 0xc2, a hashlock with
+OP_SUCCESS80) and a key-path note, and requires: the 0xc2 and OP_SUCCESS
+leaves refused; block-height, future, block-count and unelapsed relative time
+claims refused and a past locktime accepted; a ck1 for another domain refused
+at the callback and the informational GET; the right-domain ck1 accepted; a
+p1 naming a burned note refused as exactly "already in use"; a retry respelt
+(preimage vs full cw1, h vs cp1) replayed. A missing cs1 warns (SHOULD); a
+cs1 not over hex(Q) fails. Certificates are read from c and c2 only; a mint
+sending only the pre-50d740a sig/sig2 is graded uncertified (warns), and one
+sending both names passes. --address reads the internal-transfer hint from
+text/cpub (text/xpub before 50d740a is not read). Value always comes home.
+
+## Notes and spends, canonically (luds 6e865b1, keys per 50d740a)
+
+Q        32-byte x-only taproot output key; cp1<Q> (bech32m, hrp "cp"), and
+         a mint MUST refuse a Q that is not on the curve
+ck1      Q || BIP-340 sig (96 bytes), zero aux_rand, over the key-path sighash
+cw1      u32 locktime || u32 sequence || (u16 len || item)* over the leaf
+         script, the control block, then witness items bottom first; all
+         big-endian
+bearer   leaf a8 20 <h> 87 (OP_SHA256 <h> OP_EQUAL), version 0xc0, internal key
+         BIP-341's NUMS point
+         H = 50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0;
+         64 hex in a k1 slot = the preimage, in a cp1 slot (comment, p1, p2,
+         ?p=) = h
+sighash  tagged_hash("TapSighash", 0x00 || SigMsg), SIGHASH_DEFAULT, input 0 of:
+         nVersion 2; prevout (tagged_hash("LNURLcash/mint", domain), 0); empty
+         scriptSig; nSequence as claimed (0xffffffff for a key path); one
+         output, value 0, empty script; nLockTime as claimed (0 for a key
+         path); spent output (OP_1 <Q>, 0)
+domain   the mint's lowercase hostname: no scheme, no port
+leaves   refuse leaf version != 0xc0 and any OP_SUCCESSx outside pushed data
+derive   t = tagged_hash("LNURLcash/derive", P || chaincode || ser32(purpose) ||
+         ser32(i)) mod n; pk_i = x(lift_x(P) + t·G). purpose 0 = the wallet's
+         own notes (mint, rotate, merge, a split's p1), 1 = a split's change p2,
+         2 = Lightning Address auto-mint and internal transfer. One counter and
+         one recovery gap limit per purpose; one cx1 covers all three. The
+         register/unregister proof signs with purpose 0, index 0
+time     nLockTime 0, or a Unix time (>= 500000000) not in the future;
+         nSequence with bit 31 set, or bit 22 set and (low 16 bits * 512 s)
+         elapsed since the mint credited the note; heights and block counts
+         refused
+
+## Certificates, canonically
+
+message = "LNURLcash:" + amount_msat + ":" + hex(Q)      // every note, bearer too
 digest  = sha256(sha256("Lightning Signed Message:" + message))
 sig     = 65 bytes, r || s || recovery_id (wire format)
-pubkey  = 33-byte compressed, hex
+cs1     bech32m, hrp "cs" + BOLT-11 amount (cs10n = 1000 msat), over sig
+pubkey  = mintPubkey, 33-byte compressed, hex
+wire    JSON "c" (and "c2" for a split's change) on the informational GET and
+        every rotate, split or merge; note URL ...?k1=<spend>&c=<cs1>. These
+        were sig, sig2 and &sig= before luds 50d740a
+hint    payRequest metadata ["text/cpub", "cx1...:<i>"], i the purpose-2
+        counter (text/xpub before luds 50d740a)
 
 Recover from digest with NO further hashing (prehash off). Verifiers MUST
 also accept recovery_id || r || s. Library layouts differ:
@@ -120,12 +184,11 @@ the request. Full table in settle-for-value.json.
 
 ## Naming the note you are buying
 
-In LUD-25 a minted note's k1 is the payment preimage, so the preimage IS
-the money, and two sets of untrusted people learn it: every routing node
-on the payment path, and anyone who saw the invoice and polled LUD-21
-verify with its payment hash. A WALLET MAY instead send h=<64 lowercase
-hex> on the LUD-06 pay callback, the sha256 of a secret it chose; the
-SERVICE credits the note there and the preimage opens nothing. Support is
+LUD-25 names the note a payment mints in the mandatory LUD-12 comment:
+cp1<Q>, or a bearer note's hex h. The payment preimage is settlement proof,
+never the money. As an older, additive spelling a WALLET MAY also send
+h=<64 lowercase hex> on the LUD-06 pay callback, repeating the comment's h;
+the SERVICE credits the note there and the preimage opens nothing. Support is
 advertised as mintToHash: true in three places - the payRequest (every
 mint has one, so decide from this), the mint address document (the same
 fact, corroboration), and the pay callback's own response (this quote was
@@ -151,15 +214,16 @@ docs/BOUND-MINT-RECEIPTS.md.
 ## The retried mutation
 
 Every mutation is a GET, and HTTP stacks retry a GET on a dropped
-connection, so a SERVICE sees the identical request twice with its inputs
+connection, so a SERVICE sees the same request twice with its inputs
 burned the second time. Answering "already spent" makes the holder discard
-the only copy of a secret the SERVICE really did mint against. Identical =
-same input k1 SET + same h + same h2 + same amount, present or absent
-alike. Anything else naming a burned input is a double-spend and keeps
-today's refusal, so no oracle appears. Provenance is recorded, not
-inferred. The replay is a READ: nothing burns, nothing mints, the sig is
-recomputed from (output id, amount). SHOULD, not MUST: the grader reports
-it as unimplemented rather than failing. Table in retried-mutation.json.
+the only copy of a spend the SERVICE really did mint against. The same
+request = the same SET of notes burned + same p1 + same p2 + same amount,
+compared as the Qs they decode to, never the strings (one note has several
+spellings: preimage or full cw1, h or cp1). Anything else naming a burned
+input is a double-spend and keeps today's refusal, so no oracle appears.
+Provenance is recorded, not inferred. The replay is a READ: nothing burns,
+nothing mints, the same certificates come back. A MUST: the grader fails a
+mint that refuses it. Table in retried-mutation.json.
 
 ## Fee arithmetic