lnurlcash-kit 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 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
+  `mintToHash` advertisement alone no longer authorizes minting.
+- `fetchPayRequest()` rejects a minting payRequest that cannot carry the
+  mandatory 64-character commitment, so a caller cannot proceed into an
+  invoice flow that has no conforming output name.
+- Mint requests carrying an output hash continue to send identical
+  `comment` and `h` fields. Documentation now treats the former as mandatory
+  LUD-25 and the latter as the Moneyer/ForgeSworn receipt extension.
+
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 

package/README.md

@@ -58,14 +58,15 @@ console.log(info.maxWithdrawable, 'msat')
 // that GET put the secret on the wire, so rotate it
 const fresh = await rotateNote(info.callback, info.k1)
 
-// and check the mint really issued it, without asking anyone
-if (info.mintPubkey && fresh.signature) {
-  verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature, info.mintPubkey)
-}
+// and check the mint really issued it, without asking anyone. Both fields
+// are guaranteed here: LUD-25 requires the mint to publish mintPubkey and
+// to sign what it mints, and this library refuses a mint that does neither.
+verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature!, info.mintPubkey)
 ```
 
 Every request function takes options last — `fetch`, `timeoutMs`, `offline`,
-`randomSecret`. `createClient(options)` binds one set once:
+`randomSecret`, `requireSignatures`, `mutationRetries`.
+`createClient(options)` binds one set once:
 
 ```ts
 const client = createClient({timeoutMs: 10_000})
