lnurlcash-kit 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,105 @@
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 
+## 0.5.0 - 2026-08-29
+
+**A large merge is folded in batches rather than sent as one over-long
+URL.** LUD-25 bounds a merge by ordinary URL length, not by anything in the
+protocol: every repeated `k1=` costs about 68 characters, and browsers,
+servers and proxies commonly cap a whole URL near 2000. Past roughly 28
+notes `mergeNotes` built a request that something upstream truncates,
+turning a large merge into a malformed one rather than a clean refusal. It
+now measures the URL this SERVICE's own callback actually produces and
+folds the inputs batch into batch, each merge's output carried into the
+next, as the draft advises.
+
+A fold can fail with value already moved, which a single merge never could:
+once a batch has landed, the carried note is one the SERVICE has already
+minted, worth every batch folded so far, and the fold holds its only copy.
+It is returned with the failure whatever the class of failure - a network
+drop, a policy refusal, a k1 count the mint caps at, an input mid-melt
+elsewhere - so a caller that persists what `newSecretsOf` hands it cannot
+lose the fold's own output. The error's class is preserved, so a caller
+telling pending apart from spent still can.
+
+Batches are bounded by note count as well as URL length. No LUD-25 field
+advertises a SERVICE's own limit on how many `k1` one request may name, and
+the limits in the wild are tighter than 2000 characters allows - moneyer
+defaults to 21, lnurl-mint to 100 - so batching on length alone built
+requests a conforming mint refuses outright. The default is 20, under the
+tightest cap known.
+
+`mergeBatches(callback, k1s, options?)` is exported for callers that want to
+plan the batches themselves - `{budget, maxNotes}`, or a bare number for the
+budget as before. A caller that has learned a SERVICE's real limit should
+pass it.
+
+## 0.4.0 - 2026-08-26
+
+**Breaking: `restoreNotes` asks by hash, and no longer discloses note
+secrets by default.**
+
+The walk queries every index up to `gap` past the last one in use, and those
+are exactly the indices the wallet is about to mint into next. Asking by
+secret therefore published the next `gap` secrets the wallet would ever use,
+in cleartext query strings, and the returned `next` then pointed straight at
+one of them. A five-note wallet put twenty-five live-or-future secrets on the
+wire and resumed at an index it had just disclosed.
+
+- The walk now uses the informational GET's `h` parameter (LUD-25, "Checking
+  a note without exposing it"), so nothing spendable leaves the wallet.
+  `fetchNoteInfoByHash` and `buildNoteInfoUrlByHash` expose it directly, and
+  `RestoredNote.callback` carries the callback so a caller need not ask again
+  with the raw secret.
+- `RestoreOptions.allowSecretDisclosure` (default `false`) permits the old
+  form as an explicit fallback, never automatically. When it is used,
+  `RestoreResult.disclosesSecrets` is `true` and `next` skips every index the
+  walk touched, because a disclosed secret is spent whether or not a note was
+  ever minted under it.
+- `h` support is OPTIONAL in LUD-25 with no capability flag, so a SERVICE
+  that cannot answer by hash is indistinguishable from one holding none of
+  the notes asked about. A walk that never gets a positive answer now throws
+  `HashLookupUnsupportedError` rather than reporting an empty wallet.
+  `RestoreOptions.probeK1` supplies a positive control, and
+  `RestoreResult.hashLookupsConfirmed` reports what was established.
+
+**`requestInvoice` names the mint output with a LUD-12 `comment`.**
+
+LUD-25 specifies the mint-time output hash as `comment = hex(h)`, and that is
+what a conforming SERVICE reads. The kit sent only `h`, a parameter one
+implementation adopted before the comment form was written, so a wallet
+naming an output against a conforming mint was silently ignored and its note
+was keyed by the payment preimage instead.
+
+- `comment` is now sent alongside `h`. A SERVICE reading either gets the same
+  hash; one reading neither behaves exactly as before.
+- This matters beyond conformance: an unnamed mint's `k1` **is** the payment
+  preimage `P`, so a SERVICE offering LUD-21 `verify` on that payment hands
+  the note to whoever holds the verify URL. Naming the output is what makes
+  `verify` safe to offer at all.
+
+- `PayRequestInfo.commentAllowed` is surfaced and `namesMintOutput()` decides
+  the capability from either spelling: LUD-25 advertises it as
+  `commentAllowed >= 64`, one mint shipped `mintToHash` first. One rule in
+  one place, because both directions of a wrong answer cost a note - read it
+  as no and the note is the payment preimage, published on the mint's verify
+  URL; read it as yes and the wallet waits for a note minted elsewhere.
+
+**Also breaking: an unrecognised refusal no longer aborts a restore, and no
+longer counts toward the gap.**
+
+`classifyNoteError` falls through to a bare `ServiceRejectedError` for any
+reason string it has no pattern for, and the walk rethrew it, so a single
+unfamiliar reason from a SERVICE ended the whole restore. Any new note state
+- expiry being the obvious one - would have done it.
+
+- Only `NoteUnknownError` advances the gap counter now. Every other refusal
+  means the SERVICE knows the index, so it resets the counter and is reported
+  in the new `RestoreResult.unresolved`. Advancing it was how a walk could
+  terminate early and silently abandon live notes beyond the run.
+- Transport and protocol failures still throw: a SERVICE being down is not a
+  statement about an index.
+
 ## 0.3.0 - 2026-08-24
 
 - Additive bound-mint receipt parsing and validation for sealed signers:

