@forgezero/runtime 0.1.0

package/dist/finance/binance.js

@@ -0,0 +1,452 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/finance/money.ts
+class MoneyError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MoneyError";
+  }
+}
+var ASSETS = [
+  { code: "USDT", decimals: 6 },
+  { code: "USDC", decimals: 6 },
+  { code: "BTC", decimals: 8 },
+  { code: "ETH", decimals: 18 },
+  { code: "BNB", decimals: 18 },
+  { code: "EUR", decimals: 2 },
+  { code: "USD", decimals: 2 }
+];
+var REGISTRY = new Map(ASSETS.map((asset) => [asset.code, asset]));
+function defineAsset(spec) {
+  if (spec.decimals < 0 || spec.decimals > 30 || !Number.isInteger(spec.decimals)) {
+    throw new MoneyError("UNKNOWN_ASSET", `${spec.code}: decimals must be an integer 0–30.`);
+  }
+  REGISTRY.set(spec.code, spec);
+}
+function assetSpec(code) {
+  const spec = REGISTRY.get(code);
+  if (!spec)
+    throw new MoneyError("UNKNOWN_ASSET", `Unknown asset "${code}". Call defineAsset first.`);
+  return spec;
+}
+var money = (units, asset) => {
+  assetSpec(asset);
+  return { units, asset };
+};
+var zero = (asset) => money(0n, asset);
+function parseAmount(value, asset) {
+  const spec = assetSpec(asset);
+  const text = value.trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) {
+    throw new MoneyError("NOT_FINITE", `"${value}" is not a plain decimal amount.`);
+  }
+  const negative = text.startsWith("-");
+  const [whole, fraction = ""] = text.replace("-", "").split(".");
+  if (fraction.length > spec.decimals) {
+    throw new MoneyError("PRECISION_LOSS", `${asset} has ${spec.decimals} decimals; "${value}" has ${fraction.length}.`);
+  }
+  const padded = fraction.padEnd(spec.decimals, "0");
+  const units = BigInt(whole + padded);
+  return { units: negative ? -units : units, asset };
+}
+function formatAmount(amount, options = {}) {
+  const spec = assetSpec(amount.asset);
+  const negative = amount.units < 0n;
+  const digits = (negative ? -amount.units : amount.units).toString().padStart(spec.decimals + 1, "0");
+  const whole = digits.slice(0, digits.length - spec.decimals);
+  let fraction = spec.decimals === 0 ? "" : digits.slice(digits.length - spec.decimals);
+  if (options.trim && fraction)
+    fraction = fraction.replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
+}
+function sameAsset(a, b) {
+  if (a.asset !== b.asset) {
+    throw new MoneyError("ASSET_MISMATCH", `Cannot combine ${a.asset} and ${b.asset}.`);
+  }
+}
+function add(a, b) {
+  sameAsset(a, b);
+  return { units: a.units + b.units, asset: a.asset };
+}
+function subtract(a, b) {
+  sameAsset(a, b);
+  return { units: a.units - b.units, asset: a.asset };
+}
+var negate = (amount) => ({ units: -amount.units, asset: amount.asset });
+var abs = (amount) => ({
+  units: amount.units < 0n ? -amount.units : amount.units,
+  asset: amount.asset
+});
+var isZero = (amount) => amount.units === 0n;
+var isNegative = (amount) => amount.units < 0n;
+function compare(a, b) {
+  sameAsset(a, b);
+  return a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
+}
+var equals = (a, b) => a.asset === b.asset && a.units === b.units;
+var ROUNDING = ["down", "up", "half-up"];
+function divideRounded(numerator, denominator, mode) {
+  if (denominator === 0n)
+    throw new MoneyError("DIVIDE_BY_ZERO", "Division by zero.");
+  const negative = numerator < 0n !== denominator < 0n;
+  const a = numerator < 0n ? -numerator : numerator;
+  const b = denominator < 0n ? -denominator : denominator;
+  const quotient = a / b;
+  const remainder = a % b;
+  if (remainder === 0n)
+    return negative ? -quotient : quotient;
+  let result = quotient;
+  if (mode === "up")
+    result += 1n;
+  else if (mode === "half-up" && remainder * 2n >= b)
+    result += 1n;
+  return negative ? -result : result;
+}
+function mulRate(amount, rate, mode = "down") {
+  if (!/^-?\d+(\.\d+)?$/.test(rate.trim())) {
+    throw new MoneyError("NOT_FINITE", `"${rate}" is not a plain decimal rate.`);
+  }
+  const [whole, fraction = ""] = rate.trim().replace("-", "").split(".");
+  const scale = 10n ** BigInt(fraction.length);
+  const scaled = BigInt(whole + fraction) * (rate.trim().startsWith("-") ? -1n : 1n);
+  return { units: divideRounded(amount.units * scaled, scale, mode), asset: amount.asset };
+}
+function convert(amount, to, rate, mode = "down") {
+  const from = assetSpec(amount.asset);
+  const target = assetSpec(to);
+  const asTarget = mulRate({ units: amount.units, asset: to }, rate, mode);
+  const shift = target.decimals - from.decimals;
+  if (shift === 0)
+    return asTarget;
+  if (shift > 0)
+    return { units: asTarget.units * 10n ** BigInt(shift), asset: to };
+  return { units: divideRounded(asTarget.units, 10n ** BigInt(-shift), mode), asset: to };
+}
+function allocate(amount, parts) {
+  if (parts < 1)
+    throw new MoneyError("NOT_FINITE", "Cannot allocate into fewer than one part.");
+  const each = divideRounded(amount.units, BigInt(parts), "down");
+  const allocated = Array.from({ length: parts }, () => each);
+  let remainder = amount.units - each * BigInt(parts);
+  const step = remainder < 0n ? -1n : 1n;
+  for (let index = 0;remainder !== 0n; index = (index + 1) % parts) {
+    allocated[index] += step;
+    remainder -= step;
+  }
+  return allocated.map((units) => ({ units, asset: amount.asset }));
+}
+function toStep(amount, step, mode = "down") {
+  const stepUnits = parseAmount(step, amount.asset).units;
+  if (stepUnits <= 0n)
+    throw new MoneyError("NOT_FINITE", "A step must be positive.");
+  return { units: divideRounded(amount.units, stepUnits, mode) * stepUnits, asset: amount.asset };
+}
+var VERSION = "0.1.0";
+
+// src/finance/venues.ts
+var MARKET_TYPES = ["spot", "margin", "futures"];
+var ORDER_SIDES = ["buy", "sell"];
+var ORDER_TYPES = ["market", "limit", "stop-limit"];
+var TIME_IN_FORCE = ["gtc", "ioc", "fok"];
+var VENUES = [
+  {
+    key: "binance",
+    label: "Binance",
+    markets: ["spot", "margin", "futures"],
+    rateLimit: { perMinute: 6000, counts: "weight" },
+    clientOrderIds: true,
+    note: "Publishes no AAAA records, so every endpoint is IPv4-only and the budget is per IP."
+  }
+];
+var venue = (key) => VENUES.find((entry) => entry.key === key);
+var venuesFor = (type) => VENUES.filter((entry) => entry.markets.includes(type));
+var symbolOf = (base, quote) => `${base.toUpperCase()}/${quote.toUpperCase()}`;
+function parseSymbol(symbol) {
+  const [base, quote] = symbol.toUpperCase().split("/");
+  if (!base || !quote)
+    throw new VenueError("BAD_SYMBOL", `"${symbol}" is not BASE/QUOTE.`);
+  return { base, quote };
+}
+
+class VenueError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VenueError";
+  }
+}
+function notionalOf(request, market) {
+  const price = request.price;
+  if (!price)
+    return parseAmount("0", market.quote);
+  const quantity = Number(formatAmount(request.quantity));
+  const priceText = formatAmount(price);
+  return parseAmount((quantity * Number(priceText)).toFixed(0) === "NaN" ? "0" : String(quantity * Number(priceText)), market.quote);
+}
+function validateOrder(request, market) {
+  const spec = venue(request.venue);
+  if (!spec)
+    throw new VenueError("UNKNOWN_VENUE", `Unknown venue "${request.venue}".`);
+  if (!spec.markets.includes(request.type)) {
+    throw new VenueError("MARKET_UNSUPPORTED", `${spec.label} does not offer ${request.type}.`);
+  }
+  if (market.venue !== request.venue || market.type !== request.type || market.symbol !== request.symbol) {
+    throw new VenueError("UNKNOWN_MARKET", "The market does not describe this order.");
+  }
+  if (request.orderType !== "market" && !request.price) {
+    throw new VenueError("PRICE_REQUIRED", `A ${request.orderType} order needs a price.`);
+  }
+  const snapped = toStep(request.quantity, market.lotStep);
+  if (compare(snapped, request.quantity) !== 0) {
+    throw new VenueError("LOT_STEP", `Quantity ${formatAmount(request.quantity, { trim: true })} is not a multiple of ${market.lotStep}.`);
+  }
+  if (request.price) {
+    const onTick = toStep(request.price, market.tickStep);
+    if (compare(onTick, request.price) !== 0) {
+      throw new VenueError("TICK_STEP", `Price ${formatAmount(request.price, { trim: true })} is not a multiple of ${market.tickStep}.`);
+    }
+    const notional = notionalOf(request, market);
+    if (compare(notional, parseAmount(market.minNotional, market.quote)) < 0) {
+      throw new VenueError("MIN_NOTIONAL", `Order is worth ${formatAmount(notional, { trim: true })} ${market.quote}; the minimum is ${market.minNotional}.`);
+    }
+  }
+  if (request.leverage !== undefined) {
+    if (request.type === "spot" || market.maxLeverage === undefined) {
+      throw new VenueError("LEVERAGE_UNSUPPORTED", `${request.type} markets have no leverage.`);
+    }
+    if (request.leverage < 1 || request.leverage > market.maxLeverage) {
+      throw new VenueError("LEVERAGE_TOO_HIGH", `Leverage ${request.leverage}× exceeds the ${market.maxLeverage}× maximum on this market.`);
+    }
+  }
+}
+async function submitOrder(adapter, request, market) {
+  validateOrder(request, market);
+  return adapter.placeOrder(request, market);
+}
+var VERSION2 = "0.1.0";
+
+// src/finance/binance.ts
+import { createHttpClient, binanceWeight } from "@forgezero/providers/http";
+var BUDGET_HOST = "binance";
+var DEFAULT_HOSTS = {
+  spot: "https://api.binance.com",
+  margin: "https://api.binance.com",
+  futures: "https://fapi.binance.com"
+};
+var binanceSymbol = (symbol) => {
+  const { base, quote } = parseSymbol(symbol);
+  return `${base}${quote}`;
+};
+var PATHS = {
+  spot: {
+    order: "/api/v3/order",
+    openOrders: "/api/v3/openOrders",
+    account: "/api/v3/account",
+    exchangeInfo: "/api/v3/exchangeInfo"
+  },
+  margin: {
+    order: "/sapi/v1/margin/order",
+    openOrders: "/sapi/v1/margin/openOrders",
+    account: "/sapi/v1/margin/account",
+    exchangeInfo: "/api/v3/exchangeInfo"
+  },
+  futures: {
+    order: "/fapi/v1/order",
+    openOrders: "/fapi/v1/openOrders",
+    account: "/fapi/v2/account",
+    exchangeInfo: "/fapi/v1/exchangeInfo"
+  }
+};
+function toOrderStatus(status) {
+  switch (status) {
+    case "NEW":
+    case "PENDING_NEW":
+      return "accepted";
+    case "PARTIALLY_FILLED":
+      return "partial";
+    case "FILLED":
+      return "filled";
+    case "CANCELED":
+    case "PENDING_CANCEL":
+    case "EXPIRED":
+    case "EXPIRED_IN_MATCH":
+      return "cancelled";
+    default:
+      return "rejected";
+  }
+}
+var SIDE = { buy: "BUY", sell: "SELL" };
+var TYPE = { market: "MARKET", limit: "LIMIT", "stop-limit": "STOP_LOSS_LIMIT" };
+async function sign(secret, query) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(query));
+  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createBinanceAdapter(options) {
+  const hosts = { ...DEFAULT_HOSTS, ...options.hosts };
+  const recvWindow = options.recvWindowMs ?? 5000;
+  const now = options.now ?? Date.now;
+  const clients = new Map;
+  const clientFor = (type) => {
+    const base = hosts[type];
+    const existing = clients.get(base);
+    if (existing)
+      return existing;
+    const client = createHttpClient({
+      baseUrl: base,
+      fetch: options.fetch,
+      costOf: binanceWeight,
+      budget: { host: BUDGET_HOST, limit: 6000, windowMs: 60000, defaultCost: 1, headroom: 0.9 }
+    });
+    clients.set(base, client);
+    return client;
+  };
+  async function signed(args) {
+    const entries = Object.entries(args.params).filter(([, value]) => value !== undefined);
+    const base = new URLSearchParams(entries.map(([name, value]) => [name, String(value)])).toString();
+    const withTiming = `${base}${base ? "&" : ""}recvWindow=${recvWindow}&timestamp=${now()}`;
+    const signature = await sign(options.credentials.apiSecret, withTiming);
+    const response = await clientFor(args.type).call({
+      path: `${args.path}?${withTiming}&signature=${signature}`,
+      method: args.method,
+      weight: args.weight,
+      headers: { "X-MBX-APIKEY": options.credentials.apiKey }
+    });
+    return response.body;
+  }
+  return {
+    venue: "binance",
+    symbolFor: (symbol) => binanceSymbol(symbol),
+    async markets(type) {
+      const info = await clientFor(type).call({ path: PATHS[type].exchangeInfo, weight: 20 });
+      return (info.body.symbols ?? []).filter((entry) => entry.status === "TRADING").map((entry) => {
+        const filter = (name) => entry.filters.find((candidate) => candidate.filterType === name);
+        return {
+          venue: "binance",
+          type,
+          symbol: `${entry.baseAsset}/${entry.quoteAsset}`,
+          base: entry.baseAsset,
+          quote: entry.quoteAsset,
+          lotStep: filter("LOT_SIZE")?.stepSize ?? "0.00000001",
+          tickStep: filter("PRICE_FILTER")?.tickSize ?? "0.00000001",
+          minNotional: filter("NOTIONAL")?.minNotional ?? filter("MIN_NOTIONAL")?.minNotional ?? "0",
+          ...type === "spot" ? {} : { maxLeverage: 125 }
+        };
+      });
+    },
+    async placeOrder(request, market) {
+      if (request.type === "futures" && request.leverage) {
+        await signed({
+          type: "futures",
+          path: "/fapi/v1/leverage",
+          method: "POST",
+          params: { symbol: binanceSymbol(request.symbol), leverage: request.leverage }
+        });
+      }
+      const raw = await signed({
+        type: request.type,
+        path: PATHS[request.type].order,
+        method: "POST",
+        weight: 1,
+        params: {
+          symbol: binanceSymbol(request.symbol),
+          side: SIDE[request.side],
+          type: TYPE[request.orderType],
+          quantity: formatAmount(request.quantity, { trim: true }),
+          price: request.price ? formatAmount(request.price, { trim: true }) : undefined,
+          stopPrice: request.stopPrice ? formatAmount(request.stopPrice, { trim: true }) : undefined,
+          timeInForce: request.orderType === "market" ? undefined : (request.timeInForce ?? "gtc").toUpperCase(),
+          newClientOrderId: request.clientOrderId,
+          ...request.type === "margin" ? { sideEffectType: "NO_SIDE_EFFECT" } : {},
+          ...request.dryRun ? { test: "true" } : {}
+        }
+      });
+      return readOrder(raw, market);
+    },
+    async cancelOrder(args) {
+      await signed({
+        type: args.type,
+        path: PATHS[args.type].order,
+        method: "DELETE",
+        params: { symbol: binanceSymbol(args.symbol), orderId: args.venueOrderId }
+      });
+    },
+    async openOrders(args) {
+      const raw = await signed({
+        type: args.type,
+        path: PATHS[args.type].openOrders,
+        method: "GET",
+        weight: args.symbol ? 3 : 40,
+        params: { symbol: args.symbol ? binanceSymbol(args.symbol) : undefined }
+      });
+      return (raw ?? []).map((entry) => readOrder(entry, undefined));
+    },
+    async balances(type) {
+      const raw = await signed({ type, path: PATHS[type].account, method: "GET", weight: 10, params: {} });
+      const rows = raw.balances ?? raw.userAssets ?? (raw.assets ?? []).map((entry) => ({ asset: entry.asset, free: entry.availableBalance }));
+      return rows.filter((entry) => Number(entry.free) > 0).map((entry) => {
+        try {
+          return parseAmount(entry.free, entry.asset);
+        } catch {
+          return null;
+        }
+      }).filter((amount) => amount !== null);
+    }
+  };
+}
+function readOrder(raw, market) {
+  const asset = market?.base ?? "BTC";
+  const executed = String(raw.executedQty ?? raw.origQty ?? "0");
+  let filledQuantity;
+  try {
+    filledQuantity = parseAmount(executed, asset);
+  } catch {
+    filledQuantity = zero(asset);
+  }
+  const quoteFilled = Number(raw.cummulativeQuoteQty ?? 0);
+  const filled = Number(executed);
+  return {
+    venueOrderId: String(raw.orderId ?? ""),
+    clientOrderId: raw.clientOrderId ? String(raw.clientOrderId) : undefined,
+    status: toOrderStatus(String(raw.status ?? "NEW")),
+    filledQuantity,
+    ...market && filled > 0 && quoteFilled > 0 ? {
+      averagePrice: (() => {
+        try {
+          return parseAmount((quoteFilled / filled).toFixed(assetSpec(market.quote).decimals), market.quote);
+        } catch {
+          return;
+        }
+      })()
+    } : {},
+    raw
+  };
+}
+function readBinanceError(error) {
+  const body = error.body;
+  if (!body?.code)
+    return;
+  const known = {
+    [-1013]: ["MIN_NOTIONAL", "The order is below the venue minimum, or off its lot or tick step."],
+    [-2010]: ["MIN_NOTIONAL", "Rejected: insufficient balance, or below the minimum."],
+    [-1111]: ["LOT_STEP", "More decimal places than this market accepts."],
+    [-1121]: ["UNKNOWN_MARKET", "That symbol is not traded on this venue."]
+  };
+  const match = known[body.code];
+  return match ? new VenueError(match[0], `${match[1]} (${body.msg})`) : undefined;
+}
+export {
+  toOrderStatus,
+  readBinanceError,
+  createBinanceAdapter,
+  binanceSymbol
+};

