lnurlcash-conformance 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,292 @@ 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.2.0 - 2026-08-22
+
+- 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 people
+  learn it without being trusted with it: every routing node on the
+  payment path, because that is how HTLC settlement works, and anyone who
+  merely saw the invoice, because they can poll LUD-21 verify with its
+  payment hash and take the preimage the moment it settles. A QR on a
+  desktop screen is exactly that. "Rotate immediately" is the only defence
+  and it is a race. A wallet may instead send `h` on the LUD-06 pay
+  callback, the sha256 of a secret it chose, and be credited there.
+
+  - New `vectors/mint-to-hash.json` fixes the parameter and both refusal
+    reasons, so kits in other languages answer the same wallet the same
+    way. `h` is 64 lowercase hex, exactly what it means on the withdraw
+    callback. A malformed one is refused with `Invalid h.` before any
+    invoice exists, so a wallet never pays for a quote the mint was always
+    going to reject; one that already names a note, an invoice, or another
+    quote's output is refused with `Invalid or already spent k1.`, the
+    same reason the withdraw callback gives a colliding output hash, so no
+    oracle appears. Ten cases, four of them refusals, plus a worked
+    settlement both ways round: bound, the note is at the wallet's own
+    secret and the preimage opens nothing; unbound, it is the preimage's,
+    exactly as before.
+
+  - Support is advertised in three places and they say different things.
+    `mintToHash: true` on the payRequest means "I accept an `h` on my pay
+    callback", and since every mint publishes a payRequest while the mint
+    address document is experimental, that is the one a wallet decides
+    from. The mint address document repeats it, as corroboration. The pay
+    callback's own response echoes it when *that* quote was bound, which
+    is the one that matters at the moment money moves, because the other
+    two can be cached or stale. Anything that is not exactly the boolean
+    `true` is no, everywhere, so a mint that omits the field is safely
+    read as not bound. All fifteen spellings are in the vector.
+
+  - Mock knob `mintToHash`, off by default, and with it off nothing about
+    this reaches the wire: nothing is advertised anywhere and the pay
+    callback does not read `h` at all. `mintToHashAdvertisedOn` narrows
+    which of the three places claim it, changing only what is claimed and
+    never what the mint does, so a mint that shipped the feature before
+    the advertisement can be reproduced. Three misbehaviours, each needing
+    `mintToHash` alongside: `mintToHashAcceptsMalformedH`,
+    `mintToHashAcceptsUsedH` and `mintToHashIgnoresH`, the last of which
+    claims the capability, echoes it on the quote, and mints at the
+    payment hash anyway.
+
+  - New grader check `accepts an output hash on the mint quote
+    (mintToHash, optional)`. Soft where it should be: a mint that says
+    nothing anywhere and ignores `h` is reported as not offering it and
+    the run passes, which is every mint today and not a defect. A mint
+    that claims it is asked to prove the refusals, and an invoice issued
+    for a malformed `h` fails, because a wallet that pays for a quote the
+    mint will reject has bought nothing while the mint keeps the sats.
+    Disagreements between the three claims are named rather than failed:
+    none of them loses anyone money on its own, since a wallet reading a
+    missing field as false falls back to the preimage flow.
+
+  - New grader check `a bound mint credits the hash the wallet named
+    (optional)`, exported as `gradeBoundMint` and wired to a new
+    `--preimage` flag. Like the minted-value check it needs a payment the
+    runner cannot make itself: given the note URL carrying the wallet's
+    own secret and the preimage of the invoice that funded it, it fails a
+    mint that claimed the capability and did not bind. That is the one
+    worth failing rather than warning, because a wallet that believed the
+    claim stopped rotating on sight.
+
+  - Also refused now, on the withdraw callback: an `h` or `h2` colliding
+    with the output a bound quote is waiting to credit. Unreachable unless
+    `mintToHash` is on, so nothing about a mint without it changes.
+
+  - The case rule, stated as a rule rather than a verdict. Hex is
+    case-insensitive, so `AAAA...` and `aaaa...` are the same 32 bytes and
+    name one output, not two. A wallet MUST send `h` as 64 lowercase hex,
+    which keeps the producer side strict and is what every client here
+    does. A service SHOULD normalise case before comparing, and MUST NOT
+    treat an otherwise well-formed upper-case `h` as a different output
+    from its lowercase form: keying the string it was handed files the
+    note under the upper-case spelling and never finds it again when the
+    wallet asks the withdraw endpoint for its own lowercase secret, and
+    nobody is told. The vector says so with a worked pair and with two
+    upper-case cases, one binding where its lowercase twin binds and one
+    colliding where its twin collides, which is also what pins case being
+    normalised *before* the collision check. Every genuinely malformed
+    case is unchanged: empty, not hex, and both off-by-one lengths. The
+    mock normalises. The grader does not probe it in either direction: a
+    mint that normalises loses nobody money, and one that refuses upper
+    case outright is being strict rather than wrong, because the wallet
+    learns before it pays.
+
+- New `vectors/derivation.json`: deterministic note secrets from a BIP39
+  seed, so that a wallet can be restored from words alone and two
+  implementations of the same wallet derive the same notes.
+  - `k1` is WALLET-generated in LUD-25 and the draft says nothing about how
+    one is produced, so a wallet is free to derive it instead of drawing it
+    at random. Nothing about this is observable on the wire: the mint still
+    only ever sees `sha256(k1)`.
+  - The scheme, in full, so this entry alone is enough to reimplement it.
+    `root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed bytes)`,
+    then `k1 = HMAC-SHA256(key = root, msg = utf8(host + ":" + index))`.
+    Output is 32 bytes, lowercase hex, the same size as a payment preimage.
+    `host` is the mint host as the wallet stores it, lowercase, with the
+    port when there is one; `index` is decimal ASCII counting from 0. The
+    seed is the 64-byte BIP39 seed of a 12-word English mnemonic with no
+    passphrase.
+  - Cases cover the standard `abandon ... about` mnemonic at `mint.example`
+    for indices 0, 1, 2, 19 and 20 (19 and 20 straddle a 20-index gap
+    limit), a second mnemonic at the same host and index to show the seed
+    separates them, and a host carrying a port.
+  - Every case carries `seedHex` as well as the mnemonic, so an
+    implementation with no BIP39 library can still test the derivation
+    half on its own.
+  - `@scure/bip39` is a devDependency, used only to generate the file. The
+    published package gains no runtime dependency.
+
+- Self-check covers the new file: every `k1` recomputes from its own
+  `seedHex`, every mnemonic validates against the English wordlist and
+  produces the stated seed, and no two cases collide.
+
+- The retried mutation. Every mutation in LUD-25 is a GET, and HTTP stacks
+  retry a GET when the connection they used is dropped: Go's `net/http`
+  retries one that failed on a reused idle connection, the JDK's
+  `HttpClient` retries idempotent methods with no switch to turn it off.
+  The service therefore sees the byte-identical request twice, and by the
+  time the second arrives its inputs are burned. Answering it as an
+  already-spent input tells the holder the mutation never happened, and a
+  holder that believes it discards the only copy of a secret the service
+  really did mint a note against. Nobody is told; the money is gone.
+
+  - New `vectors/retried-mutation.json` fixes what identical means, so two
+    services do not give the same wallet two different answers to the same
+    dropped connection: the same input `k1` set (a set, so a merge naming
+    the same notes in a different order is the same merge), the same `h`,
+    the same `h2` and the same `amount`, present or absent alike. Twelve
+    cases, four of them replays and eight of them still double-spend
+    attempts, each turning on one thing being different. Anything that is
+    not a retry keeps today's refusal and today's reason string, so no
+    oracle appears for whoever holds a burned secret. Provenance is
+    recorded, never inferred: matching on "a note exists at `h`" alone
+    would let anyone holding a burned `k1` and any outstanding note id
+    pull a success out of a mint.
+
+  - Mock knob `retriedMutation`, `'refuse'` by default, which is exactly
+    what this mock has always done. `'replay'` answers a byte-identical
+    repeat with the original success. The replay path is a read: it burns
+    nothing, mints nothing and moves no balance, and the signature is
+    recomputed from the output id and amount rather than stored.
+
+  - New grader check `replays a retried mutation rather than refusing it
+    (optional)`, covering a rotate and a split so `h2` and the change
+    amount are covered too. Soft, because this is a SHOULD: a mint that
+    refuses the retry is reported as not having implemented it, not
+    failed. What is not soft is damage, so a retry that burns the output
+    or changes its value fails outright whichever answer it gives.
+
+  - The existing `refuses a replayed burn` check is untouched. It sends a
+    burned input with a *fresh* output hash, which is a genuine
+    double-spend attempt and a different request, and it still passes in
+    both modes.
+
+- Three optional extensions a mint may publish, none of them in LUD-25,
+  all of them absent or off unless asked for. A mock started with no
+  options answers byte for byte what it answered before, and a mint
+  publishing none of them is not graded down.
+
+  - **Mint info** on the experimental discovery endpoint. Mock knobs
+    `name`, `description`, `contact` (`{nostr, email, url}`), `tosUrl`,
+    `motd`, `version` and `previousPubkeys`, appended after the existing
+    fields so nothing above them moves. `fees: {baseFeeMsat, feePpm}` is
+    emitted whenever a fee is configured: the structured twin of the fee
+    line in the payRequest metadata, which stays exactly as it was.
+    `nodeCapacity` is emitted as before, under that name.
+
+  - **Liabilities**. Mock knob `stats: true` (default `false`, and when
+    off `/stats` falls through to the same 404 every unknown path gets)
+    serving `GET /stats` as `{at, outstandingMsat, outstandingNotes,
+    pendingMsat, pendingMelts, oldestPendingMeltAgeSecs, localBalanceMsat?,
+    coverage?, reconciledAt}`. Notes here are not blinded, so a mint can
+    state what it owes exactly. A note mid-melt counts under `pending`
+    rather than `outstanding`: its value is committed, not free, and it
+    comes back if the payment fails. `coverage` is
+    `localBalanceMsat / outstandingMsat` to four decimal places, omitted
+    when nothing is owed. Knob `localBalanceMsat` sets what the node
+    claims to hold, so a mock can be told to look under-covered.
+
+  - **Signing-key rotation**. Mock knobs `previousPrivateKey` (an old key
+    the mock still holds; its public half joins `previousPubkeys` on its
+    own) and `previousPubkeys`. `state.creditNote(k1, amount,
+    {previousKey: true})` signs one note under the old key and leaves the
+    rest under the new, and `/_test/credit?...&key=previous` does the
+    same out of process. `signWithPreviousKey` issues every note under the
+    old key while still advertising the new one: the mid-rotation state a
+    mint passes through when the advertisement moves before the signer.
+
+- Grader, all soft, all read-only:
+
+  - `publishes a mint address (experimental, optional)` keeps its name and
+    its existing assertions, and now checks the shape of the new fields
+    when they are present: the string fields non-empty, `tosUrl` and
+    `contact.url` fetchable, `contact.nostr` decoded as an npub rather
+    than pattern-matched, `contact.email` address-shaped, `fees` numeric
+    and not negative, `previousPubkeys` an array of 33-byte compressed
+    pubkeys in hex that does not merely restate the current one. A
+    malformed field is a warning, never a failure, and absence is neither.
+    The pass line names which fields it saw. A mint publishing its node
+    capacity as `nodeCapacityMsat` warns as well: the wire name carries no
+    suffix, and anything mapping the documented name reads undefined.
+
+  - New `publishes liabilities (optional)`. No `/stats`, or a `/stats`
+    that answers with something other than a liabilities body, is a
+    warning and nothing more. When it does answer, `outstandingMsat` must
+    be a number at or above zero and `coverage` must be numeric when
+    present. A node holding less than the mint owes warns rather than
+    fails: whether a mint is fully backed is the operator's to disclose,
+    and one that publishes an uncomfortable number is behaving better than
+    one that publishes nothing.
+
+  - `signs the notes it issues (optional)` accepts a signature recovering
+    any key the mint publishes, the current `mintPubkey` first and then
+    anything in `previousPubkeys`, and says which it was. Grading a note
+    issued before a rotation as forged would punish a mint for rotating
+    properly. `gradeNote` takes the list as `options.previousPubkeys`; the
+    CLI carries it across from the discovery endpoint on its own, which
+    `gradeMint` now hangs off the payRequest it returns as `mintAddress`.
+
+- New `vectors/payment-request.json`: one holder asking another for value,
+  as a string a payer's wallet can act on. Not to be confused with
+  `pay-request.json`, which is the LUD-06 payRequest a mint publishes; no
+  mint is involved in reading this one.
+  - Encoding is the NUT-18 `creqA` idiom with our own prefix:
+    `lnurlcashreq1` followed by the request canonicalised under RFC 8785
+    (JCS) and carried as unpadded base64url. Canonical because two wallets
+    building the same request must produce the same string, or the payee
+    cannot match what came back to what they asked for. One encode case is
+    the same request with its keys in a different order, encoding
+    identically, and one carries a non-ASCII memo, which JCS leaves alone
+    rather than escaping.
+  - `amount` is whole sat as a decimal string, matching what the 402
+    payment-method schemas carry; the payer sends `amount * 1000` msat
+    exactly. Sub-sat requests are not a thing.
+  - Decode cases cover the round trips, an expiry still in the future, an
+    expired one, one expiring exactly now, a bad prefix, no prefix, a
+    payload that is not base64url, a payload that is not a JSON object, an
+    unknown version, a non-integer amount in four spellings, an empty
+    mints array, no `methodDetails` at all, a `to` that is neither an npub
+    nor address-shaped, a `to` that looks like an npub but does not
+    decode, a currency that is not sat, and a malformed id. Every refusal
+    names a reason from a declared list, and every declared reason has a
+    case.
+  - The file states `evaluatedAt`, a fixed unix time the decode cases are
+    read at, so an expiry means the same thing on every run.
+
+- New `vectors/settle-for-value.json`: the decision table a server works
+  through when a bearer note arrives as payment, with the order it works
+  through it in.
+  - The order is the interesting part. Host, then what the mint says
+    (which is where a spent or in-flight note surfaces), then the
+    signature when one is required, then the value, then the rotate. A
+    note wrong in two ways is refused for the first reason in order, or
+    two servers explain the same note two different ways, and cases where
+    two things are wrong at once pin that.
+  - The rotate is deliberately last: it is both the ownership transfer and
+    the double-spend check, and a server that rotates before comparing the
+    amount has taken the money and refused the request.
+  - Outcomes are `accept`, `wrong-host`, `insufficient`, `bad-signature`,
+    `missing-signature`, `spent` and `pending`, all reachable. Also pinned:
+    hosts compare lowercased with the port included, an empty accepted-mint
+    list takes nothing rather than everything, a note worth exactly the
+    price is paid, and a signature that does not verify is accepted when
+    none was required, because the value came from asking the mint and the
+    mint is authoritative.
+
+- Self-check reimplements both decision tables rather than calling the
+  generator's, because a check that calls the function it is checking
+  proves only that the function is deterministic.
+
+- `signature.json` gains a `rotation` block: a note signed under a
+  previous key with both keys published (valid), the same signature byte
+  for byte with only the current key published (invalid), a
+  current-key signature alongside a published previous one (valid), and a
+  signature under a key that was never published (invalid). The cases
+  carry `mintPubkeys` as a list rather than the single `mintPubkey` the
+  existing cases carry, and live in their own block for that reason: a
+  verifier that knows nothing about rotation reads `cases` and is
+  completely unaffected by this release.
+
 ## 0.1.2 - 2026-08-21
 
 - The minted-value check took a band instead of a single number, because

