lnurlcash-kit 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.12.1 - 2026-09-11
+
+- `fetchNoteInfo` compares the mint's echoed `k1` with the one it asked
+  about as the note each names (`noteIdOf`), not as strings. One Part 2 note
+  has many valid `ck1`s: anyone can turn one into its high-S twin, and its
+  holder can re-sign, so a mint echoing another spelling of the same note
+  was reported as having handed back a different note. An echo that names no
+  note at all is still refused, and a Part 1 secret compares as it always did.
+
+## 0.12.0 - 2026-09-11
+
+**A Part 2 branch rooted in a Nostr key.**
+
+- `deriveNostrCashSeed(secretKey)` and `deriveNostrAddressNode(secretKey,
+  host)`: a Part 2 address branch rooted in a Nostr identity key, for a holder
+  with no BIP-39 words. The seed is `HMAC-SHA256(key, "LNURLcash/nostr-seed")`
+  and the path from it is the reference wallet's. heartwood-esp32 derives the
+  same branch on the device, and `test/vectors/nostr-seed.json` is the file
+  both grade against.
+- `deriveCashMaster(seed)`: the BIP-32 master node, exported beside
+  `deriveCashChild` for walking a path the kit does not name, such as
+  nsec-tree's `m/44'/1237'/727'/0'/0'`.
+
 ## 0.11.0 - 2026-09-11
 
 **The wire calls take LUD-25 Part 2 notes.**

package/README.md

@@ -422,8 +422,19 @@ Three things worth knowing:
 - **`i` is any uint32**, serialised as 4 bytes big-endian, never hardened.
   lnurl-wallet and lnurl-mint agree on that; the spec does not say.
 
-`test/vectors/part2.json` was generated from lnurl-wallet and checked against
-lnurl-mint. It moves into lnurlcash-conformance next.
+The tests grade against lnurlcash-conformance's `vectors/part2.json`, built
+from the primitives there and identical to vectors generated from lnurl-wallet
+and checked against lnurl-mint.
+
+**A branch rooted in a Nostr key.** A holder with no BIP-39 words, such as a
+hardware signer that keeps only its identity key, or a wallet that never made
+any, can still be paid to keys of its own. `deriveNostrAddressNode(secretKey,
+host)` takes the branch from the key that owns the lightning address:
+`HMAC-SHA256(key = secret key, msg = "LNURLcash/nostr-seed")`, then the path
+above unchanged. heartwood-esp32 derives exactly this on the device, graded
+against the same values as conformance's `vectors/nostr-seed.json`, so its notes come back from
+its nsec (or the phrase the nsec came from) without the device. This is ours,
+not LUD-25's; a mint sees an ordinary `cx1` either way.
 
 ## Minting a note you named yourself
 

package/dist/index.d.ts

@@ -262,6 +262,7 @@ type CashNode = {
     chainCode: Uint8Array;
 };
 declare const deriveCashChild: (node: CashNode, index: number) => CashNode;
+declare const deriveCashMaster: (seed: Uint8Array) => CashNode;
 declare const deriveCashRoot: (seed: Uint8Array) => CashNode;
 declare const cashDomainIndices: (root: CashNode, host: string) => number[];
 declare const deriveCashDomainNode: (root: CashNode, host: string) => CashNode;
@@ -297,6 +298,9 @@ declare const noteIdOf: (k1: string) => string | null;
 declare const noteLookupOf: (k1: string) => string | null;
 declare const deriveCashAddressNode: (root: CashNode, host: string) => CashNode;
 declare const cashNodeToCx1: (node: CashNode) => Cx1;
+declare const NOSTR_CASH_SEED_LABEL = "LNURLcash/nostr-seed";
+declare const deriveNostrCashSeed: (secretKey: Uint8Array) => Uint8Array;
+declare const deriveNostrAddressNode: (secretKey: Uint8Array, host: string) => CashNode;
 
 declare const PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
 type PaymentRequestMethodDetails = {
@@ -405,4 +409,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type CashNode, type Cx1, 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, type NoteScheme, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, type SeedRestoreOptions, type SeedRestoreResult, 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, cashDomainIndices, cashNodeFromHex, cashNodeToCx1, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodeCk1, decodeCp1, decodeCs1, decodeCx1, decodePaymentRequest, defaultRandomSecret, deriveCashAddressNode, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, deriveNotePubkey, deriveNoteRoot, deriveNoteSecret, deriveNoteSecretKey, derivedSecretSource, describeMintFee, encodeCk1, encodeCp1, encodeCs1, encodeCx1, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isCk1, isCp1, isCs1, isCx1, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteIdOf, noteK1, noteLookupOf, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, recoverNoteOwnershipPubkey, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, signNoteOwnership, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type CashNode, type Cx1, 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, NOSTR_CASH_SEED_LABEL, type NoteInfoByHash, type NoteScheme, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, type SeedRestoreOptions, type SeedRestoreResult, 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, cashDomainIndices, cashNodeFromHex, cashNodeToCx1, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodeCk1, decodeCp1, decodeCs1, decodeCx1, decodePaymentRequest, defaultRandomSecret, deriveCashAddressNode, deriveCashChild, deriveCashDomainNode, deriveCashMaster, deriveCashRoot, deriveCashSecret, deriveNostrAddressNode, deriveNostrCashSeed, deriveNotePubkey, deriveNoteRoot, deriveNoteSecret, deriveNoteSecretKey, derivedSecretSource, describeMintFee, encodeCk1, encodeCp1, encodeCs1, encodeCx1, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isCk1, isCp1, isCs1, isCx1, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteIdOf, noteK1, noteLookupOf, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, recoverNoteOwnershipPubkey, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, signNoteOwnership, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { bech32, base64urlnopad, bech32m } from '@scure/base';
 import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { hmac } from '@noble/hashes/hmac.js';
 import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
-import { hmac } from '@noble/hashes/hmac.js';
 
 // src/urls.ts
 var isBech32Lnurl = (data) => data.trim().toUpperCase().startsWith("LNURL1");
@@ -154,6 +154,7 @@ var deriveCashChild = (node, index) => {
   }
   return { privateKey: to32Bytes(key), chainCode: material.slice(32) };
 };
+var deriveCashMaster = (seed) => masterFrom(seed);
 var masterFrom = (seed) => {
   if (seed.length < 16 || seed.length > 64) {
     throw new RangeError(
@@ -346,6 +347,14 @@ var cashNodeToCx1 = (node) => ({
   pubkeyXOnly: secp256k1.getPublicKey(node.privateKey, true).slice(1),
   chainCode: node.chainCode.slice()
 });
+var NOSTR_CASH_SEED_LABEL = "LNURLcash/nostr-seed";
+var deriveNostrCashSeed = (secretKey) => {
+  if (!(secretKey instanceof Uint8Array) || secretKey.length !== 32) {
+    throw new RangeError("A Nostr secret key is 32 bytes.");
+  }
+  return hmac(sha256, secretKey, utf8ToBytes(NOSTR_CASH_SEED_LABEL));
+};
+var deriveNostrAddressNode = (secretKey, host) => deriveCashAddressNode(deriveCashRoot(deriveNostrCashSeed(secretKey)), host);
 
 // src/note.ts
 var noteK1 = (url) => {
@@ -958,7 +967,8 @@ var fetchNoteInfo = async (url, options = {}) => {
     requireMintPubkey: opts.requireSignatures
   });
   const queried = noteK1(url);
-  if (queried && body.k1.toLowerCase() !== queried) {
+  const echoed = noteIdOf(body.k1);
+  if (queried && (echoed === null || echoed !== noteIdOf(queried))) {
     throw new ProtocolError(
       "The service echoed back a different k1 than was queried - the note may have been redeemed elsewhere, or the service isn't spec-compliant."
     );
@@ -1738,4 +1748,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, UnverifiableNoteError, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, cashDomainIndices, cashNodeFromHex, cashNodeToCx1, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodeCk1, decodeCp1, decodeCs1, decodeCx1, decodePaymentRequest, defaultRandomSecret, deriveCashAddressNode, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, deriveNotePubkey, deriveNoteRoot, deriveNoteSecret, deriveNoteSecretKey, derivedSecretSource, describeMintFee, encodeCk1, encodeCp1, encodeCs1, encodeCx1, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isCk1, isCp1, isCs1, isCx1, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteIdOf, noteK1, noteLookupOf, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, recoverNoteOwnershipPubkey, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, signNoteOwnership, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, HashLookupUnsupportedError, InsufficientValueError, LnurlcashError, NOSTR_CASH_SEED_LABEL, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, UnverifiableNoteError, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, cashDomainIndices, cashNodeFromHex, cashNodeToCx1, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodeCk1, decodeCp1, decodeCs1, decodeCx1, decodePaymentRequest, defaultRandomSecret, deriveCashAddressNode, deriveCashChild, deriveCashDomainNode, deriveCashMaster, deriveCashRoot, deriveCashSecret, deriveNostrAddressNode, deriveNostrCashSeed, deriveNotePubkey, deriveNoteRoot, deriveNoteSecret, deriveNoteSecretKey, derivedSecretSource, describeMintFee, encodeCk1, encodeCp1, encodeCs1, encodeCx1, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isCk1, isCp1, isCs1, isCx1, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeBatches, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, newSecretsOf, noteDeclaredAmount, noteIdOf, noteK1, noteLookupOf, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, recoverNoteOwnershipPubkey, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreFromSeed, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, signNoteOwnership, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/llms.txt

@@ -64,6 +64,10 @@ deriveNoteSecretKey(p, chainCode, i) -> sk negates p first when P has odd y
 signNoteOwnership(sk) -> 65 bytes          RFC6979 over fixed "LNURLcash"
 recoverNoteOwnershipPubkey(sig) -> pk | null
 verifyNoteSignature also takes a ck1 as k1 and a cs1 as the signature
+deriveCashMaster(seed) -> CashNode   the BIP-32 master, for walking a path the kit does not name
+deriveNostrCashSeed(secretKey) -> 32-byte seed   HMAC-SHA256(key, "LNURLcash/nostr-seed")
+deriveNostrAddressNode(secretKey, host) -> CashNode   the address path from that seed;
+  a branch for a holder with no BIP-39 words (heartwood-esp32 derives the same)
 noteIdOf(k1) -> id | null   sha256(k1) for a secret, the recovered key for a
   ck1. One note has many valid ck1 strings: compare notes by this, not by k1
 noteLookupOf(k1) -> string  hash, or cp1 for a ck1; for fetchNoteInfoByHash

package/package.json

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