lnurlcash-kit 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,331 @@
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 
+## 0.2.0 - 2026-08-22
+
+### Deterministic note secrets and restore from a seed
+
+- `deriveNoteRoot(seed)`, `deriveNoteSecret(root, host, index)` and
+  `derivedSecretSource(root, host, start)` in `secrets.ts`, plus
+  `restoreNotes(baseUrl, root, host, {gap, start}, opts)` in a new
+  `restore.ts`. All additive; nothing existing changes shape.
+- The scheme, in full, so this entry alone is enough to reimplement it:
+
+  ```
+  root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed)
+  k1_i = HMAC-SHA256(key = root,                      msg = utf8(host + ":" + index))
+  ```
+
+  `seed` is raw bytes of any length. A 64-byte BIP39 seed (12 words,
+  English wordlist, no passphrase) is what wallets use in practice, but the
+  kit is seed-format agnostic and depends on no wordlist. `host` is the
+  mint host exactly as `serverOf` produces it: lowercase, port included
+  where there is one, so `127.0.0.1:8899` and `mint.example` derive
+  different secrets. `index` is decimal ASCII counting from 0, and the
+  separator is a single colon. The HMAC output is 32 bytes, rendered
+  lowercase hex, which is the size of a payment preimage and therefore
+  indistinguishable from a randomly drawn `k1` on the wire. `hashK1`
+  applies unchanged, so the mint only ever receives `sha256(k1)` and sees
+  nothing different from before.
+
+  Worked example. The BIP39 mnemonic `abandon abandon abandon abandon
+  abandon abandon abandon abandon abandon abandon abandon about` with an
+  empty passphrase gives the seed
+  `5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4`.
+  Its root is
+  `948f8f49347549cf2726e8b53f673a4185379344d2d7ba8877d3ded45d34d127`, and
+  index 0 at host `mint.example` is
+  `1f6016c80339b45dfdd1b3877c1a97d74b063cad54c4ccb866be39ed25ee2ab0`.
+- Why it is in the kit rather than in a wallet: because the derivation is
+  written down once, the same words restore the same notes in a different
+  wallet, and the Kotlin, Python and Go ports agree with this one. That
+  cross-wallet portability is the point, and it is the reason the scheme
+  ships with a conformance vector.
+- Counters are the wallet's, one per mint host. `derivedSecretSource` is a
+  `RandomSecret`, so it drops straight into
+  `LnurlcashOptions.randomSecret` and rotate, split and merge draw derived
+  secrets without knowing anything about derivation; `source.index()` reads
+  back the next unused index afterwards. A rotate consumes one index, a
+  split consumes two. Minting can draw from the same source where the mint
+  advertises `mintToHash` - see "Name the note you are buying" below - and
+  the note is then derived from birth rather than from its first rotate. Persist that counter in the SAME write that stages
+  the new records, and do it BEFORE the hash goes on the wire: a crash
+  between the bump and the request wastes an index, which costs nothing,
+  while a crash the other way round re-derives a secret the mint has
+  already seen and the second note minted at it collides with the first.
+- `restoreNotes` walks indices from `start`, asking the mint what each
+  derived secret is worth. A live note is recorded; a note the mint reports
+  as spent still counts the index as used, since re-deriving it would mint
+  a duplicate id; a note the mint reports as pending is recorded with a
+  null amount for the caller to reconcile later; an unknown note counts
+  towards the gap. The walk stops after `gap` consecutive unknowns,
+  defaulting to 20, and `next` is one past the highest index the mint
+  recognised. It reads only, so an interrupted restore has changed nothing.
+  Any other failure is thrown rather than swallowed, because a short walk
+  reported as a finished one would leave the wallet re-deriving live
+  secrets.
+- A restored note carries no signature and its `k1` has just been on the
+  wire, so rotate each one straight after restoring. That closes the
+  exposure and gets the signature in the same call.
+- The seed is bearer material for every note the wallet will ever hold.
+  Store it the way the notes are stored, and never log it.
+- `classifyNoteError` now returns `PendingNoteError` for the exact reason
+  string `pending`, which LUD-25 fixes verbatim. Previously only the
+  mutating callback classified it, so an informational GET on a note with a
+  melt in flight raised a bare `ServiceRejectedError` that callers had to
+  re-parse. `PendingNoteError` extends `ServiceRejectedError`, so anything
+  catching the parent is unaffected.
+
+### Name the note you are buying
+
+- `requestInvoice(payCallback, amountMsat, {h, ...opts})` takes an optional
+  `h`: the sha256 of a secret the wallet chose, sent on the LUD-06 pay
+  callback exactly as `h` is sent on the withdraw callback. A mint that
+  accepts it credits the minted note at that hash on settlement, so the
+  wallet names the note it is buying instead of being handed one. The
+  options argument is the same object as before with one more optional
+  field on it, so every existing call is unaffected.
+- Why it matters. Without `h` the payment preimage IS the money, and two
+  sets of people learn it without being trusted: 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 the
+  payment hash that travels inside it and take the preimage the moment it
+  settles. A QR on a desktop screen is exactly that. "Rotate immediately"
+  is a race against a thief in a tight polling loop with a warm connection.
+  Choosing the secret yourself is not a race at all.
+- The capability appears in three places, and they say different things.
+  `PayRequestInfo.mintToHash` is "I accept an `h`", and is the one to
+  decide from: the payRequest is the only endpoint every mint has, it is
+  where a wallet already is at the moment it is about to mint, and it sits
+  alongside the `withdrawLink` the draft already hangs there for
+  LNURLcash's sake. `MintAddressInfo.mintToHash` is the same statement on
+  the experimental discovery document, kept for consistency with the other
+  capability fields there and the fallback for a mint that only says it
+  there. `InvoiceResult.mintToHash` is "I bound THIS quote to the hash you
+  named": per quote, and the one that matters at the moment money moves.
+- So the order is: read the payRequest, fall back to the mint address, and
+  a mint that advertises in neither place ignores the `h`. Undefined means
+  the mint said nothing, which a wallet reads as no. Anything that is not
+  exactly the boolean `true` is no, everywhere, which matters on the
+  payRequest because that response is spread through and a truthy string
+  would otherwise land on the typed field.
+- `InvoiceResult.mintToHash` being `false` is not a refusal: it means the
+  quote said nothing about `h`, and a mint may accept the parameter without
+  echoing it back. Decide from the advertisement, claim by probing.
+- A malformed `h` is refused with `RequestRefusedError` before anything is
+  sent, so a wallet never pays for a quote the mint was always going to
+  reject. The hash is normalised to lowercase on the way out.
+- Persist the secret BEFORE calling `requestInvoice`. Paying for a note and
+  then losing the secret is the one way this is worse than the preimage
+  scheme, and persisting first removes it.
+- `claimMintedNote(withdrawLink, k1, opts)` is the claim half, returning
+  `{state, k1, amountMsat, callback}` with `state` one of `'minted'`,
+  `'unminted'`, `'pending'` or `'spent'`. A wallet that chose its own
+  secret has nothing to fetch, so it asks the mint what the note at that
+  secret is worth and a live answer is the claim. Poll it while the invoice
+  is unpaid; it reads only, so an `'unminted'` answer has changed nothing.
+  A mint that cannot be reached throws rather than reporting `'unminted'`,
+  which a caller would fairly read as "not yet" and give up on.
+- No rotate follows a bound claim, and that is the point. The preimage
+  scheme needs one because the mint generated the secret and `verify` hands
+  it to anyone who saw the invoice. Here the mint never had it and no third
+  party can learn it, so the note belongs to the wallet from the moment it
+  exists. The claim GET does disclose the secret to the mint it is a claim
+  on, which is not the same exposure, and a wallet that wants an offline
+  signature on the note can still rotate to get one.
+- **This changes what the derivation section above says about minting.**
+  Until now a freshly minted note was never derived: its secret was the
+  mint's preimage, which nothing in a seed produces, so the note existed
+  outside the wallet's derivation until the immediate rotate moved it back
+  in. Draw the secret from `deriveNoteSecret` at the next index, send its
+  hash as `h`, and the minted note is seed-derived from birth. `restoreNotes`
+  finds it with no rotate having happened at all, which is what closes the
+  window where a wallet that crashed between paying and rotating could not
+  recover the note from its words. The counter rule is unchanged and applies
+  to the mint too: persist the bumped index in the same write that stages the
+  pending mint, before the hash goes on the wire.
+- Purely additive on the wire. A mint that does not offer `mintToHash`
+  ignores the parameter, keys the note by the preimage as it always has,
+  and the LUD-21 verify path is unchanged and still the way in.
+- `createClient(opts).requestInvoice(payCallback, amountMsat, h?)` takes the
+  hash as a third argument, and `claimMintedNote` is bound alongside it.
+
+### Mint info, and verifying against a key history
+
+- `MintAddressInfo` gains the operator fields a mint may publish on the
+  experimental discovery endpoint: `name`, `description`, `contact`
+  (`{nostr?, email?, url?}`), `tosUrl`, `motd`, `fees` (`{baseFeeMsat,
+  feePpm}`, the same shape `parseMintFee` returns, so it feeds
+  `applyMintFee` and `mintFeeBand` directly), `version` and
+  `previousPubkeys`. All optional, all absent on most mints, and none of
+  them is needed to spend a note.
+- `fetchMintAddress` now maps the response field by field instead of
+  spreading it through. The spread is what hid `nodeCapacity` under its
+  wire name until 0.1.1, and it also put whatever a mint decided to send on
+  a typed object with no type behind it. An unrecognised wire field is now
+  dropped rather than carried, so a caller reading one off the object with
+  a cast will find it undefined; the version of this library that
+  understands that field will map it deliberately.
+- `nodeCapacityMsat` is now populated from either spelling. The bare
+  `nodeCapacity` is what the reference mint, the mock and everything that
+  copied them emit, and it wins where a mint sends both; one live mint
+  emits `nodeCapacityMsat` instead, which previously survived only by
+  riding the spread.
+- `verifyNoteSignature(k1, amountMsat, sig, keys)` accepts a single pubkey
+  or an array, and is true if any of them signed. New
+  `verifyNoteSignatureAgainst(...)` returns `{valid, pubkey}` so a caller
+  learns WHICH key signed. An empty array is a rejection, never a pass.
+- Why: a mint that rotates its signing key would otherwise invalidate every
+  outstanding signature at once, and a wallet holding only the new key would
+  read every note it already had as forged. The mint publishes its retired
+  keys as `previousPubkeys`, the wallet verifies against the current key and
+  that history together, and a note that verifies only against a retired key
+  is one to rotate so the mint re-signs it. Only one recovery is performed
+  per signature layout, so a long key history costs a string comparison
+  each, not a recovery each.
+
+### Accepting a note as payment
+
+- `settleNoteForValue(noteUrl, {mints, minMsat, requireSignature}, opts)`
+  in a new `settle.ts`, returning `{note, newUrl}`. It is the decision
+  sequence every server accepting a bearer note performs, written once:
+  parse the input; check the note's mint is one the server accepts, before
+  any round trip, so an unaccepted mint is never contacted; fetch the
+  authoritative value and the mint's signing key; verify the signature over
+  that value where the server demands one; compare against the price;
+  rotate.
+- The rotate is the settlement, not bookkeeping after it. It burns the
+  secret the payer handed over and mints a replacement only the server
+  knows, in one atomic request at the mint, so it transfers ownership and
+  rejects a replay in the same call: a second presentation of the same note
+  finds it spent. A server that checks a note's value and grants access
+  without rotating has verified a photograph of a banknote.
+- New `InsufficientValueError`, extending `ServiceRejectedError` and
+  carrying `amountMsat` and `minMsat`, so a server can say how short a note
+  was rather than "declined". An unaccepted mint or a signature that will
+  not verify raises `ServiceRejectedError`; a spent note passes
+  `NoteSpentError` through; a note with a melt in flight raises
+  `PendingNoteError`, which is worth retrying rather than refusing. Nothing
+  is burned by any refusal, so a rejected note is still the payer's, intact.
+- `AmbiguousMutationError` from the rotate reaches the caller unchanged,
+  carrying the fresh secret. If that request landed, the secret is the money
+  and it belongs to the server: persist it before anything else.
+- An empty `mints` list accepts nothing. A note is a claim on one specific
+  operator, and "any mint" is not a policy a server should be able to hold
+  by accident.
+- The value compared against the price is always the one the mint states.
+  A note URL's own `amount` is a claim by whoever encoded it, and a
+  signature, where one is required, is checked over the mint's figure, so an
+  inflated URL fails rather than passing on a signature issued for the true
+  amount.
+
+### A retried mutation no longer loses the secret it minted
+
+- Every mutation is a GET, and HTTP stacks retry a GET whose connection
+  dropped: browsers on a stale keep-alive connection, Go's `net/http` on a
+  reused idle one, the JDK's `HttpClient` on any idempotent method with no
+  switch to stop it. The retry is byte-identical, so the mint sees the same
+  request twice and answers the second with its ordinary refusal for a
+  burned input, its inputs having been burned by the first. The caller was
+  told the mutation never happened while a note sat at the hash it had
+  disclosed, and the only copy of that secret went out of scope with the
+  call. The money was not stolen, it was made unspendable by anyone at all.
+- `rotateNote`, `splitNote` and `mergeNotes` now attach the secrets they
+  generated to a `NoteSpentError` or a `NoteUnknownError`, the way
+  `AmbiguousMutationError` already carried them. New `newSecretsOf(err)`
+  reads them off any error in one line, returning an empty array when there
+  are none, so a caller's catch block does not have to know which family it
+  is holding.
+- Only those two classes carry anything. They are the refusals that mean
+  "this input is not spendable", which is exactly what a landed-then-retried
+  mutation looks like. `PendingNoteError` means the input is alive and
+  untouched, and a refusal on policy grounds (dust, a fee, a sunsetting
+  mint) burned nothing, so both carry nothing and a caller may discard its
+  staged records at once.
+- The classification itself is unchanged, deliberately. At the wire a retry
+  and a genuine double spend are the same answer, and whether the input was
+  live when the request went out is knowledge the caller has and this
+  library does not. So it hands back the secret rather than a verdict:
+  persist it, then ask the mint what the note at that secret is worth. A
+  live note means the mutation landed.
+
+### The mint's signing key is called mintPubkey
+
+- `MintAddressInfo.mintPubkey` carries the wire value unchanged and is the
+  name to reach for. `nodePubkey` remains, populated with the same value,
+  and is deprecated: it will be removed at the next breaking change.
+  Nothing breaks in this release.
+- The two keys in a discovery document are different keys. `mintPubkey` is
+  what a note's signature verifies against; the Lightning node's identity
+  key is embedded in `nodeUri`. Every other `node*` field on the type
+  really is about the node - alias, colour, capacity, channel and peer
+  counts - so the signing key was the one exception, and its name said
+  nothing about that. A reader who pulled the pubkey out of `nodeUri` and
+  tried to verify a note with it got a failure that explained nothing.
+- It also makes the package internally consistent: the same key is already
+  called `mintPubkey` on a note's own info, so a reader moving between the
+  two objects met one key under two names.
+
+### Payment requests
+
+- `encodePaymentRequest(request)`, `decodePaymentRequest(string, {now})`,
+  `isPaymentRequest(string)` and `paymentRequestAmountMsat(request)` in a
+  new `request.ts`, with the `PaymentRequest` type and the
+  `PAYMENT_REQUEST_PREFIX` constant.
+- A request names an amount, the mints the payee accepts and where to
+  deliver, so a payer's wallet can split a note and send it straight across
+  instead of doing a mint-and-zap round trip through the mint's node for
+  something neither party needed a node for:
+
+  ```json
+  {"v": 1, "id": "0123456789abcdef", "amount": "500", "currency": "sat",
+   "methodDetails": {"mints": ["mint.example"]},
+   "to": "npub1...", "memo": "lunch", "expires": 1756000000}
+  ```
+
+  `id` is 16 lowercase hex characters, `amount` is whole sats as a decimal
+  string with no leading zeros, `to` is a Nostr npub or a Lightning Address
+  and is absent on a charge request served over HTTP, and `expires` is unix
+  seconds. `methodDetails` also accepts an optional `mintPubkeys`.
+- Encoded as `lnurlcashreq1` followed by base64url (unpadded) of the
+  request serialised as RFC 8785 JCS-canonical JSON: keys sorted by UTF-16
+  code unit at every level, no whitespace, integers only. Canonical because
+  a request is a thing people copy, quote back and match against a record of
+  what they asked for, so two encodings of the same request must be the same
+  string. This is NUT-18's `creqA` idiom with our own prefix, and it stays
+  short enough for a single static QR.
+- The object is the same charge request an HTTP 402 lnurlcash rail serves,
+  plus the transport fields a wallet-to-wallet send needs, so one encoder
+  covers both.
+- Validation is strict in both directions, an unrecognised field included:
+  quietly paying a request one did not fully understand is how a payer pays
+  the wrong person. Every refusal is a `ProtocolError`.
+- `amount` is in sat, which is the one exception to this library's
+  msat-everywhere rule, because the field is shared with the 402 rail and
+  the Cashu payment method and both count in whole units.
+  `paymentRequestAmountMsat` converts exactly, so nothing has to multiply by
+  hand.
+- An expired request does not decode, since paying one is always wrong. At
+  the expiry counts as expired, not merely past it, so a payer whose clock
+  is a second behind the payee's does not send a note against a request the
+  payee has already written off. `isPaymentRequest` still returns true for
+  it, so a scanner routes it to the pay screen and the holder is told it
+  lapsed rather than that their input was gibberish, and
+  `decodePaymentRequest(input, {now: 0})` returns it for display.
+- `to` is checked rather than shape-matched: an npub must survive its bech32
+  checksum. A request naming a destination nobody can route to is a request
+  nobody can pay, and a mistyped npub passes any regex.
+- **`lnurlcashreq1` means the schema above and nothing else.** An earlier
+  HTTP 402 rail emitted a shorter object under the same prefix -
+  `{"a": 21, "m": ["mint.example"], "u": "sat"}`, with the amount as a
+  number, no version and no id - and two schemas under one prefix cannot
+  both be right. This is the one the conformance vectors pin, so it is the
+  definition. The decoder reads the short form anyway, because returning
+  nothing for a string it can plainly understand helps no one, and gives it
+  a deterministic id derived from its own canonical bytes so the same
+  challenge always reads back as the same request. Nothing in this library
+  ever emits the short form.
+
 ## 0.1.2 - 2026-08-21
 
 - `mintFeeBand` and `withinMintFeeBand`. LUD-25 states the mint fee as

