lnurlcash-kit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 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

package/dist/index.d.ts

@@ -112,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;
@@ -337,4 +342,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, 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, 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

@@ -948,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);
@@ -961,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),
@@ -1303,4 +1362,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, 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, 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.4.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",