lnurlcash-kit 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.11.0 - 2026-09-11
+
+**The wire calls take LUD-25 Part 2 notes.**
+
+- A `ck1` goes anywhere a `k1` does. `resolveNoteInput` accepts a note URL
+  carrying one, and rotate, split, merge, melt and `fetchNoteInfo` pass it
+  through.
+- A `cp1` goes anywhere an output does. `requestInvoice` sends it as the
+  comment alone. The `*WithHash` calls send it as `p1`/`p2`, while a hash
+  keeps `h`/`h2`, which every mint understands. That is lnurl-wallet's rule.
+- `fetchNoteInfoByHash` and `buildNoteInfoUrlByHash` take a `cp1`, sent as
+  `p`.
+- `noteIdOf(k1)` is the id a mint files a note under, for either kind.
+  `noteLookupOf(k1)` is what to look it up by without disclosing it.
+- `noteSignatureMessage` and `noteSignatureDigest` build the message over the
+  key for a `ck1`.
+
+## 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,58 @@ 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`.
+
+The wire calls take both kinds. A `ck1` goes anywhere a `k1` does: a note
+URL, `fetchNoteInfo`, rotate, split, merge and melt. A `cp1` goes anywhere an
+output does: `requestInvoice`'s `h`, and the output of every `*WithHash` call,
+where it is sent as `p1`/`p2` while a hash keeps `h`/`h2`, the same rule as
+lnurl-wallet. `noteIdOf(k1)` gives the id a mint files either kind under, and
+`noteLookupOf(k1)` what to pass `fetchNoteInfoByHash` to check a note without
+disclosing it. 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,31 @@ 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 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 PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
 type PaymentRequestMethodDetails = {
     mints: string[];
@@ -380,4 +405,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, 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 } from '@scure/base';
-import { hmac } from '@noble/hashes/hmac.js';
+import { bech32, base64urlnopad, bech32m } from '@scure/base';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
 import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
-import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { hmac } from '@noble/hashes/hmac.js';
 
 // src/urls.ts
 var isBech32Lnurl = (data) => data.trim().toUpperCase().startsWith("LNURL1");
@@ -120,12 +120,95 @@ var serverOf = (url) => {
     return url;
   }
 };
+var HARDENED = 2147483648;
+var CURVE_N = secp256k1.Point.Fn.ORDER;
+var MASTER_KEY_DOMAIN = utf8ToBytes("Bitcoin seed");
+var CASH_PURPOSE = 139;
+var numberOf = (bytes) => bytes.length === 0 ? 0n : BigInt(`0x${bytesToHex(bytes)}`);
+var to32Bytes = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
+var readUint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+var deriveCashChild = (node, index) => {
+  if (!Number.isSafeInteger(index) || index < 0 || index > 4294967295) {
+    throw new RangeError(`A BIP-32 child index must be a uint32, not ${index}.`);
+  }
+  const data = new Uint8Array(37);
+  if (index >= HARDENED) {
+    data.set(node.privateKey, 1);
+  } else {
+    data.set(
+      secp256k1.Point.BASE.multiply(numberOf(node.privateKey)).toBytes(true),
+      0
+    );
+  }
+  data[33] = index >>> 24 & 255;
+  data[34] = index >>> 16 & 255;
+  data[35] = index >>> 8 & 255;
+  data[36] = index & 255;
+  const material = hmac(sha512, node.chainCode, data);
+  const left = numberOf(material.subarray(0, 32));
+  const key = (left + numberOf(node.privateKey)) % CURVE_N;
+  if (left >= CURVE_N || key === 0n) {
+    throw new Error(
+      `BIP-32 derivation at index ${index} produced an invalid key. Use the next index.`
+    );
+  }
+  return { privateKey: to32Bytes(key), chainCode: material.slice(32) };
+};
+var masterFrom = (seed) => {
+  if (seed.length < 16 || seed.length > 64) {
+    throw new RangeError(
+      `A BIP-32 seed must be 16 to 64 bytes, not ${seed.length}.`
+    );
+  }
+  const material = hmac(sha512, MASTER_KEY_DOMAIN, seed);
+  const key = numberOf(material.subarray(0, 32));
+  if (key === 0n || key >= CURVE_N) {
+    throw new Error("This seed does not produce a valid BIP-32 master key.");
+  }
+  return { privateKey: material.slice(0, 32), chainCode: material.slice(32) };
+};
+var deriveCashRoot = (seed) => deriveCashChild(masterFrom(seed), CASH_PURPOSE + HARDENED);
+var cashDomainIndices = (root, host) => {
+  const hashingKey = deriveCashChild(root, 0).privateKey;
+  const material = hmac(sha256, hashingKey, utf8ToBytes(host));
+  return [0, 4, 8, 12].map((offset) => readUint32BE(material, offset));
+};
+var deriveCashDomainNode = (root, host) => cashDomainIndices(root, host).reduce(deriveCashChild, root);
+var requireIndex = (index) => {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= HARDENED) {
+    throw new RangeError(
+      `A note index must be an integer in [0, 2^31), not ${index}.`
+    );
+  }
+  return index;
+};
+var cashSecretAt = (domainNode, index) => bytesToHex(
+  deriveCashChild(domainNode, requireIndex(index) + HARDENED).privateKey
+);
+var deriveCashSecret = (root, host, index) => cashSecretAt(deriveCashDomainNode(root, host), index);
+var cashNodeToHex = (node) => bytesToHex(node.privateKey) + bytesToHex(node.chainCode);
+var cashNodeFromHex = (hex) => {
+  const bytes = hexToBytes(hex.trim().toLowerCase());
+  if (bytes.length !== 64) {
+    throw new RangeError(
+      `A cash node is 64 bytes - a 32-byte key and a 32-byte chain code - not ${bytes.length}.`
+    );
+  }
+  return { privateKey: bytes.slice(0, 32), chainCode: bytes.slice(32) };
+};
+var cashSecretSource = (root, host, start = 0) => {
+  const domainNode = deriveCashDomainNode(root, host);
+  let next = requireIndex(start);
+  const source = (() => cashSecretAt(domainNode, next++));
+  source.index = () => next;
+  return source;
+};
 var hashK1 = (k1) => bytesToHex(sha256(hexToBytes(k1)));
 var defaultRandomSecret = () => bytesToHex(crypto.getRandomValues(new Uint8Array(32)));
 var isPreimage = (value) => /^[0-9a-fA-F]{64}$/.test(value.trim());
 var NOTE_DERIVATION_DOMAIN = utf8ToBytes("lnurlcash-note-v1");
 var deriveNoteRoot = (seed) => hmac(sha256, NOTE_DERIVATION_DOMAIN, seed);
