@usewhisk/cctp 0.0.0 → 0.1.1

package/dist/iris.cjs

@@ -0,0 +1,557 @@
+'use strict';
+
+// src/iris/urls.ts
+var IRIS_MAINNET_URL = "https://iris-api.circle.com";
+var IRIS_SANDBOX_URL = "https://iris-api-sandbox.circle.com";
+function irisBaseUrl(network) {
+  return network === "mainnet" ? IRIS_MAINNET_URL : IRIS_SANDBOX_URL;
+}
+
+// src/errors.ts
+var CctpError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "CctpError";
+    this.code = code;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var IrisError = class extends CctpError {
+  constructor(code, message, cause) {
+    super(code, message, cause);
+    this.name = "IrisError";
+  }
+};
+var IrisHttpError = class extends IrisError {
+  status;
+  bodySnippet;
+  url;
+  constructor(status, url, bodySnippet) {
+    super(
+      "iris_http",
+      `Iris ${status} on ${url}: ${bodySnippet.slice(0, 200)}`
+    );
+    this.name = "IrisHttpError";
+    this.status = status;
+    this.url = url;
+    this.bodySnippet = bodySnippet;
+  }
+};
+var IrisRateLimitedError = class extends IrisError {
+  retryAt;
+  host;
+  constructor(host, retryAt) {
+    super(
+      "iris_rate_limited",
+      `Iris rate limit reached on ${host}; requests resume at ${new Date(retryAt).toISOString()}`
+    );
+    this.name = "IrisRateLimitedError";
+    this.host = host;
+    this.retryAt = retryAt;
+  }
+};
+var IrisNetworkError = class extends IrisError {
+  constructor(message, cause) {
+    super("iris_network", message, cause);
+    this.name = "IrisNetworkError";
+  }
+};
+var IrisParseError = class extends IrisError {
+  constructor(message, cause) {
+    super("iris_parse", message, cause);
+    this.name = "IrisParseError";
+  }
+};
+var IrisAbortedError = class extends IrisError {
+  constructor(message) {
+    super("iris_aborted", message);
+    this.name = "IrisAbortedError";
+  }
+};
+var ProtocolError = class extends CctpError {
+  constructor(code, message, cause) {
+    super(code, message, cause);
+    this.name = "ProtocolError";
+  }
+};
+
+// src/iris/limiter.ts
+function createIrisLimiter(options = {}) {
+  const rate = options.ratePerSecond ?? 30;
+  const standDownMs = options.standDownMs ?? 5 * 6e4;
+  const now = options.now ?? (() => Date.now());
+  const sleep3 = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const buckets = /* @__PURE__ */ new Map();
+  const bucket = (host) => {
+    let b = buckets.get(host);
+    if (!b) {
+      b = { tokens: rate, updatedAt: now(), blockedUntil: 0 };
+      buckets.set(host, b);
+    }
+    return b;
+  };
+  return {
+    async acquire(host) {
+      const b = bucket(host);
+      if (now() < b.blockedUntil) {
+        throw new IrisRateLimitedError(host, b.blockedUntil);
+      }
+      const elapsed = (now() - b.updatedAt) / 1e3;
+      b.tokens = Math.min(rate, b.tokens + elapsed * rate);
+      b.updatedAt = now();
+      if (b.tokens < 1) {
+        const waitMs = Math.ceil((1 - b.tokens) / rate * 1e3);
+        await sleep3(waitMs);
+        b.tokens += waitMs / 1e3 * rate;
+        b.updatedAt = now();
+      }
+      b.tokens -= 1;
+    },
+    standDown(host) {
+      const b = bucket(host);
+      b.blockedUntil = now() + standDownMs;
+      return b.blockedUntil;
+    },
+    now,
+    sleep: sleep3
+  };
+}
+var defaultIrisLimiter = createIrisLimiter();
+
+// src/iris/fetch.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_BASE_DELAY_MS = 300;
+async function fetchIrisJson(url, options = {}, request = {
+  method: "GET"
+}) {
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    baseDelayMs = DEFAULT_BASE_DELAY_MS,
+    signal,
+    fetch: fetchImpl = fetch,
+    limiter = defaultIrisLimiter
+  } = options;
+  const host = new URL(url).host;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (signal?.aborted) throw new IrisAbortedError("Aborted by caller");
+    await limiter.acquire(host);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const onCallerAbort = () => ctrl.abort();
+    signal?.addEventListener("abort", onCallerAbort);
+    try {
+      const res = await fetchImpl(url, {
+        method: request.method,
+        headers: {
+          accept: "application/json",
+          ...request.method === "POST" && {
+            "content-type": "application/json"
+          }
+        },
+        ...request.method === "POST" && {
+          body: JSON.stringify(request.body)
+        },
+        signal: ctrl.signal
+      });
+      if (res.ok) {
+        let json;
+        try {
+          json = await res.json();
+        } catch (err) {
+          throw new IrisParseError(`Invalid JSON from ${url}`, err);
+        }
+        return json;
+      }
+      if (res.status === 429) {
+        throw new IrisRateLimitedError(host, limiter.standDown(host));
+      }
+      if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+        throw new IrisHttpError(res.status, url, await safeText(res));
+      }
+      lastError = new IrisHttpError(res.status, url, await safeText(res));
+    } catch (err) {
+      if (err instanceof IrisParseError) throw err;
+      if (err instanceof IrisRateLimitedError) throw err;
+      if (err instanceof IrisHttpError) {
+        if (err.status < 500 && err.status !== 429) throw err;
+      }
+      if (signal?.aborted) throw new IrisAbortedError("Aborted by caller");
+      lastError = err;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onCallerAbort);
+    }
+    if (attempt < maxRetries) {
+      await sleep(baseDelayMs * (attempt + 1), signal);
+    }
+  }
+  if (lastError instanceof IrisHttpError) throw lastError;
+  throw new IrisNetworkError(
+    `Iris request failed after ${maxRetries + 1} attempts`,
+    lastError
+  );
+}
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new IrisAbortedError("Aborted by caller"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new IrisAbortedError("Aborted by caller"));
+    }
+    signal?.addEventListener("abort", onAbort);
+  });
+}
+
+// src/iris/types.ts
+var FINALITY_FAST = 1e3;
+var FINALITY_STANDARD = 2e3;
+
+// src/fees/math.ts
+var DECIMAL = /^(\d+)(?:\.(\d+))?$/;
+function ceilDecimal(raw, decimals, what) {
+  const text = typeof raw === "number" ? String(raw) : typeof raw === "string" ? raw : "";
+  const match = DECIMAL.exec(text);
+  if (!match) {
+    throw new IrisParseError(`Iris ${what} is invalid: ${String(raw)}`);
+  }
+  const fraction = match[2] ?? "";
+  const kept = fraction.slice(0, decimals).padEnd(decimals, "0");
+  const dropped = /[1-9]/.test(fraction.slice(decimals)) ? 1n : 0n;
+  return BigInt((match[1] ?? "0") + kept) + dropped;
+}
+function parseFeeBps(raw) {
+  return ceilDecimal(raw, 2, "minimumFee");
+}
+function parseForwarderFee(raw) {
+  return ceilDecimal(raw, 0, "forwardFee");
+}
+function selectForwarderFee(tier, level = "med") {
+  if (!tier.forwardFee) {
+    throw new ProtocolError(
+      "fee_unavailable",
+      "Tier has no forwardFee. Fetch burn fees with includeForwarderFee=true"
+    );
+  }
+  const value = tier.forwardFee[level];
+  if (value < 0n) {
+    throw new ProtocolError(
+      "fee_unavailable",
+      `Invalid forwardFee.${level}: ${value}`
+    );
+  }
+  return value;
+}
+
+// src/iris/fees.ts
+async function getBurnFees(network, sourceDomain, destinationDomain, options = {}) {
+  const { includeForwarderFee = true, ...fetchOpts } = options;
+  const base = irisBaseUrl(network);
+  const url = new URL(
+    `${base}/v2/burn/USDC/fees/${sourceDomain}/${destinationDomain}`
+  );
+  if (includeForwarderFee) url.searchParams.set("forward", "true");
+  const raw = await fetchIrisJson(url.toString(), fetchOpts);
+  if (!Array.isArray(raw)) {
+    throw new IrisParseError("Iris burn-fees response is not an array");
+  }
+  return raw.map((row) => normalizeTier(row)).filter((t) => t !== null);
+}
+function normalizeTier(row) {
+  if (!row || typeof row !== "object") {
+    throw new IrisParseError("Iris fee tier is not an object");
+  }
+  const r = row;
+  const threshold = r.finalityThreshold;
+  if (threshold !== FINALITY_FAST && threshold !== FINALITY_STANDARD) {
+    return null;
+  }
+  const out = {
+    finalityThreshold: threshold,
+    minimumFee: parseFeeBps(r.minimumFee)
+  };
+  if (r.forwardFee && typeof r.forwardFee === "object") {
+    const ff = r.forwardFee;
+    out.forwardFee = {
+      low: parseForwarderFee(ff.low),
+      med: parseForwarderFee(ff.med),
+      high: parseForwarderFee(ff.high)
+    };
+  }
+  return out;
+}
+function pickFeeTier(tiers, speed) {
+  const threshold = speed === "fast" ? FINALITY_FAST : FINALITY_STANDARD;
+  const tier = tiers.find((t) => t.finalityThreshold === threshold);
+  if (!tier) {
+    throw new ProtocolError(
+      "tier_not_found",
+      `Iris returned no ${speed === "fast" ? "Fast" : "Standard"} Transfer fee for this route.`
+    );
+  }
+  return tier;
+}
+function pickForwarderFee(tier, level = "med") {
+  return selectForwarderFee(tier, level);
+}
+
+// src/iris/messages.ts
+async function getMessages(query, options) {
+  const { network, baseUrl, ...fetchOpts } = options;
+  const base = (baseUrl ?? irisBaseUrl(network)).replace(/\/+$/, "");
+  const url = new URL(`${base}/v2/messages/${query.sourceDomain}`);
+  if (query.transactionHash) {
+    url.searchParams.set("transactionHash", query.transactionHash);
+  }
+  if (query.nonce) {
+    url.searchParams.set("nonce", query.nonce);
+  }
+  try {
+    const json = await fetchIrisJson(
+      url.toString(),
+      fetchOpts
+    );
+    return json.messages ?? [];
+  } catch (err) {
+    if (err instanceof IrisHttpError && err.status === 404) {
+      return [];
+    }
+    throw err;
+  }
+}
+var DEFAULT_INTERVAL_MS = 3e3;
+var DEFAULT_TIMEOUT_MS2 = 15 * 60 * 1e3;
+var TIMEOUT_MARGIN_MS = 5 * 60 * 1e3;
+function pollBudget(eta) {
+  const intervalMs = eta.max <= 60 ? 2e3 : eta.max <= 30 * 60 ? 1e4 : 3e4;
+  return { intervalMs, timeoutMs: eta.max * 2 * 1e3 + TIMEOUT_MARGIN_MS };
+}
+function isForwardDone(message) {
+  return (message.forwardState === "CONFIRMED" || message.forwardState === "COMPLETE") && !!message.forwardTxHash;
+}
+function defaultIsDone(message) {
+  if (message.forwardState != null) {
+    return isForwardDone(message) || message.forwardState === "FAILED";
+  }
+  return message.status === "complete";
+}
+async function pollMessages(query, options) {
+  const {
+    intervalMs = DEFAULT_INTERVAL_MS,
+    timeoutMs = DEFAULT_TIMEOUT_MS2,
+    isDone = defaultIsDone,
+    onRateLimited,
+    signal,
+    ...rest
+  } = options;
+  const limiter = rest.limiter ?? defaultIrisLimiter;
+  let deadline = limiter.now() + timeoutMs;
+  let latest = null;
+  while (limiter.now() < deadline) {
+    if (signal?.aborted) throw new IrisAbortedError("Aborted by caller");
+    let messages;
+    try {
+      messages = await getMessages(query, { ...rest, signal });
+    } catch (err) {
+      if (!(err instanceof IrisRateLimitedError)) throw err;
+      onRateLimited?.(err.retryAt);
+      const waitMs = Math.max(0, err.retryAt - limiter.now());
+      deadline += waitMs;
+      await limiter.sleep(waitMs);
+      continue;
+    }
+    if (messages.length > 0) {
+      const first = messages[0];
+      if (first) {
+        latest = first;
+        if (isDone(first)) return first;
+      }
+    }
+    await sleep2(intervalMs, signal);
+  }
+  return latest;
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new IrisAbortedError("Aborted by caller"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new IrisAbortedError("Aborted by caller"));
+    }
+    signal?.addEventListener("abort", onAbort);
+  });
+}
+
+// src/iris/reattest.ts
+async function reattest(nonce, options) {
+  const { network, ...fetchOpts } = options;
+  const url = `${irisBaseUrl(network)}/v2/reattest/${nonce}`;
+  let json;
+  try {
+    json = await fetchIrisJson(url, fetchOpts, {
+      method: "POST",
+      body: {}
+    });
+  } catch (err) {
+    if (err instanceof IrisHttpError && err.status === 404) return null;
+    throw err;
+  }
+  const acknowledged = typeof json === "object" && json !== null && "nonce" in json ? json.nonce : void 0;
+  if (typeof acknowledged !== "string") {
+    throw new IrisParseError("Iris reattest reply has no nonce");
+  }
+  return { nonce: acknowledged };
+}
+
+// src/iris/quote.ts
+async function getSignedBurnQuote(network, sourceDomain, destinationDomain, request, options = {}) {
+  const url = `${irisBaseUrl(network)}/v2/quote/burn/usdc/${sourceDomain}/${destinationDomain}`;
+  const raw = await fetchIrisJson(url, options, {
+    method: "POST",
+    body: {
+      amount: request.amount.toString(),
+      feeToken: request.feeToken,
+      requests: request.requests.map((type) => ({ type }))
+    }
+  });
+  const quote = parseQuote(raw);
+  if (quote.burnAmount !== void 0 && quote.burnAmount !== request.amount) {
+    throw new IrisParseError(
+      `Iris quoted ${quote.burnAmount} subunits, not the ${request.amount} requested`
+    );
+  }
+  if (quote.feeToken.toLowerCase() !== request.feeToken.toLowerCase()) {
+    throw new IrisParseError(
+      `Iris priced the fee in ${quote.feeToken}, not ${request.feeToken}`
+    );
+  }
+  const types = quote.items.map((i) => i.type).sort();
+  if (types.join() !== [...request.requests].sort().join()) {
+    throw new IrisParseError(
+      `Iris priced ${types.join(", ")}, not ${request.requests.join(", ")}`
+    );
+  }
+  return quote;
+}
+function parseQuote(raw) {
+  const fail = (what) => {
+    throw new IrisParseError(`Iris quote: ${what}`);
+  };
+  if (typeof raw !== "object" || raw === null) return fail("not an object");
+  const r = raw;
+  const signedQuote = r.signedQuote;
+  if (typeof signedQuote !== "string" || !/^0x([0-9a-fA-F]{2})+$/.test(signedQuote)) {
+    return fail("signedQuote is not hex bytes");
+  }
+  if (!Number.isSafeInteger(r.issuedAt))
+    return fail("issuedAt is not a timestamp");
+  const feeToken = r.feeToken;
+  if (typeof feeToken !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(feeToken)) {
+    return fail("feeToken is not an address");
+  }
+  const feeTotalAmount = subunits(r.feeTotalAmount) ?? fail("feeTotalAmount");
+  const burnAmount = r.burnAmount === void 0 ? void 0 : subunits(r.burnAmount) ?? fail("burnAmount");
+  if (!Array.isArray(r.items) || r.items.length === 0) return fail("no items");
+  const items = r.items.map(
+    (item) => {
+      const i = item ?? {};
+      if (i.type !== "FORWARD" && i.type !== "PRE_FINALITY") {
+        return fail(`unknown item type ${String(i.type)}`);
+      }
+      return {
+        type: i.type,
+        amount: subunits(i.amount) ?? fail("item amount")
+      };
+    }
+  );
+  if (items.reduce((sum, i) => sum + i.amount, 0n) !== feeTotalAmount) {
+    return fail("items do not add up to feeTotalAmount");
+  }
+  return {
+    signedQuote,
+    issuedAt: r.issuedAt,
+    expiry: parseExpiry(r.expiry) ?? fail("expiry"),
+    feeTotalAmount,
+    feeToken,
+    ...burnAmount !== void 0 && { burnAmount },
+    items
+  };
+}
+function parseExpiry(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const e = raw;
+  if (e.mode === "TIMESTAMP" && Number.isSafeInteger(e.expiresAt)) {
+    return { mode: "TIMESTAMP", expiresAt: e.expiresAt };
+  }
+  if (e.mode === "BLOCK_NUMBER" && Number.isSafeInteger(e.expiresAtBlock)) {
+    return {
+      mode: "BLOCK_NUMBER",
+      expiresAtBlock: BigInt(e.expiresAtBlock)
+    };
+  }
+  return void 0;
+}
+function subunits(raw) {
+  return typeof raw === "string" && /^(0|[1-9]\d*)$/.test(raw) ? BigInt(raw) : void 0;
+}
+async function getFastBurnAllowance(network, options = {}) {
+  const raw = await fetchIrisJson(
+    `${irisBaseUrl(network)}/v2/fastBurn/USDC/allowance`,
+    options
+  );
+  const value = typeof raw === "object" && raw !== null && "allowance" in raw ? raw.allowance : void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new IrisParseError("Iris allowance is not a non-negative number");
+  }
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(String(value));
+  if (!match)
+    throw new IrisParseError(`Iris allowance ${value} is not decimal`);
+  const frac = (match[2] ?? "").padEnd(6, "0").slice(0, 6);
+  return BigInt(match[1]) * 1000000n + BigInt(frac);
+}
+
+exports.FINALITY_FAST = FINALITY_FAST;
+exports.FINALITY_STANDARD = FINALITY_STANDARD;
+exports.IRIS_MAINNET_URL = IRIS_MAINNET_URL;
+exports.IRIS_SANDBOX_URL = IRIS_SANDBOX_URL;
+exports.createIrisLimiter = createIrisLimiter;
+exports.defaultIrisLimiter = defaultIrisLimiter;
+exports.fetchIrisJson = fetchIrisJson;
+exports.getBurnFees = getBurnFees;
+exports.getFastBurnAllowance = getFastBurnAllowance;
+exports.getMessages = getMessages;
+exports.getSignedBurnQuote = getSignedBurnQuote;
+exports.irisBaseUrl = irisBaseUrl;
+exports.isForwardDone = isForwardDone;
+exports.pickFeeTier = pickFeeTier;
+exports.pickForwarderFee = pickForwarderFee;
+exports.pollBudget = pollBudget;
+exports.pollMessages = pollMessages;
+exports.reattest = reattest;
+//# sourceMappingURL=iris.cjs.map
+//# sourceMappingURL=iris.cjs.map