lnurlcash-kit 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,4 +1,5 @@
-import { bech32 } from '@scure/base';
+import { bech32, base64urlnopad } from '@scure/base';
+import { hmac } from '@noble/hashes/hmac.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { utf8ToBytes, bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import { secp256k1 } from '@noble/curves/secp256k1.js';
@@ -122,6 +123,23 @@ var serverOf = (url) => {
 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) => {
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new RangeError(
+      `A note index must be a non-negative integer, not ${index}.`
+    );
+  }
+  return index;
+};
+var deriveNoteSecret = (root, host, index) => bytesToHex(hmac(sha256, root, utf8ToBytes(`${host}:${requireIndex(index)}`)));
+var derivedSecretSource = (root, host, start = 0) => {
+  let next = requireIndex(start);
+  const source = (() => deriveNoteSecret(root, host, next++));
+  source.index = () => next;
+  return source;
+};
 
 // src/note.ts
 var noteK1 = (url) => {
@@ -188,125 +206,6 @@ var withoutK1 = (url, amountMsat, signature) => {
   else newUrl.searchParams.delete("sig");
   return newUrl.toString();
 };
-var LIGHTNING_SIGNED_MESSAGE_PREFIX = utf8ToBytes("Lightning Signed Message:");
-var noteSignatureMessage = (k1, amountMsat) => `LNURLcash:${amountMsat}:${hashK1(k1)}`;
-var noteSignatureDigest = (k1, amountMsat) => sha256(
-  sha256(
-    new Uint8Array([
-      ...LIGHTNING_SIGNED_MESSAGE_PREFIX,
-      ...utf8ToBytes(noteSignatureMessage(k1, amountMsat))
-    ])
-  )
-);
-var verifyNoteSignature = (k1, amountMsat, signatureHex, mintPubkeyHex) => {
-  let wireSig;
-  try {
-    wireSig = hexToBytes(signatureHex);
-  } catch {
-    return false;
-  }
-  if (wireSig.length !== 65) return false;
-  let digest;
-  try {
-    digest = noteSignatureDigest(k1, amountMsat);
-  } catch {
-    return false;
-  }
-  const target = mintPubkeyHex.trim().toLowerCase();
-  const recoveryIdFirst = new Uint8Array([
-    wireSig[64],
-    ...wireSig.subarray(0, 64)
-  ]);
-  for (const candidate of [recoveryIdFirst, wireSig]) {
-    try {
-      const recovered = secp256k1.recoverPublicKey(candidate, digest, {
-        prehash: false
-      });
-      if (bytesToHex(recovered) === target) return true;
-    } catch {
-    }
-  }
-  return false;
-};
-
-// src/fees.ts
-var parseMintFee = (metadata) => {
-  let entries;
-  try {
-    entries = JSON.parse(metadata);
-  } catch {
-    return null;
-  }
-  if (!Array.isArray(entries)) return null;
-  for (const entry of entries) {
-    if (!Array.isArray(entry) || entry[0] !== "text/plain") continue;
-    const match = typeof entry[1] === "string" && entry[1].match(/^Mint fees:\s*(\d+)\s*,\s*(\d+)\s*$/);
-    if (!match) continue;
-    const baseFeeMsat = Number(match[1]);
-    const feePpm = Number(match[2]);
-    if (!Number.isSafeInteger(baseFeeMsat) || !Number.isSafeInteger(feePpm)) continue;
-    if (feePpm >= 1e6) continue;
-    if (baseFeeMsat === 0 && feePpm === 0) return null;
-    return { baseFeeMsat, feePpm };
-  }
-  return null;
-};
-var proportionalFee = (grossMsat, feePpm) => Math.floor(grossMsat / 1e6) * feePpm + Math.floor(grossMsat % 1e6 * feePpm / 1e6);
-var applyMintFee = (grossMsat, fee) => Math.max(0, grossMsat - fee.baseFeeMsat - proportionalFee(grossMsat, fee.feePpm));
-var mintFeeBand = (grossMsat, fee) => {
-  const exactFee = fee.baseFeeMsat + proportionalFee(grossMsat, fee.feePpm);
-  const satCeilinged = Math.ceil(exactFee / 1e3) * 1e3;
-  return {
-    minNetMsat: Math.max(0, grossMsat - satCeilinged),
-    maxNetMsat: Math.max(0, grossMsat - exactFee)
-  };
-};
-var withinMintFeeBand = (grossMsat, netMsat, fee) => {
-  const { minNetMsat, maxNetMsat } = mintFeeBand(grossMsat, fee);
-  return netMsat >= minNetMsat && netMsat <= maxNetMsat;
-};
-var grossUpForMintFee = (netMsat, fee) => {
-  if (netMsat <= 0) return 0;
-  let hi = netMsat + fee.baseFeeMsat;
-  while (applyMintFee(hi, fee) < netMsat) hi *= 2;
-  let lo = 0;
-  while (lo < hi) {
-    const mid = Math.floor((lo + hi) / 2);
-    if (applyMintFee(mid, fee) >= netMsat) hi = mid;
-    else lo = mid + 1;
-  }
-  return lo;
-};
-var formatFeePercent = (ppm) => (ppm / 1e4).toFixed(4).replace(/\.?0+$/, "");
-var describeMintFee = (fee) => [
-  fee.baseFeeMsat > 0 ? `${Math.round(fee.baseFeeMsat / 1e3)} sat flat` : null,
-  fee.feePpm > 0 ? `${formatFeePercent(fee.feePpm)}% of the amount paid` : null
-].filter(Boolean).join(" + ");
-
-// src/bolt11.ts
-var isBolt11Invoice = (value) => /^ln(bc|tb|bcrt|tbs|sb)[0-9]*[munp]?1[a-z0-9]+$/.test(
-  value.trim().toLowerCase()
-);
-var sameInvoice = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
-var BOLT11_AMOUNT_MSAT_PER_UNIT = {
-  "": 1e11,
-  m: 1e8,
-  u: 1e5,
-  n: 100,
-  p: 0.1
-};
-var decodeBolt11AmountMsat = (pr) => {
-  const trimmed = pr.trim().toLowerCase();
-  const sep = trimmed.lastIndexOf("1");
-  if (sep < 2) return null;
-  const hrp = trimmed.slice(0, sep);
-  const match = hrp.match(/^ln(?:bc|tb|bcrt|tbs|sb)(\d+)?([munp])?$/);
-  if (!match) return null;
-  const [, digits, multiplier] = match;
-  if (!digits) return null;
-  const msat = Number(digits) * BOLT11_AMOUNT_MSAT_PER_UNIT[multiplier || ""];
-  return Number.isInteger(msat) ? msat : null;
-};
 
 // src/errors.ts
 var LnurlcashError = class extends Error {
@@ -321,6 +220,11 @@ var ProtocolError = class extends LnurlcashError {
 };
 var ServiceRejectedError = class extends LnurlcashError {
   reason;
+  // The WALLET-generated secrets a MUTATION disclosed the hashes of, when
+  // this refusal is one that could describe a mutation the SERVICE had
+  // already applied - see newSecretsOf. Absent on every other refusal, and
+  // absent on every non-mutating call.
+  newSecrets;
   constructor(reason) {
     super(reason || "The service rejected the request.");
     this.reason = reason;
@@ -353,12 +257,190 @@ var AmbiguousMutationError = class extends AmbiguousMintError {
     this.newSecrets = newSecrets;
   }
 };
+var InsufficientValueError = class extends ServiceRejectedError {
+  amountMsat;
+  minMsat;
+  constructor(amountMsat, minMsat) {
+    super(`worth ${amountMsat} msat, needs ${minMsat} msat`);
+    this.amountMsat = amountMsat;
+    this.minMsat = minMsat;
+    this.message = `This note is worth ${amountMsat} msat, and ${minMsat} msat is required.`;
+  }
+};
+var newSecretsOf = (err) => {
+  if (err instanceof AmbiguousMutationError) return err.newSecrets;
+  if (err instanceof ServiceRejectedError) return err.newSecrets ?? [];
+  return [];
+};
 var classifyNoteError = (reason) => {
+  if (reason === "pending") return new PendingNoteError(reason);
   if (/spent/i.test(reason)) return new NoteSpentError(reason);
   if (/unknown|not found/i.test(reason)) return new NoteUnknownError(reason);
   return new ServiceRejectedError(reason);
 };
 
+// src/request.ts
+var PAYMENT_REQUEST_PREFIX = "lnurlcashreq1";
+var MAX_ENCODED_LENGTH = 4096;
+var AMOUNT_RE = /^(?:0|[1-9][0-9]*)$/;
+var ID_RE = /^[0-9a-f]{16}$/;
+var NPUB_RE = /^npub1[023456789acdefghjklmnpqrstuvwxyz]{58}$/;
+var isNpub = (value) => {
+  if (!NPUB_RE.test(value)) return false;
+  try {
+    const { prefix, words } = bech32.decode(value);
+    return prefix === "npub" && bech32.fromWords(words).length === 32;
+  } catch {
+    return false;
+  }
+};
+var reject = (why) => {
+  throw new ProtocolError(`Not a valid payment request: ${why}`);
+};
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var canonicalise = (value) => {
+  if (Array.isArray(value)) return `[${value.map(canonicalise).join(",")}]`;
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0);
+    entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const body = entries.map(([key, v]) => `${JSON.stringify(key)}:${canonicalise(v)}`).join(",");
+    return `{${body}}`;
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) reject("a number that is not a safe integer");
+    return String(value);
+  }
+  if (typeof value === "string" || typeof value === "boolean" || value === null) {
+    return JSON.stringify(value);
+  }
+  return reject(`a value of type ${typeof value}`);
+};
+var validate = (value) => {
+  if (!isPlainObject(value)) reject("not an object");
+  const raw = value;
+  const known = /* @__PURE__ */ new Set([
+    "v",
+    "id",
+    "amount",
+    "currency",
+    "methodDetails",
+    "to",
+    "memo",
+    "expires"
+  ]);
+  for (const key of Object.keys(raw)) {
+    if (!known.has(key)) reject(`unrecognised field "${key}"`);
+  }
+  if (raw.v !== 1) reject("unsupported version");
+  if (typeof raw.id !== "string" || !ID_RE.test(raw.id)) {
+    reject("id must be 16 lowercase hex characters");
+  }
+  if (typeof raw.amount !== "string" || !AMOUNT_RE.test(raw.amount)) {
+    reject("amount must be a whole number of sats, as a decimal string");
+  }
+  const sats = Number(raw.amount);
+  if (!Number.isSafeInteger(sats) || sats < 1) {
+    reject("amount must be at least 1 sat");
+  }
+  if (raw.currency !== "sat") reject('currency must be "sat"');
+  if (!isPlainObject(raw.methodDetails)) reject("methodDetails must be an object");
+  const details = raw.methodDetails;
+  for (const key of Object.keys(details)) {
+    if (key !== "mints" && key !== "mintPubkeys") {
+      reject(`unrecognised methodDetails field "${key}"`);
+    }
+  }
+  if (!Array.isArray(details.mints) || details.mints.length === 0 || !details.mints.every((mint) => typeof mint === "string" && mint.trim() !== "")) {
+    reject("methodDetails.mints must list at least one mint");
+  }
+  if (details.mintPubkeys !== void 0 && (!Array.isArray(details.mintPubkeys) || !details.mintPubkeys.every((key) => typeof key === "string"))) {
+    reject("methodDetails.mintPubkeys must be a list of strings");
+  }
+  if (raw.to !== void 0) {
+    if (typeof raw.to !== "string") reject("to must be a string");
+    const to = raw.to;
+    if (!isNpub(to) && !isLightningAddress(to)) {
+      reject("to must be an npub or a Lightning Address");
+    }
+  }
+  if (raw.memo !== void 0 && typeof raw.memo !== "string") {
+    reject("memo must be a string");
+  }
+  if (raw.expires !== void 0 && (typeof raw.expires !== "number" || !Number.isSafeInteger(raw.expires) || raw.expires < 0)) {
+    reject("expires must be a unix timestamp in whole seconds");
+  }
+  const request = {
+    v: 1,
+    id: raw.id,
+    amount: raw.amount,
+    currency: "sat",
+    methodDetails: {
+      mints: [...details.mints],
+      ...details.mintPubkeys === void 0 ? {} : { mintPubkeys: [...details.mintPubkeys] }
+    },
+    ...raw.to === void 0 ? {} : { to: raw.to },
+    ...raw.memo === void 0 ? {} : { memo: raw.memo },
+    ...raw.expires === void 0 ? {} : { expires: raw.expires }
+  };
+  return request;
+};
+var paymentRequestAmountMsat = (request) => Number(request.amount) * 1e3;
+var SHORT_FORM_KEYS = /* @__PURE__ */ new Set(["a", "m", "u"]);
+var fromShortForm = (value) => {
+  if (!isPlainObject(value)) return value;
+  const raw = value;
+  if (raw.v !== void 0 || raw.amount !== void 0) return value;
+  const keys = Object.keys(raw);
+  if (keys.length === 0 || !keys.every((key) => SHORT_FORM_KEYS.has(key))) {
+    return value;
+  }
+  if (typeof raw.a !== "number" || !Number.isSafeInteger(raw.a)) return value;
+  if (!Array.isArray(raw.m)) return value;
+  const canonical = canonicalise(raw);
+  return {
+    v: 1,
+    id: bytesToHex(sha256(utf8ToBytes(canonical))).slice(0, 16),
+    amount: String(raw.a),
+    currency: raw.u === void 0 ? "sat" : raw.u,
+    methodDetails: { mints: raw.m }
+  };
+};
+var encodePaymentRequest = (request) => PAYMENT_REQUEST_PREFIX + base64urlnopad.encode(new TextEncoder().encode(canonicalise(validate(request))));
+var decodePaymentRequest = (value, { now = Math.floor(Date.now() / 1e3) } = {}) => {
+  const trimmed = value.trim();
+  if (trimmed.length > MAX_ENCODED_LENGTH) reject("far too long to be one");
+  if (trimmed.slice(0, PAYMENT_REQUEST_PREFIX.length).toLowerCase() !== PAYMENT_REQUEST_PREFIX) {
+    reject(`it does not start with ${PAYMENT_REQUEST_PREFIX}`);
+  }
+  let json;
+  try {
+    json = new TextDecoder().decode(
+      base64urlnopad.decode(trimmed.slice(PAYMENT_REQUEST_PREFIX.length))
+    );
+  } catch {
+    return reject("the body is not base64url");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return reject("the body is not JSON");
+  }
+  const request = validate(fromShortForm(parsed));
+  if (request.expires !== void 0 && now > 0 && request.expires <= now) {
+    reject("it expired");
+  }
+  return request;
+};
+var isPaymentRequest = (value) => {
+  try {
+    decodePaymentRequest(value, { now: 0 });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 // src/transport.ts
 var resolveOptions = (options = {}) => ({
   // Wrapped, never referenced bare: in a browser window.fetch is a method
@@ -467,6 +549,85 @@ var lnurlFetch = async (url, options) => {
   return body;
 };
 
+// src/bolt11.ts
+var isBolt11Invoice = (value) => /^ln(bc|tb|bcrt|tbs|sb)[0-9]*[munp]?1[a-z0-9]+$/.test(
+  value.trim().toLowerCase()
+);
+var sameInvoice = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+var BOLT11_AMOUNT_MSAT_PER_UNIT = {
+  "": 1e11,
+  m: 1e8,
+  u: 1e5,
+  n: 100,
+  p: 0.1
+};
+var decodeBolt11AmountMsat = (pr) => {
+  const trimmed = pr.trim().toLowerCase();
+  const sep = trimmed.lastIndexOf("1");
+  if (sep < 2) return null;
+  const hrp = trimmed.slice(0, sep);
+  const match = hrp.match(/^ln(?:bc|tb|bcrt|tbs|sb)(\d+)?([munp])?$/);
+  if (!match) return null;
+  const [, digits, multiplier] = match;
+  if (!digits) return null;
+  const msat = Number(digits) * BOLT11_AMOUNT_MSAT_PER_UNIT[multiplier || ""];
+  return Number.isInteger(msat) ? msat : null;
+};
+
+// src/fees.ts
+var parseMintFee = (metadata) => {
+  let entries;
+  try {
+    entries = JSON.parse(metadata);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(entries)) return null;
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || entry[0] !== "text/plain") continue;
+    const match = typeof entry[1] === "string" && entry[1].match(/^Mint fees:\s*(\d+)\s*,\s*(\d+)\s*$/);
+    if (!match) continue;
+    const baseFeeMsat = Number(match[1]);
+    const feePpm = Number(match[2]);
+    if (!Number.isSafeInteger(baseFeeMsat) || !Number.isSafeInteger(feePpm)) continue;
+    if (feePpm >= 1e6) continue;
+    if (baseFeeMsat === 0 && feePpm === 0) return null;
+    return { baseFeeMsat, feePpm };
+  }
+  return null;
+};
+var proportionalFee = (grossMsat, feePpm) => Math.floor(grossMsat / 1e6) * feePpm + Math.floor(grossMsat % 1e6 * feePpm / 1e6);
+var applyMintFee = (grossMsat, fee) => Math.max(0, grossMsat - fee.baseFeeMsat - proportionalFee(grossMsat, fee.feePpm));
+var mintFeeBand = (grossMsat, fee) => {
+  const exactFee = fee.baseFeeMsat + proportionalFee(grossMsat, fee.feePpm);
+  const satCeilinged = Math.ceil(exactFee / 1e3) * 1e3;
+  return {
+    minNetMsat: Math.max(0, grossMsat - satCeilinged),
+    maxNetMsat: Math.max(0, grossMsat - exactFee)
+  };
+};
+var withinMintFeeBand = (grossMsat, netMsat, fee) => {
+  const { minNetMsat, maxNetMsat } = mintFeeBand(grossMsat, fee);
+  return netMsat >= minNetMsat && netMsat <= maxNetMsat;
+};
+var grossUpForMintFee = (netMsat, fee) => {
+  if (netMsat <= 0) return 0;
+  let hi = netMsat + fee.baseFeeMsat;
+  while (applyMintFee(hi, fee) < netMsat) hi *= 2;
+  let lo = 0;
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (applyMintFee(mid, fee) >= netMsat) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+};
+var formatFeePercent = (ppm) => (ppm / 1e4).toFixed(4).replace(/\.?0+$/, "");
+var describeMintFee = (fee) => [
+  fee.baseFeeMsat > 0 ? `${Math.round(fee.baseFeeMsat / 1e3)} sat flat` : null,
+  fee.feePpm > 0 ? `${formatFeePercent(fee.feePpm)}% of the amount paid` : null
+].filter(Boolean).join(" + ");
+
 // src/client.ts
 var fetchNoteInfo = async (url, options = {}) => {
   const opts = resolveOptions(options);
@@ -501,18 +662,63 @@ var probeBurnedNote = async (url, options = {}) => {
     return "unknown";
   }
 };
+var asString = (value) => typeof value === "string" ? value : void 0;
+var asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var asContact = (value) => {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  const contact = {
+    nostr: asString(raw.nostr),
+    email: asString(raw.email),
+    url: asString(raw.url)
+  };
+  const any = contact.nostr ?? contact.email ?? contact.url;
+  return any === void 0 ? void 0 : contact;
+};
+var asFees = (value) => {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  const baseFeeMsat = asNumber(raw.baseFeeMsat);
+  const feePpm = asNumber(raw.feePpm);
+  if (baseFeeMsat === void 0 && feePpm === void 0) return void 0;
+  return { baseFeeMsat: baseFeeMsat ?? 0, feePpm: feePpm ?? 0 };
+};
+var asBoolean = (value) => typeof value === "boolean" ? value : void 0;
+var asPubkeyList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : void 0;
 var fetchMintAddress = async (url, options = {}) => {
   const body = await lnurlFetch(url, resolveOptions(options));
   if (body?.tag !== "withdrawRequest" || typeof body.callback !== "string" || typeof body.payLink !== "string" || typeof body.maxWithdrawable !== "number") {
     throw new ProtocolError("Not a mint address response (unexpected shape).");
   }
-  const { mintPubkey, nodeCapacity, ...rest } = body;
   return {
-    ...rest,
-    nodePubkey: mintPubkey,
-    // Renamed fields have to be mapped, not spread: the spread carries the
-    // wire name through, so the typed one would read undefined forever.
-    nodeCapacityMsat: typeof nodeCapacity === "number" ? nodeCapacity : void 0
+    tag: "withdrawRequest",
+    callback: body.callback,
+    minWithdrawable: asNumber(body.minWithdrawable) ?? 0,
+    maxWithdrawable: body.maxWithdrawable,
+    defaultDescription: asString(body.defaultDescription),
+    mintPubkey: asString(body.mintPubkey),
+    // the same value under both names for one release, so nothing breaks
+    nodePubkey: asString(body.mintPubkey),
+    payLink: body.payLink,
+    nodeAlias: asString(body.nodeAlias),
+    nodeUri: asString(body.nodeUri),
+    nodeColor: asString(body.nodeColor),
+    // `nodeCapacity` is the wire name the reference mint, the mock and
+    // every implementation that copied them use. One live mint emits
+    // `nodeCapacityMsat` instead, so both are accepted and the bare name
+    // wins where a SERVICE sends both.
+    nodeCapacityMsat: asNumber(body.nodeCapacity) ?? asNumber(body.nodeCapacityMsat),
+    nodeNumChannels: asNumber(body.nodeNumChannels),
+    nodeNumPeers: asNumber(body.nodeNumPeers),
+    name: asString(body.name),
+    description: asString(body.description),
+    contact: asContact(body.contact),
+    tosUrl: asString(body.tosUrl),
+    motd: asString(body.motd),
+    fees: asFees(body.fees),
+    version: asString(body.version),
+    previousPubkeys: asPubkeyList(body.previousPubkeys),
+    mintToHash: asBoolean(body.mintToHash)
   };
 };
 var callbackRequest = async (callback, params, options) => {
@@ -592,6 +798,12 @@ var mergeNotesWithHash = async (callback, k1s, h, options = {}) => {
   );
   return { signature: body.sig };
 };
+var keepingOutputs = (err, newSecrets) => {
+  if (err instanceof NoteSpentError || err instanceof NoteUnknownError) {
+    err.newSecrets = newSecrets;
+  }
+  return err;
+};
 var rotateNote = async (callback, k1, options = {}) => {
   const opts = resolveOptions(options);
   const newK1 = opts.randomSecret();
@@ -602,7 +814,7 @@ var rotateNote = async (callback, k1, options = {}) => {
     if (err instanceof AmbiguousMintError) {
       throw new AmbiguousMutationError(err.message, [newK1]);
     }
-    throw err;
+    throw keepingOutputs(err, [newK1]);
   }
 };
 var splitNote = async (callback, k1s, amountMsat, options = {}) => {
@@ -628,7 +840,7 @@ var splitNote = async (callback, k1s, amountMsat, options = {}) => {
     if (err instanceof AmbiguousMintError) {
       throw new AmbiguousMutationError(err.message, [newK1, changeK1]);
     }
-    throw err;
+    throw keepingOutputs(err, [newK1, changeK1]);
   }
 };
 var mergeNotes = async (callback, k1s, options = {}) => {
@@ -641,7 +853,7 @@ var mergeNotes = async (callback, k1s, options = {}) => {
     if (err instanceof AmbiguousMintError) {
       throw new AmbiguousMutationError(err.message, [newK1]);
     }
-    throw err;
+    throw keepingOutputs(err, [newK1]);
   }
 };
 var settleNote = async (baseUrl, k1, expectedAmountMsat, signature, options = {}) => {
@@ -672,11 +884,23 @@ var fetchPayRequest = async (url, options = {}) => {
     throw new ProtocolError("Not a payRequest (unexpected response).");
   }
   const mintFee = typeof body.metadata === "string" ? parseMintFee(body.metadata) : null;
-  return { ...body, mintFee: mintFee ?? void 0 };
+  return {
+    ...body,
+    mintFee: mintFee ?? void 0,
+    mintToHash: asBoolean(body.mintToHash)
+  };
 };
 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)) {
+      throw new RequestRefusedError(
+        "An output hash must be 32 bytes of hex - no invoice was requested."
+      );
+    }
+    cbUrl.searchParams.set("h", options.h.trim().toLowerCase());
+  }
   const body = await lnurlFetch(cbUrl, resolveOptions(options));
   if (typeof body?.pr !== "string") {
     throw new ProtocolError("The service did not return an invoice.");
@@ -690,7 +914,8 @@ var requestInvoice = async (payCallback, amountMsat, options = {}) => {
   return {
     pr: body.pr,
     verify: typeof body.verify === "string" ? body.verify : void 0,
-    disposable: body.disposable !== false
+    disposable: body.disposable !== false,
+    mintToHash: body.mintToHash === true
   };
 };
 var fetchInvoiceVerification = async (verifyUrl, options = {}) => {
@@ -704,6 +929,156 @@ var fetchInvoiceVerification = async (verifyUrl, options = {}) => {
     pr: body.pr
   };
 };
+var claimMintedNote = async (withdrawLink, k1, options = {}) => {
+  const secret = k1.trim().toLowerCase();
+  if (!isPreimage(secret)) {
+    throw new RequestRefusedError(
+      "A note secret must be 32 bytes of hex - nothing was sent."
+    );
+  }
+  const blank = {
+    k1: secret,
+    amountMsat: null,
+    callback: null
+  };
+  try {
+    const info = await fetchNoteInfo(buildNoteUrl(withdrawLink, secret), options);
+    return {
+      state: "minted",
+      k1: secret,
+      amountMsat: info.maxWithdrawable,
+      callback: info.callback
+    };
+  } catch (err) {
+    if (err instanceof PendingNoteError) return { ...blank, state: "pending" };
+    if (err instanceof NoteSpentError) return { ...blank, state: "spent" };
+    if (err instanceof NoteUnknownError) return { ...blank, state: "unminted" };
+    throw err;
+  }
+};
+var LIGHTNING_SIGNED_MESSAGE_PREFIX = utf8ToBytes("Lightning Signed Message:");
+var noteSignatureMessage = (k1, amountMsat) => `LNURLcash:${amountMsat}:${hashK1(k1)}`;
+var noteSignatureDigest = (k1, amountMsat) => sha256(
+  sha256(
+    new Uint8Array([
+      ...LIGHTNING_SIGNED_MESSAGE_PREFIX,
+      ...utf8ToBytes(noteSignatureMessage(k1, amountMsat))
+    ])
+  )
+);
+var NO_MATCH = { valid: false, pubkey: null };
+var verifyNoteSignatureAgainst = (k1, 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;
+  }
+  if (wireSig.length !== 65) return NO_MATCH;
+  let digest;
+  try {
+    digest = noteSignatureDigest(k1, amountMsat);
+  } catch {
+    return NO_MATCH;
+  }
+  const recoveryIdFirst = new Uint8Array([
+    wireSig[64],
+    ...wireSig.subarray(0, 64)
+  ]);
+  for (const candidate of [recoveryIdFirst, wireSig]) {
+    try {
+      const recovered = bytesToHex(
+        secp256k1.recoverPublicKey(candidate, digest, { prehash: false })
+      );
+      if (targets.includes(recovered)) return { valid: true, pubkey: recovered };
+    } catch {
+    }
+  }
+  return NO_MATCH;
+};
+var verifyNoteSignature = (k1, amountMsat, signatureHex, mintPubkeys) => verifyNoteSignatureAgainst(k1, amountMsat, signatureHex, mintPubkeys).valid;
+
+// src/settle.ts
+var normaliseHost = (value) => serverOf(value.trim().replace(/^@/, "")).toLowerCase();
+var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = false }, options = {}) => {
+  const url = resolveNoteInput(noteUrl);
+  if (!url) {
+    throw new RequestRefusedError(
+      "That is not a bearer note this library will fetch."
+    );
+  }
+  const host = serverOf(url).toLowerCase();
+  const accepted = mints.map(normaliseHost);
+  if (!accepted.includes(host)) {
+    throw new ServiceRejectedError(
+      accepted.length === 0 ? "This server accepts no mints." : `Notes from ${host} are not accepted here.`
+    );
+  }
+  const k1 = requireNoteK1(url);
+  const info = await fetchNoteInfo(url, options);
+  if (requireSignature) {
+    const signature = noteSignature(url);
+    if (!signature) {
+      throw new ServiceRejectedError("This note carries no signature.");
+    }
+    if (!info.mintPubkey) {
+      throw new ServiceRejectedError(
+        "The mint published no signing key to check this note against."
+      );
+    }
+    if (!verifyNoteSignature(k1, info.maxWithdrawable, signature, info.mintPubkey)) {
+      throw new ServiceRejectedError("This note's signature does not verify.");
+    }
+  }
+  if (info.maxWithdrawable < minMsat) {
+    throw new InsufficientValueError(info.maxWithdrawable, minMsat);
+  }
+  const rotated = await rotateNote(info.callback, k1, options);
+  return {
+    note: {
+      k1: rotated.k1,
+      amountMsat: info.maxWithdrawable,
+      signature: rotated.signature,
+      callback: info.callback
+    },
+    newUrl: withNewK1(url, rotated.k1, info.maxWithdrawable, rotated.signature)
+  };
+};
+
+// src/restore.ts
+var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0 } = {}, options = {}) => {
+  if (!Number.isSafeInteger(gap) || gap < 1) {
+    throw new RangeError(`The gap limit must be a positive integer, not ${gap}.`);
+  }
+  const found = [];
+  let lastUsed = null;
+  let unknownRun = 0;
+  for (let index = start; unknownRun < gap; index++) {
+    const k1 = deriveNoteSecret(root, host, index);
+    try {
+      const info = await fetchNoteInfo(buildNoteUrl(baseUrl, k1), options);
+      found.push({ index, k1, amountMsat: info.maxWithdrawable, state: "live" });
+      lastUsed = index;
+      unknownRun = 0;
+    } catch (err) {
+      if (err instanceof PendingNoteError) {
+        found.push({ index, k1, amountMsat: null, state: "pending" });
+        lastUsed = index;
+        unknownRun = 0;
+      } else if (err instanceof NoteSpentError) {
+        lastUsed = index;
+        unknownRun = 0;
+      } else if (err instanceof NoteUnknownError) {
+        unknownRun++;
+      } else {
+        throw err;
+      }
+    }
+  }
+  return { found, next: lastUsed === null ? start : lastUsed + 1 };
+};
 
 // src/index.ts
 var createClient = (options = {}) => ({
@@ -719,8 +1094,14 @@ var createClient = (options = {}) => ({
   mergeNotesWithHash: (callback, k1s, h) => mergeNotesWithHash(callback, k1s, h, options),
   settleNote: (baseUrl, k1, expectedAmountMsat, signature) => settleNote(baseUrl, k1, expectedAmountMsat, signature, options),
   fetchPayRequest: (url) => fetchPayRequest(url, options),
-  requestInvoice: (payCallback, amountMsat) => requestInvoice(payCallback, amountMsat, options),
-  fetchInvoiceVerification: (verifyUrl) => fetchInvoiceVerification(verifyUrl, options)
+  // `h` names the note the invoice will mint - see requestInvoice. The
+  // bound transport options are merged under it, so a caller can still
+  // reach for a one-off override.
+  requestInvoice: (payCallback, amountMsat, h) => requestInvoice(payCallback, amountMsat, { ...options, h }),
+  fetchInvoiceVerification: (verifyUrl) => fetchInvoiceVerification(verifyUrl, options),
+  claimMintedNote: (withdrawLink, k1) => claimMintedNote(withdrawLink, k1, options),
+  restoreNotes: (baseUrl, root, host, restoreOptions = {}) => restoreNotes(baseUrl, root, host, restoreOptions, options),
+  settleNoteForValue: (noteUrl, terms) => settleNoteForValue(noteUrl, terms, options)
 });
 
-export { AmbiguousMintError, AmbiguousMutationError, LnurlcashError, NoteSpentError, NoteUnknownError, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, classifyNoteError, createClient, decodeBolt11AmountMsat, defaultRandomSecret, describeMintFee, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, verifyNoteSignatureAgainst, withNewK1, withinMintFeeBand, withoutK1 };