lnurlcash-kit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
 

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.js

@@ -1048,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.5.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"