lnurlcash-kit 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,8 +1,54 @@
 # Changelog
 
+## Unreleased
+
+## 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.
 
+## 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/README.md

@@ -154,18 +154,10 @@ 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
 
@@ -297,18 +289,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 +315,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

@@ -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),
@@ -989,14 +1048,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;
@@ -1303,4 +1371,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.6.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.5.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"