lnurlcash-kit 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 
+## 0.1.2 - 2026-08-21
+
+- `mintFeeBand` and `withinMintFeeBand`. LUD-25 states the mint fee as
+  `base_fee_msat` plus a ppm cut and says nothing about rounding, and the
+  two live implementations read that differently: dni's lnurl-mint - the
+  reference, and what every public mint on the awesome list except moneyer
+  runs - ceilings the fee to a whole sat on purpose so the mint is "never
+  short a sat", while moneyer withholds the msat-exact amount.
+- So `applyMintFee` is right about exactly one of them, and a wallet
+  comparing a credited note against it warns spuriously against the other.
+  Measured on real sats: 40,000 msat at a 1000 + 1000 ppm mint credited
+  38,000, not the 38,960 the formula gives.
+- `mintFeeBand` returns the range - the formula is the most a holder can be
+  credited, the sat-ceilinged fee the least - and `withinMintFeeBand` is
+  what a caller should compare against. `applyMintFee` is unchanged and
+  still means the formula; it is now documented as the generous edge rather
+  than the answer.
+- Nothing here decides which reading is correct. That is a question for
+  lnurl/luds#301.
+
 ## 0.1.1 - 2026-08-20
 
 - `fetchMintAddress` now populates `nodeCapacityMsat`. The wire field is

package/README.md

@@ -178,6 +178,10 @@ The reference implementations, both dni's, both MIT:
 - [lnurl-mint](https://github.com/dni/lnurl-mint) — the reference service
 - [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
 
+Everything else built on LNURLcash — the other wallets and mints, the
+hardware vault, the sibling language ports — is indexed in
+[awesome-lnurlcash](https://github.com/TheCryptoDonkey/awesome-lnurlcash).
+
 Changes made on extraction are listed in [CHANGELOG.md](CHANGELOG.md); two
 are behavioural fixes worth reading if you are porting from that code.
 

package/dist/index.d.ts

@@ -36,6 +36,12 @@ type MintFee = {
 };
 declare const parseMintFee: (metadata: string) => MintFee | null;
 declare const applyMintFee: (grossMsat: number, fee: MintFee) => number;
+type MintFeeBand = {
+    minNetMsat: number;
+    maxNetMsat: number;
+};
+declare const mintFeeBand: (grossMsat: number, fee: MintFee) => MintFeeBand;
+declare const withinMintFeeBand: (grossMsat: number, netMsat: number, fee: MintFee) => boolean;
 declare const grossUpForMintFee: (netMsat: number, fee: MintFee) => number;
 declare const formatFeePercent: (ppm: number) => string;
 declare const describeMintFee: (fee: MintFee) => string;
@@ -190,4 +196,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type HashedMutationResult, type HashedSplitResult, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintFee, NoteSpentError, NoteUnknownError, type PayRequestInfo, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RotateResult, ServiceRejectedError, type SettledNote, type SplitResult, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, type HashedMutationResult, type HashedSplitResult, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintFee, type MintFeeBand, NoteSpentError, NoteUnknownError, type PayRequestInfo, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RotateResult, ServiceRejectedError, type SettledNote, type SplitResult, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withinMintFeeBand, withoutK1 };

package/dist/index.js

@@ -253,6 +253,18 @@ var parseMintFee = (metadata) => {
 };
 var proportionalFee = (grossMsat, feePpm) => Math.floor(grossMsat / 1e6) * feePpm + Math.floor(grossMsat % 1e6 * feePpm / 1e6);
 var applyMintFee = (grossMsat, fee) => Math.max(0, grossMsat - fee.baseFeeMsat - proportionalFee(grossMsat, fee.feePpm));
+var mintFeeBand = (grossMsat, fee) => {
+  const exactFee = fee.baseFeeMsat + proportionalFee(grossMsat, fee.feePpm);
+  const satCeilinged = Math.ceil(exactFee / 1e3) * 1e3;
+  return {
+    minNetMsat: Math.max(0, grossMsat - satCeilinged),
+    maxNetMsat: Math.max(0, grossMsat - exactFee)
+  };
+};
+var withinMintFeeBand = (grossMsat, netMsat, fee) => {
+  const { minNetMsat, maxNetMsat } = mintFeeBand(grossMsat, fee);
+  return netMsat >= minNetMsat && netMsat <= maxNetMsat;
+};
 var grossUpForMintFee = (netMsat, fee) => {
   if (netMsat <= 0) return 0;
   let hi = netMsat + fee.baseFeeMsat;
@@ -711,4 +723,4 @@ var createClient = (options = {}) => ({
   fetchInvoiceVerification: (verifyUrl) => fetchInvoiceVerification(verifyUrl, options)
 });
 
-export { AmbiguousMintError, AmbiguousMutationError, LnurlcashError, NoteSpentError, NoteUnknownError, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, LnurlcashError, NoteSpentError, NoteUnknownError, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withinMintFeeBand, withoutK1 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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.1.0",
+    "lnurlcash-conformance": "^0.1.1",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"