@arkade-os/lnurl-client 0.0.0-stage → 0.7.0

package/dist/chunk-H7W5RHP2.js

@@ -0,0 +1,58 @@
+// packages/client/src/errors.ts
+var LnurlError = class extends Error {
+  /** Human-readable failure reason, taken from the wire `reason`/`error` field. */
+  reason;
+  /** HTTP status when the failure came with one; absent for LUD-06 bodies answered at HTTP 200. */
+  httpStatus;
+  /** Machine-readable server code, when the management surface sent one. */
+  code;
+  /** True if and only if `httpStatus === 429`; every other failure is terminal. */
+  retryable;
+  /**
+   * Creates an `LnurlError`.
+   *
+   * @param reason - Human-readable failure reason, also used as the message.
+   * @param opts - Optional `httpStatus` and `code` captured from the response.
+   */
+  constructor(reason, opts) {
+    super(reason);
+    this.name = "LnurlError";
+    this.reason = reason;
+    this.httpStatus = opts?.httpStatus;
+    this.code = opts?.code;
+    this.retryable = opts?.httpStatus === 429;
+  }
+};
+var LnurlTransportError = class extends Error {
+  /**
+   * Creates an `LnurlTransportError`.
+   *
+   * @param message - Short description of which transport step failed.
+   * @param opts - Optional `cause` carrying the original thrown value.
+   */
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "LnurlTransportError";
+  }
+};
+var LnurlTimeoutError = class extends Error {
+  /** The most recent verify snapshot seen before the deadline, when one was seen. */
+  lastSnapshot;
+  /**
+   * Creates an `LnurlTimeoutError`.
+   *
+   * @param message - Short description including the timeout that elapsed.
+   * @param opts - Optional `lastSnapshot` with the latest verify state.
+   */
+  constructor(message, opts) {
+    super(message);
+    this.name = "LnurlTimeoutError";
+    this.lastSnapshot = opts?.lastSnapshot;
+  }
+};
+
+export {
+  LnurlError,
+  LnurlTransportError,
+  LnurlTimeoutError
+};

package/dist/hd.d.ts

@@ -0,0 +1,16 @@
+import * as _arkade_os_sdk from '@arkade-os/sdk';
+import { IContractManager } from '@arkade-os/sdk';
+import { b as HdReceiveConfig, c as HdReceiveAllocation } from './addresses-CPAzIbJ_.js';
+export { H as HdReceiveAllocationPage } from './addresses-CPAzIbJ_.js';
+
+interface HdReceiveBranch {
+    hd: HdReceiveConfig;
+    signingDescriptor(index: number): string;
+}
+declare function createHdReceiveBranch(params: Omit<HdReceiveConfig, "version" | "descriptor"> & {
+    accountDescriptor: string;
+    branchPath: string;
+}): HdReceiveBranch;
+declare function restoreHdReceiveAllocation(manager: Pick<IContractManager, "createContract">, allocation: HdReceiveAllocation, branch: HdReceiveBranch): Promise<_arkade_os_sdk.Contract>;
+
+export { HdReceiveAllocation, type HdReceiveBranch, HdReceiveConfig, createHdReceiveBranch, restoreHdReceiveAllocation };

package/dist/hd.js

