lnurlcash-kit 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## Unreleased
 
+## 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.
+
+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)
+```
 
-Because a retry cannot always be prevented, a mutation refused with the
-input already spent or unknown carries its outputs anyway:
+`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,

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>;
@@ -308,6 +310,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[]);
@@ -342,4 +348,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 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 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 };

package/dist/index.js

@@ -264,6 +264,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 +290,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 +473,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 +717,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 +740,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 +766,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 +888,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 +925,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 +933,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 +946,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 +1071,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 +1259,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 +1275,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.");
@@ -1371,4 +1434,4 @@ var createClient = (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, 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/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?)
@@ -53,7 +53,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 +68,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 +127,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.7.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.6.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"