package/README.md

@@ -46,6 +46,7 @@ for (const c of cases) {
 | File | Covers |
 | --- | --- |
 | `signature.json` | offline verification, both recovery-id orderings, malformed input |
+| `derivation.json` | deterministic note secrets from a BIP39 seed |
 | `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 |
@@ -56,6 +57,9 @@ for (const c of cases) {
 | `responses.json` | classifying every reply, including the ambiguous ones |
 | `withdraw-info.json` | the informational GET, and what makes a response invalid |
 | `pay-request.json` | minting, LUD-11 disposable, LUD-21 verify |
+| `payment-request.json` | `lnurlcashreq1`: one holder asking another for value |
+| `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 |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
 | `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
@@ -93,9 +97,34 @@ must survive:
 | `--baseFeeMsat=N --feePpm=N` | advertises and withholds a mint fee |
 | `--roundFeeToSat` | rounds the withheld fee up to a whole sat — the note mints short of the formula |
 | `--verifyLeaksEarly` | serves the preimage from verify before settlement — the bearer secret, to anyone with the hash |
+| `--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, echoes it back on the quote, and mints at the payment hash anyway, so the preimage is still the money |
+
+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.
 | `--verify=false` | no LUD-21 endpoint at all, not merely unadvertised |
 | `--withdrawLinkForm=lnurlw` | spells `withdrawLink` as `lnurlw://host/w` instead of the plain `https://host/w` the reference mint emits. Both are legal; a client has to take both |
 
+Five behaviours are outside LUD-25 and outside that table, because none
+of them is misbehaviour. All are absent or off unless you ask
+for them, so a mock started with no options answers exactly what it always
+answered:
+
+| Flag | What it does |
+| --- | --- |
+| `--name --description --contact --tosUrl --motd --version` | mint info on the experimental discovery endpoint: who runs this, how to reach them, the terms, and what the operator wants holders to know today |
+| `--baseFeeMsat --feePpm` | also publishes `fees: {baseFeeMsat, feePpm}` on that endpoint, the structured twin of the fee line in the payRequest metadata |
+| `--stats` | serves `GET /stats`: what the mint owes, what is in flight, what the node holds, and the coverage between them |
+| `--localBalanceMsat=N` | what the node behind a stats-publishing mock claims to hold, so a mock can be told to look under-covered |
+| `--previousPubkeys=a,b` | keys this mint has signed under before, so notes issued before a rotation still verify |
+| `--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 instead of `already spent`. The default, `refuse`, is what this mock has always done |
+| `--mintToHash` | takes an optional `h` on the pay callback and credits the minted note there, so the payment preimage is not the money. Off by default, and then `h` is not read at all |
+| `--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 |
+
 As a library, for your own test suite:
 
 ```js
@@ -109,7 +138,9 @@ 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.
+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.
 
 ## The grader
 
@@ -125,6 +156,48 @@ everyone on the payment's route knows the payment hash), whether an
 unknown note is reported distinguishably from a spent one, and the
 experimental mint address.
 
+One more is graded softly, and it is the one that changes what a bearer
+note is. In LUD-25 a minted note's `k1` is the payment preimage, so the
+preimage is the money, and every routing node on the payment path learns
+it, as does anyone who merely saw the invoice and polled LUD-21 verify with
+its payment hash. A QR on a desktop screen is exactly that. A mint may
+instead take an `h` on its pay callback, the sha256 of a secret the wallet
+chose, and credit the note there; the preimage is then an ordinary payment
+proof that opens nothing. The mint says so in three places, and they mean
+different things: `mintToHash: true` on the payRequest (every mint has one,
+so it is what a wallet decides from), the same on the experimental mint
+address document (corroboration), and the same echoed on the pay callback's
+own response when *that* quote was bound (the one that matters at the moment
+money moves, because the other two can be cached). Anything that is not
+exactly the boolean `true` is no.
+
+A mint that says nothing anywhere is reported as not offering it and passes,
+which is every mint today. A mint that claims it is asked to prove the
+refusals: a malformed `h` must get no invoice at all, since a wallet that
+pays for a quote the mint will reject has bought nothing. Malformed means
+not 32 bytes of hex, in any casing. A wallet MUST send `h` as 64 lowercase
+hex and every client here does, but hex is case-insensitive, so a service
+SHOULD normalise before comparing and MUST NOT read `AAAA...` and `aaaa...`
+as two different outputs: keying the string it was handed files the note
+where the wallet will never look for it, and nobody is told. A service that
+refuses upper case outright is being strict rather than wrong, so the grader
+does not probe it either way. Where the three
+claims disagree, the grader names the disagreement rather than failing it:
+none of those loses anyone money on its own. What is failed is a mint that
+claims the capability and does not bind, because a wallet believing the
+claim stops rotating on sight; that one needs a settlement to see, so it
+rides on `--preimage`.
+
+Three other things a mint may publish are graded softly, because none of them
+is in LUD-25: the mint info on the discovery endpoint, a `/stats` endpoint
+stating what the mint owes against what its node holds, and the signing
+keys it has used before. Publishing none of them costs nothing. Publishing
+one in the wrong shape is a warning, not a failure, because a wallet will
+try to render it and someone should say so. A mint whose node holds less
+than it owes warns too: whether it is fully backed is the operator's to
+disclose, and a mint that publishes an uncomfortable number is behaving
+better than one that publishes nothing.
+
 One check needs a real payment, which the runner cannot make on its own.
 Given a freshly minted, never-rotated note and what its mint invoice was
 paid at, it compares the note's value against the advertised fee:
@@ -141,7 +214,17 @@ npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --paid=50000
 # or --pr=<the mint invoice>, when it carries an amount
 ```
 
-This is still read-only. The full run spends:
+The bound-mint check needs a payment too. Mint against a hash you chose
+yourself, then hand the runner your own secret and the preimage of the
+invoice you paid: the note must really be at your secret, and the preimage
+must open nothing.
+
+```bash
+npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=<your secret>' \
+  --preimage=<the preimage of the invoice you paid>
+```
+
+Both are still read-only. The full run spends:
 
 ```bash
 npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --spend
@@ -151,9 +234,13 @@ 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`, that split and merge conserve value - exactly,
+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 -
-and that a burned secret cannot be replayed. It also probes three adversarial shapes a
+that a byte-identical repeat of a mutation is answered with the original
+success rather than as an already-spent input (a SHOULD, so a mint that
+has not implemented it is reported as such rather than failed), 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

package/llms.txt

@@ -11,6 +11,7 @@ Plain JSON in vectors/, loadable from any language, listed in
 vectors/index.json:
 
 signature.json       offline verification, both recovery-id orderings
+derivation.json      deterministic note secrets from a BIP39 seed
 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
@@ -21,6 +22,10 @@ callbacks.json       exact query per operation
 responses.json       classifying replies incl. ambiguous outcomes
 withdraw-info.json   the informational GET
 pay-request.json     minting, LUD-11, LUD-21
+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
 lifecycle.json       behavioural scenarios
 threat-suite.json    transport/exposure scorecard, options vs attacks (non-normative)
 
@@ -37,14 +42,43 @@ 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).
+
+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
+callback - and credits the minted note there, so the payment preimage is
+not a valid k1). Advertised in three places: mintToHash: true on the
+payRequest, the same on the mint address document, and the same echoed on
+the pay callback's own response when THAT quote was bound.
+mintToHashAdvertisedOn=payRequest,mintAddress,quote narrows which of the
+three claim it (all three by default; it changes only what is claimed).
+Misbehaviours, each needing mintToHash as well: mintToHashAcceptsMalformedH,
+mintToHashAcceptsUsedH, mintToHashIgnoresH.
+
+Optional extensions, all outside LUD-25, all absent or off by default:
+name, description, contact, tosUrl, motd, version (mint info on
+/.well-known/lnurlw/<user>); fees (emitted there whenever a fee is
+configured); stats=true (serves GET /stats: at, outstandingMsat,
+outstandingNotes, pendingMsat, pendingMelts, oldestPendingMeltAgeSecs,
+localBalanceMsat, coverage, reconciledAt) with localBalanceMsat to set
+what the node claims to hold; previousPrivateKey and previousPubkeys
+(signing-key rotation), plus signWithPreviousKey to issue every note under
+the old key. state.creditNote(k1, amount, {previousKey: true}) signs one.
+
 CLI: npx lnurlcash-mock-mint --port=8899  (nothing is payable)
 
 ## Grader
 
 npx lnurlcash-conform mint@example.com                        read-only