@@ -0,0 +1,389 @@
+import {
+  LnurlError
+} from "./chunk-H7W5RHP2.js";
+
+// node_modules/.pnpm/@scure+bip32@2.4.0/node_modules/@scure/bip32/index.js
+import { secp256k1 as secp } from "@noble/curves/secp256k1.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { ripemd160 } from "@noble/hashes/legacy.js";
+import { sha256, sha512 } from "@noble/hashes/sha2.js";
+import { abytes, concatBytes, createView } from "@noble/hashes/utils.js";
+import { createBase58check } from "@scure/base";
+var Point = /* @__PURE__ */ (() => secp.Point)();
+var Fn = /* @__PURE__ */ (() => Point.Fn)();
+var base58check = /* @__PURE__ */ createBase58check(sha256);
+var MASTER_SECRET = /* @__PURE__ */ (() => {
+  return Uint8Array.from("Bitcoin seed".split(""), (char) => char.charCodeAt(0));
+})();
+var BITCOIN_VERSIONS = { private: 76066276, public: 76067358 };
+var HARDENED_OFFSET = 2147483648;
+var MAX_DEPTH = 255;
+var hash160 = (data) => ripemd160(sha256(data));
+var fromU32 = (data) => createView(data).getUint32(0, false);
+var toU32 = (n, title = "number") => {
+  if (typeof n !== "number")
+    throw new TypeError(`"${title}" expected number, got type=${typeof n}`);
+  if (!Number.isSafeInteger(n) || n < 0 || n > 2 ** 32 - 1)
+    throw new RangeError(`"${title}" expected integer in range 0..2**32-1, got ${n}`);
+  const buf = new Uint8Array(4);
+  createView(buf).setUint32(0, n, false);
+  return buf;
+};
+var validateVersions = (versions, title = "versions") => {
+  if (!(typeof versions === "object" && versions !== null))
+    throw new Error("versions must be an object");
+  toU32(versions.private, `${title}.private`);
+  toU32(versions.public, `${title}.public`);
+  return versions;
+};
+var HDKey = class _HDKey {
+  get fingerprint() {
+    if (!this._pubHash) {
+      throw new Error("No publicKey set!");
+    }
+    return fromU32(this._pubHash);
+  }
+  get identifier() {
+    return this._pubHash ? Uint8Array.from(this._pubHash) : void 0;
+  }
+  get pubKeyHash() {
+    return this._pubHash ? Uint8Array.from(this._pubHash) : void 0;
+  }
+  get privateKey() {
+    return this._privateKey ? Uint8Array.from(this._privateKey) : null;
+  }
+  get publicKey() {
+    return this._publicKey ? Uint8Array.from(this._publicKey) : null;
+  }
+  get chainCode() {
+    return this._chainCode ? Uint8Array.from(this._chainCode) : null;
+  }
+  get privateExtendedKey() {
+    const priv = this._privateKey;
+    if (!priv) {
+      throw new Error("No private key");
+    }
+    return base58check.encode(this.serialize(this.versions.private, concatBytes(Uint8Array.of(0), priv)));
+  }
+  get publicExtendedKey() {
+    if (!this._publicKey) {
+      throw new Error("No public key");
+    }
+    return base58check.encode(this.serialize(this.versions.public, this._publicKey));
+  }
+  static fromMasterSeed(seed, versions = BITCOIN_VERSIONS) {
+    abytes(seed);
+    versions = validateVersions(versions);
+    if (8 * seed.length < 128 || 8 * seed.length > 512) {
+      throw new RangeError("HDKey: seed length must be between 128 and 512 bits; 256 bits is advised, got " + seed.length);
+    }
+    const I = hmac(sha512, MASTER_SECRET, seed);
+    const privateKey = I.slice(0, 32);
+    const chainCode = I.slice(32);
+    return new _HDKey({ versions, chainCode, privateKey });
+  }
+  static fromExtendedKey(base58key, versions = BITCOIN_VERSIONS) {
+    versions = validateVersions(versions);
+    const keyBuffer = base58check.decode(base58key);
+    if (keyBuffer.length !== 78) {
+      throw new Error(`HDKey: invalid extended key length: expected 78 bytes, got ${keyBuffer.length}`);
+    }
+    const keyView = createView(keyBuffer);
+    const version = keyView.getUint32(0, false);
+    const opt = {
+      versions,
+      depth: keyBuffer[4],
+      parentFingerprint: keyView.getUint32(5, false),
+      index: keyView.getUint32(9, false),
+      chainCode: keyBuffer.slice(13, 45)
+    };
+    const key = keyBuffer.slice(45);
+    const isPriv = key[0] === 0;
+    if (version !== versions[isPriv ? "private" : "public"]) {
+      throw new Error("Version mismatch");
+    }
+    if (isPriv) {
+      return new _HDKey({ ...opt, privateKey: key.slice(1) });
+    } else {
+      return new _HDKey({ ...opt, publicKey: key });
+    }
+  }
+  static fromJSON(json) {
+    return _HDKey.fromExtendedKey("xpriv" in json ? json.xpriv : json.xpub);
+  }
+  versions;
+  depth = 0;
+  index = 0;
+  parentFingerprint = 0;
+  _chainCode = null;
+  _privateKey;
+  _publicKey;
+  _pubHash;
+  constructor(opt) {
+    if (!opt || typeof opt !== "object") {
+      throw new Error("HDKey.constructor must not be called directly");
+    }
+    const depth = opt.depth ?? 0;
+    const index = opt.index ?? 0;
+    const parentFingerprint = opt.parentFingerprint ?? 0;
+    if (!Number.isSafeInteger(depth) || depth < 0 || depth > MAX_DEPTH) {
+      throw new RangeError("HDKey: depth must be an integer in range 0..255");
+    }
+    toU32(index, "index");
+    toU32(parentFingerprint, "parentFingerprint");
+    if (depth === 0 && (index !== 0 || parentFingerprint !== 0)) {
+      throw new Error("HDKey: zero depth with non-zero index/parent fingerprint");
+    }
+    this.versions = opt.versions ? validateVersions(opt.versions) : BITCOIN_VERSIONS;
+    this.depth = depth;
+    if (opt.chainCode)
+      abytes(opt.chainCode, 32);
+    this._chainCode = opt.chainCode ? Uint8Array.from(opt.chainCode) : null;
+    this.index = index;
+    this.parentFingerprint = parentFingerprint;
+    if (opt.publicKey && opt.privateKey) {
+      throw new Error("HDKey: publicKey and privateKey at same time.");
+    }
+    if (opt.privateKey) {
+      if (!secp.utils.isValidSecretKey(opt.privateKey))
+        throw new Error("Invalid private key");
+      this._privateKey = Uint8Array.from(opt.privateKey);
+      this._publicKey = secp.getPublicKey(this._privateKey, true);
+    } else if (opt.publicKey) {
+      this._publicKey = Point.fromBytes(opt.publicKey).toBytes(true);
+    } else {
+      throw new Error("HDKey: no public or private key provided");
+    }
+    this._pubHash = hash160(this._publicKey);
+  }
+  derive(path) {
+    if (!/^[mM]'?/.test(path)) {
+      throw new Error('Path must start with "m" or "M"');
+    }
+    if (/^[mM]'?$/.test(path)) {
+      return this;
+    }
+    const parts = path.replace(/^[mM]'?\//, "").split("/");
+    if (parts.length > MAX_DEPTH - this.depth) {
+      throw new Error("HDKey: path exceeds the serializable depth 255");
+    }
+    let child = this;
+    for (const c of parts) {
+      const m = /^(\d+)('?)$/.exec(c);
+      const m1 = m && m[1];
+      if (!m || m.length !== 3 || typeof m1 !== "string")
+        throw new Error("invalid child index: " + c);
+      let idx = +m1;
+      if (!Number.isSafeInteger(idx) || idx >= HARDENED_OFFSET) {
+        throw new Error("Invalid index");
+      }
+      if (m[2] === "'") {
+        idx += HARDENED_OFFSET;
+      }
+      child = child.deriveChild(idx);
+    }
+    return child;
+  }
+  deriveChild(index) {
+    return this._deriveChild(index);
+  }
+  /** Test-only implementation seam. Production callers must use deriveChild(). */
+  _deriveChild(index, _I) {
+    if (!this._publicKey || !this._chainCode) {
+      throw new Error("No publicKey or chainCode set");
+    }
+    let data = toU32(index, "index");
+    if (index >= HARDENED_OFFSET) {
+      const priv = this._privateKey;
+      if (!priv) {
+        throw new Error("Could not derive hardened child key");
+      }
+      data = concatBytes(Uint8Array.of(0), priv, data);
+    } else {
+      data = concatBytes(this._publicKey, data);
+    }
+    const out = _I || hmac(sha512, this._chainCode, data);
+    abytes(out, 64);
+    const childTweak = out.slice(0, 32);
+    const chainCode = out.slice(32);
+    const opt = {
+      versions: this.versions,
+      chainCode,
+      depth: this.depth + 1,
+      parentFingerprint: this.fingerprint,
+      index
+    };
+    if (opt.depth > MAX_DEPTH) {
+      throw new Error("HDKey: depth exceeds the serializable value 255");
+    }
+    const retry = () => {
+      const maxIndex = this._privateKey ? 2 ** 32 - 1 : HARDENED_OFFSET - 1;
+      if (index >= maxIndex) {
+        throw new Error(`HDKey: cannot retry child derivation at index ${index}`);
+      }
+      return this.deriveChild(index + 1);
+    };
+    const ctweak = Fn.fromBytes(childTweak, true);
+    if (!Fn.isValid(ctweak))
+      return retry();
+    if (this._privateKey) {
+      const added = Fn.create(Fn.fromBytes(this._privateKey) + ctweak);
+      if (!Fn.isValidNot0(added))
+        return retry();
+      opt.privateKey = Fn.toBytes(added);
+    } else {
+      const point = Point.fromBytes(this._publicKey);
+      const added = ctweak === 0n ? point : point.add(Point.BASE.multiply(ctweak));
+      if (added.equals(Point.ZERO))
+        return retry();
+      opt.publicKey = added.toBytes(true);
+    }
+    return new _HDKey(opt);
+  }
+  sign(hash) {
+    if (!this._privateKey) {
+      throw new Error("No privateKey set!");
+    }
+    abytes(hash, 32);
+    return secp.sign(hash, this._privateKey, { prehash: false });
+  }
+  verify(hash, signature) {
+    abytes(hash, 32);
+    abytes(signature, 64);
+    if (!this._publicKey) {
+      throw new Error("No publicKey set!");
+    }
+    return secp.verify(signature, hash, this._publicKey, { prehash: false });
+  }
+  wipePrivateData() {
+    if (this._privateKey) {
+      this._privateKey.fill(0);
+      this._privateKey = void 0;
+    }
+    return this;
+  }
+  // TODO(v3): Make automatic JSON serialization public-only so JSON.stringify cannot expose xpriv.
+  toJSON() {
+    return this.toPrivateJSON();
+  }
+  /**
+   * Explicitly exports private key material. Treat the returned value as a secret.
+   */
+  toPrivateJSON() {
+    return {
+      xpriv: this.privateExtendedKey,
+      xpub: this.publicExtendedKey
+    };
+  }
+  serialize(version, key) {
+    if (!this._chainCode) {
+      throw new Error("No chainCode set");
+    }
+    abytes(key, 33);
+    return concatBytes(toU32(version, "version"), new Uint8Array([this.depth]), toU32(this.parentFingerprint, "parentFingerprint"), toU32(this.index, "index"), this._chainCode, key);
+  }
+};
+
+// packages/client/src/hd.ts
+import { hex } from "@scure/base";
+import {
+  DefaultVtxo,
+  deriveDescriptorLeafCompressedPubKey,
+  parseHDDescriptor,
+  timelockToSequence
+} from "@arkade-os/sdk";
+var TESTNET_BIP32 = { public: 70617039, private: 70615956 };
+var INDEX_LIMIT = 2147483648;
+function indexOf(index) {
+  if (!Number.isSafeInteger(index) || index < 0 || index >= INDEX_LIMIT) {
+    throw new LnurlError("HD index must be a non-hardened integer");
+  }
+  return index;
+}
+function createHdReceiveBranch(params) {
+  const parsed = parseHDDescriptor(params.accountDescriptor);
+  if (!parsed || !params.accountDescriptor.endsWith("/*)") || !/^(xpub|tpub)/.test(parsed.xpub)) {
+    throw new LnurlError("accountDescriptor must be a public HD template");
+  }
+  if (!/^(0|[1-9]\d*)(\/(0|[1-9]\d*))*$/.test(params.branchPath)) {
+    throw new LnurlError("branchPath must name a dedicated non-hardened branch below the account xpub");
+  }
+  const path = params.branchPath.split("/").map(Number);
+  path.forEach(indexOf);
+  if (path[0] === Number(parsed.derivationPath.split("/")[0]) || path[0] === 1) {
+    throw new LnurlError("HD receive must not expose the ordinary receive or change branch");
+  }
+  const testnet = parsed.xpub.startsWith("tpub");
+  if (params.hrp === "tark" !== testnet) throw new LnurlError("HD descriptor network does not match hrp");
+  const node = HDKey.fromExtendedKey(parsed.xpub, testnet ? TESTNET_BIP32 : void 0);
+  if (node.depth !== parsed.basePath.split("/").length) throw new LnurlError("HD key origin depth does not match xpub");
+  const branch = node.derive(`m/${params.branchPath}`);
+  if (branch.depth < 4) throw new LnurlError("HD receive branch must be below account depth");
+  const basePath = parsed.basePath.split("/").map((part) => `${Number(part.replace(/['hH]$/, ""))}${/['hH]$/.test(part) ? "'" : ""}`).join("/");
+  const fingerprint = parsed.fingerprint.toLowerCase();
+  const origin = `${basePath}/${params.branchPath}`;
+  const descriptor = `tr([${fingerprint}/${origin}]${branch.publicExtendedKey}/*)`;
+  const hd = {
+    version: 1,
+    descriptor,
+    serverPubKey: params.serverPubKey.toLowerCase(),
+    hrp: params.hrp,
+    exitDelay: { ...params.exitDelay }
+  };
+  const result = {
+    hd,
+    // Keep the account xpub local: SDK signing ownership compares the embedded xpub.
+    signingDescriptor: (index) => `tr([${fingerprint}/${basePath}]${parsed.xpub}/${params.branchPath}/${indexOf(index)})`
+  };
+  hdReceiveContract(result, 0);
+  return result;
+}
+function hdReceiveContract(branch, index) {
+  const hd = branch.hd;
+  if (hd.version !== 1 || !/^[0-9a-f]{64}$/i.test(hd.serverPubKey) || !["ark", "tark"].includes(hd.hrp) || !["seconds", "blocks"].includes(hd.exitDelay.type) || !Number.isSafeInteger(hd.exitDelay.value) || hd.exitDelay.value <= 0) {
+    throw new LnurlError("Invalid HD receive script configuration");
+  }
+  const units = hd.exitDelay.type === "seconds" ? hd.exitDelay.value / 512 : hd.exitDelay.value;
+  if (!Number.isInteger(units) || units > 65535) throw new LnurlError("HD receive exit delay is outside BIP68 bounds");
+  const descriptor = hd.descriptor.replace("*", String(indexOf(index)));
+  const claimPublicKey = deriveDescriptorLeafCompressedPubKey(descriptor);
+  const localPublicKey = deriveDescriptorLeafCompressedPubKey(branch.signingDescriptor(index));
+  if (hex.encode(claimPublicKey) !== hex.encode(localPublicKey)) throw new LnurlError("HD signing branch does not match receive branch");
+  const script = new DefaultVtxo.Script({
+    pubKey: claimPublicKey.slice(1),
+    serverPubKey: hex.decode(hd.serverPubKey),
+    csvTimelock: { type: hd.exitDelay.type, value: BigInt(hd.exitDelay.value) }
+  });
+  return { descriptor, claimPublicKey, script, address: script.address(hd.hrp, hex.decode(hd.serverPubKey)).encode() };
+}
+async function restoreHdReceiveAllocation(manager, allocation, branch) {
+  const hd = branch.hd;
+  if (allocation.hd.version !== hd.version || allocation.hd.descriptor !== hd.descriptor || allocation.hd.serverPubKey !== hd.serverPubKey || allocation.hd.hrp !== hd.hrp || allocation.hd.exitDelay.type !== hd.exitDelay.type || allocation.hd.exitDelay.value !== hd.exitDelay.value) {
+    throw new LnurlError("Allocation belongs to a different HD receive configuration");
+  }
+  const derived = hdReceiveContract(branch, allocation.index);
+  if (allocation.descriptor !== derived.descriptor || allocation.arkadeAddress !== derived.address || allocation.claimPublicKey !== hex.encode(derived.claimPublicKey)) {
+    throw new LnurlError("HD allocation does not match its derived receive script");
+  }
+  return manager.createContract({
+    type: "default",
+    watch: "awaiting-funds",
+    script: hex.encode(derived.script.pkScript),
+    address: derived.address,
+    params: {
+      pubKey: hex.encode(derived.claimPublicKey.slice(1)),
+      serverPubKey: hd.serverPubKey,
+      csvTimelock: timelockToSequence(derived.script.options.csvTimelock).toString()
+    },
+    metadata: { signingDescriptor: branch.signingDescriptor(allocation.index) }
+  });
+}
+export {
+  createHdReceiveBranch,
+  restoreHdReceiveAllocation
+};
+/*! Bundled license information:
+
+@scure/bip32/index.js:
+  (*! scure-bip32 - MIT License (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com) *)
+*/