lnurlcash-kit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.10.0 - 2026-09-11
+
+**LUD-25 Part 2 building blocks.** Notes keyed by a public key and spent by a
+recoverable signature. The wire calls come next; this is the part every one of
+them rests on.
+
+- The four encodings: `cp1` (a note's public key), `ck1` (its bearer secret),
+  `cs1` (the mint's certificate) and `cx1` (a watch-only branch), with
+  `encode*`, `decode*` and `is*` for each. Decoders return null rather than
+  throw, and refuse mixed case as BIP-350 does.
+- `deriveNotePubkey` and `deriveNoteSecretKey`, the per-note key tweak.
+- `signNoteOwnership` and `recoverNoteOwnershipPubkey`.
+- `deriveCashAddressNode` and `cashNodeToCx1`. The branch sits at
+  `m/139'/1'/d1..d4`, which is what lnurl-wallet derives, not the
+  `m/139'/d1..d4` the spec text gives.
+- `verifyNoteSignature` now takes a `ck1` note and a `cs1` certificate, so a
+  Part 2 note verifies offline the same way a Part 1 note does.
+
+Names and signatures match lnurl-wallet's `src/lib`. Every value is graded
+against `test/vectors/part2.json`, generated from lnurl-wallet and checked
+against lnurl-mint.
+
 ## 0.9.0 - 2026-09-09
 
 **`fetchMintAddress` reads three more fields.** The reference mint publishes

package/README.md

@@ -373,6 +373,54 @@ them for you.
 The seed is bearer material for every note the wallet will ever hold. Store
 it the way you store the notes, and never log it.
 
+## Notes keyed by a public key (LUD-25 Part 2)
+
+A Part 2 note swaps the hash for a key pair. The wallet keeps `sk`. The mint
+only ever sees `pk`, written `cp1…`. To spend the note you hand over `ck1…`,
+a recoverable signature by `sk` over the fixed message `LNURLcash`, and the
+mint recovers `pk` from it to find the note. The mint's certificate, `cs1…`,
+is the same signature mints already make, over `hex(pk)` instead of a hash.
+So a recipient can check a note offline with nothing but `ck1` and `cs1`.
+
+This release has the building blocks: the four encodings, key derivation and
+ownership signatures. The wire calls that mint to `cp1` and spend with `ck1`
+come next. The names match lnurl-wallet's `src/lib`, so moving to it later is
+an import change.
+
+```ts
+import {
+  deriveCashRoot, deriveCashAddressNode, cashNodeToCx1, encodeCx1,
+  deriveNotePubkey, deriveNoteSecretKey, signNoteOwnership, encodeCk1,
+  verifyNoteSignature
+} from 'lnurlcash-kit'
+
+const node = deriveCashAddressNode(deriveCashRoot(seed), 'mint.example')
+const {pubkeyXOnly, chainCode} = cashNodeToCx1(node)
+const cx1 = encodeCx1(pubkeyXOnly, chainCode)             // watch-only
+
+const pk = deriveNotePubkey(pubkeyXOnly, chainCode, i)     // what a watcher derives
+const sk = deriveNoteSecretKey(node.privateKey, node.chainCode, i)
+const ck1 = encodeCk1(signNoteOwnership(sk))              // the bearer secret
+
+verifyNoteSignature(ck1, amountMsat, cs1, mintPubkey)     // offline
+```
+
+Three things worth knowing:
+
+- **The branch path follows the reference wallet, not the spec text.** It is
+  `m/139'/1'/d1/d2/d3/d4`, with the hashing key at `m/139'/1'/0`. The spec
+  says `m/139'/d1..d4`, which is the node the Part 1 ladder already uses, and
+  a wallet following it finds none of lnurl-wallet's notes.
+- **A `cx1` links every note on its branch.** It cannot spend anything, but
+  whoever holds it can list every key on the branch and ask the mint about
+  each one. Register it with a mint and that mint sees everything paid to the
+  address. Use the branch for receiving and rotate off it.
+- **`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.
+
 ## 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

@@ -273,6 +273,29 @@ declare const cashSecretSource: (root: CashNode, host: string, start?: number) =
     index: () => number;
 };
 
+declare const encodeCp1: (pubkeyXOnly: Uint8Array) => string;
+declare const decodeCp1: (value: string) => Uint8Array | null;
+declare const isCp1: (value: string) => boolean;
+declare const encodeCk1: (signature: Uint8Array) => string;
+declare const decodeCk1: (value: string) => Uint8Array | null;
+declare const isCk1: (value: string) => boolean;
+declare const encodeCs1: (signature: Uint8Array) => string;
+declare const decodeCs1: (value: string) => Uint8Array | null;
+declare const isCs1: (value: string) => boolean;
+type Cx1 = {
+    pubkeyXOnly: Uint8Array;
+    chainCode: Uint8Array;
+};
+declare const encodeCx1: (pubkeyXOnly: Uint8Array, chainCode: Uint8Array) => string;
+declare const decodeCx1: (value: string) => Cx1 | null;
+declare const isCx1: (value: string) => boolean;
+declare const deriveNotePubkey: (branchPubkeyXOnly: Uint8Array, chainCode: Uint8Array, index: number) => Uint8Array;
+declare const deriveNoteSecretKey: (branchPrivateKey: Uint8Array, chainCode: Uint8Array, index: number) => Uint8Array;
+declare const signNoteOwnership: (secretKey: Uint8Array) => Uint8Array;
+declare const recoverNoteOwnershipPubkey: (signature: Uint8Array) => Uint8Array | null;
+declare const deriveCashAddressNode: (root: CashNode, host: string) => CashNode;
+declare const cashNodeToCx1: (node: CashNode) => Cx1;
+
 declare const PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
 type PaymentRequestMethodDetails = {
     mints: string[];
@@ -380,4 +403,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type CashNode, 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, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, 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, restoreFromSeed, 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 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, noteK1, 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,4 +1,4 @@
-import { bech32, base64urlnopad } from '@scure/base';
+import { bech32, base64urlnopad, bech32m } from '@scure/base';
 import { hmac } from '@noble/hashes/hmac.js';
 import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
@@ -301,6 +301,114 @@ var cashSecretSource = (root, host, start = 0) => {
   source.index = () => next;
   return source;
 };
+var encodeFixed = (hrp, bytes, length) => {
+  if (bytes.length !== length) {
+    throw new RangeError(`A ${hrp}1 payload is ${length} bytes, not ${bytes.length}.`);
+  }
+  return bech32m.encode(hrp, bech32m.toWords(bytes), false);
+};
+var decodeFixed = (hrp, value, length) => {
+  if (typeof value !== "string") return null;
+  try {
+    const decoded = bech32m.decode(value.trim(), false);
+    if (decoded.prefix !== hrp) return null;
+    const bytes = bech32m.fromWords(decoded.words);
+    return bytes.length === length ? bytes : null;
+  } catch {
+    return null;
+  }
+};
+var encodeCp1 = (pubkeyXOnly) => encodeFixed("cp", pubkeyXOnly, 32);
+var decodeCp1 = (value) => decodeFixed("cp", value, 32);
+var isCp1 = (value) => decodeCp1(value) !== null;
+var encodeCk1 = (signature) => encodeFixed("ck", signature, 65);
+var decodeCk1 = (value) => decodeFixed("ck", value, 65);
+var isCk1 = (value) => decodeCk1(value) !== null;
+var encodeCs1 = (signature) => encodeFixed("cs", signature, 65);
+var decodeCs1 = (value) => decodeFixed("cs", value, 65);
+var isCs1 = (value) => decodeCs1(value) !== null;
+var encodeCx1 = (pubkeyXOnly, chainCode) => {
+  if (pubkeyXOnly.length !== 32 || chainCode.length !== 32) {
+    throw new RangeError("A cx1 is a 32-byte x-only public key and a 32-byte chain code.");
+  }
+  return encodeFixed("cx", new Uint8Array([...pubkeyXOnly, ...chainCode]), 64);
+};
+var decodeCx1 = (value) => {
+  const bytes = decodeFixed("cx", value, 64);
+  return bytes ? { pubkeyXOnly: bytes.slice(0, 32), chainCode: bytes.slice(32) } : null;
+};
+var isCx1 = (value) => decodeCx1(value) !== null;
+var CURVE_N2 = secp256k1.Point.Fn.ORDER;
+var NOTE_DERIVE_TAG = sha256(utf8ToBytes("LNURLcash/derive"));
+var numberOf2 = (bytes) => BigInt(`0x${bytesToHex(bytes)}`);
+var to32Bytes2 = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
+var requireUint32 = (index) => {
+  if (!Number.isSafeInteger(index) || index < 0 || index > 4294967295) {
+    throw new RangeError(`A note index must be a uint32, not ${index}.`);
+  }
+  return index;
+};
+var tweakFor = (pubkeyXOnly, chainCode, index) => {
+  if (pubkeyXOnly.length !== 32 || chainCode.length !== 32) {
+    throw new RangeError("A branch is a 32-byte x-only public key and a 32-byte chain code.");
+  }
+  const i = requireUint32(index);
+  const ser = new Uint8Array([i >>> 24 & 255, i >>> 16 & 255, i >>> 8 & 255, i & 255]);
+  const t = numberOf2(
+    sha256(new Uint8Array([...NOTE_DERIVE_TAG, ...NOTE_DERIVE_TAG, ...pubkeyXOnly, ...chainCode, ...ser]))
+  );
+  if (t >= CURVE_N2) {
+    throw new Error(`Note index ${index} is unusable on this branch. Use the next index.`);
+  }
+  return t;
+};
+var deriveNotePubkey = (branchPubkeyXOnly, chainCode, index) => {
+  const t = tweakFor(branchPubkeyXOnly, chainCode, index);
+  const branch = secp256k1.Point.fromBytes(new Uint8Array([2, ...branchPubkeyXOnly]));
+  const note = t === 0n ? branch : branch.add(secp256k1.Point.BASE.multiply(t));
+  if (note.is0()) {
+    throw new Error(`Note index ${index} is unusable on this branch. Use the next index.`);
+  }
+  return note.toBytes(true).slice(1);
+};
+var deriveNoteSecretKey = (branchPrivateKey, chainCode, index) => {
+  const p = numberOf2(branchPrivateKey);
+  if (branchPrivateKey.length !== 32 || p === 0n || p >= CURVE_N2) {
+    throw new RangeError("A branch private key is a 32-byte scalar in [1, n).");
+  }
+  const branch = secp256k1.Point.BASE.multiply(p);
+  const t = tweakFor(branch.toBytes(true).slice(1), chainCode, index);
+  const even = branch.y % 2n === 0n ? p : CURVE_N2 - p;
+  const key = (even + t) % CURVE_N2;
+  if (key === 0n) {
+    throw new Error(`Note index ${index} is unusable on this branch. Use the next index.`);
+  }
+  return to32Bytes2(key);
+};
+var NOTE_OWNERSHIP_DIGEST = sha256(
+  sha256(new Uint8Array([...utf8ToBytes("Lightning Signed Message:"), ...utf8ToBytes("LNURLcash")]))
+);
+var signNoteOwnership = (secretKey) => {
+  const signature = secp256k1.sign(NOTE_OWNERSHIP_DIGEST, secretKey, {
+    format: "recovered",
+    prehash: false
+  });
+  return new Uint8Array([...signature.subarray(1), signature[0]]);
+};
+var recoverNoteOwnershipPubkey = (signature) => {
+  if (!(signature instanceof Uint8Array) || signature.length !== 65) return null;
+  try {
+    const recoveryIdFirst = new Uint8Array([signature[64], ...signature.subarray(0, 64)]);
+    return secp256k1.recoverPublicKey(recoveryIdFirst, NOTE_OWNERSHIP_DIGEST, { prehash: false }).slice(1);
+  } catch {
+    return null;
+  }
+};
+var deriveCashAddressNode = (root, host) => deriveCashDomainNode(deriveCashChild(root, 1 + 2147483648), host);
+var cashNodeToCx1 = (node) => ({
+  pubkeyXOnly: secp256k1.getPublicKey(node.privateKey, true).slice(1),
+  chainCode: node.chainCode.slice()
+});
 
 // src/errors.ts
 var LnurlcashError = class extends Error {
@@ -756,22 +864,35 @@ var noteSignatureDigestForHash = (h, amountMsat) => sha256(
 );
 var NO_MATCH = { valid: false, pubkey: null };
 var verifyNoteSignatureAgainst = (k1, amountMsat, signatureHex, mintPubkeys) => {
-  let h;
+  const h = signedNoteId(k1);
+  if (h === null) return NO_MATCH;
+  return verifyNoteSignatureHashAgainst(h, amountMsat, signatureHex, mintPubkeys);
+};
+var signedNoteId = (k1) => {
+  const ownership = decodeCk1(k1);
+  if (ownership) {
+    const pubkey = recoverNoteOwnershipPubkey(ownership);
+    return pubkey ? bytesToHex(pubkey) : null;
+  }
   try {
-    h = hashK1(k1);
+    return hashK1(k1);
   } catch {
-    return NO_MATCH;
+    return null;
   }
-  return verifyNoteSignatureHashAgainst(h, amountMsat, signatureHex, mintPubkeys);
 };
 var verifyNoteSignatureHashAgainst = (h, amountMsat, signatureHex, mintPubkeys) => {
   const targets = (Array.isArray(mintPubkeys) ? mintPubkeys : [mintPubkeys]).filter((key) => typeof key === "string").map((key) => key.trim().toLowerCase());
   if (targets.length === 0) return NO_MATCH;
   let wireSig;
-  try {
-    wireSig = hexToBytes(signatureHex);
-  } catch {
-    return NO_MATCH;
+  const certificate = decodeCs1(signatureHex);
+  if (certificate) {
+    wireSig = certificate;
+  } else {
+    try {
+      wireSig = hexToBytes(signatureHex);
+    } catch {
+      return NO_MATCH;
+    }
   }
   if (wireSig.length !== 65) return NO_MATCH;
   let digest;
@@ -1601,4 +1722,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, cashNodeToHex, cashSecretAt, cashSecretSource, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveCashChild, deriveCashDomainNode, deriveCashRoot, deriveCashSecret, 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, restoreFromSeed, 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, 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, noteK1, 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

@@ -48,6 +48,22 @@ cashSecretSource(root, host, start) -> RandomSecret & {index()}
 cashNodeToHex/cashNodeFromHex             privateKey || chainCode, 64 bytes
 deriveCashChild(node, rawUint32) -> CashNode   BIP-32 CKDpriv, for checking
   this library against BIP-32's own vectors
+LUD-25 Part 2: a note keyed by a public key, spent by a recoverable signature
+encodeCp1/decodeCp1/isCp1   note pubkey, 32-byte x-only, bech32m "cp"
+encodeCk1/decodeCk1/isCk1   note bearer secret, 65-byte r||s||recid, "ck"
+encodeCs1/decodeCs1/isCs1   mint certificate over hex(pk), same layout, "cs"
+encodeCx1/decodeCx1/isCx1   watch-only branch {pubkeyXOnly, chainCode}, "cx"
+  decoders return null, never throw; mixed case is refused (BIP-350)
+deriveCashAddressNode(root, host) -> CashNode   m/139'/1'/d1..d4, hashing key
+  m/139'/1'/0. The REFERENCE WALLET's path, not the spec text's m/139'/d1..d4
+  (that is the Part 1 ladder's node, and finds none of its notes).
+cashNodeToCx1(node) -> Cx1
+deriveNotePubkey(P, chainCode, i) -> pk    watch-only, BIP-341 style tweak;
+  i any uint32, 4-byte big-endian, never hardened
+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
 deriveNoteRoot(seedBytes) -> Uint8Array    LEGACY, pre-spec. Do not mint under
 deriveNoteSecret(root, host, index) -> k1  it; still scanned so old notes live.
 derivedSecretSource(root, host, start) -> RandomSecret & {index()}

package/package.json

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