@unlink-xyz/sdk 0.0.2-canary.0

package/dist/index.js

@@ -0,0 +1,1465 @@
+// src/crypto/poseidon.ts
+import {
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  poseidon5,
+  poseidon6,
+  poseidon7,
+  poseidon8,
+  poseidon9,
+  poseidon10,
+  poseidon11,
+  poseidon12,
+  poseidon13,
+  poseidon14,
+  poseidon15,
+  poseidon16
+} from "poseidon-lite";
+var POSEIDON_FNS = [
+  void 0,
+  poseidon1,
+  poseidon2,
+  poseidon3,
+  poseidon4,
+  poseidon5,
+  poseidon6,
+  poseidon7,
+  poseidon8,
+  poseidon9,
+  poseidon10,
+  poseidon11,
+  poseidon12,
+  poseidon13,
+  poseidon14,
+  poseidon15,
+  poseidon16
+];
+function poseidon(inputs) {
+  const len = inputs.length;
+  if (len < 1 || len > 16) {
+    throw new Error(`Poseidon supports 1-16 inputs, got ${len}`);
+  }
+  return POSEIDON_FNS[len](inputs);
+}
+
+// src/crypto/eddsa.ts
+async function loadEdDSA() {
+  const { createRequire } = await import("module");
+  const require2 = createRequire(import.meta.url);
+  return require2("@zk-kit/eddsa-poseidon/blake-2b");
+}
+async function eddsaPublicKey(privateKey) {
+  const { derivePublicKey } = await loadEdDSA();
+  const pk = derivePublicKey(privateKey.toString());
+  return [BigInt(pk[0]), BigInt(pk[1])];
+}
+async function eddsaSign(privateKey, message) {
+  const { signMessage } = await loadEdDSA();
+  const sig = signMessage(privateKey.toString(), message);
+  return {
+    R8: [BigInt(sig.R8[0]), BigInt(sig.R8[1])],
+    S: BigInt(sig.S)
+  };
+}
+async function eddsaVerify(message, signature, publicKey) {
+  const { verifySignature } = await loadEdDSA();
+  return verifySignature(message, signature, publicKey);
+}
+
+// src/crypto/ed25519.ts
+import { ed25519 } from "@noble/curves/ed25519.js";
+function viewingPublicKey(privateKey) {
+  return ed25519.getPublicKey(privateKey);
+}
+function viewingPublicKeyFromHex(hexPrivateKey) {
+  const clean = hexPrivateKey.startsWith("0x") ? hexPrivateKey.slice(2) : hexPrivateKey;
+  if (clean.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(clean)) {
+    throw new Error(`invalid hex private key: must be 64 hex chars`);
+  }
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return viewingPublicKey(bytes);
+}
+
+// src/crypto/field.ts
+var P = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+function mod(n) {
+  return (n % P + P) % P;
+}
+function fromDecimal(s) {
+  return mod(BigInt(s));
+}
+function toBytesBE(n) {
+  const hex = n.toString(16).padStart(64, "0");
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function fromBytesBE(bytes) {
+  const n = bytesToBigInt(bytes);
+  if (n >= P) {
+    throw new Error("value >= BN254 field order");
+  }
+  return n;
+}
+function fromHex(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const n = BigInt("0x" + clean);
+  if (n >= P) {
+    throw new Error("value >= BN254 field order");
+  }
+  return n;
+}
+function toDecimal(n) {
+  return n.toString();
+}
+function bytesToBigInt(bytes) {
+  let n = 0n;
+  for (const b of bytes) {
+    n = n << 8n | BigInt(b);
+  }
+  return n;
+}
+
+// src/keys/derive.ts
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+
+// src/keys/address.ts
+import { bech32m } from "@scure/base";
+var HRP = "unlink";
+var VERSION = 0;
+function encodeAddress(mpk, viewingPubKey) {
+  if (viewingPubKey.length !== 32) {
+    throw new Error(
+      `viewingPubKey must be 32 bytes, got ${viewingPubKey.length}`
+    );
+  }
+  const payload = new Uint8Array(65);
+  payload[0] = VERSION;
+  payload.set(toBytesBE(mpk), 1);
+  payload.set(viewingPubKey, 33);
+  const words = bech32m.toWords(payload);
+  return bech32m.encode(HRP, words, 1023);
+}
+function decodeAddress(address) {
+  const { prefix, words } = bech32m.decode(
+    address,
+    1023
+  );
+  if (prefix !== HRP)
+    throw new Error(`Invalid HRP: expected "${HRP}", got "${prefix}"`);
+  const payload = bech32m.fromWords(words);
+  if (payload.length !== 65)
+    throw new Error(
+      `Invalid payload length: expected 65, got ${payload.length}`
+    );
+  if (payload[0] !== VERSION) {
+    throw new Error(
+      `unsupported address version: expected ${VERSION}, got ${payload[0]}`
+    );
+  }
+  const mpkBytes = new Uint8Array(payload.slice(1, 33));
+  let mpk = 0n;
+  for (const b of mpkBytes) {
+    mpk = mpk << 8n | BigInt(b);
+  }
+  if (mpk >= P) {
+    throw new Error(
+      "non-canonical masterPublicKey: value >= BN254 field order"
+    );
+  }
+  return {
+    version: payload[0],
+    masterPublicKey: mpk,
+    viewingPublicKey: new Uint8Array(payload.slice(33, 65))
+  };
+}
+
+// src/keys/derive.ts
+var SPENDING_PATH = (index) => [44, 1984, 0, 0, index];
+var VIEWING_PATH = (index) => [420, 1984, 0, 0, index];
+function slip10Master(seed) {
+  const I = hmac(sha512, new TextEncoder().encode("ed25519 seed"), seed);
+  return { key: I.slice(0, 32), chainCode: I.slice(32) };
+}
+function slip10DeriveHardened(parentKey, parentChainCode, index) {
+  const data = new Uint8Array(37);
+  data[0] = 0;
+  data.set(parentKey, 1);
+  new DataView(data.buffer, data.byteOffset, data.byteLength).setUint32(
+    33,
+    (index | 2147483648) >>> 0
+  );
+  const I = hmac(sha512, parentChainCode, data);
+  return { key: I.slice(0, 32), chainCode: I.slice(32) };
+}
+function slip10DerivePath(seed, path) {
+  let { key, chainCode } = slip10Master(seed);
+  for (const index of path) {
+    ({ key, chainCode } = slip10DeriveHardened(key, chainCode, index));
+  }
+  return key;
+}
+async function buildAccountKeys(spendingPrivateKey, viewingPrivateKey) {
+  const spendingPublicKey = await eddsaPublicKey(spendingPrivateKey);
+  const viewingPubKey = viewingPublicKey(viewingPrivateKey);
+  const vpkScalar = mod(bytesToBigInt(viewingPrivateKey));
+  const nullifyingKey = poseidon([vpkScalar]);
+  const masterPublicKey = poseidon([
+    spendingPublicKey[0],
+    spendingPublicKey[1],
+    nullifyingKey
+  ]);
+  const address = encodeAddress(masterPublicKey, viewingPubKey);
+  return {
+    spendingPrivateKey,
+    spendingPublicKey,
+    viewingPrivateKey,
+    viewingPublicKey: viewingPubKey,
+    nullifyingKey,
+    masterPublicKey,
+    address
+  };
+}
+async function deriveAccountKeys(seed, index = 0) {
+  if (!Number.isInteger(index) || index < 0 || index >= 2 ** 31) {
+    throw new Error(
+      `index must be a non-negative integer < 2^31, got ${index}`
+    );
+  }
+  const spendingRaw = slip10DerivePath(seed, SPENDING_PATH(index));
+  const spendingPrivateKey = mod(bytesToBigInt(spendingRaw));
+  const viewingPrivateKey = slip10DerivePath(seed, VIEWING_PATH(index));
+  return buildAccountKeys(spendingPrivateKey, viewingPrivateKey);
+}
+
+// src/account-provider.ts
+import { mnemonicToSeedSync } from "@scure/bip39";
+
+// src/keys/account-export.ts
+var HEX_64_RE = /^0x[0-9a-fA-F]{64}$/;
+function bytesToHex(bytes) {
+  let hex = "0x";
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function hexToBytes(hex) {
+  const clean = hex.slice(2);
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function exportAccountKeys(keys) {
+  if (typeof keys !== "object" || keys === null) {
+    throw new Error("keys must be a non-null AccountKeys object");
+  }
+  if (typeof keys.spendingPrivateKey !== "bigint") {
+    throw new Error("keys.spendingPrivateKey must be a bigint");
+  }
+  if (keys.spendingPrivateKey < 0n || keys.spendingPrivateKey >= P) {
+    throw new Error(
+      "keys.spendingPrivateKey out of range [0, BN254 field order)"
+    );
+  }
+  if (!(keys.viewingPrivateKey instanceof Uint8Array) || keys.viewingPrivateKey.length !== 32) {
+    throw new Error("keys.viewingPrivateKey must be a 32-byte Uint8Array");
+  }
+  return {
+    version: 1,
+    spendingPrivateKey: "0x" + keys.spendingPrivateKey.toString(16).padStart(64, "0"),
+    viewingPrivateKey: bytesToHex(keys.viewingPrivateKey)
+  };
+}
+async function importAccountKeys(input) {
+  if (typeof input !== "object" || input === null) {
+    throw new Error("account export payload must be a non-null object");
+  }
+  const obj = input;
+  if (obj.version !== 1) {
+    throw new Error(
+      `unsupported account export version: expected 1 (number), got ${JSON.stringify(obj.version)}`
+    );
+  }
+  if (typeof obj.spendingPrivateKey !== "string" || !HEX_64_RE.test(obj.spendingPrivateKey)) {
+    throw new Error(
+      "spendingPrivateKey must be a 0x-prefixed 64-character hex string"
+    );
+  }
+  if (typeof obj.viewingPrivateKey !== "string" || !HEX_64_RE.test(obj.viewingPrivateKey)) {
+    throw new Error(
+      "viewingPrivateKey must be a 0x-prefixed 64-character hex string"
+    );
+  }
+  const spendingPrivateKey = fromHex(obj.spendingPrivateKey);
+  const viewingPrivateKey = hexToBytes(obj.viewingPrivateKey);
+  return buildAccountKeys(spendingPrivateKey, viewingPrivateKey);
+}
+
+// src/account-provider.ts
+var DEFAULT_ACCOUNT_INDEX = 0;
+var StaticAccountProvider = class {
+  constructor(keys) {
+    this.keys = keys;
+  }
+  async getAccountKeys() {
+    return this.keys;
+  }
+};
+var DerivedAccountProvider = class {
+  constructor(options) {
+    this.options = options;
+  }
+  keysPromise;
+  async getAccountKeys() {
+    if (!this.keysPromise) {
+      this.keysPromise = deriveAccountKeys(
+        this.options.seed,
+        this.options.accountIndex ?? DEFAULT_ACCOUNT_INDEX
+      ).catch((error) => {
+        this.keysPromise = void 0;
+        throw error;
+      });
+    }
+    return this.keysPromise;
+  }
+};
+var unlinkAccount = {
+  fromKeys(keys) {
+    return new StaticAccountProvider(keys);
+  },
+  fromSeed(options) {
+    return new DerivedAccountProvider(options);
+  },
+  fromMnemonic(options) {
+    return unlinkAccount.fromSeed({
+      seed: mnemonicToSeedSync(options.mnemonic),
+      accountIndex: options.accountIndex
+    });
+  },
+  export(keys) {
+    return exportAccountKeys(keys);
+  },
+  async import(input) {
+    return importAccountKeys(input);
+  }
+};
+
+// src/client.ts
+import createClient from "openapi-fetch";
+var createUnlinkClient = (baseUrl, apiKey, options) => {
+  const opts = typeof options === "function" ? { customFetch: options } : options ?? {};
+  const maxRetries = opts.maxRetries ?? 3;
+  const baseFetch = opts.customFetch ?? globalThis.fetch;
+  const fetchFn = maxRetries > 0 ? createRetryFetch(baseFetch, maxRetries) : baseFetch;
+  return createClient({
+    baseUrl,
+    headers: { Authorization: `Bearer ${apiKey}` },
+    fetch: fetchFn
+  });
+};
+function createRetryFetch(baseFetch, maxRetries) {
+  return async (input, init) => {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const response = await baseFetch(input, init);
+      if (response.status !== 429 || attempt === maxRetries) {
+        return response;
+      }
+      await response.body?.cancel();
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSecs = retryAfterHeader ? parseInt(retryAfterHeader, 10) || 1 : 1;
+      const baseDelay = attempt === 0 ? retryAfterSecs * 1e3 : Math.min(1e3 * 2 ** attempt, 3e4);
+      const delayMs = baseDelay * (1 + Math.random() * 0.1);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    throw new Error("unreachable: retry loop exited without returning");
+  };
+}
+
+// src/errors.ts
+var UnlinkApiError = class _UnlinkApiError extends Error {
+  operation;
+  code;
+  detail;
+  constructor(operation, error) {
+    const errObj = typeof error === "object" && error !== null && "error" in error && typeof error.error === "object" && error.error !== null ? error.error : null;
+    const code = typeof errObj?.code === "string" ? errObj.code : "UNKNOWN";
+    const detail = typeof errObj?.message === "string" ? errObj.message : "Unknown error";
+    super(`${operation} failed: ${detail}`);
+    this.name = "UnlinkApiError";
+    this.operation = operation;
+    this.code = code;
+    this.detail = detail;
+    Object.setPrototypeOf(this, _UnlinkApiError.prototype);
+  }
+};
+var UnlinkCapabilityError = class _UnlinkCapabilityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnlinkCapabilityError";
+    Object.setPrototypeOf(this, _UnlinkCapabilityError.prototype);
+  }
+};
+
+// src/approval.ts
+var APPROVE_SELECTOR = "095ea7b3";
+var MAX_UINT256 = (1n << 256n) - 1n;
+async function getApprovalState(params) {
+  const allowanceValue = await params.evm.getErc20Allowance({
+    token: params.token,
+    owner: params.owner,
+    spender: params.spender
+  });
+  const allowance = normalizeUint256(allowanceValue);
+  const amount = normalizeUint256(params.amount);
+  return {
+    token: params.token,
+    owner: params.owner,
+    spender: params.spender,
+    amount,
+    allowance,
+    isApproved: BigInt(allowance) >= BigInt(amount)
+  };
+}
+function buildApprovalTx(params) {
+  return {
+    to: params.token,
+    data: `0x${APPROVE_SELECTOR}${encodeAddressWord(params.spender)}${encodeUint256Word(MAX_UINT256)}`,
+    value: 0n
+  };
+}
+async function ensureErc20Approval(params) {
+  const state = await getApprovalState(params);
+  if (state.isApproved) {
+    return {
+      status: "already-approved",
+      state
+    };
+  }
+  if (!params.evm.sendTransaction) {
+    throw new UnlinkCapabilityError(
+      "ensureErc20Approval requires an UnlinkEvmProvider with sendTransaction()"
+    );
+  }
+  const transaction = buildApprovalTx(params);
+  const txHash = await params.evm.sendTransaction(transaction);
+  return {
+    status: "submitted",
+    state,
+    txHash,
+    transaction
+  };
+}
+function encodeAddressWord(address) {
+  return stripHexPrefix(address).padStart(64, "0");
+}
+function encodeUint256Word(value) {
+  return toBigInt(value).toString(16).padStart(64, "0");
+}
+function stripHexPrefix(value) {
+  return value.startsWith("0x") ? value.slice(2) : value;
+}
+function normalizeUint256(value) {
+  return toBigInt(value).toString();
+}
+function toBigInt(value) {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  return BigInt(value);
+}
+
+// src/permit2-nonce-manager.ts
+function findFirstUnsetBit(bitmap) {
+  for (let i = 0; i < 256; i++) {
+    if ((bitmap & 1n << BigInt(i)) === 0n) return i;
+  }
+  return null;
+}
+function setBit(bitmap, index) {
+  return bitmap | 1n << BigInt(index);
+}
+function clearBit(bitmap, index) {
+  return bitmap & ~(1n << BigInt(index));
+}
+function randomWordPosition() {
+  const bytes = crypto.getRandomValues(new Uint8Array(5));
+  let n = 0;
+  for (const b of bytes) n = n * 256 + b;
+  return n;
+}
+var Permit2NonceManager = class {
+  client;
+  cache = /* @__PURE__ */ new Map();
+  locks = /* @__PURE__ */ new Map();
+  startWordFn;
+  constructor(client, startWordFn) {
+    this.client = client;
+    this.startWordFn = startWordFn ?? randomWordPosition;
+  }
+  async getNextNonce(owner) {
+    const prev = this.locks.get(owner) ?? Promise.resolve();
+    let resolve;
+    const next = new Promise((r) => {
+      resolve = r;
+    });
+    this.locks.set(owner, next);
+    try {
+      await prev;
+      return await this.allocateNonce(owner);
+    } finally {
+      resolve();
+    }
+  }
+  commitNonce(_owner, _nonce) {
+  }
+  releaseNonce(owner, nonce) {
+    const entry = this.cache.get(owner);
+    if (!entry) return;
+    const nonceNum = Number(nonce);
+    const wordPos = Math.floor(nonceNum / 256);
+    const bitPos = nonceNum % 256;
+    const bitmap = entry.words.get(wordPos);
+    if (bitmap != null) {
+      entry.words.set(wordPos, clearBit(bitmap, bitPos));
+    }
+  }
+  invalidate(owner) {
+    if (owner) {
+      this.cache.delete(owner);
+    } else {
+      this.cache.clear();
+    }
+  }
+  async allocateNonce(owner) {
+    let entry = this.cache.get(owner);
+    if (!entry) {
+      const startWord = this.startWordFn();
+      entry = { words: /* @__PURE__ */ new Map(), highWaterMark: startWord };
+      this.cache.set(owner, entry);
+      await this.fetchWindow(owner, entry, startWord);
+    }
+    for (; ; ) {
+      const result = this.scanForUnsetBit(entry);
+      if (result) return result;
+      await this.fetchWindow(owner, entry, entry.highWaterMark);
+    }
+  }
+  scanForUnsetBit(entry) {
+    for (const [wordPos, bitmap] of entry.words) {
+      const bitIndex = findFirstUnsetBit(bitmap);
+      if (bitIndex != null) {
+        entry.words.set(wordPos, setBit(bitmap, bitIndex));
+        return String(wordPos * 256 + bitIndex);
+      }
+      entry.words.delete(wordPos);
+    }
+    return null;
+  }
+  async fetchWindow(owner, entry, startWord) {
+    const { data, error } = await this.client.GET(
+      "/info/permit2/nonces/{owner}",
+      {
+        params: {
+          path: { owner },
+          query: { start_word: startWord }
+        }
+      }
+    );
+    if (error) {
+      const msg = typeof error === "object" && error !== null && "error" in error ? error.error.message : "Unknown error";
+      throw new Error(`Permit2 nonce fetch failed: ${msg}`);
+    }
+    const words = data.data.bitmap_words;
+    if (words.length === 0) {
+      throw new Error(
+        "All Permit2 nonces exhausted in scanned range. Call invalidate() to re-fetch."
+      );
+    }
+    const previousHighWaterMark = entry.highWaterMark;
+    let maxWordPos = startWord - 1;
+    for (const word of words) {
+      const pos = word.word_position;
+      if (!entry.words.has(pos)) {
+        entry.words.set(pos, BigInt(word.bitmap));
+      }
+      if (pos > maxWordPos) maxWordPos = pos;
+    }
+    entry.highWaterMark = maxWordPos + 1;
+    if (entry.highWaterMark <= previousHighWaterMark) {
+      throw new Error(
+        `Permit2 nonce fetch failed: non-advancing cursor at word ${startWord}`
+      );
+    }
+  }
+};
+
+// src/queries.ts
+async function getEnvironment(client) {
+  const { data, error } = await client.GET("/info/environment");
+  if (error) throw new UnlinkApiError("getEnvironment", error);
+  return data.data;
+}
+async function getTransaction(client, txId) {
+  const { data, error } = await client.GET("/transactions/{tx_id}", {
+    params: { path: { tx_id: txId } }
+  });
+  if (error) throw new UnlinkApiError("getTransaction", error);
+  return data.data;
+}
+async function getUserTransactions(client, address, options) {
+  const { data, error } = await client.GET("/users/{address}/transactions", {
+    params: {
+      path: { address },
+      query: options
+    }
+  });
+  if (error) throw new UnlinkApiError("getUserTransactions", error);
+  return data.data;
+}
+
+// src/transactions/permit2.ts
+function buildPermit2TypedData(params) {
+  return {
+    domain: {
+      name: "Permit2",
+      chainId: params.chainId,
+      verifyingContract: params.permit2Address
+    },
+    types: {
+      PermitTransferFrom: [
+        { name: "permitted", type: "TokenPermissions" },
+        { name: "spender", type: "address" },
+        { name: "nonce", type: "uint256" },
+        { name: "deadline", type: "uint256" }
+      ],
+      TokenPermissions: [
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint256" }
+      ]
+    },
+    primaryType: "PermitTransferFrom",
+    value: {
+      permitted: { token: params.token, amount: params.amount },
+      spender: params.spender,
+      nonce: params.nonce,
+      deadline: params.deadline
+    }
+  };
+}
+function buildPermit2WitnessTypedData(params) {
+  return {
+    domain: {
+      name: "Permit2",
+      chainId: params.chainId,
+      verifyingContract: params.permit2Address
+    },
+    types: {
+      PermitWitnessTransferFrom: [
+        { name: "permitted", type: "TokenPermissions" },
+        { name: "spender", type: "address" },
+        { name: "nonce", type: "uint256" },
+        { name: "deadline", type: "uint256" },
+        { name: "witness", type: "DepositWitness" }
+      ],
+      TokenPermissions: [
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint256" }
+      ],
+      DepositWitness: [{ name: "notesHash", type: "bytes32" }]
+    },
+    primaryType: "PermitWitnessTransferFrom",
+    value: {
+      permitted: { token: params.token, amount: params.amount },
+      spender: params.spender,
+      nonce: params.nonce,
+      deadline: params.deadline,
+      witness: { notesHash: params.notesHash }
+    }
+  };
+}
+async function getPermit2Nonce(client, owner) {
+  let startWord = 0;
+  for (; ; ) {
+    const { data, error } = await client.GET("/info/permit2/nonces/{owner}", {
+      params: { path: { owner }, query: { start_word: startWord } }
+    });
+    if (error) {
+      throw new UnlinkApiError("permit2.getNonce", error);
+    }
+    if (data.data.next_available_nonce != null) {
+      return String(data.data.next_available_nonce);
+    }
+    if (data.data.next_word_position == null || data.data.next_word_position <= startWord) {
+      throw new Error(
+        "No available Permit2 nonce in scanned window. Try Permit2NonceManager for pagination."
+      );
+    }
+    startWord = data.data.next_word_position;
+  }
+}
+
+// src/transactions/deposit.ts
+async function deposit(client, params) {
+  const autoNonce = params.nonce == null;
+  if (autoNonce && !params.nonceManager) {
+    throw new Error("Either nonce or nonceManager must be provided");
+  }
+  const nonce = autoNonce ? await params.nonceManager.getNextNonce(params.evmAddress) : params.nonce;
+  const prepareResp = await client.POST("/transactions/deposit/prepare", {
+    body: {
+      unlink_address: params.unlinkAddress,
+      evm_address: params.evmAddress,
+      token: params.token,
+      amount: params.amount,
+      environment: params.environment
+    }
+  });
+  if (prepareResp.error) {
+    if (autoNonce) params.nonceManager.releaseNonce(params.evmAddress, nonce);
+    throw new UnlinkApiError("deposit.prepare", prepareResp.error);
+  }
+  const { tx_id: txId, notes_hash: notesHash } = prepareResp.data.data;
+  const typedData = buildPermit2WitnessTypedData({
+    token: params.token,
+    amount: params.amount,
+    spender: params.poolAddress,
+    nonce,
+    deadline: String(params.deadline),
+    chainId: params.chainId,
+    permit2Address: params.permit2Address,
+    notesHash
+  });
+  let signature;
+  try {
+    signature = await params.signTypedData(typedData);
+  } catch (err) {
+    if (autoNonce) params.nonceManager.releaseNonce(params.evmAddress, nonce);
+    throw err;
+  }
+  const submitResp = await client.POST("/transactions/deposit/{tx_id}/submit", {
+    params: { path: { tx_id: txId } },
+    body: {
+      permit2_signature: signature,
+      permit2_nonce: nonce,
+      permit2_deadline: params.deadline
+    }
+  });
+  if (submitResp.error) {
+    if (autoNonce) params.nonceManager.releaseNonce(params.evmAddress, nonce);
+    throw new UnlinkApiError("deposit.submit", submitResp.error);
+  }
+  return {
+    txId: submitResp.data.data.tx_id,
+    status: submitResp.data.data.status
+  };
+}
+
+// src/transactions/sign-submit.ts
+async function signAndSubmit(client, params) {
+  const signature = await eddsaSign(
+    params.spendingPrivateKey,
+    BigInt(params.messageHash)
+  );
+  const { data: submitData, error: submitError } = await client.POST(
+    "/transactions/{tx_id}/submit",
+    {
+      params: { path: { tx_id: params.txId } },
+      body: {
+        signature: [
+          signature.R8[0].toString(),
+          signature.R8[1].toString(),
+          signature.S.toString()
+        ]
+      }
+    }
+  );
+  if (submitError) {
+    throw new UnlinkApiError(
+      `${params.operationLabel.toLowerCase()}.submit`,
+      submitError
+    );
+  }
+  return { txId: submitData.data.tx_id, status: submitData.data.status };
+}
+
+// src/transactions/transfer.ts
+async function transfer(client, params) {
+  const { data: prepareData, error: prepareError } = await client.POST(
+    "/transactions/prepare/transfer",
+    {
+      body: {
+        unlink_address: params.senderKeys.address,
+        transfers: params.transfers.map((t) => ({
+          unlink_address: t.recipientAddress,
+          token: t.token,
+          amount: t.amount
+        })),
+        environment: params.environment
+      }
+    }
+  );
+  if (prepareError) {
+    throw new UnlinkApiError("transfer.prepare", prepareError);
+  }
+  const { tx_id, signing_request } = prepareData.data;
+  return signAndSubmit(client, {
+    txId: tx_id,
+    messageHash: signing_request.message_hash,
+    spendingPrivateKey: params.senderKeys.spendingPrivateKey,
+    operationLabel: "Transfer"
+  });
+}
+
+// src/transactions/withdraw.ts
+async function withdraw(client, params) {
+  const { data: prepareData, error: prepareError } = await client.POST(
+    "/transactions/prepare/withdraw",
+    {
+      body: {
+        unlink_address: params.senderKeys.address,
+        evm_address: params.recipientEvmAddress,
+        token: params.token,
+        amount: params.amount,
+        environment: params.environment
+      }
+    }
+  );
+  if (prepareError) {
+    throw new UnlinkApiError("withdraw.prepare", prepareError);
+  }
+  const { tx_id, signing_request } = prepareData.data;
+  return signAndSubmit(client, {
+    txId: tx_id,
+    messageHash: signing_request.message_hash,
+    spendingPrivateKey: params.senderKeys.spendingPrivateKey,
+    operationLabel: "Withdraw"
+  });
+}
+
+// src/users.ts
+async function createUser(client, keys) {
+  const { data, error } = await client.POST("/users", {
+    body: {
+      public_key: [
+        keys.spendingPublicKey[0].toString(),
+        keys.spendingPublicKey[1].toString()
+      ],
+      viewing_private_key: Array.from(
+        keys.viewingPrivateKey,
+        (b) => b.toString(16).padStart(2, "0")
+      ).join(""),
+      nullifying_key: keys.nullifyingKey.toString()
+    }
+  });
+  if (error) throw new UnlinkApiError("createUser", error);
+  return data.data;
+}
+async function getUser(client, address) {
+  const { data, error } = await client.GET("/users/{address}", {
+    params: { path: { address } }
+  });
+  if (error) throw new UnlinkApiError("getUser", error);
+  return data.data;
+}
+
+// src/unlink.ts
+var DEFAULT_DEPOSIT_DEADLINE_SECONDS = 60 * 60;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_POLL_TIMEOUT_MS = 6e4;
+var TERMINAL_TRANSACTION_STATUSES = /* @__PURE__ */ new Set([
+  "relayed",
+  "processed",
+  "failed"
+]);
+var REGISTERED_USER_ERROR_CODES = /* @__PURE__ */ new Set(["ALREADY_EXISTS", "CONFLICT"]);
+var TenantUnlinkClient = class {
+  client;
+  account;
+  evm;
+  nonceManager;
+  environmentInfo;
+  environmentInfoPromise;
+  accountKeysPromise;
+  isRegistered = false;
+  registerPromise;
+  constructor(options) {
+    this.client = createUnlinkClient(
+      options.engineUrl,
+      options.apiKey,
+      options.customFetch
+    );
+    this.account = options.account;
+    this.evm = options.evm;
+    this.nonceManager = new Permit2NonceManager(this.client);
+  }
+  async getAddress() {
+    const keys = await this.getAccountKeys();
+    return keys.address;
+  }
+  async getPublicKey() {
+    const keys = await this.getAccountKeys();
+    return keys.spendingPublicKey;
+  }
+  async ensureRegistered() {
+    if (this.isRegistered) return;
+    if (!this.registerPromise) {
+      this.registerPromise = this.getAccountKeys().then((keys) => registerUser(this.client, keys)).then(() => {
+        this.isRegistered = true;
+      }).finally(() => {
+        this.registerPromise = void 0;
+      });
+    }
+    await this.registerPromise;
+  }
+  async deposit(params) {
+    const evm = this.resolveEvmProvider(params.evm);
+    await this.ensureRegistered();
+    const [keys, environmentInfo, evmAddress] = await Promise.all([
+      this.getAccountKeys(),
+      this.getEnvironmentInfo(),
+      evm.getAddress()
+    ]);
+    return deposit(this.client, {
+      unlinkAddress: keys.address,
+      evmAddress,
+      token: params.token,
+      amount: params.amount,
+      environment: environmentInfo.name,
+      nonce: params.nonce,
+      deadline: params.deadline ?? getDefaultPermitDeadline(),
+      chainId: environmentInfo.chain_id,
+      permit2Address: environmentInfo.permit2_address,
+      poolAddress: environmentInfo.pool_address,
+      signTypedData: (typedData) => evm.signTypedData(typedData),
+      nonceManager: this.nonceManager
+    });
+  }
+  async transfer(params) {
+    const transfers = normalizeTransfers(params);
+    await this.ensureRegistered();
+    const [keys, environmentInfo] = await Promise.all([
+      this.getAccountKeys(),
+      this.getEnvironmentInfo()
+    ]);
+    return transfer(this.client, {
+      senderKeys: keys,
+      transfers,
+      environment: environmentInfo.name
+    });
+  }
+  async withdraw(params) {
+    await this.ensureRegistered();
+    const [keys, environmentInfo] = await Promise.all([
+      this.getAccountKeys(),
+      this.getEnvironmentInfo()
+    ]);
+    return withdraw(this.client, {
+      senderKeys: keys,
+      recipientEvmAddress: params.recipientEvmAddress,
+      token: params.token,
+      amount: params.amount,
+      environment: environmentInfo.name
+    });
+  }
+  async getBalances(params = {}) {
+    const address = await this.getAddress();
+    const { data, error } = await this.client.GET("/users/{address}/balances", {
+      params: {
+        path: { address },
+        query: params.token ? { token: params.token } : {}
+      }
+    });
+    if (error) throw new UnlinkApiError("getUserBalances", error);
+    return data.data;
+  }
+  async getTransactions(params = {}) {
+    const address = await this.getAddress();
+    return getUserTransactions(this.client, address, params);
+  }
+  async pollTransactionStatus(txId, options = {}) {
+    const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const deadlineAt = Date.now() + timeoutMs;
+    for (; ; ) {
+      const transaction = await getTransaction(this.client, txId);
+      if (TERMINAL_TRANSACTION_STATUSES.has(transaction.status)) {
+        return {
+          txId: transaction.id,
+          status: transaction.status
+        };
+      }
+      if (Date.now() >= deadlineAt) {
+        throw new Error(
+          `Timed out waiting for transaction ${txId} after ${timeoutMs}ms`
+        );
+      }
+      await sleep(intervalMs);
+    }
+  }
+  async getApprovalState(params) {
+    const evm = this.resolveEvmProvider(params.evm);
+    if (!evm.getErc20Allowance) {
+      throw new UnlinkCapabilityError(
+        "getApprovalState requires an UnlinkEvmProvider with getErc20Allowance()"
+      );
+    }
+    const [environmentInfo, owner] = await Promise.all([
+      this.getEnvironmentInfo(),
+      evm.getAddress()
+    ]);
+    return getApprovalState({
+      evm: { getErc20Allowance: evm.getErc20Allowance },
+      token: params.token,
+      owner,
+      spender: environmentInfo.permit2_address,
+      amount: params.amount
+    });
+  }
+  async buildApprovalTx(params) {
+    const environmentInfo = await this.getEnvironmentInfo();
+    return buildApprovalTx({
+      token: params.token,
+      spender: environmentInfo.permit2_address,
+      amount: params.amount
+    });
+  }
+  async ensureErc20Approval(params) {
+    const evm = this.resolveEvmProvider(params.evm);
+    if (!evm.getErc20Allowance) {
+      throw new UnlinkCapabilityError(
+        "ensureErc20Approval requires an UnlinkEvmProvider with getErc20Allowance()"
+      );
+    }
+    const [environmentInfo, owner] = await Promise.all([
+      this.getEnvironmentInfo(),
+      evm.getAddress()
+    ]);
+    return ensureErc20Approval({
+      evm: {
+        getErc20Allowance: evm.getErc20Allowance,
+        ...evm.sendTransaction && { sendTransaction: evm.sendTransaction }
+      },
+      token: params.token,
+      owner,
+      spender: environmentInfo.permit2_address,
+      amount: params.amount
+    });
+  }
+  resolveEvmProvider(override) {
+    const evm = override ?? this.evm;
+    if (!evm) {
+      throw new UnlinkCapabilityError(
+        "This operation requires an UnlinkEvmProvider"
+      );
+    }
+    return evm;
+  }
+  async getAccountKeys() {
+    if (!this.accountKeysPromise) {
+      this.accountKeysPromise = this.account.getAccountKeys().catch((error) => {
+        this.accountKeysPromise = void 0;
+        throw error;
+      });
+    }
+    return this.accountKeysPromise;
+  }
+  async getEnvironmentInfo() {
+    if (this.environmentInfo) return this.environmentInfo;
+    if (!this.environmentInfoPromise) {
+      this.environmentInfoPromise = getEnvironment(this.client).then((environmentInfo) => {
+        this.environmentInfo = environmentInfo;
+        return environmentInfo;
+      }).finally(() => {
+        this.environmentInfoPromise = void 0;
+      });
+    }
+    return this.environmentInfoPromise;
+  }
+};
+function createUnlink(options) {
+  return new TenantUnlinkClient(options);
+}
+function normalizeTransfers(params) {
+  const hasTransfers = isMultiTransferParams(params);
+  const hasSingleRecipient = isSingleTransferParams(params);
+  if (hasTransfers && hasSingleRecipient) {
+    throw new Error(
+      "transfer accepts either transfers or recipientAddress/amount, not both"
+    );
+  }
+  let transfers;
+  if (hasTransfers) {
+    transfers = params.transfers;
+  } else {
+    if (!hasSingleRecipient) {
+      throw new Error("transfer requires recipientAddress and amount");
+    }
+    transfers = [
+      {
+        recipientAddress: params.recipientAddress,
+        amount: params.amount
+      }
+    ];
+  }
+  if (transfers.length === 0) {
+    throw new Error("transfer requires at least one recipient");
+  }
+  return transfers.map((transferInstruction) => ({
+    recipientAddress: transferInstruction.recipientAddress,
+    token: params.token,
+    amount: transferInstruction.amount
+  }));
+}
+function isMultiTransferParams(params) {
+  return Array.isArray(params.transfers);
+}
+function isSingleTransferParams(params) {
+  return typeof params.recipientAddress === "string" && typeof params.amount === "string";
+}
+async function registerUser(client, keys) {
+  try {
+    await createUser(client, keys);
+  } catch (error) {
+    if (error instanceof UnlinkApiError && REGISTERED_USER_ERROR_CODES.has(error.code)) {
+      return;
+    }
+    throw error;
+  }
+}
+function getDefaultPermitDeadline() {
+  return Math.floor(Date.now() / 1e3) + DEFAULT_DEPOSIT_DEADLINE_SECONDS;
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// src/evm-provider.ts
+var ERC20_ALLOWANCE_ABI = [
+  {
+    type: "function",
+    name: "allowance",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    outputs: [{ name: "", type: "uint256" }]
+  }
+];
+var ALLOWANCE_SELECTOR = "dd62ed3e";
+var unlinkEvm = {
+  fromSigner(options) {
+    return {
+      async getAddress() {
+        return options.address;
+      },
+      signTypedData: options.signTypedData,
+      ...options.getErc20Allowance && {
+        getErc20Allowance: options.getErc20Allowance
+      },
+      ...options.sendTransaction && {
+        sendTransaction: options.sendTransaction
+      }
+    };
+  },
+  fromViem(options) {
+    const walletClient = options.walletClient;
+    const publicClient = options.publicClient;
+    const walletAccount = resolveViemAccount(
+      walletClient.account,
+      options.address
+    );
+    const walletSendTransaction = walletClient.sendTransaction?.bind(walletClient);
+    return {
+      async getAddress() {
+        return resolveViemAddress(walletAccount);
+      },
+      async signTypedData(typedData) {
+        return walletClient.signTypedData({
+          account: walletAccount,
+          domain: typedData.domain,
+          types: typedData.types,
+          primaryType: typedData.primaryType,
+          message: typedData.value
+        });
+      },
+      ...publicClient && {
+        async getErc20Allowance(params) {
+          const result = await publicClient.readContract({
+            address: params.token,
+            abi: ERC20_ALLOWANCE_ABI,
+            functionName: "allowance",
+            args: [params.owner, params.spender]
+          });
+          return BigInt(result);
+        }
+      },
+      ...walletSendTransaction && {
+        async sendTransaction(tx) {
+          return walletSendTransaction({
+            account: walletAccount,
+            to: tx.to,
+            data: tx.data,
+            value: tx.value
+          });
+        }
+      }
+    };
+  },
+  fromEthers(options) {
+    const signer = options.signer;
+    const provider = options.provider ?? signer.provider ?? void 0;
+    const signerSendTransaction = signer.sendTransaction?.bind(signer);
+    return {
+      async getAddress() {
+        return signer.getAddress();
+      },
+      async signTypedData(typedData) {
+        return signer.signTypedData(
+          typedData.domain,
+          typedData.types,
+          typedData.value
+        );
+      },
+      ...provider && {
+        async getErc20Allowance(params) {
+          const result = await provider.call({
+            to: params.token,
+            data: buildAllowanceCalldata(params.owner, params.spender)
+          });
+          return decodeUint256Hex(result);
+        }
+      },
+      ...signerSendTransaction && {
+        async sendTransaction(tx) {
+          const response = await signerSendTransaction({
+            to: tx.to,
+            data: tx.data,
+            value: tx.value
+          });
+          return response.hash;
+        }
+      }
+    };
+  }
+};
+function resolveViemAccount(account, fallback) {
+  if (account !== void 0) {
+    return account;
+  }
+  if (fallback) {
+    return fallback;
+  }
+  throw new UnlinkCapabilityError(
+    "unlinkEvm.fromViem requires walletClient.account or an explicit address"
+  );
+}
+function resolveViemAddress(account) {
+  if (typeof account === "string") {
+    return account;
+  }
+  return account.address;
+}
+function buildAllowanceCalldata(owner, spender) {
+  return `0x${ALLOWANCE_SELECTOR}${encodeAddressWord2(owner)}${encodeAddressWord2(spender)}`;
+}
+function decodeUint256Hex(value) {
+  if (value === "0x" || value === "") {
+    return 0n;
+  }
+  return BigInt(value);
+}
+function encodeAddressWord2(address) {
+  const stripped = address.startsWith("0x") ? address.slice(2) : address;
+  return stripped.padStart(64, "0");
+}
+
+// src/burner.ts
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+var MemoryBurnerStorage = class {
+  keys = /* @__PURE__ */ new Map();
+  async save(address, privateKey) {
+    this.keys.set(address.toLowerCase(), privateKey);
+  }
+  async load(address) {
+    return this.keys.get(address.toLowerCase()) ?? null;
+  }
+  async delete(address) {
+    this.keys.delete(address.toLowerCase());
+  }
+};
+var BurnerWallet = class _BurnerWallet {
+  address;
+  account;
+  storage;
+  constructor(account, storage) {
+    this.account = account;
+    this.address = account.address;
+    this.storage = storage;
+  }
+  /** Generate a new burner with a fresh keypair. */
+  static async create(storage) {
+    const store = storage ?? new MemoryBurnerStorage();
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    await store.save(account.address, privateKey);
+    return new _BurnerWallet(account, store);
+  }
+  /** Restore a burner from storage by address. Returns null if not found. */
+  static async restore(address, storage) {
+    const privateKey = await storage.load(address);
+    if (!privateKey) return null;
+    const account = privateKeyToAccount(privateKey);
+    return new _BurnerWallet(account, storage);
+  }
+  /** Return a viem-compatible Account for use with WalletClient. */
+  toViemAccount() {
+    return this.account;
+  }
+  /**
+   * Fund this burner by withdrawing from the Unlink pool.
+   *
+   * Calls POST /burner/create, signs the withdrawal with EdDSA, and submits.
+   * After the withdrawal confirms on-chain, the relayer sends ETH for gas.
+   */
+  async fundFromPool(client, params) {
+    const { data, error } = await client.POST("/burner/create", {
+      body: {
+        unlink_address: params.senderKeys.address,
+        burner_address: this.address,
+        token: params.token,
+        amount: params.amount,
+        environment: params.environment
+      }
+    });
+    if (error) {
+      throw new UnlinkApiError("burner.create", error);
+    }
+    const { tx_id, signing_request } = data.data;
+    return signAndSubmit(client, {
+      txId: tx_id,
+      messageHash: signing_request.message_hash,
+      spendingPrivateKey: params.senderKeys.spendingPrivateKey,
+      operationLabel: "BurnerFund"
+    });
+  }
+  /**
+   * Deposit tokens back to the Unlink pool from this burner.
+   *
+   * The caller must ensure the burner has approved Permit2 for the token
+   * before calling this method. This uses the standard deposit flow with
+   * the burner signing the Permit2 typed data.
+   */
+  async depositToPool(client, params) {
+    const signTypedData = async (typedData) => {
+      return this.account.signTypedData({
+        domain: {
+          ...typedData.domain,
+          verifyingContract: typedData.domain.verifyingContract
+        },
+        types: typedData.types,
+        primaryType: typedData.primaryType,
+        message: typedData.value
+      });
+    };
+    return deposit(client, {
+      unlinkAddress: params.unlinkAddress,
+      evmAddress: this.address,
+      token: params.token,
+      amount: params.amount,
+      environment: params.environment,
+      nonce: params.nonce,
+      deadline: params.deadline,
+      chainId: params.chainId,
+      permit2Address: params.permit2Address,
+      poolAddress: params.poolAddress,
+      signTypedData,
+      nonceManager: params.nonceManager
+    });
+  }
+  /** Check the burner's lifecycle status. */
+  async getStatus(client) {
+    const { data, error } = await client.GET(
+      "/burner/{burner_address}/status",
+      { params: { path: { burner_address: this.address } } }
+    );
+    if (error) {
+      throw new UnlinkApiError("burner.getStatus", error);
+    }
+    return data.data;
+  }
+  /** Mark this burner as disposed, optionally linking a deposit-back tx. */
+  async dispose(client, depositBackTxId) {
+    const { error } = await client.POST("/burner/{burner_address}/dispose", {
+      params: { path: { burner_address: this.address } },
+      body: { deposit_back_tx_id: depositBackTxId }
+    });
+    if (error) {
+      throw new UnlinkApiError("burner.dispose", error);
+    }
+  }
+  /** Delete the burner key from storage. Call after dispose. */
+  async deleteKey() {
+    await this.storage.delete(this.address);
+  }
+  /** Get chain configuration for burner operations. */
+  static async getInfo(client) {
+    const { data, error } = await client.GET("/burner/info");
+    if (error) {
+      throw new UnlinkApiError("burner.getInfo", error);
+    }
+    return data.data;
+  }
+};
+export {
+  P as BN254_FIELD_ORDER,
+  BurnerWallet,
+  Permit2NonceManager,
+  UnlinkApiError,
+  UnlinkCapabilityError,
+  buildApprovalTx,
+  buildPermit2TypedData,
+  createUnlink,
+  createUnlinkClient,
+  createUser,
+  decodeAddress,
+  deposit,
+  deriveAccountKeys,
+  eddsaPublicKey,
+  eddsaSign,
+  eddsaVerify,
+  encodeAddress,
+  ensureErc20Approval,
+  fromBytesBE,
+  fromDecimal,
+  fromHex,
+  getApprovalState,
+  getEnvironment,
+  getPermit2Nonce,
+  getTransaction,
+  getUser,
+  getUserTransactions,
+  mod,
+  poseidon,
+  toBytesBE,
+  toDecimal,
+  transfer,
+  unlinkAccount,
+  unlinkEvm,
+  viewingPublicKey,
+  viewingPublicKeyFromHex,
+  withdraw
+};