lnurlcash-kit 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-09-04
+
+**LUD-25's own derivation, and it is now the one to mint under.** The draft's
+"Seed-recoverable note secrets" section specifies a BIP-32 scheme under
+`m/139'`, and the reference wallet implements it. This kit had shipped its own
+HMAC scheme four days before that section existed. One convention is the whole
+point of writing either of them down, so the specified one wins.
+
+- `deriveCashRoot(seed)`, `deriveCashDomainNode(root, host)`,
+  `deriveCashSecret(root, host, index)`, `cashSecretAt(domainNode, index)`,
+  `cashSecretSource(root, host, start)`, `cashNodeToHex` / `cashNodeFromHex`
+  and `deriveCashChild` in a new `cash.ts`. Additive - nothing existing
+  changes shape.
+- The scheme, in full, so this entry alone is enough to reimplement it:
+
+  ```
+  cashHashingKey   = m/139'/0
+  (d1, d2, d3, d4) = HMAC-SHA256(key = cashHashingKey, msg = utf8(host))[0..16]
+                     as 4 big-endian uint32
+  k1_i             = m/139'/d1/d2/d3/d4/i'
+  ```
+
+  `d1..d4` are used **exactly as they fall**. BIP-32 already reads any index
+  `>= 2^31` as hardened, so which of the four levels are hardened is decided
+  by the mint's host name and roughly half of them will be. Masking the top
+  bit, or hardening all four, derives a different tree and restores nothing,
+  silently. Only `i` is always hardened. `host` is what `serverOf` produces -
+  lowercase, port included - byte-identical to the reference wallet's.
+
+  Worked example. The BIP39 mnemonic `abandon abandon abandon abandon abandon
+  abandon abandon abandon abandon abandon abandon about` with an empty
+  passphrase gives `m/139'` as
+  `c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60`
+  (privateKey || chainCode). At `mint.example` the four levels are
+  `[2589708612, 3693348916, 172082394, 3793182078]`, of which the third is
+  the only unhardened one, and index 0 is
+  `de5b81405a12e1297b350d80e2ad85043ed5b9436a0c5592d3302778de330499`.
+- **The hardware-signer path.** Every unhardened level sits at or above the
+  per-mint node, so a signer provisioned with `deriveCashDomainNode`'s output
+  rather than the seed needs no elliptic curve at all: each `i'` beneath it is
+  HMAC-SHA512 and one modular addition. Whoever derives that node can derive
+  every note secret the wallet will hold at that mint, so it is provisioning
+  material - one mint's subtree, not the wallet.
+- BIP-32 is implemented here from its own primitives rather than pulled in as
+  a dependency, and tested against BIP-32's published test vector 1. Every
+  LUD-25 value above is checked against output from the reference
+  implementation's own library.
+
+**`restoreFromSeed` walks both schemes.** Notes minted under the old scheme
+are still money and a wallet that walked only the new one would leave them at
+a mint it can no longer name.
+
+- `restoreFromSeed(baseUrl, seed, host, {gap?, start?, probeK1?,
+  allowSecretDisclosure?}, opts?)`. `RestoredNote.scheme` is `bip32` or
+  `hmac`, `next` is `{bip32, hmac}`, and `start` takes one per scheme.
+- `restoreNotes` is unchanged in signature and behaviour, and still walks the
+  legacy scheme alone. `RestoredNote` and `UnresolvedIndex` gain a `scheme`
+  field.
+- `deriveNoteRoot`, `deriveNoteSecret` and `derivedSecretSource` are not
+  deprecated and are not going anywhere. Do not mint under them.
+
+**Say plainly what a restore can and cannot do.** LUD-25 requires a hash
+lookup to answer for a burned note exactly as it answers for one that never
+existed, and both reference mints do. So a by-hash walk cannot see a spent
+index at all; and since a rotate burns the *old* index, a wallet's spent
+indices sit below its live ones, and one that has rotated more than `gap`
+times scans as completely empty. The persisted per-host counter is what makes
+recovery work - the scan is the fallback. That counter is not secret, so it
+belongs in an ordinary backup, and a restore should merge counters upwards
+only. Documented on `RestoreOptions.start`, in the README and in `llms.txt`.
+
+Graded against `lnurlcash-conformance` 0.7.0, whose `cash-derivation.json`
+cases this suite now runs: the LUD-25 path, the four domain levels per host,
+the hardened-by-magnitude flags, and BIP-32's own published test vector 1.
+
+## 0.7.0 - 2026-09-04
+
+**Offline verification is mandatory, and this library now insists on it.**
+LUD-25 stopped treating a note signature as optional: a SERVICE MUST
+publish `mintPubkey` and MUST sign every note a rotate, split or merge
+mints. A wallet that quietly accepted unsigned notes was handing its holder
+something nobody downstream could check, which is exactly the gap offline
+verification exists to close.
+
+- `fetchNoteInfo` and `fetchNoteInfoByHash` refuse a `withdrawRequest` that
+  publishes no `mintPubkey`, or one that is not a 33-byte compressed
+  secp256k1 key. `WithdrawRequestInfo.mintPubkey` is typed as present.
+- `rotateNote`, `splitNote`, `mergeNotes` and their `*WithHash` forms throw
+  the new `UnverifiableNoteError` when the SERVICE confirms the mutation but
+  returns no `sig` (or no `sig2` on a split's change).
+- **That error carries the secrets.** The mutation landed - `status` was OK -
+  so the note exists at the hash the wallet disclosed and its secret is the
+  only key to that value. `newSecretsOf()` reads them exactly as it reads
+  them off an ambiguous mutation. Enforcing conformance must never be the
+  thing that destroys the money.
+- `requireSignatures: false` opts out, for a mint that predates the
+  requirement. One option, stated once, at the call site that needs it.
+
+**A mutation whose answer was lost is now re-sent, and usually completes.**
+LUD-25 gained a "Retrying a mutation" section: a SERVICE MUST answer a
+byte-identical rotate, split or merge with the success it already returned,
+signature and all, rather than with the already-spent refusal its burned
+inputs would otherwise earn.
+
+That closes the sharpest edge in the protocol. Every mutation is a GET,
+HTTP treats GET as idempotent, and stacks retry one whose connection
+dropped - browsers on a stale keep-alive, Go's `net/http` on a reused
+connection, the JDK's `HttpClient` with no way to switch it off. The mint
+saw the request twice, answered the second as already spent, and the wallet
+was told a mutation had not happened while a note sat at the hash it had
+disclosed. Now the second answer is the first one.
+
+- `mutationRetries` defaults to 1. Set 0 for the previous behaviour.
+- Only rotate, split and merge. A melt is **never** retried: it carries
+  `pr`, is paid out asynchronously, and the replay rule does not cover it.
+- Only an ambiguous failure is retried. A definitive refusal is the
+  SERVICE's considered answer and asking again cannot improve it.
+- The retry re-sends the identical request rather than rebuilding it. The
+  replay is matched on the k1 set, `h`, `h2` and `amount`, so a freshly
+  generated secret would make the second attempt a different mutation - and
+  a second real burn.
+
+Against a SERVICE that has not implemented the replay rule, retrying leaves
+a caller exactly where giving up would have: the same secrets on the same
+error, and the same instruction to go and ask what the note at each hash is
+worth.
+
+Requires `lnurlcash-conformance` 0.6.0, whose vectors carry the same MUSTs.
+
 ## 0.6.0 - 2026-08-31
 
 - `namesMintOutput()` now requires `commentAllowed >= 64`; the additive

package/README.md

@@ -58,14 +58,15 @@ console.log(info.maxWithdrawable, 'msat')
 // that GET put the secret on the wire, so rotate it
 const fresh = await rotateNote(info.callback, info.k1)
 
-// and check the mint really issued it, without asking anyone
-if (info.mintPubkey && fresh.signature) {
-  verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature, info.mintPubkey)
-}
+// and check the mint really issued it, without asking anyone. Both fields
+// are guaranteed here: LUD-25 requires the mint to publish mintPubkey and
+// to sign what it mints, and this library refuses a mint that does neither.
+verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature!, info.mintPubkey)
 ```
 
 Every request function takes options last — `fetch`, `timeoutMs`, `offline`,
-`randomSecret`. `createClient(options)` binds one set once:
+`randomSecret`, `requireSignatures`, `mutationRetries`.
+`createClient(options)` binds one set once:
 
 ```ts
 const client = createClient({timeoutMs: 10_000})