@@ -107,23 +108,39 @@ try {
 
 `RequestRefusedError` is the opposite and safe: nothing left the process.
 
-**3. Your HTTP stack must not retry.** Every mutation is a GET, HTTP treats GET
-as idempotent, and an LNURLcash mutation is not — the first attempt burns the
-input. A retried mutation is answered "already spent", which reads as a
-*definitive* rejection, so the fresh secret gets discarded along with the note
-the service just minted. Node's `fetch` does not retry on its own, but a
-browser will resend an idempotent request that failed on a stale pooled
-connection, and any retry wrapper, service worker or proxy in front of this
-will do the same. If you pass your own `fetch`, do not make it retry these.
-
-This is not hypothetical: the same hazard broke the
+**3. A retried mutation is now a replay, not a double spend.** Every mutation
+is a GET, HTTP treats GET as idempotent, and an LNURLcash mutation is not —
+the first attempt burns the input. For most of this draft's life that was the
+sharpest edge in the protocol: a stack that resent a dropped GET got "already
+spent" for the second attempt, which reads as a *definitive* rejection, so the
+fresh secret got discarded along with the note the service had just minted.
+Node's `fetch` does not retry on its own, but a browser resends an idempotent
+request that failed on a stale pooled connection, and Go and the JDK do the
+same by their own routes — the hazard broke the
 [Kotlin](https://github.com/TheCryptoDonkey/lnurlcash-kotlin) and
 [Go](https://github.com/TheCryptoDonkey/lnurlcash-go) siblings during
-development, by two different mechanisms, and is now a named scenario in the
-conformance vectors.
+development, by two different mechanisms.
 
-Because a retry cannot always be prevented, a mutation refused with the
-input already spent or unknown carries its outputs anyway:
+LUD-25 closed it. A service MUST answer a byte-identical rotate, split or
+merge with the success it already returned, signature and all. So this library
+re-sends one whose answer was lost, and an unstoppable transport retry is now
+simply invisible:
+
+```ts
+// the connection dropped after the mint applied this. It completes anyway.
+const fresh = await rotateNote(callback, oldK1)
+```
+
+`mutationRetries` sets how many times (default 1; `0` restores the old
+give-up-at-once behaviour). Only rotate, split and merge are re-sent — never a
+melt, which carries `pr`, is paid asynchronously and has no replay guarantee —
+and only an ambiguous failure, never a refusal the service actually
+considered. The re-sent request is byte-identical, because the replay is
+matched on the k1 set, `h`, `h2` and `amount`.
+
+A service that has not implemented the rule answers the second attempt as
+already spent, exactly as before. So the old defence stays: a mutation refused
+with the input already spent or unknown carries its outputs anyway:
 
 ```ts
 try {
@@ -154,23 +171,16 @@ callback — it is only observable as the note becoming spendable again. Other
 operations on that `k1` raise `PendingNoteError` meanwhile; retry, never
 read it as spent.
 
-**5. Rotate the instant you claim a minted note.** The preimage that mints a
-note is generated by the service, and if it serves
-[LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) `verify`, *anyone*
-who saw the unpaid invoice can poll for it — the payment hash travels inside
-the invoice. First rotater wins. A wallet that rotates on settlement wins by
-construction; a human copying a preimage by hand does not.
-
-That is a race, and the way to win a race is not to enter it. Where a mint
-advertises `mintToHash`, name the note you are buying and the preimage is
-not its secret at all: see
-[Minting a note you named yourself](#minting-a-note-you-named-yourself).
-The rule above stands for every mint that does not offer it.
+**5. Persist the mint secret before requesting the invoice.** Current
+LUD-25 requires `comment=hex(sha256(secret))`; there is no preimage-backed
+creation fallback. If the payRequest cannot carry that 64-character comment,
+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))
@@ -178,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,
@@ -297,18 +315,19 @@ can poll LUD-21 `verify` with the payment hash inside it and take the
 preimage the moment it settles, which is what a QR code on a desktop screen
 hands out.
 
-A mint can instead bind the note to a hash you supply, the same `h` you
-already send on every rotate, split and merge. Then you chose the secret,
-nobody else ever had it, and the preimage is an ordinary payment proof.
+A current-draft mint binds the note to the hash supplied in the mandatory
+LUD-12 comment. The kit repeats the same value as `h` for the additive
+Moneyer/ForgeSworn receipt extension. You chose the secret, nobody else ever
+had it, and the preimage is ordinary payment proof.
 
 ```ts
 import {
   fetchPayRequest, requestInvoice, claimMintedNote,
-  deriveNoteRoot, deriveNoteSecret, hashK1
+  deriveNoteRoot, deriveNoteSecret, hashK1, namesMintOutput
 } from 'lnurlcash-kit'
 
 const pay = await fetchPayRequest(payUrl)      // a Lightning Address resolves here
-if (!pay.mintToHash) { /* preimage path, rotate on claim */ }
+if (!namesMintOutput(pay)) throw new Error('mint lacks commentAllowed: 64')
 
 const root = deriveNoteRoot(seed)
 const k1 = deriveNoteSecret(root, 'mint.example', nextIndex)
@@ -322,26 +341,20 @@ const claim = await claimMintedNote(pay.withdrawLink!, k1)
 // 'minted'   -> claim.amountMsat is what it is worth, claim.callback melts it
 ```
 
-Ask before you buy. `mintToHash` is how a mint says it accepts the parameter,
-and reading it first is the difference between naming your own note and paying
-for one whose secret three other parties can learn. It turns up in three
-places, saying three different things:
+Ask before you buy. `commentAllowed >= 64` is the normative minting
+capability. `mintToHash` describes only the additive `h` and receipt fields:
 
 | Where | What it means |
 | --- | --- |
-| `PayRequestInfo.mintToHash` | "I accept an `h`." **Decide from this one.** |
+| `PayRequestInfo.commentAllowed` | room for the mandatory hash comment; required for minting |
+| `PayRequestInfo.mintToHash` | "I also accept the matching `h` extension." |
 | `MintAddressInfo.mintToHash` | the same fact on the experimental discovery document |
 | `InvoiceResult.mintToHash` | "I bound *this quote* to the hash you named" |
 
-Prefer the payRequest: it is the only endpoint every mint has, it is where
-your wallet already is when it is about to mint, and it sits next to the
-`withdrawLink` the draft already hangs there for LNURLcash's sake. Fall back
-to `fetchMintAddress` for a mint that only advertises on that document. A mint
-that says it in neither place ignores the `h`, keys the note by the preimage
-as it always has, and the verify path is unchanged. Anything that is not
-exactly `true` is a no, everywhere, and `false` on the invoice result is
-silence rather than a refusal, so decide from the advertisement and claim by
-probing.
+Decide whether minting is possible from `commentAllowed` on the payRequest;
+never substitute the mint-address extension field. Anything other than
+boolean `true` is no for `mintToHash`, but that affects only extension receipt
+handling. The note remains comment-bound either way.
 
 **Persist the secret before you ask for the invoice.** Paying for a note and
 then losing the secret is the one way this is worse than the preimage scheme,

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
@@ -1048,14 +1111,23 @@ var fetchPayRequest = async (url, options = {}) => {
     throw new ProtocolError("Not a payRequest (unexpected response).");
   }
   const mintFee = typeof body.metadata === "string" ? parseMintFee(body.metadata) : null;
+  const commentAllowed = asNumber(body.commentAllowed);
+  if (body.withdrawLink !== void 0 && typeof body.withdrawLink !== "string") {
+    throw new ProtocolError("A minting payRequest has an invalid withdrawLink.");
+  }
+  if (typeof body.withdrawLink === "string" && !(typeof commentAllowed === "number" && commentAllowed >= 64)) {
+    throw new ProtocolError(
+      "A minting payRequest must allow a 64-character output commitment."
+    );
+  }
   return {
     ...body,
     mintFee: mintFee ?? void 0,
     mintToHash: asBoolean(body.mintToHash),
-    commentAllowed: asNumber(body.commentAllowed)
+    commentAllowed
   };
 };
-var namesMintOutput = (info) => info.mintToHash === true || typeof info.commentAllowed === "number" && info.commentAllowed >= 64;
+var namesMintOutput = (info) => typeof info.commentAllowed === "number" && info.commentAllowed >= 64;
 var asBoundMintCommitment = (value) => {
   if (!value || typeof value !== "object") return void 0;
   const raw = value;
@@ -1187,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(
@@ -1203,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.");
@@ -1362,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.5.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.3.0",
+    "lnurlcash-conformance": "^0.6.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"