lnurlcash-kit 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 ## 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.**

package/README.md

@@ -245,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
@@ -288,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.
 
@@ -323,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

@@ -191,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;
@@ -201,6 +203,7 @@ type RestoredNote = {
 type UnresolvedIndex = {
     index: number;
     k1: string;
+    scheme: NoteScheme;
     reason: string;
 };
 type RestoreResult = {
@@ -217,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;
@@ -242,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[];
@@ -344,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, UnverifiableNoteError, 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 {
@@ -1305,12 +1388,67 @@ var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature: req
 };
 
 // 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) {
@@ -1321,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
@@ -1389,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) {
@@ -1398,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 {
@@ -1431,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, UnverifiableNoteError, 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

@@ -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?)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.7.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.6.0",
+    "lnurlcash-conformance": "^0.7.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"