package/dist/index.d.ts

@@ -31,6 +31,9 @@ declare const grossUpForMintFee: (netMsat: number, fee: MintFee) => number;
 declare const formatFeePercent: (ppm: number) => string;
 declare const describeMintFee: (fee: MintFee) => string;
 
+type NoteInfoByHash = Omit<WithdrawRequestInfo, 'k1'> & {
+    k1?: string;
+};
 type WithdrawRequestInfo = {
     tag: 'withdrawRequest';
     callback: string;
@@ -42,6 +45,7 @@ type WithdrawRequestInfo = {
     payLink?: string;
 };
 declare const fetchNoteInfo: (url: string, options?: LnurlcashOptions) => Promise<WithdrawRequestInfo>;
+declare const fetchNoteInfoByHash: (withdrawLink: string, h: string, options?: LnurlcashOptions) => Promise<NoteInfoByHash>;
 declare const probeBurnedNote: (url: string, options?: LnurlcashOptions) => Promise<"live" | "gone" | "unknown">;
 type MintContact = {
     nostr?: string;
@@ -108,6 +112,11 @@ type SplitResult = {
     changeSignature?: string;
 };
 declare const splitNote: (callback: string, k1s: string[], amountMsat: number, options?: LnurlcashOptions) => Promise<SplitResult>;
+type MergeBatchOptions = {
+    budget?: number;
+    maxNotes?: number;
+};
+declare const mergeBatches: (callback: string, k1s: string[], options?: MergeBatchOptions | number) => string[][];
 declare const mergeNotes: (callback: string, k1s: string[], options?: LnurlcashOptions) => Promise<RotateResult>;
 type SettledNote = {
     k1: string;
@@ -126,8 +135,13 @@ type PayRequestInfo = {
     mintPubkey?: string;
     mintFee?: MintFee;
     mintToHash?: boolean;
+    commentAllowed?: number;
 };
 declare const fetchPayRequest: (url: string, options?: LnurlcashOptions) => Promise<PayRequestInfo>;
+declare const namesMintOutput: (info: {
+    mintToHash?: boolean;
+    commentAllowed?: number;
+}) => boolean;
 type InvoiceResult = {
     pr: string;
     verify?: string;
@@ -180,16 +194,27 @@ type RestoredNote = {
     k1: string;
     amountMsat: number | null;
     state: 'live' | 'pending';
+    callback?: string;
+};
+type UnresolvedIndex = {
+    index: number;
+    k1: string;
+    reason: string;
 };
 type RestoreResult = {
     found: RestoredNote[];
+    unresolved: UnresolvedIndex[];
     next: number;
+    hashLookupsConfirmed: boolean;
+    disclosesSecrets: boolean;
 };
 type RestoreOptions = {
     gap?: number;
     start?: number;
+    probeK1?: string;
+    allowSecretDisclosure?: boolean;
 };
-declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
+declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start, probeK1, allowSecretDisclosure }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
 
 declare const isBech32Lnurl: (data: string) => boolean;
 declare const toBech32Lnurl: (url: string) => string;
@@ -210,6 +235,7 @@ declare const noteDeclaredAmount: (url: string) => number | null;
 declare const noteSignature: (url: string) => string | null;
 declare const resolveNoteInput: (value: string) => string | null;
 declare const isValidNoteInput: (value: string) => boolean;
+declare const buildNoteInfoUrlByHash: (withdrawLink: string, h: string) => string;
 declare const buildNoteUrl: (withdrawLink: string, k1: string, amountMsat?: number) => string;
 declare const withNewK1: (url: string, k1: string, amountMsat: number, signature?: string) => string;
 declare const withoutK1: (url: string, amountMsat: number, signature?: string) => string;
@@ -278,6 +304,8 @@ declare class NoteSpentError extends ServiceRejectedError {
 declare class NoteUnknownError extends ServiceRejectedError {
     constructor(reason: string);
 }
+declare class HashLookupUnsupportedError extends LnurlcashError {
+}
 declare class AmbiguousMintError extends LnurlcashError {
 }
 declare class AmbiguousMutationError extends AmbiguousMintError {
@@ -294,6 +322,7 @@ declare const classifyNoteError: (reason: string) => ServiceRejectedError;
 
 declare const createClient: (options?: LnurlcashOptions) => {
     fetchNoteInfo: (url: string) => Promise<WithdrawRequestInfo>;
+    fetchNoteInfoByHash: (withdrawLink: string, h: string) => Promise<NoteInfoByHash>;
     probeBurnedNote: (url: string) => Promise<"live" | "gone" | "unknown">;
     fetchMintAddress: (url: string) => Promise<MintAddressInfo>;
     meltNote: (callback: string, k1: string, pr: string) => Promise<MeltResult>;
@@ -313,4 +342,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type DecodeOptions, 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, 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 ValidatedBoundMintReceipt, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, 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 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 };

package/dist/index.js

@@ -182,6 +182,18 @@ var resolveNoteInput = (value) => {
   return url;
 };
 var isValidNoteInput = (value) => resolveNoteInput(value) !== null;
+var buildNoteInfoUrlByHash = (withdrawLink, h) => {
+  const hex = h.trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(hex)) {
+    throw new Error("A note hash must be 32 bytes of hex.");
+  }
+  const url = new URL(fromLud17(withdrawLink.trim()));
+  url.searchParams.delete("k1");
+  url.searchParams.delete("amount");
+  url.searchParams.delete("sig");
+  url.searchParams.set("h", hex);
+  return url.toString();
+};
 var buildNoteUrl = (withdrawLink, k1, amountMsat) => {
   const url = new URL(fromLud17(withdrawLink.trim()));
   url.searchParams.set("k1", k1.trim().toLowerCase());
@@ -248,6 +260,8 @@ var NoteUnknownError = class extends ServiceRejectedError {
     this.message = `The service doesn't recognise this note (service says: "${reason}").`;
   }
 };
+var HashLookupUnsupportedError = class extends LnurlcashError {
+};
 var AmbiguousMintError = class extends LnurlcashError {
 };
 var AmbiguousMutationError = class extends AmbiguousMintError {
@@ -685,6 +699,11 @@ 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 }) => {
+  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).");
+  }
+};
 var fetchNoteInfo = async (url, options = {}) => {
   const opts = resolveOptions(options);
   const reqUrl = new URL(url);
@@ -696,9 +715,7 @@ var fetchNoteInfo = async (url, options = {}) => {
     if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
     throw err;
   }
-  if (body?.tag !== "withdrawRequest" || typeof body.callback !== "string" || 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).");
-  }
+  assertWithdrawRequestShape(body, { requireK1: true });
   const queried = noteK1(url);
   if (queried && body.k1.toLowerCase() !== queried) {
     throw new ProtocolError(
@@ -711,6 +728,23 @@ var fetchNoteInfo = async (url, options = {}) => {
   else info.payLink = payLink;
   return info;
 };
+var fetchNoteInfoByHash = async (withdrawLink, h, options = {}) => {
+  const opts = resolveOptions(options);
+  const reqUrl = new URL(buildNoteInfoUrlByHash(withdrawLink, h));
+  let body;
+  try {
+    body = await lnurlFetch(reqUrl, opts);
+  } catch (err) {
+    if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
+    throw err;
+  }
+  assertWithdrawRequestShape(body, { requireK1: false });
+  const info = body;
+  const payLink = sameOriginPayLink(body.payLink, reqUrl);
+  if (payLink === void 0) delete info.payLink;
+  else info.payLink = payLink;
+  return info;
+};
 var sameOriginPayLink = (value, noteUrl) => {
   if (typeof value !== "string" || value.length === 0) return void 0;
   let candidate;
@@ -914,8 +948,39 @@ var splitNote = async (callback, k1s, amountMsat, options = {}) => {
     throw keepingOutputs(err, [newK1, changeK1]);
   }
 };
+var MAX_URL_CHARS = 2e3;
+var MAX_NOTES_PER_BATCH = 20;
+var mergeBatches = (callback, k1s, options = {}) => {
+  const { budget = MAX_URL_CHARS, maxNotes = MAX_NOTES_PER_BATCH } = typeof options === "number" ? { budget: options } : options;
+  const placeholder = "0".repeat(64);
+  try {
+    new URL(callback);
+  } catch {
+    throw new RequestRefusedError("The service provided an invalid callback URL.");
+  }
+  const fits = (candidate, carried) => {
+    const url = new URL(callback);
+    if (carried) url.searchParams.append("k1", placeholder);
+    for (const k1 of candidate) url.searchParams.append("k1", k1);
+    url.searchParams.append("h", placeholder);
+    return url.href.length <= budget;
+  };
+  const batches = [];
+  let batch = [];
+  for (const k1 of k1s) {
+    const next = [...batch, k1];
+    if (batch.length > 0 && (next.length > maxNotes || !fits(next, batches.length > 0))) {
+      batches.push(batch);
+      batch = [k1];
+    } else batch = next;
+  }
+  if (batch.length > 0) batches.push(batch);
+  return batches;
+};
 var mergeNotes = async (callback, k1s, options = {}) => {
   const opts = resolveOptions(options);
+  const batches = mergeBatches(callback, k1s);
+  if (batches.length > 1) return foldNotes(callback, batches, opts, options);
   const newK1 = opts.randomSecret();
   try {
     const result = await mergeNotesWithHash(callback, k1s, hashK1(newK1), options);
@@ -927,6 +992,34 @@ var mergeNotes = async (callback, k1s, options = {}) => {
     throw keepingOutputs(err, [newK1]);
   }
 };
+var foldNotes = async (callback, batches, opts, options) => {
+  let carried = null;
+  let signature;
+  for (const batch of batches) {
+    const inputs = carried === null ? batch : [carried, ...batch];
+    const newK1 = opts.randomSecret();
+    try {
+      const result = await mergeNotesWithHash(callback, inputs, hashK1(newK1), options);
+      carried = newK1;
+      signature = result.signature;
+    } catch (err) {
+      const live = carried === null ? [newK1] : [carried, newK1];
+      if (err instanceof AmbiguousMintError) {
+        throw new AmbiguousMutationError(err.message, live);
+      }
+      if (carried === null) throw keepingOutputs(err, live);
+      if (err instanceof ServiceRejectedError) {
+        err.newSecrets = live;
+        throw err;
+      }
+      throw new AmbiguousMutationError(
+        err instanceof Error ? err.message : String(err),
+        live
+      );
+    }
+  }
+  return { k1: carried, signature };
+};
 var settleNote = async (baseUrl, k1, expectedAmountMsat, signature, options = {}) => {
   const info = await fetchNoteInfo(
     withNewK1(baseUrl, k1, expectedAmountMsat, signature),
@@ -958,9 +1051,11 @@ var fetchPayRequest = async (url, options = {}) => {
   return {
     ...body,
     mintFee: mintFee ?? void 0,
-    mintToHash: asBoolean(body.mintToHash)
+    mintToHash: asBoolean(body.mintToHash),
+    commentAllowed: asNumber(body.commentAllowed)
   };
 };
+var namesMintOutput = (info) => info.mintToHash === true || typeof info.commentAllowed === "number" && info.commentAllowed >= 64;
 var asBoundMintCommitment = (value) => {
   if (!value || typeof value !== "object") return void 0;
   const raw = value;
@@ -982,7 +1077,9 @@ var requestInvoice = async (payCallback, amountMsat, options = {}) => {
         "An output hash must be 32 bytes of hex - no invoice was requested."
       );
     }
-    cbUrl.searchParams.set("h", options.h.trim().toLowerCase());
+    const h = options.h.trim().toLowerCase();
+    cbUrl.searchParams.set("comment", h);
+    cbUrl.searchParams.set("h", h);
   }
   const body = await lnurlFetch(cbUrl, resolveOptions(options));
   if (typeof body?.pr !== "string") {
@@ -1136,18 +1233,86 @@ var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = fa
 };
 
 // src/restore.ts
-var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0 } = {}, options = {}) => {
+var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0, probeK1, allowSecretDisclosure = false } = {}, 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}.`);
+  }
+  let hashLookupsConfirmed = false;
+  if (probeK1) {
+    try {
+      await fetchNoteInfoByHash(baseUrl, hashK1(probeK1), options);
+      hashLookupsConfirmed = true;
+    } catch (err) {
+      if (!(err instanceof ServiceRejectedError)) throw err;
+    }
+  }
+  const byHash = await walk(
+    start,
+    gap,
+    async (k1) => {
+      const info = await fetchNoteInfoByHash(baseUrl, hashK1(k1), options);
+      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
+    };
+  }
+  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;
+  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
+  };
+};
+var walk = async (start, gap, lookup, root, host) => {
   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);
+    highestWalked = index;
     try {
-      const info = await fetchNoteInfo(buildNoteUrl(baseUrl, k1), options);
-      found.push({ index, k1, amountMsat: info.maxWithdrawable, state: "live" });
+      const info = await lookup(k1);
+      found.push({
+        index,
+        k1,
+        amountMsat: info.maxWithdrawable,
+        state: "live",
+        callback: info.callback
+      });
       lastUsed = index;
       unknownRun = 0;
     } catch (err) {
@@ -1160,17 +1325,22 @@ var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0 } = {}, opt
         unknownRun = 0;
       } else if (err instanceof NoteUnknownError) {
         unknownRun++;
+      } else if (err instanceof ServiceRejectedError) {
+        unresolved.push({ index, k1, reason: err.reason });
+        lastUsed = index;
+        unknownRun = 0;
       } else {
         throw err;
       }
     }
   }
-  return { found, next: lastUsed === null ? start : lastUsed + 1 };
+  return { found, unresolved, lastUsed, highestWalked };
 };
 
 // src/index.ts
 var createClient = (options = {}) => ({
   fetchNoteInfo: (url) => fetchNoteInfo(url, options),
+  fetchNoteInfoByHash: (withdrawLink, h) => fetchNoteInfoByHash(withdrawLink, h, options),
   probeBurnedNote: (url) => probeBurnedNote(url, options),
   fetchMintAddress: (url) => fetchMintAddress(url, options),
   meltNote: (callback, k1, pr) => meltNote(callback, k1, pr, options),
@@ -1192,4 +1362,4 @@ var createClient = (options = {}) => ({
   settleNoteForValue: (noteUrl, terms) => settleNoteForValue(noteUrl, terms, options)
 });
 
-export { AmbiguousMintError, AmbiguousMutationError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "LNURLcash (LUD-25) bearer note client for TypeScript - mint, rotate, split, merge, melt, and verify offline",
   "author": "TheCryptoDonkey",
   "license": "MIT",