lnurlcash-conformance 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,357 @@ 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
+  it was failing the reference implementation.
+  - LUD-25 states the mint fee as `base_fee_msat` plus a ppm cut and says
+    nothing about rounding. dni's lnurl-mint ceilings that fee to a whole
+    sat on purpose, so the mint is "never short a sat"; moneyer is
+    msat-exact. Every public mint on the awesome list except moneyer runs
+    lnurl-mint, so the majority of live services round.
+  - The check asserted equality against the msat-exact formula, and even
+    named the rounding in its failure message as something "the formula
+    does not allow". Measured on real sats: 40,000 msat at
+    mint.forgesworn.dev with a 1000 + 1000 ppm fee credits 38,000, not
+    38,960. A clean grade was unreachable for the reference.
+  - Deciding which reading is right is not this repo's job - "either may
+    be wrong, and the LUD-25 PR is where that gets settled". So the
+    compliant answer is now the range between the two: the formula is the
+    most a holder can be credited, the sat-ceilinged fee the least. The
+    report names which one it saw.
+  - Both edges are graded, and selfgrade proves it: a msat past the
+    ceilinged fee fails, and so does crediting more than the formula. A
+    band with no edges would grade nothing. The mock's `roundFeeToSat` is
+    reclassified from a misbehaviour to the reference's behaviour, and
+    gains `extraFeeMsat` for landing outside the band deliberately.
+
+- Two refusals LUD-25 spells out were never graded. Both are reachable
+  against a live mint, and both were being stepped around rather than
+  tested.
+  - `refuses a split with no h2`: a split names two outputs, so a mint
+    given only `h` either refuses or invents the change note's secret
+    itself. The second is the exact prior-holder exposure wallet-generated
+    secrets exist to close, and it was ungraded.
+  - `refuses a split whose change cannot cover the base fee`: the grader
+    already knew the advertised base fee, and skipped (`note too small to
+    split past the advertised base fee`) rather than deliberately leaving
+    change one msat short of it. It now does that on purpose and expects
+    `insufficient value`. Warns when no fee is advertised, since the rule
+    cannot bite.
+  - Both confirm the note survives the refusal, and both are self-verified:
+    the mock gains `acceptsMissingH2` and `splitIgnoresBaseFee`, and
+    selfgrade asserts each is caught by name rather than by failure count.
+- The grader never melts, so `pending`, restore-on-failure and a melt's own
+  LUD-21 `verify` cannot be graded against a live service - melting real
+  sats is not something a grader may do on its own initiative. The mock
+  covers all three for client-side suites. Said so in the README, which
+  previously left the gap to be inferred.
+
+- `withdrawLink` has two legal spellings in the wild. LUD-25 calls it "a
+  raw, non bech32-encoded URL as described in LUD-17", and LUD-17 describes
+  both the `lnurlw://` scheme and the plain `https://` URL it stands for.
+  lnurl-mint (and the spec's own diagram) emit `https://mint.example/w`;
+  moneyer emits `lnurlw://moneyer.dev/w`. The mock mint only ever served
+  the second, so a client that broke on the reference mint's form would
+  still have passed here.
+  - The mock mint now serves the plain `https://` spelling by default,
+    matching the reference mint, and takes `withdrawLinkForm: 'lnurlw'`
+    for the other. A test asserting the old `lnurlw://` default needs
+    updating (lnurlcash-kit's did).
+  - `pay-request.json` gains accepted cases for the plain form and for an
+    onion host; a parser must pass both through untouched.
+  - The grader accepts either spelling, rejects a bech32 `lnurl1...` value,
+    and names the form in its report. Its three ad-hoc `lnurlw://` rewrites
+    are now one exported `fromLud17`.
+  - Selfgrade runs the compliant mock in both forms.
+
 ## 0.1.1 - 2026-08-20
 
 - The mock mint's mint-address response now carries the node stats

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,7 +57,11 @@ 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) |
 
 Regenerate with `npm run generate`; check them with `npm test`, which
 verifies every digest recomputes, every declared signature really does
@@ -92,7 +97,33 @@ 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:
 
@@ -107,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
 
@@ -115,24 +148,83 @@ actually did rather than what it said.
 npx lnurlcash-conform mint@example.com
 ```
 
-Read-only by default: resolves the payRequest, checks the `withdrawLink`,
+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, that LUD-21 verify serves no
 preimage before settlement (on a mint that value IS the bearer secret, and
 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 fee formula - msat-exact,
-so a fee implementation that quietly rounds up to whole sats is caught:
+paid at, it compares the note's value against the advertised fee:
+
+LUD-25 says nothing about whether that fee rounds, and the two live
+implementations differ. dni's lnurl-mint ceilings it to a whole sat on
+purpose, so the mint is never short a sat; moneyer withholds the
+msat-exact amount. Both pass. The check grades the range between them and
+names which it saw, and a msat outside it either way fails - a mint taking
+more than the ceilinged fee, or crediting more than it advertised.
 
 ```bash
 npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --paid=500000
 # 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
@@ -142,18 +234,34 @@ 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
-that id's preimage), and a split whose `h` equals `h2` (one id cannot carry
-two notes). And it replays the callback as a POST and as an OPTIONS
+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.
 
+**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,
+so `pending` on a k1 mid-melt, restoring the note when the outgoing payment
+fails, and the melt's own LUD-21 `verify` are all outside what a grade can
+say anything about. They are not unspecified and not untested: the mock mint
+implements every one of them (`meltNeverSettles`, `meltAlwaysFails`), so a
+client suite driving the mock covers the whole melt path. A clean grade
+means the read-only and non-melt mutating surface is compliant, no more.
+
 The grader shares no code with any LNURLcash library — it is written against
 `fetch` and `@noble` directly. A grader that shared an implementation with
 the thing it grades would agree with that implementation's mistakes, which
@@ -171,6 +279,9 @@ Spec and reference implementations, all by dni, all MIT:
 - [lnurl-mint](https://github.com/dni/lnurl-mint) — the reference service
 - [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
 
+Implementations to run these vectors against are indexed in
+[awesome-lnurlcash](https://github.com/TheCryptoDonkey/awesome-lnurlcash).
+
 Contributions of vectors are welcome, particularly from implementers who
 found a case these missed. See [CONTRIBUTING.md](CONTRIBUTING.md).