-var requireIndex = (index) => {
+var requireIndex2 = (index) => {
   if (!Number.isSafeInteger(index) || index < 0) {
     throw new RangeError(
       `A note index must be a non-negative integer, not ${index}.`
@@ -133,14 +216,137 @@ var requireIndex = (index) => {
   }
   return index;
 };
-var deriveNoteSecret = (root, host, index) => bytesToHex(hmac(sha256, root, utf8ToBytes(`${host}:${requireIndex(index)}`)));
+var deriveNoteSecret = (root, host, index) => bytesToHex(hmac(sha256, root, utf8ToBytes(`${host}:${requireIndex2(index)}`)));
 var derivedSecretSource = (root, host, start = 0) => {
-  let next = requireIndex(start);
+  let next = requireIndex2(start);
   const source = (() => deriveNoteSecret(root, host, next++));
   source.index = () => next;
   return source;
 };
 
+// src/recoverable.ts
+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 noteIdOf = (k1) => {
+  if (typeof k1 !== "string") return null;
+  const value = k1.trim().toLowerCase();
+  if (isPreimage(value)) return hashK1(value);
+  const signature = decodeCk1(value);
+  const pubkey = signature ? recoverNoteOwnershipPubkey(signature) : null;
+  return pubkey ? bytesToHex(pubkey) : null;
+};
+var noteLookupOf = (k1) => {
+  const id = noteIdOf(k1);
+  if (id === null) return null;
+  return isCk1(k1.trim().toLowerCase()) ? encodeCp1(hexToBytes(id)) : id;
+};
+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/note.ts
 var noteK1 = (url) => {
   try {
@@ -178,20 +384,21 @@ var noteSignature = (url) => {
 var resolveNoteInput = (value) => {
   const url = resolveLnurlInput(value);
   const k1 = url ? noteK1(url) : null;
-  if (!url || !k1 || !isPreimage(k1)) return null;
+  if (!url || !k1 || noteIdOf(k1) === null) return null;
   return url;
 };
 var isValidNoteInput = (value) => resolveNoteInput(value) !== null;
 var buildNoteInfoUrlByHash = (withdrawLink, h) => {
-  const hex = h.trim().toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(hex)) {
-    throw new Error("A note hash must be 32 bytes of hex.");
+  const value = h.trim().toLowerCase();
+  const key = isCp1(value);
+  if (!key && !/^[0-9a-f]{64}$/.test(value)) {
+    throw new Error("A note hash must be 32 bytes of hex, or a cp1 key.");
   }
   const url = new URL(fromLud17(withdrawLink.trim()));
   url.searchParams.delete("k1");
   url.searchParams.delete("amount");
   url.searchParams.delete("sig");
-  url.searchParams.set("h", hex);
+  url.searchParams.set(key ? "p" : "h", value);
   return url.toString();
 };
 var buildNoteUrl = (withdrawLink, k1, amountMsat) => {
@@ -218,89 +425,6 @@ var withoutK1 = (url, amountMsat, signature) => {
   else newUrl.searchParams.delete("sig");
   return newUrl.toString();
 };
-var HARDENED = 2147483648;
-var CURVE_N = secp256k1.Point.Fn.ORDER;
-var MASTER_KEY_DOMAIN = utf8ToBytes("Bitcoin seed");
-var CASH_PURPOSE = 139;
-var numberOf = (bytes) => bytes.length === 0 ? 0n : BigInt(`0x${bytesToHex(bytes)}`);
-var to32Bytes = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
-var readUint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
-var deriveCashChild = (node, index) => {
-  if (!Number.isSafeInteger(index) || index < 0 || index > 4294967295) {
-    throw new RangeError(`A BIP-32 child index must be a uint32, not ${index}.`);
-  }
-  const data = new Uint8Array(37);
-  if (index >= HARDENED) {
-    data.set(node.privateKey, 1);
-  } else {
-    data.set(
-      secp256k1.Point.BASE.multiply(numberOf(node.privateKey)).toBytes(true),
-      0
-    );
-  }
-  data[33] = index >>> 24 & 255;
-  data[34] = index >>> 16 & 255;
-  data[35] = index >>> 8 & 255;
-  data[36] = index & 255;
-  const material = hmac(sha512, node.chainCode, data);
-  const left = numberOf(material.subarray(0, 32));
-  const key = (left + numberOf(node.privateKey)) % CURVE_N;
-  if (left >= CURVE_N || key === 0n) {
-    throw new Error(
-      `BIP-32 derivation at index ${index} produced an invalid key. Use the next index.`
-    );
-  }
-  return { privateKey: to32Bytes(key), chainCode: material.slice(32) };
-};
-var masterFrom = (seed) => {
-  if (seed.length < 16 || seed.length > 64) {
-    throw new RangeError(
-      `A BIP-32 seed must be 16 to 64 bytes, not ${seed.length}.`
-    );
-  }
-  const material = hmac(sha512, MASTER_KEY_DOMAIN, seed);
-  const key = numberOf(material.subarray(0, 32));
-  if (key === 0n || key >= CURVE_N) {
-    throw new Error("This seed does not produce a valid BIP-32 master key.");
-  }
-  return { privateKey: material.slice(0, 32), chainCode: material.slice(32) };
-};
-var deriveCashRoot = (seed) => deriveCashChild(masterFrom(seed), CASH_PURPOSE + HARDENED);
-var cashDomainIndices = (root, host) => {
-  const hashingKey = deriveCashChild(root, 0).privateKey;
-  const material = hmac(sha256, hashingKey, utf8ToBytes(host));
-  return [0, 4, 8, 12].map((offset) => readUint32BE(material, offset));
-};
-var deriveCashDomainNode = (root, host) => cashDomainIndices(root, host).reduce(deriveCashChild, root);
-var requireIndex2 = (index) => {
-  if (!Number.isSafeInteger(index) || index < 0 || index >= HARDENED) {
-    throw new RangeError(
-      `A note index must be an integer in [0, 2^31), not ${index}.`
-    );
-  }
-  return index;
-};
-var cashSecretAt = (domainNode, index) => bytesToHex(
-  deriveCashChild(domainNode, requireIndex2(index) + HARDENED).privateKey
-);
-var deriveCashSecret = (root, host, index) => cashSecretAt(deriveCashDomainNode(root, host), index);
-var cashNodeToHex = (node) => bytesToHex(node.privateKey) + bytesToHex(node.chainCode);
-var cashNodeFromHex = (hex) => {
-  const bytes = hexToBytes(hex.trim().toLowerCase());
-  if (bytes.length !== 64) {
-    throw new RangeError(
-      `A cash node is 64 bytes - a 32-byte key and a 32-byte chain code - not ${bytes.length}.`
-    );
-  }
-  return { privateKey: bytes.slice(0, 32), chainCode: bytes.slice(32) };
-};
-var cashSecretSource = (root, host, start = 0) => {
-  const domainNode = deriveCashDomainNode(root, host);
-  let next = requireIndex2(start);
-  const source = (() => cashSecretAt(domainNode, next++));
-  source.index = () => next;
-  return source;
-};
 
 // src/errors.ts
 var LnurlcashError = class extends Error {
@@ -743,9 +867,14 @@ var describeMintFee = (fee) => [
   fee.feePpm > 0 ? `${formatFeePercent(fee.feePpm)}% of the amount paid` : null
 ].filter(Boolean).join(" + ");
 var LIGHTNING_SIGNED_MESSAGE_PREFIX = utf8ToBytes("Lightning Signed Message:");
-var noteSignatureMessage = (k1, amountMsat) => noteSignatureMessageForHash(hashK1(k1), amountMsat);
+var requireNoteId = (k1) => {
+  const id = noteIdOf(k1);
+  if (id === null) throw new Error("A k1 is 32 bytes of hex or a ck1.");
+  return id;
+};
+var noteSignatureMessage = (k1, amountMsat) => noteSignatureMessageForHash(requireNoteId(k1), amountMsat);
 var noteSignatureMessageForHash = (h, amountMsat) => `LNURLcash:${amountMsat}:${h.trim().toLowerCase()}`;
-var noteSignatureDigest = (k1, amountMsat) => noteSignatureDigestForHash(hashK1(k1), amountMsat);
+var noteSignatureDigest = (k1, amountMsat) => noteSignatureDigestForHash(requireNoteId(k1), amountMsat);
 var noteSignatureDigestForHash = (h, amountMsat) => sha256(
   sha256(
     new Uint8Array([
@@ -756,22 +885,23 @@ var noteSignatureDigestForHash = (h, amountMsat) => sha256(
 );
 var NO_MATCH = { valid: false, pubkey: null };
 var verifyNoteSignatureAgainst = (k1, amountMsat, signatureHex, mintPubkeys) => {
-  let h;
-  try {
-    h = hashK1(k1);
-  } catch {
-    return NO_MATCH;
-  }
+  const h = noteIdOf(k1);
+  if (h === null) return NO_MATCH;
   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;
@@ -1020,12 +1150,16 @@ var meltNote = async (callback, k1, pr, options = {}) => {
     pr: typeof body.pr === "string" ? body.pr : void 0
   };
 };
+var outputParam = (value, which) => {
+  const cp1 = isCp1(value.trim().toLowerCase());
+  return [cp1 ? `p${which}` : which === 1 ? "h" : "h2", value];
+};
 var rotateNoteWithHash = async (callback, k1, h, options = {}) => {
   const body = await replayableCallbackRequest(
     callback,
     [
       ["k1", k1],
-      ["h", h]
+      outputParam(h, 1)
     ],
     options
   );
@@ -1037,8 +1171,8 @@ var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) =
     [
       ...k1s.map((k1) => ["k1", k1]),
       ["amount", String(amountMsat)],
-      ["h", h],
-      ["h2", h2]
+      outputParam(h, 1),
+      outputParam(h2, 2)
     ],
     options
   );
@@ -1050,7 +1184,7 @@ var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) =
 var mergeNotesWithHash = async (callback, k1s, h, options = {}) => {
   const body = await replayableCallbackRequest(
     callback,
-    [...k1s.map((k1) => ["k1", k1]), ["h", h]],
+    [...k1s.map((k1) => ["k1", k1]), outputParam(h, 1)],
     options
   );
   return { signature: requireSignature(body.sig, options, "merge") };
@@ -1246,14 +1380,17 @@ var requestInvoice = async (payCallback, amountMsat, options = {}) => {
   const cbUrl = new URL(payCallback);
   cbUrl.searchParams.set("amount", String(amountMsat));
   if (options.h !== void 0) {
-    if (!isPreimage(options.h)) {
+    const h = options.h.trim().toLowerCase();
+    if (isCp1(h)) {
+      cbUrl.searchParams.set("comment", h);
+    } else if (isPreimage(h)) {
+      cbUrl.searchParams.set("comment", h);
+      cbUrl.searchParams.set("h", h);
+    } else {
       throw new RequestRefusedError(
-        "An output hash must be 32 bytes of hex - no invoice was requested."
+        "An output must be 32 bytes of hex or a cp1 key - no invoice was requested."
       );
     }
-    const h = options.h.trim().toLowerCase();
-    cbUrl.searchParams.set("comment", h);
-    cbUrl.searchParams.set("h", h);
   }
   const body = await lnurlFetch(cbUrl, resolveOptions(options));
   if (typeof body?.pr !== "string") {
@@ -1601,4 +1738,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, 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

@@ -48,6 +48,27 @@ 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
+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
+Wire: a ck1 goes wherever a k1 does; a cp1 wherever an output does
+  (requestInvoice h, *WithHash outputs: cp1 sent as p1/p2, hash as h/h2)
 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.11.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"