@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/data/providers/solend-lending.mjs

@@ -0,0 +1,166 @@
+// Save (formerly Solend) — Solana lending markets and reserve rates.
+//
+// Solend rebranded to Save; api.solend.fi is retired and api.save.finance is
+// the live surface. Read-only: market/reserve configuration and current
+// supply/borrow APY. No deposit or borrow preparation lives here.
+
+import { httpJson } from "../http.mjs";
+
+export const SAVE_API = "https://api.save.finance";
+// The canonical "main" pool — used as the health probe and the default market.
+export const SAVE_MAIN_MARKET = "4UpD2fh7xH3VP9QQaXtsS1YY3bxzWhtfpks7FatyKvdY";
+export const SAVE_MAIN_MSOL_RESERVE = "CCpirWrgNuBVLdkP2haxLTbD6XqEgaYuVXixbbpxUB6";
+
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+function base(opts = {}) {
+  return String(opts.baseUrl || process.env.SAVE_API_URL || process.env.SOLEND_API_URL || SAVE_API).replace(/\/$/, "");
+}
+
+function pubkey(value, label = "address") {
+  const text = String(value ?? "").trim();
+  if (!BASE58.test(text)) throw new Error(`solend-lending: ${label} must be a base58 public key`);
+  return text;
+}
+
+function pct(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function normalizeMarket(market = {}) {
+  return {
+    address: market.address || null,
+    name: market.name || null,
+    description: market.description || "",
+    isPrimary: Boolean(market.isPrimary),
+    isPermissionless: Boolean(market.isPermissionless),
+    hidden: Boolean(market.hidden),
+    owner: market.owner || null,
+    authorityAddress: market.authorityAddress || null,
+    lookupTableAddress: market.lookupTableAddress || null,
+    reserveCount: Array.isArray(market.reserves) ? market.reserves.length : 0,
+    reserves: (market.reserves || []).map((r) => ({
+      address: r.address || null,
+      symbol: r.liquidityToken?.symbol || null,
+      name: r.liquidityToken?.name || null,
+      mint: r.liquidityToken?.mint || null,
+      decimals: r.liquidityToken?.decimals ?? null,
+      collateralMint: r.collateralMintAddress || null,
+      pythOracle: r.pythOracle || null,
+      switchboardOracle: r.switchboardOracle || null,
+      volume24h: r.liquidityToken?.volume24h ?? null,
+    })),
+  };
+}
+
+function normalizeReserve(entry = {}) {
+  const reserve = entry.reserve || {};
+  const liquidity = reserve.liquidity || {};
+  const collateral = reserve.collateral || {};
+  return {
+    address: entry.address || reserve.address || null,
+    lendingMarket: reserve.lendingMarket || null,
+    mint: liquidity.mintPubkey || null,
+    mintDecimals: liquidity.mintDecimals ?? null,
+    // Save returns these already as percentages ("26.38" = 26.38% APY).
+    supplyApyPct: pct(entry.rates?.supplyInterest),
+    borrowApyPct: pct(entry.rates?.borrowInterest),
+    cTokenExchangeRate: entry.cTokenExchangeRate ?? null,
+    availableAmount: liquidity.availableAmount ?? null,
+    borrowedAmountWads: liquidity.borrowedAmountWads ?? null,
+    marketPrice: liquidity.marketPrice ?? null,
+    collateralMint: collateral.mintPubkey || null,
+    collateralTotalSupply: collateral.mintTotalSupply ?? null,
+    rewards: entry.rewards || [],
+    lastUpdateSlot: reserve.lastUpdate?.slot ?? null,
+    stale: reserve.lastUpdate?.stale === 1,
+    raw: entry,
+  };
+}
+
+export async function solendHealth(opts = {}) {
+  try {
+    const data = await httpJson(`${base(opts)}/v1/reserves?ids=${SAVE_MAIN_MSOL_RESERVE}`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 15_000,
+    });
+    const results = Array.isArray(data?.results) ? data.results : [];
+    return {
+      ok: results.length > 0,
+      provider: "solend-lending",
+      probeReserve: SAVE_MAIN_MSOL_RESERVE,
+      reserves: results.length,
+      exec: false,
+    };
+  } catch (error) {
+    return { ok: false, provider: "solend-lending", error: String(error?.message || error), exec: false };
+  }
+}
+
+/**
+ * List lending markets. Default scope returns the curated set; scope=all
+ * includes every permissionless pool (200+, noticeably slower).
+ */
+export async function solendMarkets(args = {}, opts = {}) {
+  const url = new URL(`${base(opts)}/v1/markets/configs`);
+  if (args.scope) url.searchParams.set("scope", String(args.scope));
+  if (args.deployment) url.searchParams.set("deployment", String(args.deployment));
+  const data = await httpJson(url.toString(), {
+    fetchImpl: opts.fetchImpl,
+    // scope=all walks every permissionless pool and is genuinely slow upstream.
+    timeoutMs: opts.timeoutMs ?? (args.scope === "all" ? 45_000 : 20_000),
+  });
+  let markets = (Array.isArray(data) ? data : []).map(normalizeMarket);
+  if (args.includeHidden !== true) markets = markets.filter((m) => !m.hidden);
+  if (args.name) {
+    const want = String(args.name).toLowerCase();
+    markets = markets.filter((m) => String(m.name || "").toLowerCase() === want);
+  }
+  const limit = Number(args.limit);
+  if (Number.isFinite(limit) && limit > 0) markets = markets.slice(0, limit);
+  return {
+    provider: "solend-lending",
+    chain: "solana-mainnet-beta",
+    scope: args.scope || "default",
+    count: markets.length,
+    markets,
+  };
+}
+
+/**
+ * Current rates for reserves. Accepts explicit reserve addresses, or a market
+ * address whose reserve set is resolved from the market config first.
+ */
+export async function solendReserves(args = {}, opts = {}) {
+  let ids = [];
+  if (args.ids || args.reserves) {
+    const list = Array.isArray(args.ids || args.reserves) ? args.ids || args.reserves : String(args.ids || args.reserves).split(",");
+    ids = list.map((v) => pubkey(String(v).trim(), "reserve"));
+  } else {
+    const market = pubkey(args.market || args.marketAddress || SAVE_MAIN_MARKET, "market");
+    const config = await solendMarkets({ scope: "all", includeHidden: true }, opts);
+    const found = config.markets.find((m) => m.address === market);
+    if (!found) throw new Error(`solend-lending: market ${market} not found`);
+    ids = found.reserves.map((r) => r.address).filter(Boolean);
+  }
+  if (!ids.length) throw new Error("solend-lending: no reserves to query");
+  const limit = Number.isFinite(Number(args.limit)) && Number(args.limit) > 0 ? Number(args.limit) : 50;
+  ids = ids.slice(0, limit);
+
+  const data = await httpJson(`${base(opts)}/v1/reserves?ids=${ids.join(",")}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 25_000,
+  });
+  const reserves = (Array.isArray(data?.results) ? data.results : []).map((entry, i) => ({
+    ...normalizeReserve(entry),
+    address: entry.address || entry.reserve?.address || ids[i] || null,
+  }));
+  return {
+    provider: "solend-lending",
+    chain: "solana-mainnet-beta",
+    requested: ids.length,
+    count: reserves.length,
+    reserves,
+  };
+}

package/src/data/providers/spark-lend.mjs

@@ -0,0 +1,42 @@
+// Spark Lend / Sky Savings — ERC-4626 vault APY + market data (no API key).
+// Read-only API exposing Spark and Sky Savings Vaults V2.
+
+import { httpJson } from "../http.mjs";
+
+export const SPARK_API = "https://api.spark.fi";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.SPARK_API_URL || SPARK_API).replace(/\/$/, "");
+}
+
+export async function sparkHealth(opts = {}) {
+  try {
+    // Probe the savings endpoint with a known vault
+    const data = await httpJson(`${base(opts)}/v1/savings/spark/mainnet/usdc`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 10_000,
+    });
+    return { ok: data?.data?.vault?.address != null, provider: "spark-lend" };
+  } catch (e) {
+    return { ok: false, provider: "spark-lend", error: String(e.message || e).slice(0, 120) };
+  }
+}
+
+export async function sparkMarkets(args = {}, opts = {}) {
+  const protocol = String(args.protocol || "spark");
+  const chain = String(args.chain || "mainnet");
+  const token = args.token ? String(args.token).toLowerCase() : null;
+
+  if (token) {
+    // Single vault: /v1/savings/{protocol}/{chain}/{token}
+    return httpJson(`${base(opts)}/v1/savings/${encodeURIComponent(protocol)}/${encodeURIComponent(chain)}/${encodeURIComponent(token)}`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 15_000,
+    });
+  }
+  // All vaults for protocol + chain
+  return httpJson(`${base(opts)}/v1/savings/${encodeURIComponent(protocol)}/${encodeURIComponent(chain)}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 15_000,
+  });
+}

