@oracle-agent/oracle 0.1.0

package/src/data/providers/uniswap-v3.mjs

@@ -0,0 +1,303 @@
+// Uniswap V3 QuoterV2 — exact-input quotes via eth_call (no API key).
+// Chains: Ethereum, Base, Arbitrum. Read-only; never signs or swaps.
+
+import { Interface, getAddress, isAddress } from "ethers";
+import { rpcCall } from "./evm-rpc.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+
+/** @type {Record<number, { quoter: string, weth: string, usdc: string, name: string }>} */
+export const UNI_V3_CHAINS = {
+  1: {
+    name: "ethereum",
+    quoter: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+    router: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  8453: {
+    name: "base",
+    quoter: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+    router: "0x2626664c2603336E57B271c5C0b26F421741e481",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  42161: {
+    name: "arbitrum",
+    quoter: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+    router: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    weth: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  },
+};
+
+export const UNI_V3_FEE_TIERS = [100, 500, 3000, 10000];
+
+const QUOTER_IFACE = new Interface([
+  "function quoteExactInputSingle((address tokenIn, address tokenOut, uint256 amountIn, uint24 fee, uint160 sqrtPriceLimitX96) params) returns (uint256 amountOut, uint160 sqrtPriceX96After, uint32 initializedTicksCrossed, uint256 gasEstimate)",
+  "function quoteExactInput(bytes path, uint256 amountIn) returns (uint256 amountOut, uint160[] sqrtPriceX96AfterList, uint32[] initializedTicksCrossedList, uint256 gasEstimate)",
+]);
+
+const ROUTER_IFACE = new Interface([
+  "function exactInputSingle((address tokenIn,address tokenOut,uint24 fee,address recipient,uint256 amountIn,uint256 amountOutMinimum,uint160 sqrtPriceLimitX96) params) payable returns (uint256 amountOut)",
+  "function multicall(uint256 deadline,bytes[] data) payable returns (bytes[] results)",
+]);
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+const ZERO = "0x0000000000000000000000000000000000000000";
+
+function chainMeta(chainId) {
+  const id = Number(chainId);
+  const m = UNI_V3_CHAINS[id];
+  if (!m) {
+    throw new Error(
+      `uniswap-v3: unsupported chainId ${chainId} (supported: ${Object.keys(UNI_V3_CHAINS).join(", ")})`
+    );
+  }
+  return { chainId: id, ...m };
+}
+
+function normalizeToken(addr, chainId) {
+  const meta = UNI_V3_CHAINS[Number(chainId)];
+  if (!addr || addr === NATIVE || addr === ZERO || /^eth$/i.test(String(addr))) {
+    return getAddress(meta.weth);
+  }
+  const s = String(addr);
+  if (/^weth$/i.test(s)) return getAddress(meta.weth);
+  if (/^usdc$/i.test(s)) return getAddress(meta.usdc);
+  if (!isAddress(s)) throw new Error(`invalid token address: ${addr}`);
+  return getAddress(s);
+}
+
+function encodePath(tokens, fees) {
+  // path = token0 (20) + fee (3) + token1 (20) [+ fee + token2 ...]
+  if (tokens.length !== fees.length + 1) {
+    throw new Error("path: fees.length must be tokens.length - 1");
+  }
+  let hex = "0x";
+  for (let i = 0; i < fees.length; i++) {
+    hex += tokens[i].slice(2).toLowerCase();
+    hex += Number(fees[i]).toString(16).padStart(6, "0");
+  }
+  hex += tokens[tokens.length - 1].slice(2).toLowerCase();
+  return hex;
+}
+
+/**
+ * Quote exact-input single hop via QuoterV2.
+ * @param {object} q
+ * @param {number} q.chainId
+ * @param {string} [q.tokenIn] default WETH
+ * @param {string} [q.tokenOut] default USDC
+ * @param {string|number|bigint} q.amountIn  raw wei/base units
+ * @param {number} [q.fee] 100|500|3000|10000 — if omitted, tries tiers best-out
+ */
+export async function uniV3QuoteExactIn(q = {}, opts = {}) {
+  const { chainId, quoter, router } = chainMeta(q.chainId ?? 8453);
+  const tokenIn = normalizeToken(q.tokenIn || "WETH", chainId);
+  const tokenOut = normalizeToken(q.tokenOut || UNI_V3_CHAINS[chainId].usdc, chainId);
+  const amountIn = BigInt(q.amountIn ?? 0);
+  if (amountIn <= 0n) throw new Error("amountIn required (raw base units)");
+
+  const fees =
+    q.fee != null
+      ? [Number(q.fee)]
+      : q.tryFees === false
+        ? [3000]
+        : [...UNI_V3_FEE_TIERS];
+
+  const results = [];
+  let best = null;
+
+  for (const fee of fees) {
+    const data = QUOTER_IFACE.encodeFunctionData("quoteExactInputSingle", [
+      {
+        tokenIn,
+        tokenOut,
+        amountIn,
+        fee,
+        sqrtPriceLimitX96: 0n,
+      },
+    ]);
+    try {
+      const raw = await rpcCall(chainId, "eth_call", [{ to: quoter, data }, "latest"], opts);
+      if (!raw || raw === "0x") {
+        results.push({ fee, ok: false, error: "empty result" });
+        continue;
+      }
+      const decoded = QUOTER_IFACE.decodeFunctionResult("quoteExactInputSingle", raw);
+      const row = {
+        fee,
+        ok: true,
+        amountOut: decoded[0].toString(),
+        sqrtPriceX96After: decoded[1].toString(),
+        initializedTicksCrossed: Number(decoded[2]),
+        gasEstimate: decoded[3].toString(),
+      };
+      results.push(row);
+      if (!best || BigInt(row.amountOut) > BigInt(best.amountOut)) best = row;
+    } catch (e) {
+      results.push({ fee, ok: false, error: String(e.message || e).slice(0, 160) });
+    }
+  }
+
+  if (!best) {
+    const err = results.map((r) => `${r.fee}:${r.error || "fail"}`).join("; ");
+    throw new Error(`uniswap-v3 quote failed chain=${chainId}: ${err}`);
+  }
+
+  return attachAutoSlippage({
+    venue: "uniswap-v3",
+    chainId,
+    chain: UNI_V3_CHAINS[chainId].name,
+    quoter,
+    tokenIn,
+    tokenOut,
+    amountIn: amountIn.toString(),
+    fee: best.fee,
+    amountOut: best.amountOut,
+    gasEstimate: best.gasEstimate,
+    sqrtPriceX96After: best.sqrtPriceX96After,
+    initializedTicksCrossed: best.initializedTicksCrossed,
+    triedFees: results,
+    best: true,
+  }, {
+    chainId,
+    venue: router,
+    amountOut: best.amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+/**
+ * Multi-hop exact input. pathTokens + pathFees.
+ * e.g. tokens [WETH, USDC], fees [500]
+ */
+export async function uniV3QuoteExactInPath(q = {}, opts = {}) {
+  const { chainId, quoter, router } = chainMeta(q.chainId ?? 8453);
+  const tokens = (q.tokens || []).map((t) => normalizeToken(t, chainId));
+  const fees = (q.fees || []).map(Number);
+  if (tokens.length < 2) throw new Error("tokens[] need at least 2 addresses");
+  const amountIn = BigInt(q.amountIn ?? 0);
+  if (amountIn <= 0n) throw new Error("amountIn required");
+
+  const path = encodePath(tokens, fees);
+  const data = QUOTER_IFACE.encodeFunctionData("quoteExactInput", [path, amountIn]);
+  const raw = await rpcCall(chainId, "eth_call", [{ to: quoter, data }, "latest"], opts);
+  const decoded = QUOTER_IFACE.decodeFunctionResult("quoteExactInput", raw);
+
+  return attachAutoSlippage({
+    venue: "uniswap-v3",
+    chainId,
+    chain: UNI_V3_CHAINS[chainId].name,
+    quoter,
+    tokens,
+    fees,
+    path,
+    amountIn: amountIn.toString(),
+    amountOut: decoded[0].toString(),
+    gasEstimate: decoded[3].toString(),
+  }, {
+    chainId,
+    venue: router,
+    amountOut: decoded[0].toString(),
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+/** Convenience: WETH → USDC for amountIn wei (default 0.001 ETH). */
+export async function uniV3EthUsdc(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 8453);
+  const amountIn = q.amountIn ?? "1000000000000000"; // 0.001 ether
+  const quote = await uniV3QuoteExactIn(
+    {
+      chainId,
+      tokenIn: UNI_V3_CHAINS[chainId].weth,
+      tokenOut: UNI_V3_CHAINS[chainId].usdc,
+      amountIn,
+      fee: q.fee,
+    },
+    opts
+  );
+  const usdc = Number(quote.amountOut) / 1e6;
+  return { ...quote, amountOutUsdc: usdc, pair: "WETH/USDC" };
+}
+
+export async function uniV3PrepareExactIn(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 8453);
+  const meta = chainMeta(chainId);
+  const recipient = getAddress(q.recipient);
+  const inputRaw = String(q.tokenIn || "WETH");
+  const nativeInput = !q.tokenIn || inputRaw === NATIVE || inputRaw === ZERO || /^eth$/i.test(inputRaw);
+  const quote = await uniV3QuoteExactIn(q, opts);
+  const exact = ROUTER_IFACE.encodeFunctionData("exactInputSingle", [{
+    tokenIn: quote.tokenIn,
+    tokenOut: quote.tokenOut,
+    fee: quote.fee,
+    recipient,
+    amountIn: BigInt(quote.amountIn),
+    amountOutMinimum: BigInt(quote.amountOutMinimum),
+    sqrtPriceLimitX96: 0n,
+  }]);
+  const deadlineWindow = Math.min(600, Math.max(30, Number(q.deadlineSeconds ?? 300)));
+  const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
+  const deadline = nowSeconds + deadlineWindow;
+  const data = ROUTER_IFACE.encodeFunctionData("multicall", [deadline, [exact]]);
+  return {
+    provider: "uniswap-v3",
+    calldataReady: true,
+    // NOT executable authority. The bytes are assembled but nothing is signed:
+    // the user's wallet is still the only thing that can authorize this. The
+    // previous `executionReady: true` read as "cleared to execute" and trained
+    // agents to treat a quote as permission.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    chainId,
+    deadline,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: nativeInput ? null : {
+      token: quote.tokenIn,
+      spender: meta.router,
+      amount: quote.amountIn,
+    },
+    transaction: {
+      chainId,
+      from: recipient,
+      to: meta.router,
+      data,
+      value: nativeInput ? quote.amountIn : "0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: meta.router, data }),
+    },
+  };
+}
+
+export async function uniV3Health(opts = {}) {
+  const chainId = Number(opts.chainId ?? 8453);
+  try {
+    const q = await uniV3EthUsdc({ chainId, amountIn: "1000000000000000" }, opts);
+    return {
+      ok: true,
+      chainId,
+      fee: q.fee,
+      amountOutUsdc: q.amountOutUsdc,
+      midPxHint: q.amountOutUsdc / 0.001,
+    };
+  } catch (e) {
+    return { ok: false, chainId, error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function uniV3Chains() {
+  return Object.entries(UNI_V3_CHAINS).map(([id, m]) => ({
+    chainId: Number(id),
+    name: m.name,
+    quoter: m.quoter,
+    weth: m.weth,
+    usdc: m.usdc,
+  }));
+}

package/src/data/providers/zerox.mjs

@@ -0,0 +1,166 @@
+// 0x Swap API v2 — price/quote. Requires ZEROX_API_KEY (or 0X_API_KEY).
+
+import { httpJson } from "../http.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
+import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+
+export const ZEROX_API = "https://api.0x.org";
+
+function endpoint(opts = {}) {
+  return resolveProviderEndpoint({
+    provider: "zerox",
+    defaultUrl: ZEROX_API,
+    hosts: ["api.0x.org"],
+    url: opts.baseUrl || process.env.ZEROX_API_URL,
+  });
+}
+
+function base(opts = {}) {
+  return endpoint(opts).baseUrl;
+}
+
+function apiKey(opts = {}) {
+  return (
+    opts.apiKey ||
+    process.env.ZEROX_API_KEY ||
+    process.env.OX_API_KEY ||
+    process.env["0X_API_KEY"] ||
+    ""
+  );
+}
+
+function headers(opts = {}) {
+  return credentialedHeaders(
+    { "0x-version": "v2", accept: "application/json" },
+    { "0x-api-key": apiKey(opts) },
+    endpoint(opts).trusted
+  );
+}
+
+export async function zeroxHealth(opts = {}) {
+  if (!apiKey(opts)) {
+    return { ok: false, configured: false, error: "ZEROX_API_KEY not set" };
+  }
+  try {
+    const q = await zeroxPrice(
+      {
+        chainId: 8453,
+        sellToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+        buyToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        sellAmount: "1000000000000000",
+      },
+      opts
+    );
+    return { ok: true, configured: true, buyAmount: q.buyAmount || q.grossBuyAmount };
+  } catch (e) {
+    return { ok: false, configured: true, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+/** Indicative price (no firm quote). */
+export async function zeroxPrice(q = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("ZEROX_API_KEY required for 0x");
+  const {
+    chainId = 8453,
+    sellToken,
+    buyToken,
+    sellAmount,
+    taker,
+  } = q;
+  if (!sellToken || !buyToken || !sellAmount) {
+    throw new Error("zeroxPrice requires sellToken, buyToken, sellAmount");
+  }
+  const params = new URLSearchParams({
+    chainId: String(chainId),
+    sellToken,
+    buyToken,
+    sellAmount: String(sellAmount),
+  });
+  if (taker) params.set("taker", taker);
+  return httpJson(`${base(opts)}/swap/allowance-holder/price?${params}`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}
+
+/** Firm quote (may include transaction). */
+export async function zeroxQuote(q = {}, opts = {}) {
+  if (!apiKey(opts)) throw new Error("ZEROX_API_KEY required for 0x");
+  const {
+    chainId = 8453,
+    sellToken,
+    buyToken,
+    sellAmount,
+    taker,
+  } = q;
+  if (!sellToken || !buyToken || !sellAmount) {
+    throw new Error("zeroxQuote requires sellToken, buyToken, sellAmount");
+  }
+  const selected = resolveAutoSlippage({
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+  if (!selected.executable) {
+    throw new Error(`0x: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
+  }
+  const params = new URLSearchParams({
+    chainId: String(chainId),
+    sellToken,
+    buyToken,
+    sellAmount: String(sellAmount),
+    slippageBps: String(selected.selectedBps),
+  });
+  if (taker) params.set("taker", taker);
+  const result = await httpJson(`${base(opts)}/swap/allowance-holder/quote?${params}`, {
+    headers: headers(opts),
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+  const amountOut = result?.buyAmount || result?.grossBuyAmount;
+  if (!amountOut) return { ...result, autoSlippagePolicy: selected };
+  return attachAutoSlippage(result, {
+    chainId,
+    venue: result?.transaction?.to || result?.to || "0x",
+    amountOut,
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+export async function zeroxPrepare(q = {}, opts = {}) {
+  if (!q.taker) throw new Error("0x: taker required for executable prepare");
+  const quote = await zeroxQuote(q, opts);
+  const tx = quote?.transaction;
+  if (!tx?.to || !tx?.data) throw new Error("0x: firm quote returned no transaction");
+  const chainId = Number(q.chainId ?? 8453);
+  const spender = quote?.issues?.allowance?.spender || quote?.allowanceTarget;
+  return {
+    provider: "zerox",
+    calldataReady: true,
+    // NOT executable authority. The bytes are assembled but nothing is signed:
+    // the user's wallet is still the only thing that can authorize this. The
+    // previous `executionReady: true` read as "cleared to execute" and trained
+    // agents to treat a quote as permission.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    chainId,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: quote?.issues?.allowance?.actual != null && BigInt(quote.issues.allowance.actual) < BigInt(q.sellAmount)
+      ? { token: q.sellToken, spender, amount: String(q.sellAmount) }
+      : null,
+    transaction: {
+      chainId,
+      from: q.taker,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value ?? "0x0",
+      ...(tx.gas != null ? { gasLimit: tx.gas } : {}),
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
+    },
+  };
+}

package/src/data/public-api-scan.mjs

@@ -0,0 +1,61 @@
+import { dataCatalog, dataHealth } from "./desk-data.mjs";
+
+export const COVERED_CHAINS = Object.freeze({
+  1: "Ethereum",
+  10: "Optimism",
+  56: "BNB Chain",
+  137: "Polygon",
+  988: "Stable",
+  999: "HyperEVM",
+  2741: "Abstract",
+  4663: "Robinhood Chain",
+  8453: "Base",
+  42161: "Arbitrum",
+  43114: "Avalanche",
+});
+
+function providerStatus(record) {
+  if (!record) return "not-probed";
+  if (!record.ok) return "down";
+  if (record.detail?.configured === false) return "key-missing";
+  if (record.detail?.ok === false) return "degraded";
+  return "healthy";
+}
+
+export function buildPublicApiCoverage(catalog, health) {
+  const globals = catalog.filter((p) => !p.chainIds.length).map((p) => p.id);
+  const providers = Object.fromEntries(catalog.map((p) => [p.id, {
+    venue: p.venue,
+    auth: p.auth,
+    chainIds: p.chainIds,
+    ops: p.ops,
+    description: p.description,
+    status: providerStatus(health?.providers?.[p.id]),
+    probe: health?.providers?.[p.id] || null,
+  }]));
+  const chains = {};
+  for (const [chainId, name] of Object.entries(COVERED_CHAINS)) {
+    const id = Number(chainId);
+    const explicit = catalog.filter((p) => p.chainIds.includes(id)).map((p) => p.id);
+    chains[chainId] = {
+      name,
+      providers: [...new Set([...globals, ...explicit])],
+      explicitProviders: explicit,
+      failClosed: explicit.length === 0,
+    };
+  }
+  return {
+    generatedAt: health?.when || new Date().toISOString(),
+    coveredChainCount: Object.keys(COVERED_CHAINS).length,
+    providerCount: catalog.length,
+    globals,
+    chains,
+    providers,
+  };
+}
+
+export async function scanPublicApis({ providers, timeoutMs = 12_000 } = {}) {
+  const catalog = dataCatalog();
+  const health = await dataHealth({ providers, timeoutMs });
+  return buildPublicApiCoverage(catalog, health);
+}

package/src/data/quote-placeholder.mjs

@@ -0,0 +1,31 @@
+// Placeholder addresses for quote-only provider calls.
+//
+// Several aggregator APIs (LI.FI, CoW, bridge quoters) require a `from`/`user`
+// address to price a route, even when nothing will be signed. Hardcoding a real
+// operator wallet as that default is a privacy and correctness bug: public users
+// would silently quote against someone else's account, and balance-aware routers
+// can return routes tailored to that stranger's holdings.
+//
+// So: callers SHOULD pass their own address. When they don't, we fall back to a
+// well-known burn/zero-ish placeholder that holds nothing and signs nothing.
+//
+// vitalik.eth is deliberately NOT used here either -- a placeholder must be
+// obviously inert, not a real person's account.
+
+/**
+ * ERC-191 "dead" address. Universally recognizable as a placeholder, holds no
+ * meaningful balance, and cannot sign. Safe default for price-only queries.
+ */
+export const QUOTE_PLACEHOLDER_ADDRESS =
+  "0x000000000000000000000000000000000000dEaD";
+
+/**
+ * Resolve the address to use for a quote-only request.
+ *
+ * @param {string} [preferred] caller-supplied address (their own wallet)
+ * @returns {string} the caller's address when usable, else the inert placeholder
+ */
+export function quoteAddress(preferred) {
+  const v = String(preferred || "").trim();
+  return /^0x[0-9a-fA-F]{40}$/.test(v) ? v : QUOTE_PLACEHOLDER_ADDRESS;
+}

package/src/exact-integer.mjs

@@ -0,0 +1,72 @@
+// Exact integer parsing for anything that bounds money.
+//
+// A JS number cannot represent every uint256, and above 2^53 it silently
+// rounds — usually UPWARD, which widens a cap past what the user wrote.
+// `9007199254740995` becomes `...996`. Every guard, allowance, and policy
+// ceiling must therefore refuse unsafe numbers rather than quietly storing a
+// different value than the caller asked for.
+//
+// This lives in one place because the same bug was found independently in
+// token-transfer-guard, approval-guard, session grants, and exec-policy.
+
+/**
+ * Parse a value into an exact non-negative BigInt.
+ * Accepts: decimal string, BigInt, or a safe-integer number.
+ * Refuses: non-integers, unsafe numbers, and unparseable input.
+ */
+export function exactBigInt(value, label = "amount") {
+  if (typeof value === "bigint") return value;
+
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new Error(`${label} must be an integer`);
+    }
+    if (!Number.isSafeInteger(value)) {
+      throw new Error(
+        `${label} exceeds safe integer precision — pass it as a decimal string or BigInt so the exact value is preserved`
+      );
+    }
+    return BigInt(value);
+  }
+
+  const text = String(value ?? "").trim();
+  if (text === "") throw new Error(`${label} is required`);
+  // Reject scientific notation and floats outright: BigInt("1e3") throws, but
+  // Number("1e3") would silently succeed if a caller coerced first.
+  if (!/^-?\d+$/.test(text) && !/^0x[0-9a-fA-F]+$/.test(text)) {
+    throw new Error(`${label} must be an integer in decimal or 0x-hex form, got ${JSON.stringify(text)}`);
+  }
+  try {
+    return BigInt(text);
+  } catch {
+    throw new Error(`${label} must be an integer, got ${JSON.stringify(text)}`);
+  }
+}
+
+/** As exactBigInt, but also requires the value to be strictly positive. */
+export function exactPositiveBigInt(value, label = "amount") {
+  const n = exactBigInt(value, label);
+  if (n <= 0n) throw new Error(`${label} must be positive`);
+  return n;
+}
+
+/**
+ * Convert a decimal string to a scaled integer WITHOUT floats.
+ * `toScaledInteger("1.5", 6)` -> 1500000n, and `"01.5"` -> 1500000n.
+ * Leading zeros, missing fractions, and long fractions are all handled by
+ * string arithmetic, so magnitude never affects the scale.
+ */
+export function toScaledInteger(value, decimals, label = "amount") {
+  const text = String(value ?? "").trim();
+  if (!/^-?\d*(\.\d+)?$/.test(text) || text === "" || text === "." || text === "-") {
+    throw new Error(`${label} must be a decimal number, got ${JSON.stringify(text)}`);
+  }
+  const negative = text.startsWith("-");
+  const body = negative ? text.slice(1) : text;
+  const [intPart = "0", fracPart = ""] = body.split(".");
+  if (fracPart.length > decimals) {
+    throw new Error(`${label} has more than ${decimals} decimal places, which would lose precision`);
+  }
+  const scaled = BigInt((intPart || "0") + fracPart.padEnd(decimals, "0"));
+  return negative ? -scaled : scaled;
+}