@@ -107,23 +108,39 @@ try {
 
 `RequestRefusedError` is the opposite and safe: nothing left the process.
 
-**3. Your HTTP stack must not retry.** Every mutation is a GET, HTTP treats GET
-as idempotent, and an LNURLcash mutation is not — the first attempt burns the
-input. A retried mutation is answered "already spent", which reads as a
-*definitive* rejection, so the fresh secret gets discarded along with the note
-the service just minted. Node's `fetch` does not retry on its own, but a
-browser will resend an idempotent request that failed on a stale pooled
-connection, and any retry wrapper, service worker or proxy in front of this
-will do the same. If you pass your own `fetch`, do not make it retry these.
-
-This is not hypothetical: the same hazard broke the
+**3. A retried mutation is now a replay, not a double spend.** Every mutation
+is a GET, HTTP treats GET as idempotent, and an LNURLcash mutation is not —
+the first attempt burns the input. For most of this draft's life that was the
+sharpest edge in the protocol: a stack that resent a dropped GET got "already
+spent" for the second attempt, which reads as a *definitive* rejection, so the
+fresh secret got discarded along with the note the service had just minted.
+Node's `fetch` does not retry on its own, but a browser resends an idempotent
+request that failed on a stale pooled connection, and Go and the JDK do the
+same by their own routes — the hazard broke the
 [Kotlin](https://github.com/TheCryptoDonkey/lnurlcash-kotlin) and
 [Go](https://github.com/TheCryptoDonkey/lnurlcash-go) siblings during
-development, by two different mechanisms, and is now a named scenario in the
-conformance vectors.
+development, by two different mechanisms.
 
-Because a retry cannot always be prevented, a mutation refused with the
-input already spent or unknown carries its outputs anyway:
+LUD-25 closed it. A service MUST answer a byte-identical rotate, split or
+merge with the success it already returned, signature and all. So this library
+re-sends one whose answer was lost, and an unstoppable transport retry is now
+simply invisible:
+
+```ts
+// the connection dropped after the mint applied this. It completes anyway.
+const fresh = await rotateNote(callback, oldK1)
+```
+
+`mutationRetries` sets how many times (default 1; `0` restores the old
+give-up-at-once behaviour). Only rotate, split and merge are re-sent — never a
+melt, which carries `pr`, is paid asynchronously and has no replay guarantee —
+and only an ambiguous failure, never a refusal the service actually
+considered. The re-sent request is byte-identical, because the replay is
+matched on the k1 set, `h`, `h2` and `amount`.
+
+A service that has not implemented the rule answers the second attempt as
+already spent, exactly as before. So the old defence stays: a mutation refused
+with the input already spent or unknown carries its outputs anyway:
 
 ```ts
 try {
@@ -161,8 +178,9 @@ do not mint. Existing notes still redeem through ordinary LUD-03.
 
 ## Offline verification
 
-A service may sign each note with its Lightning node identity key, so a
-holder can confirm issuer and amount with nothing but the note:
+Mandatory, and enforced here. A service MUST publish `mintPubkey` and MUST
+sign every note a rotate, split or merge mints, so a holder can confirm
+issuer and amount with nothing but the note:
 
 ```
 message = "LNURLcash:" || amount_msat || ":" || hex(sha256(k1))
@@ -170,6 +188,14 @@ digest  = sha256(sha256("Lightning Signed Message:" || message))
 sig     = 65 bytes, r || s || recovery_id
 ```
 
+A `withdrawRequest` publishing no `mintPubkey`, or one that is not a 33-byte
+compressed secp256k1 key, is refused with a `ProtocolError`. A mutation the
+service confirms but does not sign raises `UnverifiableNoteError` — which
+**carries the fresh secrets**, because the mutation landed and the note it
+minted is real; read them with `newSecretsOf` and persist them before
+anything else. Pass `requireSignatures: false` to deal with a mint that
+predates the requirement.
+
 `verifyNoteSignature` recovers the pubkey and compares it to `mintPubkey`.
 It accepts the recovery id at either end, because lnurl-mint once emitted
 the reverse layout and other implementations may still; trying both is safe,
@@ -219,36 +245,87 @@ 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.
+A note's `k1` is generated by the wallet. 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, and the same words
+restore the same notes in a *different* wallet.
+
+LUD-25 specifies how, and this is the scheme to mint under:
 
 ```
-root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed)
-k1_i = HMAC-SHA256(key = root,                      msg = utf8(host + ":" + index))
+cashHashingKey   = m/139'/0
+(d1, d2, d3, d4) = HMAC-SHA256(key = cashHashingKey, msg = utf8(host))[0..16] as 4 uint32
+k1_i             = m/139'/d1/d2/d3/d4/i'
 ```
 
+`d1..d4` are used **exactly as they fall**. BIP-32 reads any index `>= 2^31`
+as hardened, so which of the four levels are hardened is decided by the
+mint's own host name, and half of them will be. Do not mask the top bit and
+do not harden all four: either one derives a different tree, and a wallet
+restoring against it finds nothing, silently. Only `i` is always hardened.
+
 `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)
+collide. `index` counts 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)`.
+
+```ts
+import {deriveCashRoot, cashSecretSource, restoreFromSeed} from 'lnurlcash-kit'
+
+const root = deriveCashRoot(seed)          // seed: Uint8Array, yours to keep safe
+const source = cashSecretSource(root, 'mint.example', counter)
+```
+
+### The hardware-signer path
+
+Every unhardened level sits at or above the per-mint node, so a signer given
+`m/139'/d1/d2/d3/d4` rather than the seed needs **no elliptic curve at all**:
+each `i'` beneath it is HMAC-SHA512 and one modular addition. That is the
+difference between a device that can do LUD-25 recovery and one that would
+need secp256k1 added to its firmware.
+
+```ts
+import {deriveCashDomainNode, cashNodeToHex, cashNodeFromHex, cashSecretAt} from 'lnurlcash-kit'
+
+const node = deriveCashDomainNode(root, 'mint.example')
+provision(cashNodeToHex(node))             // 64 bytes: privateKey || chainCode
+
+// on the device, or anywhere holding only that node
+cashSecretAt(cashNodeFromHex(hex), index)
+```
+
+Whoever derives that node can derive every note secret the wallet will ever
+hold **at that mint**. It is provisioning material: one mint's subtree, not
+the wallet.
+
+### The legacy scheme
+
+This kit shipped its own derivation in 0.2.0, four days before LUD-25 had a
+section on one:
+
+```
+root = HMAC-SHA256(key = utf8("lnurlcash-note-v1"), msg = seed)
+k1_i = HMAC-SHA256(key = root,                      msg = utf8(host + ":" + index))
+```
+
+`deriveNoteRoot`, `deriveNoteSecret` and `derivedSecretSource` still
+implement it and are not going anywhere, because notes minted under it are
+still money. Do not mint under it. `restoreFromSeed` walks it alongside the
+specified scheme so none of those notes goes missing.
+
+Both schemes ship with
+[conformance vectors](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 root = deriveNoteRoot(seed)          // legacy: existing notes only
 const source = derivedSecretSource(root, 'mint.example', counter)
 
 // hand it to any mutating call and the fresh secrets come from the seed
@@ -262,20 +339,37 @@ 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
+
 Restoring walks the indices and asks the mint what each derived secret is
-worth:
+worth. From a seed it walks both schemes at once:
 
 ```ts
-const {found, next} = await restoreNotes('https://mint.example/w', root, 'mint.example')
+const {found, next} = await restoreFromSeed('https://mint.example/w', seed, 'mint.example')
+// found[].scheme is 'bip32' or 'hmac'; next is {bip32, hmac}
 ```
 
-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
+A live note is recorded, an unknown index counts towards the gap, and the
+walk stops after 20 consecutive unknowns. 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 scan is the fallback, not the backup.** LUD-25 requires a hash lookup
+to answer for a burned note exactly as it answers for one that never existed,
+so a by-hash walk cannot see a spent index at all. A rotate burns the *old*
+index, which means a wallet's spent indices sit below its live ones: rotate
+more than `gap` times and a scan from 0 finds nothing whatever. The counter
+`next` gives you is the thing that makes recovery work, so **persist it and
+back it up**. It is not secret - an index reveals nothing without the root -
+so it belongs in an ordinary backup, and a restore should merge counters
+upwards only, never down.
+
+Only a walk that discloses raw secrets (`allowSecretDisclosure`) sees "spent"
+at all, because only a `k1` lookup gets that answer. It costs the whole
+window it walked: every index it touched is burned whether or not a note was
+ever minted there, since the secret is in someone's log now. `next` skips
+them for you.
+
 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.
 
@@ -297,14 +391,14 @@ had it, and the preimage is ordinary payment proof.
 ```ts
 import {
   fetchPayRequest, requestInvoice, claimMintedNote,
-  deriveNoteRoot, deriveNoteSecret, hashK1, namesMintOutput
+  deriveCashRoot, deriveCashSecret, hashK1, namesMintOutput
 } from 'lnurlcash-kit'
 
 const pay = await fetchPayRequest(payUrl)      // a Lightning Address resolves here
 if (!namesMintOutput(pay)) throw new Error('mint lacks commentAllowed: 64')
 
-const root = deriveNoteRoot(seed)
-const k1 = deriveNoteSecret(root, 'mint.example', nextIndex)
+const root = deriveCashRoot(seed)
+const k1 = deriveCashSecret(root, 'mint.example', nextIndex)
 await persist({k1, index: nextIndex})          // BEFORE the invoice. always.
 
 const {pr} = await requestInvoice(pay.callback, 21_000, {h: hashK1(k1)})

package/dist/index.d.ts

@@ -13,6 +13,8 @@ type LnurlcashOptions = {
     timeoutMs?: number;
     offline?: boolean;
     randomSecret?: RandomSecret;
+    requireSignatures?: boolean;
+    mutationRetries?: number;
 };
 
 type MintFee = {
@@ -41,7 +43,7 @@ type WithdrawRequestInfo = {
     minWithdrawable: number;
     maxWithdrawable: number;
     defaultDescription?: string;
-    mintPubkey?: string;
+    mintPubkey: string;
     payLink?: string;
 };
 declare const fetchNoteInfo: (url: string, options?: LnurlcashOptions) => Promise<WithdrawRequestInfo>;
@@ -189,9 +191,11 @@ type SettledForValue = {
 };
 declare const settleNoteForValue: (noteUrl: string, { mints, minMsat, requireSignature }: SettleForValueOptions, options?: LnurlcashOptions) => Promise<SettledForValue>;
 
+type NoteScheme = 'bip32' | 'hmac';
 type RestoredNote = {
     index: number;
     k1: string;
+    scheme: NoteScheme;
     amountMsat: number | null;
     state: 'live' | 'pending';
     callback?: string;
@@ -199,6 +203,7 @@ type RestoredNote = {
 type UnresolvedIndex = {
     index: number;
     k1: string;
+    scheme: NoteScheme;
     reason: string;
 };
 type RestoreResult = {
@@ -215,6 +220,15 @@ type RestoreOptions = {
     allowSecretDisclosure?: boolean;
 };
 declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start, probeK1, allowSecretDisclosure }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
+type SeedRestoreOptions = Omit<RestoreOptions, 'start'> & {
+    start?: {
+        [K in NoteScheme]?: number;
+    };
+};
+type SeedRestoreResult = Omit<RestoreResult, 'next'> & {
+    next: Record<NoteScheme, number>;
+};
+declare const restoreFromSeed: (baseUrl: string, seed: Uint8Array, host: string, { gap, start, probeK1, allowSecretDisclosure }?: SeedRestoreOptions, options?: LnurlcashOptions) => Promise<SeedRestoreResult>;
 
 declare const isBech32Lnurl: (data: string) => boolean;
 declare const toBech32Lnurl: (url: string) => string;
@@ -240,6 +254,22 @@ declare const buildNoteUrl: (withdrawLink: string, k1: string, amountMsat?: numb
 declare const withNewK1: (url: string, k1: string, amountMsat: number, signature?: string) => string;
 declare const withoutK1: (url: string, amountMsat: number, signature?: string) => string;
 
+type CashNode = {
+    privateKey: Uint8Array;
+    chainCode: Uint8Array;
+};
+declare const deriveCashChild: (node: CashNode, index: number) => CashNode;
+declare const deriveCashRoot: (seed: Uint8Array) => CashNode;
+declare const cashDomainIndices: (root: CashNode, host: string) => number[];
+declare const deriveCashDomainNode: (root: CashNode, host: string) => CashNode;
+declare const cashSecretAt: (domainNode: CashNode, index: number) => string;
+declare const deriveCashSecret: (root: CashNode, host: string, index: number) => string;
+declare const cashNodeToHex: (node: CashNode) => string;
+declare const cashNodeFromHex: (hex: string) => CashNode;
+declare const cashSecretSource: (root: CashNode, host: string, start?: number) => RandomSecret & {
+    index: () => number;
+};
+
 declare const PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
 type PaymentRequestMethodDetails = {
     mints: string[];
@@ -308,6 +338,10 @@ declare class HashLookupUnsupportedError extends LnurlcashError {
 }
 declare class AmbiguousMintError extends LnurlcashError {
 }
+declare class UnverifiableNoteError extends LnurlcashError {
+    newSecrets: string[];
+    constructor(message: string, newSecrets?: string[]);
+}
 declare class AmbiguousMutationError extends AmbiguousMintError {
     readonly newSecrets: string[];
     constructor(message: string, newSecrets: string[]);
@@ -338,8 +372,9 @@ declare const createClient: (options?: LnurlcashOptions) => {
     fetchInvoiceVerification: (verifyUrl: string) => Promise<VerifyResult>;
     claimMintedNote: (withdrawLink: string, k1: string) => Promise<MintClaim>;
     restoreNotes: (baseUrl: string, root: Uint8Array, host: string, restoreOptions?: RestoreOptions) => Promise<RestoreResult>;
+    restoreFromSeed: (baseUrl: string, seed: Uint8Array, host: string, restoreOptions?: SeedRestoreOptions) => Promise<SeedRestoreResult>;
     settleNoteForValue: (noteUrl: string, terms: SettleForValueOptions) => Promise<SettledForValue>;
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type DecodeOptions, HashLookupUnsupportedError, type HashedMutationResult, type HashedSplitResult, InsufficientValueError, type InvoiceRequestOptions, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintClaim, type MintContact, type MintFee, type MintFeeBand, type NoteInfoByHash, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, ServiceRejectedError, type SettleForValueOptions, type SettledForValue, type SettledNote, type SignatureCheck, type SplitResult, type UnresolvedIndex, type ValidatedBoundMintReceipt, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type CashNode, type DecodeOptions, HashLookupUnsupportedError, type HashedMutationResult, type HashedSplitResult, InsufficientValueError, type InvoiceRequestOptions, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintClaim, type MintContact, type MintFee, type MintFeeBand, type NoteInfoByHash, type NoteScheme, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, type SeedRestoreOptions, type SeedRestoreResult, ServiceRejectedError, type SettleForValueOptions, type SettledForValue, type SettledNote, type SignatureCheck, type SplitResult, type UnresolvedIndex, UnverifiableNoteError, type ValidatedBoundMintReceipt, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, cashDomainIndices, cashNodeFromHex, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { bech32, base64urlnopad } from '@scure/base';
 import { hmac } from '@noble/hashes/hmac.js';
-import { sha256 } from '@noble/hashes/sha2.js';
+import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import { secp256k1 } from '@noble/curves/secp256k1.js';
 
@@ -218,6 +218,89 @@ var withoutK1 = (url, amountMsat, signature) => {
   else newUrl.searchParams.delete("sig");
   return newUrl.toString();
 };
+var HARDENED = 2147483648;
+var CURVE_N = secp256k1.Point.Fn.ORDER;
+var MASTER_KEY_DOMAIN = utf8ToBytes("Bitcoin seed");
+var CASH_PURPOSE = 139;
+var numberOf = (bytes) => bytes.length === 0 ? 0n : BigInt(`0x${bytesToHex(bytes)}`);
+var to32Bytes = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
+var readUint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+var deriveCashChild = (node, index) => {
+  if (!Number.isSafeInteger(index) || index < 0 || index > 4294967295) {
+    throw new RangeError(`A BIP-32 child index must be a uint32, not ${index}.`);
+  }
+  const data = new Uint8Array(37);
+  if (index >= HARDENED) {
+    data.set(node.privateKey, 1);
+  } else {
+    data.set(
+      secp256k1.Point.BASE.multiply(numberOf(node.privateKey)).toBytes(true),
+      0
+    );
+  }
+  data[33] = index >>> 24 & 255;
+  data[34] = index >>> 16 & 255;
+  data[35] = index >>> 8 & 255;
+  data[36] = index & 255;
+  const material = hmac(sha512, node.chainCode, data);
+  const left = numberOf(material.subarray(0, 32));
+  const key = (left + numberOf(node.privateKey)) % CURVE_N;
+  if (left >= CURVE_N || key === 0n) {
+    throw new Error(
+      `BIP-32 derivation at index ${index} produced an invalid key. Use the next index.`
+    );
+  }
+  return { privateKey: to32Bytes(key), chainCode: material.slice(32) };
+};
+var masterFrom = (seed) => {
+  if (seed.length < 16 || seed.length > 64) {
+    throw new RangeError(
+      `A BIP-32 seed must be 16 to 64 bytes, not ${seed.length}.`
+    );
+  }
+  const material = hmac(sha512, MASTER_KEY_DOMAIN, seed);
+  const key = numberOf(material.subarray(0, 32));
+  if (key === 0n || key >= CURVE_N) {
+    throw new Error("This seed does not produce a valid BIP-32 master key.");
+  }
+  return { privateKey: material.slice(0, 32), chainCode: material.slice(32) };
+};
+var deriveCashRoot = (seed) => deriveCashChild(masterFrom(seed), CASH_PURPOSE + HARDENED);
+var cashDomainIndices = (root, host) => {
+  const hashingKey = deriveCashChild(root, 0).privateKey;
+  const material = hmac(sha256, hashingKey, utf8ToBytes(host));
+  return [0, 4, 8, 12].map((offset) => readUint32BE(material, offset));
+};
+var deriveCashDomainNode = (root, host) => cashDomainIndices(root, host).reduce(deriveCashChild, root);
+var requireIndex2 = (index) => {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= HARDENED) {
+    throw new RangeError(
+      `A note index must be an integer in [0, 2^31), not ${index}.`
+    );
+  }
+  return index;
+};
+var cashSecretAt = (domainNode, index) => bytesToHex(
+  deriveCashChild(domainNode, requireIndex2(index) + HARDENED).privateKey
+);
+var deriveCashSecret = (root, host, index) => cashSecretAt(deriveCashDomainNode(root, host), index);
+var cashNodeToHex = (node) => bytesToHex(node.privateKey) + bytesToHex(node.chainCode);
+var cashNodeFromHex = (hex) => {
+  const bytes = hexToBytes(hex.trim().toLowerCase());
+  if (bytes.length !== 64) {
+    throw new RangeError(
+      `A cash node is 64 bytes - a 32-byte key and a 32-byte chain code - not ${bytes.length}.`
+    );
+  }
+  return { privateKey: bytes.slice(0, 32), chainCode: bytes.slice(32) };
+};
+var cashSecretSource = (root, host, start = 0) => {
+  const domainNode = deriveCashDomainNode(root, host);
+  let next = requireIndex2(start);
+  const source = (() => cashSecretAt(domainNode, next++));
+  source.index = () => next;
+  return source;
+};
 
 // src/errors.ts
 var LnurlcashError = class extends Error {
@@ -264,6 +347,13 @@ var HashLookupUnsupportedError = class extends LnurlcashError {
 };
 var AmbiguousMintError = class extends LnurlcashError {
 };
+var UnverifiableNoteError = class extends LnurlcashError {
+  newSecrets;
+  constructor(message, newSecrets = []) {
+    super(message);
+    this.newSecrets = newSecrets;
+  }
+};
 var AmbiguousMutationError = class extends AmbiguousMintError {
   newSecrets;
   constructor(message, newSecrets) {
@@ -283,6 +373,7 @@ var InsufficientValueError = class extends ServiceRejectedError {
 };
 var newSecretsOf = (err) => {
   if (err instanceof AmbiguousMutationError) return err.newSecrets;
+  if (err instanceof UnverifiableNoteError) return err.newSecrets;
   if (err instanceof ServiceRejectedError) return err.newSecrets ?? [];
   return [];
 };
@@ -465,8 +556,18 @@ var resolveOptions = (options = {}) => ({
   fetch: options.fetch ?? ((...args) => globalThis.fetch(...args)),
   timeoutMs: options.timeoutMs ?? 3e4,
   offline: options.offline ?? false,
-  randomSecret: options.randomSecret ?? defaultRandomSecret
+  randomSecret: options.randomSecret ?? defaultRandomSecret,
+  requireSignatures: options.requireSignatures ?? true,
+  // A negative or non-finite count is read as none rather than thrown on:
+  // this is a resilience knob, and refusing the whole operation over it
+  // would be a worse answer than not retrying.
+  mutationRetries: normaliseRetries(options.mutationRetries)
 });
+var normaliseRetries = (value) => {
+  if (value === void 0) return 1;
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  return Math.floor(value);
+};
 var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 var MAX_REDIRECTS = 5;
 var MAX_BODY_BYTES = 1048576;
@@ -699,10 +800,17 @@ var verifyNoteSignature = (k1, amountMsat, signatureHex, mintPubkeys) => verifyN
 var verifyNoteSignatureHash = (h, amountMsat, signatureHex, mintPubkeys) => verifyNoteSignatureHashAgainst(h, amountMsat, signatureHex, mintPubkeys).valid;
 
 // src/client.ts
-var assertWithdrawRequestShape = (body, { requireK1 }) => {
+var COMPRESSED_PUBKEY = /^0[23][0-9a-f]{64}$/;
+var isCompressedPubkey = (value) => typeof value === "string" && COMPRESSED_PUBKEY.test(value.trim().toLowerCase());
+var assertWithdrawRequestShape = (body, { requireK1, requireMintPubkey }) => {
   if (body?.tag !== "withdrawRequest" || typeof body.callback !== "string" || requireK1 && typeof body.k1 !== "string" || typeof body.maxWithdrawable !== "number" || !Number.isSafeInteger(body.maxWithdrawable) || body.maxWithdrawable < 0 || body.minWithdrawable !== void 0 && (typeof body.minWithdrawable !== "number" || !Number.isSafeInteger(body.minWithdrawable) || body.minWithdrawable < 0 || body.minWithdrawable > body.maxWithdrawable)) {
     throw new ProtocolError("Not a withdrawRequest (unexpected response).");
   }
+  if (requireMintPubkey && !isCompressedPubkey(body.mintPubkey)) {
+    throw new ProtocolError(
+      body.mintPubkey === void 0 ? "This service publishes no mintPubkey, so its notes cannot be verified offline (LUD-25 requires one)." : "This service published a mintPubkey that is not a 33-byte compressed secp256k1 key."
+    );
+  }
 };
 var fetchNoteInfo = async (url, options = {}) => {
   const opts = resolveOptions(options);
@@ -715,7 +823,10 @@ var fetchNoteInfo = async (url, options = {}) => {
     if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
     throw err;
   }
-  assertWithdrawRequestShape(body, { requireK1: true });
+  assertWithdrawRequestShape(body, {
+    requireK1: true,
+    requireMintPubkey: opts.requireSignatures
+  });
   const queried = noteK1(url);
   if (queried && body.k1.toLowerCase() !== queried) {
     throw new ProtocolError(
@@ -738,7 +849,10 @@ var fetchNoteInfoByHash = async (withdrawLink, h, options = {}) => {
     if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
     throw err;
   }
-  assertWithdrawRequestShape(body, { requireK1: false });
+  assertWithdrawRequestShape(body, {
+    requireK1: false,
+    requireMintPubkey: opts.requireSignatures
+  });
   const info = body;
   const payLink = sameOriginPayLink(body.payLink, reqUrl);
   if (payLink === void 0) delete info.payLink;
@@ -857,6 +971,28 @@ var callbackRequest = async (callback, params, options) => {
   }
   return body;
 };
+var replayableCallbackRequest = async (callback, params, options) => {
+  const { mutationRetries } = resolveOptions(options);
+  let lastError;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await callbackRequest(callback, params, options);
+    } catch (err) {
+      if (!(err instanceof AmbiguousMintError) || attempt >= mutationRetries) {
+        throw err;
+      }
+      lastError = err;
+    }
+  }
+  throw lastError;
+};
+var requireSignature = (value, options, what) => {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (!resolveOptions(options).requireSignatures) return void 0;
+  throw new UnverifiableNoteError(
+    `The service confirmed the ${what} but returned no signature, so the note it just minted cannot be verified offline. The note exists - keep the secret.`
+  );
+};
 var meltNote = async (callback, k1, pr, options = {}) => {
   const body = await callbackRequest(
     callback,
@@ -872,7 +1008,7 @@ var meltNote = async (callback, k1, pr, options = {}) => {
   };
 };
 var rotateNoteWithHash = async (callback, k1, h, options = {}) => {
-  const body = await callbackRequest(
+  const body = await replayableCallbackRequest(
     callback,
     [
       ["k1", k1],
@@ -880,10 +1016,10 @@ var rotateNoteWithHash = async (callback, k1, h, options = {}) => {
     ],
     options
   );
-  return { signature: body.sig };
+  return { signature: requireSignature(body.sig, options, "rotate") };
 };
 var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) => {
-  const body = await callbackRequest(
+  const body = await replayableCallbackRequest(
     callback,
     [
       ...k1s.map((k1) => ["k1", k1]),
@@ -893,20 +1029,26 @@ var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) =
     ],
     options
   );
-  return { signature: body.sig, changeSignature: body.sig2 };
+  return {
+    signature: requireSignature(body.sig, options, "split"),
+    changeSignature: requireSignature(body.sig2, options, "split's change")
+  };
 };
 var mergeNotesWithHash = async (callback, k1s, h, options = {}) => {
-  const body = await callbackRequest(
+  const body = await replayableCallbackRequest(
     callback,
     [...k1s.map((k1) => ["k1", k1]), ["h", h]],
     options
   );
-  return { signature: body.sig };
+  return { signature: requireSignature(body.sig, options, "merge") };
 };
 var keepingOutputs = (err, newSecrets) => {
   if (err instanceof NoteSpentError || err instanceof NoteUnknownError) {
     err.newSecrets = newSecrets;
   }
+  if (err instanceof UnverifiableNoteError) {
+    err.newSecrets = newSecrets;
+  }
   return err;
 };
 var rotateNote = async (callback, k1, options = {}) => {
@@ -1012,6 +1154,10 @@ var foldNotes = async (callback, batches, opts, options) => {
         err.newSecrets = live;
         throw err;
       }
+      if (err instanceof UnverifiableNoteError) {
+        err.newSecrets = live;
+        throw err;
+      }
       throw new AmbiguousMutationError(
         err instanceof Error ? err.message : String(err),
         live
@@ -1196,7 +1342,7 @@ var claimMintedNote = async (withdrawLink, k1, options = {}) => {
 
 // src/settle.ts
 var normaliseHost = (value) => serverOf(value.trim().replace(/^@/, "")).toLowerCase();
-var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = false }, options = {}) => {
+var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature: requireSignature2 = false }, options = {}) => {
   const url = resolveNoteInput(noteUrl);
   if (!url) {
     throw new RequestRefusedError(
@@ -1212,7 +1358,7 @@ var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = fa
   }
   const k1 = requireNoteK1(url);
   const info = await fetchNoteInfo(url, options);
-  if (requireSignature) {
+  if (requireSignature2) {
     const signature = noteSignature(url);
     if (!signature) {
       throw new ServiceRejectedError("This note carries no signature.");
@@ -1242,12 +1388,67 @@ var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = fa
 };
 
 // src/restore.ts
-var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0, probeK1, allowSecretDisclosure = false } = {}, options = {}) => {
+var restoreNotes = async (baseUrl, root, host, {
+  gap = 20,
+  start = 0,
+  probeK1,
+  allowSecretDisclosure = false
+} = {}, options = {}) => {
+  const walked = await restoreSchemes(
+    baseUrl,
+    [
+      {
+        scheme: "hmac",
+        start,
+        secretAt: (index) => deriveNoteSecret(root, host, index)
+      }
+    ],
+    { gap, probeK1, allowSecretDisclosure },
+    options
+  );
+  return { ...walked, next: walked.next.hmac };
+};
+var restoreFromSeed = async (baseUrl, seed, host, {
+  gap = 20,
+  start = {},
+  probeK1,
+  allowSecretDisclosure = false
+} = {}, options = {}) => {
+  const domainNode = deriveCashDomainNode(deriveCashRoot(seed), host);
+  const legacyRoot = deriveNoteRoot(seed);
+  const walked = await restoreSchemes(
+    baseUrl,
+    [
+      {
+        scheme: "bip32",
+        start: start.bip32 ?? 0,
+        secretAt: (index) => cashSecretAt(domainNode, index)
+      },
+      {
+        scheme: "hmac",
+        start: start.hmac ?? 0,
+        secretAt: (index) => deriveNoteSecret(legacyRoot, host, index)
+      }
+    ],
+    { gap, probeK1, allowSecretDisclosure },
+    options
+  );
+  return { ...walked, next: { bip32: walked.next.bip32, hmac: walked.next.hmac } };
+};
+var restoreSchemes = async (baseUrl, schemes, {
+  gap,
+  probeK1,
+  allowSecretDisclosure
+}, options) => {
   if (!Number.isSafeInteger(gap) || gap < 1) {
     throw new RangeError(`The gap limit must be a positive integer, not ${gap}.`);
   }
-  if (!Number.isSafeInteger(start) || start < 0) {
-    throw new RangeError(`The start index must be a non-negative integer, not ${start}.`);
+  for (const { scheme, start } of schemes) {
+    if (!Number.isSafeInteger(start) || start < 0) {
+      throw new RangeError(
+        `The start index for the ${scheme} scheme must be a non-negative integer, not ${start}.`
+      );
+    }
   }
   let hashLookupsConfirmed = false;
   if (probeK1) {
@@ -1258,66 +1459,75 @@ var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0, probeK1, a
       if (!(err instanceof ServiceRejectedError)) throw err;
     }
   }
-  const byHash = await walk(
-    start,
-    gap,
-    async (k1) => {
-      const info = await fetchNoteInfoByHash(baseUrl, hashK1(k1), options);
+  const byHash = [];
+  for (const scheme of schemes) {
+    const outcome = await walk(
+      scheme,
+      gap,
+      async (k1) => {
+        const info = await fetchNoteInfoByHash(baseUrl, hashK1(k1), options);
+        hashLookupsConfirmed = true;
+        return info;
+      }
+    );
+    if (outcome.found.length > 0 || outcome.unresolved.length > 0) {
       hashLookupsConfirmed = true;
-      return info;
-    },
-    root,
-    host
-  );
-  if (byHash.found.length > 0 || byHash.unresolved.length > 0) hashLookupsConfirmed = true;
-  if (hashLookupsConfirmed) {
-    return {
-      found: byHash.found,
-      unresolved: byHash.unresolved,
-      next: byHash.lastUsed === null ? start : byHash.lastUsed + 1,
-      hashLookupsConfirmed: true,
-      disclosesSecrets: false
-    };
+    }
+    byHash.push(outcome);
   }
+  if (hashLookupsConfirmed) return collate(schemes, byHash, false);
   if (!allowSecretDisclosure) {
     throw new HashLookupUnsupportedError(
       "This service never answered a lookup by hash, so a restore cannot tell an empty wallet from a service that only accepts raw secrets. Pass a probeK1 for a note known to exist here, or allowSecretDisclosure to walk by secret instead."
     );
   }
-  const bySecret = await walk(
-    start,
-    gap,
-    (k1) => fetchNoteInfo(buildNoteUrl(baseUrl, k1), options),
-    root,
-    host
-  );
-  const walkedThrough = bySecret.highestWalked === null ? start - 1 : bySecret.highestWalked;
-  const used = bySecret.lastUsed === null ? start - 1 : bySecret.lastUsed;
+  const bySecret = [];
+  for (const scheme of schemes) {
+    bySecret.push(
+      await walk(
+        scheme,
+        gap,
+        (k1) => fetchNoteInfo(buildNoteUrl(baseUrl, k1), options)
+      )
+    );
+  }
+  return collate(schemes, bySecret, true);
+};
+var collate = (schemes, outcomes, disclosesSecrets) => {
+  const next = {};
+  schemes.forEach(({ scheme, start }, at) => {
+    const outcome = outcomes[at];
+    if (!disclosesSecrets) {
+      next[scheme] = outcome.lastUsed === null ? start : outcome.lastUsed + 1;
+      return;
+    }
+    const used = outcome.lastUsed ?? start - 1;
+    const walkedThrough = outcome.highestWalked ?? start - 1;
+    next[scheme] = Math.max(used, walkedThrough) + 1;
+  });
   return {
-    found: bySecret.found,
-    unresolved: bySecret.unresolved,
-    // Every index this walk touched is burned, whether or not a note was
-    // ever minted under it: its secret is in a log somewhere now, so
-    // minting into it later would be minting a note a stranger can spend.
-    next: Math.max(used, walkedThrough) + 1,
-    hashLookupsConfirmed: false,
-    disclosesSecrets: true
+    found: outcomes.flatMap((outcome) => outcome.found),
+    unresolved: outcomes.flatMap((outcome) => outcome.unresolved),
+    next,
+    hashLookupsConfirmed: !disclosesSecrets,
+    disclosesSecrets
   };
 };
-var walk = async (start, gap, lookup, root, host) => {
+var walk = async ({ scheme, start, secretAt }, gap, lookup) => {
   const found = [];
   const unresolved = [];
   let lastUsed = null;
   let highestWalked = null;
   let unknownRun = 0;
   for (let index = start; unknownRun < gap; index++) {
-    const k1 = deriveNoteSecret(root, host, index);
+    const k1 = secretAt(index);
     highestWalked = index;
     try {
       const info = await lookup(k1);
       found.push({
         index,
         k1,
+        scheme,
         amountMsat: info.maxWithdrawable,
         state: "live",
         callback: info.callback
@@ -1326,7 +1536,7 @@ var walk = async (start, gap, lookup, root, host) => {
       unknownRun = 0;
     } catch (err) {
       if (err instanceof PendingNoteError) {
-        found.push({ index, k1, amountMsat: null, state: "pending" });
+        found.push({ index, k1, scheme, amountMsat: null, state: "pending" });
         lastUsed = index;
         unknownRun = 0;
       } else if (err instanceof NoteSpentError) {
@@ -1335,7 +1545,7 @@ var walk = async (start, gap, lookup, root, host) => {
       } else if (err instanceof NoteUnknownError) {
         unknownRun++;
       } else if (err instanceof ServiceRejectedError) {
-        unresolved.push({ index, k1, reason: err.reason });
+        unresolved.push({ index, k1, scheme, reason: err.reason });
         lastUsed = index;
         unknownRun = 0;
       } else {
@@ -1368,7 +1578,8 @@ var createClient = (options = {}) => ({
   fetchInvoiceVerification: (verifyUrl) => fetchInvoiceVerification(verifyUrl, options),
   claimMintedNote: (withdrawLink, k1) => claimMintedNote(withdrawLink, k1, options),
   restoreNotes: (baseUrl, root, host, restoreOptions = {}) => restoreNotes(baseUrl, root, host, restoreOptions, options),
+  restoreFromSeed: (baseUrl, seed, host, restoreOptions = {}) => restoreFromSeed(baseUrl, seed, host, restoreOptions, options),
   settleNoteForValue: (noteUrl, terms) => settleNoteForValue(noteUrl, terms, options)
 });
 
-export { AmbiguousMintError, AmbiguousMutationError, HashLookupUnsupportedError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, HashLookupUnsupportedError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, UnverifiableNoteError, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, cashDomainIndices, cashNodeFromHex, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/llms.txt

@@ -18,10 +18,10 @@ Reference wallet: https://github.com/dni/lnurl-wallet
 ## Core API
 
 resolveNoteInput(text) -> url | null    accepts bech32 LNURL, lnurlw://, https
-fetchNoteInfo(url, opts?) -> {callback, k1, maxWithdrawable, mintPubkey?}
-rotateNote(callback, k1, opts?) -> {k1, signature?}
-splitNote(callback, k1s, amountMsat, opts?) -> {k1, change, signature?, changeSignature?}
-mergeNotes(callback, k1s, opts?) -> {k1, signature?}
+fetchNoteInfo(url, opts?) -> {callback, k1, maxWithdrawable, mintPubkey}
+rotateNote(callback, k1, opts?) -> {k1, signature}
+splitNote(callback, k1s, amountMsat, opts?) -> {k1, change, signature, changeSignature}
+mergeNotes(callback, k1s, opts?) -> {k1, signature}
 meltNote(callback, k1, bolt11, opts?) -> {pr?, verify?}
 settleNote(baseUrl, k1, expectedMsat, sig?, opts?) -> {k1, amountMsat, signature?, callback}
 settleNoteForValue(noteUrl, {mints, minMsat, requireSignature?}, opts?)
@@ -35,10 +35,31 @@ fetchMintAddress(url, opts?) -> {mintPubkey?, payLink, name?, motd?, contact?,
   mintPubkey verifies note signatures. It is NOT the node key in nodeUri.
   nodePubkey is a deprecated alias for mintPubkey, dropped next breaking change.
   mintToHash is the fallback copy of the payRequest's flag - see 13.
-deriveNoteRoot(seedBytes) -> Uint8Array    HMAC-SHA256("lnurlcash-note-v1", seed)
-deriveNoteSecret(root, host, index) -> k1  HMAC-SHA256(root, host + ":" + index)
+deriveCashRoot(seedBytes) -> CashNode      LUD-25's scheme: BIP-32 m/139'
+deriveCashDomainNode(root, host) -> CashNode   m/139'/d1/d2/d3/d4, d1..d4 =
+  first 16 bytes of HMAC-SHA256(privkey at m/139'/0, host) as 4 raw uint32.
+  RAW: BIP-32 reads >= 2^31 as hardened, so ~half the levels are, by the
+  host name alone. Never mask the top bit, never harden all four - either
+  derives a different tree and restores nothing, silently.
+deriveCashSecret(root, host, index) -> k1  the hardened child i' of that node
+cashSecretAt(domainNode, index) -> k1      no EC needed below the domain node,
+  which is why a hardware signer is provisioned with the node, not the seed
+cashSecretSource(root, host, start) -> RandomSecret & {index()}
+cashNodeToHex/cashNodeFromHex             privateKey || chainCode, 64 bytes
+deriveCashChild(node, rawUint32) -> CashNode   BIP-32 CKDpriv, for checking
+  this library against BIP-32's own vectors
+deriveNoteRoot(seedBytes) -> Uint8Array    LEGACY, pre-spec. Do not mint under
+deriveNoteSecret(root, host, index) -> k1  it; still scanned so old notes live.
 derivedSecretSource(root, host, start) -> RandomSecret & {index()}
+restoreFromSeed(baseUrl, seed, host, {gap?, start?, probeK1?,
+  allowSecretDisclosure?}, opts?) -> {found[] (.scheme), next: {bip32, hmac}}
+  walks BOTH schemes. A by-hash walk CANNOT see a spent index (LUD-25 makes
+  spent and never-issued the same answer), and a rotate burns the old index,
+  so a wallet that rotated more than `gap` times scans as empty. The
+  persisted per-host counter is the real backup; the scan is the fallback.
+  The counter is not secret - back it up, and merge it upwards only.
 restoreNotes(baseUrl, root, host, {gap?, start?}, opts?) -> {found[], next}
+  legacy scheme only
 fetchPayRequest(url, opts?) -> {callback, minSendable, maxSendable, metadata,
   withdrawLink?, mintFee?, mintToHash?}     mintToHash: mint accepts an `h`
 fetchInvoiceVerification(url, opts?)
@@ -53,7 +74,11 @@ paymentRequestAmountMsat(req) -> msat  request amount is in SAT, this is the
 parseMintFee(metadata) / applyMintFee(gross, fee) / grossUpForMintFee(net, fee)
 createClient(opts) -> all of the above with opts bound
 
-Options (always last): {fetch?, timeoutMs?, offline?, randomSecret?}
+Options (always last): {fetch?, timeoutMs?, offline?, randomSecret?,
+                        requireSignatures?, mutationRetries?}
+  requireSignatures defaults true: refuse a mint that publishes no
+  mintPubkey or returns an unsigned mutation. mutationRetries defaults 1:
+  re-send a rotate/split/merge whose answer was lost, never a melt.
 
 ## Rules an implementation MUST follow
 
@@ -64,12 +89,23 @@ Options (always last): {fetch?, timeoutMs?, offline?, randomSecret?}
 3. On ANY error from a mutation call newSecretsOf(err) FIRST, persist what
    it returns, then call probeBurnedNote to learn what happened. Treating a
    failure as a failure destroys money the service may already have minted.
-   AmbiguousMutationError always carries secrets; so does a NoteSpentError
-   or NoteUnknownError from a mutation, because that is also what a retried
-   GET looks like once its first attempt burned the input.
+   AmbiguousMutationError always carries secrets; so does UnverifiableNoteError,
+   and so does a NoteSpentError or NoteUnknownError from a mutation, because
+   that is also what a retried GET looks like at a service that has not
+   implemented the replay rule.
 4. RequestRefusedError means nothing was sent - safe to treat as no-op.
 5. A melt's OK means IN FLIGHT, not spent. PendingNoteError means retry, not
    spent.
+5b. Offline verification is MANDATORY. A conforming service publishes
+   mintPubkey on every withdrawRequest and returns sig (and sig2 on a split)
+   from every rotate/split/merge. This library refuses a service that does
+   not; UnverifiableNoteError means the mutation LANDED unsigned, so keep its
+   secrets. Opt out per call with requireSignatures: false.
+5c. A retried rotate/split/merge MUST be answered by the service as a replay
+   of the original success, so re-sending one whose answer was lost is safe
+   and usually completes it. Re-send the IDENTICAL request: the replay is
+   matched on the k1 set, h, h2 and amount, so a fresh secret makes it a
+   different mutation and a second real burn. Never re-send a melt.
 6. Rotate immediately after claiming a minted note: the mint generated that
    preimage, and LUD-21 verify exposes it to anyone who saw the invoice.
    Does not apply to a note minted with `h` - see 13.
@@ -112,14 +148,18 @@ Options (always last): {fetch?, timeoutMs?, offline?, randomSecret?}
 RequestRefusedError    nothing sent, note untouched
 ServiceRejectedError   processed and refused (definitive)
   PendingNoteError     a melt is in flight on this k1 - retry
-  NoteSpentError       authoritative: already burned - but from a MUTATION it
-                       may be a retry whose first attempt landed; read
+  NoteSpentError       authoritative: already burned - but from a MUTATION at
+                       a service that will not replay a retry, it may be a
+                       retry whose first attempt landed; read
                        newSecretsOf(err) before believing it
   NoteUnknownError     service does not recognise it
 AmbiguousMintError     outcome UNKNOWN - assume nothing
   AmbiguousMutationError  carries .newSecrets - persist them
+UnverifiableNoteError  the mutation LANDED and came back unsigned. The note is
+                       real; carries .newSecrets - persist them
 newSecretsOf(err) -> string[]  the secrets any error is carrying, or none
-ProtocolError          a non-mutating response did not match the spec
+ProtocolError          a non-mutating response did not match the spec, which
+                       includes a withdrawRequest publishing no mintPubkey
 
 ## Conformance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "LNURLcash (LUD-25) bearer note client for TypeScript - mint, rotate, split, merge, melt, and verify offline",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "lnurlcash-conformance": "^0.5.0",
+    "lnurlcash-conformance": "^0.7.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"