lnurlcash-kit 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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

@@ -425,6 +425,16 @@ Three things worth knowing:
 `test/vectors/part2.json` was generated from lnurl-wallet and checked against
 lnurl-mint. It moves into lnurlcash-conformance next.
 
+**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 `test/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
 
 By default the secret of a freshly minted note is the invoice's payment

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) => {
@@ -1738,4 +1747,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.0",
   "description": "LNURLcash (LUD-25) bearer note client for TypeScript - mint, rotate, split, merge, melt, and verify offline",
   "author": "TheCryptoDonkey",
   "license": "MIT",