package/README.md

@@ -122,6 +122,31 @@ This is not hypothetical: the same hazard broke the
 development, by two different mechanisms, and is now a named scenario in the
 conformance vectors.
 
+Because a retry cannot always be prevented, a mutation refused with the
+input already spent or unknown carries its outputs anyway:
+
+```ts
+try {
+  await rotateNote(callback, oldK1)
+} catch (err) {
+  const secrets = newSecretsOf(err)   // works on both error families
+  if (secrets.length) {
+    await save(secrets)               // first. always.
+    // then ask: is there a note at that secret?
+    const fate = await probeBurnedNote(buildNoteUrl(base, secrets[0]))
+    // 'live' -> the mutation landed and you own the output
+    // 'gone' -> the refusal was honest, discard
+  }
+}
+```
+
+The class does not change: at the wire a retry and a genuine double spend are
+the same answer, and whether your input was live when the request went out is
+something you know and this library does not. So it hands back the secret
+rather than a verdict. A refusal that cannot be a landed mutation, such as a
+mint refusing on policy grounds, carries nothing, and you can discard your
+staged records at once.
+
 **4. A melt's `OK` means "in flight", not "spent".** The service pays
 asynchronously and only burns the note once the payment settles, restoring
 it if the payment fails. A failed melt is never reported back through the