+npx lnurlcash-conform mint@example.com --note=<url> --preimage=<hex>  bound mint
 npx lnurlcash-conform mint@example.com --note=<url> --spend   full, burns the note
 
-Exit code non-zero on any failure.
+Exit code non-zero on any failure. The optional extensions are graded
+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
 
@@ -59,6 +93,59 @@ also accept recovery_id || r || s. Library layouts differ:
 @noble recid-leading; coincurve trailing; Rust secp256k1 64-byte compact +
 RecoveryId; Go btcec recid+27 leading.
 
+## Payment requests, canonically
+
+lnurlcashreq1 || base64url(JCS(request)), no padding. JCS is RFC 8785:
+keys sorted by UTF-16 code unit, no whitespace, non-ASCII left alone.
+Canonical so two wallets building the same request produce the same
+string. request = {v: 1, id: 16 hex, amount: whole sat as a DECIMAL
+STRING, currency: "sat", methodDetails: {mints: [host, ...]}, to?: npub or
+name@domain, memo?: string, expires?: unix seconds}. The payer sends
+amount * 1000 msat exactly. Refusal reasons are enumerated in the vector.
+
+## Settling a note for value, in order
+
+host in acceptedMints -> ask the mint (spent/pending surface here) ->
+signature when required -> value >= price -> rotate. The rotate is LAST:
+it is the settlement and the double-spend check in one call, and a server
+that rotates before comparing the amount has taken the money and refused
+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
+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
+bound; the only one that cannot be stale). Anything not exactly the
+boolean true is no. A WALLET MUST send h as 64 lowercase hex; a SERVICE
+SHOULD normalise case before comparing and MUST NOT read AAAA... and
+aaaa... as two outputs, since keying the string handed over files the note
+where the wallet never looks. A malformed h - not 32 bytes of hex in any
+casing - is refused with "Invalid h." before any invoice exists; an h already naming a note, an invoice or another quote's
+output is refused with "Invalid or already spent k1.", the same reason the
+withdraw callback gives, so no oracle appears. A WALLET MUST persist its
+secret BEFORE asking for the invoice. Purely additive: without h, nothing
+changes. Table in mint-to-hash.json.
+
+## 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
+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.
+
 ## Fee arithmetic
 
 apply(gross, fee) = max(0, gross - base - floor(gross*ppm/1e6))