package/dist/finance/chain-addresses.d.ts

@@ -0,0 +1,130 @@
+import { depositAddress, toChecksumAddress } from './custody';
+import type { AddressScheme, ChainSpec } from './chain';
+/**
+ * One deposit address per user per chain, derived rather than allocated.
+ *
+ * The naive design gives each user a real account created on-chain. That costs
+ * gas per user before they have deposited anything, so onboarding a hundred
+ * thousand people costs real money for the ones who never fund. Worse, the
+ * address list becomes state: lose it and the deposits keep arriving somewhere
+ * nobody is watching.
+ *
+ * A counterfactual CREATE2 address costs nothing. The contract that would live
+ * there is not deployed until there is something to sweep out of it, and until
+ * then it is a pure function of (factory, salt, init code hash). The whole
+ * address book is therefore reproducible from a backup of three values, and
+ * "restore the deposit addresses" stops being a recovery procedure at all.
+ *
+ * ## What this adds over `custody.ts`
+ *
+ * Almost nothing, deliberately. `custody.depositAddress` already mirrors the
+ * deployed factory byte for byte, and `chain.validateAddress` already knows the
+ * shape of every scheme. What was missing is the CONVENTION on top: which salt
+ * a given user on a given chain gets, and the refusal to answer at all for a
+ * chain whose scheme has no counterfactual derivation.
+ *
+ * Re-exporting rather than reimplementing is the point. Two functions that both
+ * compute a deposit address are two chances to disagree, and the one that
+ * disagrees sends money somewhere unreachable.
+ */
+export { validateAddress, type AddressScheme } from './chain';
+/**
+ * Which schemes can derive an address without touching the chain.
+ *
+ * Only EVM, today. Bitcoin's equivalent is an HD derivation path and Solana's
+ * is a program-derived address — both are real designs and neither is this one,
+ * so a chain using them must not silently fall through to a formula written for
+ * something else. Listing what IS supported rather than excluding what is not
+ * means adding a chain fails closed.
+ */
+export declare const COUNTERFACTUAL_SCHEMES: readonly AddressScheme[];
+export declare class AddressError extends Error {
+    readonly code: 'SCHEME_UNSUPPORTED' | 'CHAIN_DISABLED' | 'MISSING_DEPLOYMENT' | 'MALFORMED';
+    constructor(code: 'SCHEME_UNSUPPORTED' | 'CHAIN_DISABLED' | 'MISSING_DEPLOYMENT' | 'MALFORMED', message: string);
+}
+/**
+ * Where a chain's factory lives, and what it deploys.
+ *
+ * `proxyInitCodeHash` is read from the DEPLOYED factory rather than compiled in.
+ * A Solidity version bump changes the init code and therefore every address
+ * derived from it; a hardcoded constant would keep deriving addresses the live
+ * factory cannot sweep, and the failure appears only once somebody has already
+ * sent funds to one.
+ */
+export interface ChainDeployment {
+    chain: string;
+    factory: string;
+    proxyInitCodeHash: string;
+}
+/**
+ * The salt for one owner on one chain.
+ *
+ * The CHAIN is inside the salt even though each chain has its own factory. Two
+ * chains that deploy the factory to the same address — which happens, because a
+ * deterministic deployer is the normal way to deploy one — would otherwise
+ * derive the same deposit address for the same user on both. That is not
+ * immediately a loss, but it makes the address ambiguous in every log, alert
+ * and support conversation afterwards, and it costs nothing to prevent here.
+ */
+export declare const depositSaltFor: (args: {
+    chain: string;
+    owner: string;
+}) => string;
+/**
+ * The deposit address for one owner on one chain.
+ *
+ * Pure: same inputs, same answer, forever. That property is what lets a scanner
+ * recompute the whole address book on every pass instead of trusting a stored
+ * list, and what makes a stored list a cache rather than a record.
+ */
+export declare function deriveDepositAddress(args: {
+    chain: ChainSpec;
+    deployment: ChainDeployment;
+    owner: string;
+}): string;
+/**
+ * The raw CREATE2 formula, exposed for anything deriving something else.
+ *
+ * A thin alias over `custody.depositAddress` so callers with their own salt
+ * convention — a per-invoice address, say — do not reach past this module and
+ * end up with a second copy of the formula.
+ */
+export declare const create2Address: typeof depositAddress;
+/**
+ * Every address to watch on one chain, for a set of owners.
+ *
+ * The scanner needs the whole set on every pass, keyed for lookup rather than
+ * listed: matching a block's transfers against an array is a scan per transfer,
+ * and a busy block against a large user base is where that becomes the reason a
+ * deposit is late.
+ *
+ * Keyed LOWERCASE. Chains report addresses in whatever case they please, and a
+ * checksum-cased key silently fails to match a lowercase one — a deposit that
+ * arrives, is seen, and is not credited.
+ */
+export declare function depositAddressBook(args: {
+    chain: ChainSpec;
+    deployment: ChainDeployment;
+    owners: readonly string[];
+}): Map<string, string>;
+/**
+ * Whose address is this, if anyone's?
+ *
+ * Case-insensitive for the reason above. Returns `null` rather than throwing:
+ * most addresses in any block belong to nobody here, and that is the normal
+ * case rather than an error.
+ */
+export declare const ownerOfAddress: (book: Map<string, string>, address: string) => string | null;
+/**
+ * Check a derived address against what the chain actually reports.
+ *
+ * Worth doing once per deployment, not per address: if these disagree the
+ * formula and the factory have diverged, and every address derived since is
+ * wrong. Comparing case-insensitively because the checksum casing is a display
+ * convention — a mismatch that is only casing is not a divergence.
+ */
+export declare function assertDerivationMatches(args: {
+    derived: string;
+    reportedByChain: string;
+}): void;
+export { toChecksumAddress };