package/src/data/providers/squid-router.mjs

@@ -0,0 +1,29 @@
+// Squid Router — Axelar-powered cross-chain bridge + swap.
+// https://docs.squidrouter.com — public REST API, no key.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const SQUID_API = "https://api.squidrouter.com/v1";
+
+export async function squidQuote({ fromChain, toChain, fromToken, toToken, fromAmount, fromAddress, slippage = 1.0 } = {}) {
+  if (!fromChain || !toChain || !fromToken || !toToken || !fromAmount || !fromAddress) {
+    return { error: "squid quote requires fromChain, toChain, fromToken, toToken, fromAmount, fromAddress" };
+  }
+  try {
+    const body = { fromChain, toChain, fromToken, toToken, fromAmount: String(fromAmount), fromAddress, slippage };
+    const data = await httpJson(`${SQUID_API}/route`, { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json" } });
+    return { route: data?.route ?? {}, toAmount: data?.route?.estimate?.toAmount, fee: data?.route?.estimate?.feeCosts };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function squidHealth() {
+  try {
+    const tokens = await httpJson(`${SQUID_API}/tokens`);
+    return { ok: true, tokenCount: tokens?.tokens?.length ?? 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/stargate.mjs

@@ -0,0 +1,29 @@
+// Stargate — LayerZero cross-chain bridge. Highest TVL bridge protocol.
+// https://stargateprotocol.gitbook.io/stargate — public REST API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const STARGATE_API = "https://api.stargate.finance";
+
+export async function stargateQuote({ srcChainId, dstChainId, token, amount, dstGasForCall = 0, minAmountOut = "0" } = {}) {
+  if (!srcChainId || !dstChainId || !token || !amount) {
+    return { error: "stargate quote requires srcChainId, dstChainId, token, amount" };
+  }
+  try {
+    const params = new URLSearchParams({ srcChainId: String(srcChainId), dstChainId: String(dstChainId), token, amount: String(amount), dstGasForCall: String(dstGasForCall), minAmountOut: String(minAmountOut) });
+    const data = await httpJson(`${STARGATE_API}/quote?${params}`);
+    return { amountOut: data?.amountOut, fee: data?.fee, estimatedTime: data?.estimatedTime };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function stargateHealth() {
+  try {
+    const chains = ["ethereum", "arbitrum", "optimism", "base", "bsc", "polygon", "avalanche"];
+    return { ok: true, supportedChains: chains };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/sushiswap.mjs

@@ -0,0 +1,30 @@
+// SushiSwap — multi-chain DEX with v3 concentrated liquidity.
+// https://docs.sushi.com — public subgraph APIs across 30+ chains.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+const SUSHI_SUBGRAPH = (chainId) => `https://api.thegraph.com/subgraphs/name/sushi-v3/v3-${chainIdMap[chainId] || "ethereum"}`;
+
+const chainIdMap = { 1: "ethereum", 10: "optimism", 56: "bsc", 137: "polygon", 8453: "base", 42161: "arbitrum", 43114: "avalanche", 59144: "linea", 534352: "scroll", 324: "zksync-era", 250: "fantom", 2222: "kava", 1088: "metis", 1284: "moonbeam", 1285: "moonriver", 288: "boba", 1101: "polygon-zkevm", 5000: "mantle", 81457: "blast" };
+
+export async function sushiQuote({ chainId = 1, tokenIn, tokenOut, amountIn, fee = 500 } = {}) {
+  if (!tokenIn || !tokenOut || !amountIn) {
+    return { error: "sushi quote requires tokenIn, tokenOut, amountIn" };
+  }
+  try {
+    const query = `{ quote(tokenIn:"${tokenIn}",tokenOut:"${tokenOut}",amountIn:"${amountIn}",fee:${fee}) { amountOut route } }`;
+    const data = await httpJson(`${SUSHI_SUBGRAPH(chainId)}/quote?query=${encodeURIComponent(query)}`);
+    return { amountOut: data?.data?.quote?.amountOut, route: data?.data?.quote?.route };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function sushiHealth() {
+  try {
+    return { ok: true, chains: Object.keys(chainIdMap).length + " chains" };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/symbiotic-restaking.mjs

@@ -0,0 +1,41 @@
+// Symbiotic restaking — vaults, collateral data, operator stats (no API key).
+
+import { httpJson } from "../http.mjs";
+
+export const SYMBIOTIC_API = "https://api.symbiotic.fi";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.SYMBIOTIC_API_URL || SYMBIOTIC_API).replace(/\/$/, "");
+}
+
+export async function symbioticHealth(opts = {}) {
+  try {
+    const data = await httpJson(`${base(opts)}/v1/vaults`, {
+      fetchImpl: opts.fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 15_000,
+    });
+    return { ok: Array.isArray(data) && data.length > 0, provider: "symbiotic-restaking", count: data.length };
+  } catch (e) {
+    return { ok: false, provider: "symbiotic-restaking", error: String(e.message || e).slice(0, 120) };
+  }
+}
+
+export async function symbioticVaults(args = {}, opts = {}) {
+  const limit = Math.min(200, Math.max(1, Number(args.limit || 50)));
+  const data = await httpJson(`${base(opts)}/v1/vaults?limit=${limit}&offset=${Math.max(0, Number(args.offset || 0))}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  // Filter by approved if requested
+  if (args.approvedOnly) return data.filter((v) => v.approved === true);
+  return data;
+}
+
+export async function symbioticVaultDetail(args = {}, opts = {}) {
+  const address = String(args.address || "").trim();
+  if (!address) throw new Error("symbiotic-restaking: address is required");
+  return httpJson(`${base(opts)}/v1/vaults/${encodeURIComponent(address)}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}

package/src/data/providers/thorchain.mjs

@@ -0,0 +1,36 @@
+// THORChain — native cross-chain swaps. No wrapped tokens.
+// Midgard public API: https://midgard.ninerealms.com/v2/doc
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const THORCHAIN_API = "https://midgard.ninerealms.com/v2";
+
+export async function thorchainQuote({ fromAsset, toAsset, amount, destination } = {}) {
+  if (!fromAsset || !toAsset || !amount) {
+    return { error: "thorchain quote requires fromAsset, toAsset, amount" };
+  }
+  try {
+    const params = new URLSearchParams({ from_asset: fromAsset, to_asset: toAsset, amount: String(amount), destination: destination || "" });
+    const data = await httpJson(`${THORCHAIN_API}/quote/swap?${params}`);
+    return {
+      expectedAmountOut: data?.expected_amount_out,
+      fees: data?.fees,
+      slippageBps: data?.slippage_bps,
+      inboundAddress: data?.inbound_address,
+      memo: data?.memo,
+      estimatedTime: data?.total_swap_seconds ? `${Math.round(data.total_swap_seconds / 60)} min` : "unknown",
+    };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function thorchainHealth() {
+  try {
+    const data = await httpJson(`${THORCHAIN_API}/health`);
+    return { ok: data?.scannerHeight > 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/traderjoe.mjs

@@ -0,0 +1,28 @@
+// Trader Joe — Avalanche's largest DEX (v2.1 Liquidity Book).
+// https://docs.traderjoexyz.com — public subgraph API.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+const JOE_SUBGRAPH = "https://subgraph.satsuma-prod.com/traderjoe-xyz/joe-v2-avalanche/api";
+
+export async function joeQuote({ tokenIn, tokenOut, amountIn } = {}) {
+  if (!tokenIn || !tokenOut || !amountIn) {
+    return { error: "joe quote requires tokenIn, tokenOut, amountIn" };
+  }
+  try {
+    const query = `{ quote(tokenIn:"${tokenIn}",tokenOut:"${tokenOut}",amountIn:"${amountIn}") { amountOut route } }`;
+    const data = await httpJson(`${JOE_SUBGRAPH}/quote?query=${encodeURIComponent(query)}`);
+    return { amountOut: data?.data?.quote?.amountOut, route: data?.data?.quote?.route };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function joeHealth() {
+  try {
+    return { ok: true, chains: ["Avalanche (43114), Arbitrum (42161), BSC (56)"] };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/twap.mjs

@@ -0,0 +1,152 @@
+// TWAP (time-weighted average price) DCA execution engine.
+//
+// Splits a single large order into equal-sized chunks spaced evenly over a
+// configurable window. Each chunk executes independently; the aggregator
+// uses the best available route at execution time rather than locking in
+// a single venue upfront.
+//
+// Custody: prepare-only. Every chunk is an unsigned transaction artifact.
+// This module never signs, never broadcasts, never touches key material.
+
+import { bestSwapRoute } from "../../router/index.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
+
+const MIN_SPLITS = 2;
+const MAX_SPLITS = 100;
+const MIN_WINDOW_SEC = 60;       // 1 minute
+const DEFAULT_SPLITS = 10;
+const DEFAULT_WINDOW_HOURS = 6;
+
+/**
+ * Validate and normalize TWAP parameters.
+ * @param {{ amount: string|bigint, chainId: number, tokenIn: string, tokenOut: string, splits?: number, windowHours?: number, taker: string, slippageBps?: number }} params
+ */
+export function normalizeTwapParams(params = {}) {
+  const splits = Math.max(MIN_SPLITS, Math.min(MAX_SPLITS, Number(params.splits) || DEFAULT_SPLITS));
+  const windowHours = Math.max(0.1, Number(params.windowHours) || DEFAULT_WINDOW_HOURS);
+  const windowSec = Math.max(MIN_WINDOW_SEC, windowHours * 3600);
+  const chunkSize = BigInt(params.amount) / BigInt(splits);
+  const intervalSec = Math.floor(windowSec / splits);
+  const slippageBps = Number(params.slippageBps) || 100;
+
+  if (!params.chainId) throw new Error("twap requires chainId");
+  if (!params.tokenIn || !params.tokenOut) throw new Error("twap requires tokenIn and tokenOut");
+  if (!params.taker) throw new Error("twap requires taker address");
+  if (BigInt(params.amount) <= 0n) throw new Error("twap amount must be positive");
+
+  return {
+    chainId: Number(params.chainId),
+    tokenIn: String(params.tokenIn),
+    tokenOut: String(params.tokenOut),
+    amount: String(params.amount),
+    splits,
+    chunkSize: String(chunkSize),
+    windowHours,
+    windowSec,
+    intervalSec,
+    taker: String(params.taker),
+    slippageBps,
+    status: "planned",
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Generate the split schedule. Returns an array of { splitIndex, executeAfter (ISO), chunkSize }.
+ */
+export function buildTwapSchedule(params) {
+  const p = normalizeTwapParams(params);
+  const now = Math.floor(Date.now() / 1000);
+  const schedule = [];
+  for (let i = 0; i < p.splits; i++) {
+    schedule.push({
+      splitIndex: i + 1,
+      executeAfter: new Date((now + i * p.intervalSec) * 1000).toISOString(),
+      chunkSize: p.chunkSize,
+    });
+  }
+  return { params: p, schedule };
+}
+
+/**
+ * Prepare a single TWAP chunk — quote + unsigned swap artifact.
+ * Same custody contract as oracle swap: requiresWalletSignature, backendSigner false.
+ */
+export async function prepareTwapChunk(twap, splitIndex, { chainId, tokenIn, tokenOut, chunkSize, taker, slippageBps } = twap.params) {
+  if (splitIndex < 1 || splitIndex > twap.params.splits) {
+    throw new Error(`splitIndex ${splitIndex} out of range 1-${twap.params.splits}`);
+  }
+  const route = await bestSwapRoute({
+    chainId,
+    tokenIn,
+    tokenOut,
+    amountIn: chunkSize,
+    taker,
+  });
+
+  const prepared = stampPrepared(route.transaction ?? route.tx, {
+    chainId,
+    taker,
+    tokenIn,
+    tokenOut,
+    amountIn: chunkSize,
+    slippageBps,
+    kind: "twap",
+    splitIndex,
+    totalSplits: twap.params.splits,
+  });
+
+  return {
+    splitIndex,
+    chunkSize,
+    quote: {
+      amountOut: route.amountOut ?? route.quote?.amountOut,
+      source: route.source ?? route.venue,
+      priceImpact: route.priceImpact,
+    },
+    ...prepared,
+  };
+}
+
+/**
+ * Simulate a full TWAP run: quote every chunk at current prices.
+ * Used for preview/planning; does NOT prepare transactions.
+ */
+export async function simulateTwap(params, { quoteFn = bestSwapRoute } = {}) {
+  const plan = buildTwapSchedule(params);
+  const chunks = [];
+  let totalOut = 0n;
+  let bestSource = "unknown";
+
+  for (let i = 0; i < plan.params.splits; i++) {
+    try {
+      const q = await quoteFn({
+        chainId: plan.params.chainId,
+        tokenIn: plan.params.tokenIn,
+        tokenOut: plan.params.tokenOut,
+        amountIn: plan.params.chunkSize,
+        taker: plan.params.taker,
+      });
+      const out = BigInt(q.amountOut ?? q.quote?.amountOut ?? "0");
+      totalOut += out;
+      bestSource = q.source ?? q.venue ?? bestSource;
+      chunks.push({ splitIndex: i + 1, amountOut: String(out), source: q.source ?? q.venue });
+    } catch (e) {
+      chunks.push({ splitIndex: i + 1, error: String(e.message || e).slice(0, 200) });
+    }
+  }
+
+  const averagePrice = totalOut > 0n
+    ? (Number(totalOut) / Number(BigInt(plan.params.amount))).toFixed(6)
+    : null;
+
+  return {
+    params: plan.params,
+    schedule: plan.schedule,
+    totalOut: String(totalOut),
+    averagePrice,
+    bestSource,
+    chunks,
+    simulatedAt: new Date().toISOString(),
+  };
+}