@@ -136,6 +161,12 @@ who saw the unpaid invoice can poll for it — the payment hash travels inside
 the invoice. First rotater wins. A wallet that rotates on settlement wins by
 construction; a human copying a preimage by hand does not.
 
+That is a race, and the way to win a race is not to enter it. Where a mint
+advertises `mintToHash`, name the note you are buying and the preimage is
+not its secret at all: see
+[Minting a note you named yourself](#minting-a-note-you-named-yourself).
+The rule above stands for every mint that does not offer it.
+
 ## Offline verification
 
 A service may sign each note with its Lightning node identity key, so a
@@ -156,6 +187,289 @@ The signature commits to the note's *hash*, not its secret — so you can
 prove a mint issued a note, to expose one that will not honour it, without
 handing over what would let anyone spend it.
 
+### When a mint rotates its signing key
+
+Rotating invalidates nothing. The notes already issued are still genuine and
+their signatures still verify, but only against the key that made them, so a
+wallet holding the new key alone would suddenly read every outstanding note
+as forged. A mint publishes the keys it has retired as `previousPubkeys` on
+its mint address, and verification takes the whole set:
+
+```ts
+const {mintPubkey, previousPubkeys = []} = await fetchMintAddress(addressUrl)
+const check = verifyNoteSignatureAgainst(k1, amountMsat, sig, [
+  mintPubkey,
+  ...previousPubkeys
+])
+// check.pubkey names the key that signed. A note that verifies only against
+// a retired one is worth rotating: the mint re-signs it under the current key.
+```
+
+`verifyNoteSignature` takes the same one-or-many argument and returns a plain
+boolean. An empty list is a rejection, not a pass.
+
+### What else a mint says about itself
+
+`mintPubkey` is the key note signatures verify against, and it is *not* the
+Lightning node's key: that one is embedded in `nodeUri`, and every other
+`node*` field really is about the node. Verifying a note against the key
+pulled out of `nodeUri` fails, and the failure says nothing about why.
+`nodePubkey` is a deprecated alias for the same value, kept for one release.
+
+`fetchMintAddress` reads the experimental discovery endpoint, and a mint may
+publish a `name`, a `description`, `contact` details, a `tosUrl`, a `motd`,
+its structured `fees` and its software `version` there. All optional, all
+absent on most mints, and none of it is needed to spend a note. Surface the
+MOTD when it changes: it is how an operator announces maintenance, a fee
+change or a sunset date, and there is no other channel to a bearer holder.
+The endpoint carries no LUD number, so treat a rejection as "no extra
+information" and fall back to `fetchPayRequest`.
+
+## Secrets
+
+A note's `k1` is generated by the wallet, and LUD-25 says nothing about how.
+Draw it from a CSPRNG and the note lives only in your wallet file: the mint
+holds `sha256(k1)` and cannot tell you apart from a stranger, so a lost file
+is lost money. Derive it from a seed instead and the wallet restores from
+words alone.
+
+```
+root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed)
+k1_i = HMAC-SHA256(key = root,                      msg = utf8(host + ":" + index))
+```
+
+`seed` is raw bytes. A 64-byte BIP39 seed is what wallets use in practice,
+but nothing here depends on BIP39, so a device with its own entropy store
+derives the same way and no consumer carries a wordlist it does not need.
+`host` is the mint host exactly as `serverOf` spells it, lowercase and with
+the port where there is one, so `127.0.0.1:8899` and `mint.example` never
+collide. `index` is decimal ASCII from 0. The output is 32 bytes of hex, the
+size of a payment preimage, and the mint sees nothing different: it only
+ever receives `sha256(k1)`.
+
+Because the scheme is written down here rather than invented per wallet, the
+same words restore the same notes in a *different* wallet. That
+cross-wallet portability is the point of putting it in the kit, with
+[a conformance vector](https://github.com/TheCryptoDonkey/lnurlcash-conformance)
+for the ports.
+
+```ts
+import {deriveNoteRoot, derivedSecretSource, restoreNotes} from 'lnurlcash-kit'
+
+const root = deriveNoteRoot(seed)          // seed: Uint8Array, yours to keep safe
+const source = derivedSecretSource(root, 'mint.example', counter)
+
+// hand it to any mutating call and the fresh secrets come from the seed
+const {k1, change} = await splitNote(callback, [note], 40_000, {randomSecret: source})
+saveCounter('mint.example', source.index())  // a split consumed two indices
+```
+
+Persist that counter in the **same write that stages the new records**, and
+do it **before** the hash goes on the wire. A crash between the bump and the
+request wastes an index, which costs nothing. A crash the other way round
+re-derives a secret the mint has already seen, and the second note minted at
+it collides with the first. This is the rule wallets get wrong.
+
+Restoring walks the indices and asks the mint what each derived secret is
+worth:
+
+```ts
+const {found, next} = await restoreNotes('https://mint.example/w', root, 'mint.example')
+```
+
+A live note is recorded, a spent index still counts as used (re-deriving it
+would mint a duplicate), an unknown one counts towards the gap, and the walk
+stops after 20 consecutive unknowns. `next` is the counter to resume from.
+Restoring puts every `k1` it walks on the wire and a restored note carries no
+signature, so rotate each one straight after: that closes the exposure and
+gets the signature in the same call.
+
+The seed is bearer material for every note the wallet will ever hold. Store
+it the way you store the notes, and never log it.
+
+## Minting a note you named yourself
+
+By default the secret of a freshly minted note is the invoice's payment
+preimage, which means the money is a thing two sets of people learn without
+being trusted. Every routing node on the payment path sees it, because that
+is how HTLC settlement works. And anyone who merely saw the unpaid invoice
+can poll LUD-21 `verify` with the payment hash inside it and take the
+preimage the moment it settles, which is what a QR code on a desktop screen
+hands out.
+
+A mint can instead bind the note to a hash you supply, the same `h` you
+already send on every rotate, split and merge. Then you chose the secret,
+nobody else ever had it, and the preimage is an ordinary payment proof.
+
+```ts
+import {
+  fetchPayRequest, requestInvoice, claimMintedNote,
+  deriveNoteRoot, deriveNoteSecret, hashK1
+} from 'lnurlcash-kit'
+
+const pay = await fetchPayRequest(payUrl)      // a Lightning Address resolves here
+if (!pay.mintToHash) { /* preimage path, rotate on claim */ }
+
+const root = deriveNoteRoot(seed)
+const k1 = deriveNoteSecret(root, 'mint.example', nextIndex)
+await persist({k1, index: nextIndex})          // BEFORE the invoice. always.
+
+const {pr} = await requestInvoice(pay.callback, 21_000, {h: hashK1(k1)})
+
+// pay `pr`, then poll. No verify, because you already know the secret.
+const claim = await claimMintedNote(pay.withdrawLink!, k1)
+// 'unminted' -> not settled yet, ask again
+// 'minted'   -> claim.amountMsat is what it is worth, claim.callback melts it
+```
+
+Ask before you buy. `mintToHash` is how a mint says it accepts the parameter,
+and reading it first is the difference between naming your own note and paying
+for one whose secret three other parties can learn. It turns up in three
+places, saying three different things:
+
+| Where | What it means |
+| --- | --- |
+| `PayRequestInfo.mintToHash` | "I accept an `h`." **Decide from this one.** |
+| `MintAddressInfo.mintToHash` | the same fact on the experimental discovery document |
+| `InvoiceResult.mintToHash` | "I bound *this quote* to the hash you named" |
+
+Prefer the payRequest: it is the only endpoint every mint has, it is where
+your wallet already is when it is about to mint, and it sits next to the
+`withdrawLink` the draft already hangs there for LNURLcash's sake. Fall back
+to `fetchMintAddress` for a mint that only advertises on that document. A mint
+that says it in neither place ignores the `h`, keys the note by the preimage
+as it always has, and the verify path is unchanged. Anything that is not
+exactly `true` is a no, everywhere, and `false` on the invoice result is
+silence rather than a refusal, so decide from the advertisement and claim by
+probing.
+
+**Persist the secret before you ask for the invoice.** Paying for a note and
+then losing the secret is the one way this is worse than the preimage scheme,
+and persisting first removes it. Derive it rather than drawing it at random
+and there is a second reason: the note is then seed-derived *from birth*, so
+`restoreNotes` finds it without any rotate having happened. Under the preimage
+scheme a minted note lives outside your derivation until the immediate rotate
+pulls it in, and a wallet that crashes in that window cannot recover the note
+from its words.
+
+No rotate follows a bound claim. The preimage scheme needs one because the
+mint made the secret and hands it out; here the mint never had it, so the note
+is yours from the moment it exists. The claim GET does show the secret to the
+mint it is a claim on, which is a different thing from showing it to whoever
+scanned the QR, and you can still rotate if you want the offline signature.
+
+## Asking to be paid
+
+"Send me 500 sat" today means handing over a Lightning Address, which is a
+mint-and-zap round trip through the mint's node for something neither party
+needed a node for. A payment request names the amount, the mints the payee
+will accept and where to deliver, and the payer's wallet splits a note and
+sends it straight across. Wallet to wallet; the mint only ever sees a split.
+
+```ts
+import {encodePaymentRequest, decodePaymentRequest, paymentRequestAmountMsat} from 'lnurlcash-kit'
+
+const encoded = encodePaymentRequest({
+  v: 1,
+  id: '0123456789abcdef',            // 8 random bytes, hex
+  amount: '500',                     // whole sats, decimal string
+  currency: 'sat',
+  methodDetails: {mints: ['mint.example']},
+  to: 'npub1...',                    // or alice@mint.example
+  memo: 'lunch'
+})
+// lnurlcashreq1eyJhbW91bnQiOiI1MDAiLCJjdXJyZW5jeSI6InNhdCIsImlkIjoiMDEy...
+
+const request = decodePaymentRequest(scanned)   // throws ProtocolError if it is not one
+const owed = paymentRequestAmountMsat(request)  // 500_000
+```
+
+The encoding is `lnurlcashreq1` followed by base64url of the request as
+[JCS](https://www.rfc-editor.org/rfc/rfc8785)-canonical JSON, which is
+NUT-18's `creqA` idiom with our own prefix. Canonical because a request is a
+thing people copy, quote back and match against a record of what they asked
+for: two encodings of the same request must be the same string, or none of
+that works. It stays short enough for one static QR.
+
+The object is the same charge request an HTTP 402 lnurlcash rail serves,
+plus the transport fields a wallet-to-wallet send needs, so one encoder
+covers both. Validation is strict in both directions, including an
+unrecognised field: quietly paying a request you did not fully understand is
+how you pay the wrong person.
+
+`amount` is in **sat**, and it is the one exception to this library's
+msat-everywhere rule. That is deliberate: the field is shared with the 402
+rail and the Cashu payment method, both of which count in whole units. Use
+`paymentRequestAmountMsat` rather than multiplying by hand.
+
+An expired request will not decode, because paying one is always wrong. At
+the expiry counts as expired, not merely past it, so a payer whose clock is a
+second behind the payee's does not send a note against a request the payee
+has already written off. `isPaymentRequest` still returns true for it, so a
+scanner routes it to the pay screen and the user is told it lapsed rather
+than that their input was gibberish; `decodePaymentRequest(input, {now: 0})`
+returns it for display.
+
+`to` is checked, not merely shape-matched: an npub has to survive its bech32
+checksum, because a request naming a destination nobody can route to is a
+request nobody can pay.
+
+**`lnurlcashreq1` means this schema and nothing else.** An earlier HTTP 402
+rail emitted a shorter object under the same prefix (`{"a": 21, "m":
+["mint.example"], "u": "sat"}`: amount as a number, no version, no id). Two
+schemas under one prefix cannot both be right, and this is the one the
+vectors pin. The decoder reads the short form anyway, because refusing a
+string it can plainly understand helps nobody, and gives it a deterministic
+id derived from its own bytes. Nothing here ever emits it.
+
+## Taking a note as payment
+
+A server that accepts bearer notes for something makes the same decisions
+every time, in this order, and `settleNoteForValue` is that order written
+once:
+
+```ts
+import {settleNoteForValue, InsufficientValueError} from 'lnurlcash-kit'
+
+try {
+  const {note, newUrl} = await settleNoteForValue(offered, {
+    mints: ['mint.example'],   // hosts this server accepts. An empty list accepts nothing.
+    minMsat: 21_000,           // the price
+    requireSignature: false    // demand offline proof of issuance first
+  })
+  grantAccess()                // note.k1 is yours now; newUrl is a note to store or melt
+} catch (err) {
+  if (err instanceof InsufficientValueError) refuse(err.amountMsat, err.minMsat)
+  else refuse()
+}
+```
+
+1. the input parses as a note at all
+2. its mint is one this server accepts (checked before any round trip, so an
+   unaccepted mint is never contacted)
+3. an informational GET for the **authoritative** value and the mint's key
+4. the signature, where the server demands one, over the value the mint
+   stated rather than the one the URL claims
+5. that value covers the price
+6. **rotate**
+
+Step 6 is the settlement, not bookkeeping after it. Rotating burns the
+secret the payer handed over and mints a replacement only this server knows,
+in one atomic request: it transfers ownership and rejects a replay in the
+same call, because a second presentation of the same note finds it spent. A
+server that checks a note's value and grants access without rotating has
+verified a photograph of a banknote.
+
+Refusals are typed, and nothing is burned by any of them: `ServiceRejectedError`
+for an unaccepted mint or a signature that will not verify,
+`InsufficientValueError` (carrying both amounts) for a note worth too
+little, `NoteSpentError` for one already spent or presented twice,
+`PendingNoteError` for one with a melt in flight, which is worth retrying
+rather than refusing outright. `AmbiguousMutationError` from the rotate is
+the case to handle with care: persist `err.newSecrets` before anything else,
+because if the request landed then that secret is the money and it is now
+this server's.
+
 ## Scope
 
 This library speaks the protocol. It does not store notes, hold keys, manage