@oracle-agent/oracle 0.1.0

package/src/data/providers/balancer.mjs

@@ -0,0 +1,208 @@
+// Balancer public GraphQL API + v3 Router exact-input prepare. No key.
+import { Interface, getAddress, isAddress } from "ethers";
+import { httpJson } from "../http.mjs";
+import { rpcCall as defaultRpcCall } from "./evm-rpc.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+
+export const BALANCER_API = "https://api-v3.balancer.fi/";
+const endpoint = (o = {}) => o.baseUrl || process.env.BALANCER_API_URL || BALANCER_API;
+
+async function gql(query, variables, opts = {}) {
+  return httpJson(endpoint(opts), {
+    method: "POST",
+    body: { query, variables },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+const POOLS_QUERY = `query Pools($first: Int, $where: GqlPoolFilter) { poolGetPools(first: $first, where: $where) { id address chain type protocolVersion dynamicData { totalLiquidity volume24h fees24h } } }`;
+
+// Official Balancer v3 Router deployments; bytecode checked via eth_getCode on
+// 2026-07-23. Polygon is intentionally excluded from this v3 prepare slice.
+export const BALANCER_V3_CHAINS = Object.freeze({
+  1: {
+    name: "ethereum",
+    router: "0xAE563E3f8219521950555F5962419C8919758Ea2",
+    weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  10: {
+    name: "optimism",
+    router: "0xe2fa4e1d17725e72dcdAfe943Ecf45dF4B9E285b",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
+  },
+  8453: {
+    name: "base",
+    router: "0x3f170631ed9821Ca51A59D996aB095162438DC10",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  42161: {
+    name: "arbitrum",
+    router: "0xEAedc32a51c510d35ebC11088fD5fF2b47aACF2E",
+    weth: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  },
+  43114: {
+    name: "avalanche",
+    router: "0xF39CA6ede9BF7820a952b52f3c94af526bAB9015",
+    weth: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
+    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+  },
+});
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+const ZERO = "0x0000000000000000000000000000000000000000";
+const BALANCER_V3_IFACE = new Interface([
+  "function querySwapSingleTokenExactIn(address pool,address tokenIn,address tokenOut,uint256 exactAmountIn,address sender,bytes userData) returns (uint256 amountOut)",
+  "function swapSingleTokenExactIn(address pool,address tokenIn,address tokenOut,uint256 exactAmountIn,uint256 minAmountOut,uint256 deadline,bool wethIsEth,bytes userData) payable returns (uint256 amountOut)",
+]);
+
+function chainMeta(chainId) {
+  const id = Number(chainId ?? 8453);
+  const meta = BALANCER_V3_CHAINS[id];
+  if (!meta) {
+    throw new Error(`balancer-v3: unsupported chainId ${chainId} (supported: ${Object.keys(BALANCER_V3_CHAINS).join(", ")})`);
+  }
+  return { chainId: id, ...meta };
+}
+
+function isNativeToken(value) {
+  const v = String(value || "").toLowerCase();
+  return !v || v === "eth" || v === "native" || v === ZERO || v === NATIVE.toLowerCase();
+}
+
+function normalizeAddress(value, label) {
+  if (!isAddress(value)) throw new Error(`${label} must be a valid EVM address`);
+  return getAddress(value);
+}
+
+function normalizeToken(value, meta, label) {
+  const s = String(value || "");
+  if (isNativeToken(s) || /^weth$/i.test(s)) return getAddress(meta.weth);
+  if (/^usdc$/i.test(s)) return getAddress(meta.usdc);
+  return normalizeAddress(s, label);
+}
+
+function positiveAmount(value, label) {
+  let amount;
+  try {
+    amount = BigInt(String(value));
+  } catch {
+    throw new Error(`${label} must be an integer string`);
+  }
+  if (amount <= 0n) throw new Error(`${label} must be positive`);
+  return amount;
+}
+
+function userData(value) {
+  if (value == null || value === "") return "0x";
+  const data = String(value);
+  if (!/^0x[0-9a-fA-F]*$/.test(data)) throw new Error("balancer userData must be hex");
+  return data;
+}
+
+export async function balancerPools(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chains = (args.chains || [args.chain || "ETHEREUM"]).map((x) => String(x).toUpperCase());
+  return gql(POOLS_QUERY, { first, chains, where: { chainIn: chains } }, opts);
+}
+
+export async function balancerHealth(opts = {}) {
+  const data = await gql("query { __typename }", {}, opts);
+  return { ok: data?.data?.__typename === "Query" };
+}
+
+export async function balancerQuote(q = {}, opts = {}) {
+  const meta = chainMeta(q.chainId);
+  const pool = normalizeAddress(q.pool, "balancer pool");
+  const tokenInRaw = q.tokenIn || "WETH";
+  const tokenIn = normalizeToken(tokenInRaw, meta, "balancer tokenIn");
+  const tokenOut = normalizeToken(q.tokenOut || "USDC", meta, "balancer tokenOut");
+  const amountIn = positiveAmount(q.amountIn, "balancer amountIn");
+  const sender = normalizeAddress(q.sender || q.from || q.fromAddress || q.recipient, "balancer sender");
+  const data = BALANCER_V3_IFACE.encodeFunctionData("querySwapSingleTokenExactIn", [
+    pool,
+    tokenIn,
+    tokenOut,
+    amountIn,
+    sender,
+    userData(q.userData),
+  ]);
+  const call = opts.rpcCall || defaultRpcCall;
+  const raw = await call(meta.chainId, "eth_call", [{ to: meta.router, data }, q.blockTag || "latest"], opts);
+  const decoded = BALANCER_V3_IFACE.decodeFunctionResult("querySwapSingleTokenExactIn", raw);
+  const amountOut = BigInt(decoded[0]);
+  if (amountOut <= 0n) throw new Error("balancer quote returned zero output");
+  return attachAutoSlippage({
+    venue: "balancer",
+    protocolVersion: 3,
+    chainId: meta.chainId,
+    chain: meta.name,
+    router: meta.router,
+    pool,
+    tokenIn,
+    tokenOut,
+    amountIn: amountIn.toString(),
+    amountOut: amountOut.toString(),
+  }, {
+    chainId: meta.chainId,
+    venue: meta.router,
+    amountOut: amountOut.toString(),
+    liquidityUsd: q.liquidityUsd,
+    priceChange5m: q.priceChange5m,
+    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+  });
+}
+
+export async function balancerPrepare(q = {}, opts = {}) {
+  const meta = chainMeta(q.chainId);
+  const sender = normalizeAddress(q.sender || q.from || q.fromAddress || q.recipient, "balancer sender");
+  const inputRaw = q.tokenIn || "WETH";
+  const nativeInput = isNativeToken(inputRaw);
+  const quote = await balancerQuote({ ...q, sender }, opts);
+  const deadlineWindow = Math.min(600, Math.max(30, Number(q.deadlineSeconds ?? 300)));
+  const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
+  const deadline = BigInt(nowSeconds + deadlineWindow);
+  const wethIsEth = q.wethIsEth != null ? Boolean(q.wethIsEth) : nativeInput;
+  const data = BALANCER_V3_IFACE.encodeFunctionData("swapSingleTokenExactIn", [
+    quote.pool,
+    quote.tokenIn,
+    quote.tokenOut,
+    BigInt(quote.amountIn),
+    BigInt(quote.amountOutMinimum),
+    deadline,
+    wethIsEth,
+    userData(q.userData),
+  ]);
+  return {
+    provider: "balancer",
+    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: meta.chainId,
+    deadline: deadline.toString(),
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: nativeInput ? null : {
+      token: quote.tokenIn,
+      spender: meta.router,
+      amount: quote.amountIn,
+    },
+    transaction: {
+      chainId: meta.chainId,
+      from: sender,
+      to: meta.router,
+      data,
+      value: nativeInput ? quote.amountIn : "0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId: meta.chainId, venue: meta.router, data }),
+    },
+  };
+}

package/src/data/providers/bitcoin-esplora.mjs

@@ -0,0 +1,230 @@
+// Bitcoin L1 read/broadcast via Esplora HTTP (mempool.space / Blockstream).
+// No Bitcoin Core RPC required. No keys, no signing.
+
+import { httpJson } from "../http.mjs";
+
+export const BTC_NETWORK_MAINNET = "mainnet";
+export const BTC_ESPLORA_MAINNET = "https://mempool.space/api";
+export const BTC_ESPLORA_TESTNET = "https://mempool.space/testnet/api";
+
+function network(opts = {}) {
+  const n = String(opts.network || process.env.BTC_NETWORK || BTC_NETWORK_MAINNET).trim().toLowerCase();
+  return n === "testnet" ? "testnet" : "mainnet";
+}
+
+function baseUrl(opts = {}) {
+  if (opts.baseUrl) return String(opts.baseUrl).replace(/\/$/, "");
+  if (process.env.BTC_ESPLORA_URL) return String(process.env.BTC_ESPLORA_URL).replace(/\/$/, "");
+  return network(opts) === "testnet" ? BTC_ESPLORA_TESTNET : BTC_ESPLORA_MAINNET;
+}
+
+export function btcAddress(value, label = "address") {
+  const text = String(value || "").trim();
+  // bech32 / bech32m / legacy / p2sh — loose shape check, not full BIP validation
+  if (!/^(bc1|tb1|bcrt1)[a-z0-9]{20,90}$/i.test(text) && !/^[13mn2][a-km-zA-HJ-NP-Z1-9]{25,34}$/.test(text)) {
+    throw new Error(`bitcoin-esplora: ${label} must look like a Bitcoin address`);
+  }
+  return text;
+}
+
+export function btcTxHex(value, label = "txHex") {
+  const text = String(value || "").trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(text) || text.length < 20 || text.length % 2 !== 0) {
+    throw new Error(`bitcoin-esplora: ${label} must be even-length hex`);
+  }
+  return text;
+}
+
+async function getText(path, opts = {}) {
+  const url = `${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`;
+  const fetchImpl = opts.fetchImpl || fetch;
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: { accept: "application/json,text/plain;q=0.9,*/*;q=0.8" },
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 12_000),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`bitcoin-esplora GET ${path}: HTTP ${res.status} ${text.slice(0, 160)}`);
+  return text;
+}
+
+async function getJson(path, opts = {}) {
+  const text = await getText(path, opts);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function postText(path, body, opts = {}) {
+  const url = `${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`;
+  const fetchImpl = opts.fetchImpl || fetch;
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "text/plain", accept: "application/json,text/plain;q=0.9,*/*;q=0.8" },
+    body: String(body || ""),
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`bitcoin-esplora POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
+  return text.trim();
+}
+
+export async function btcHealth(opts = {}) {
+  try {
+    const tip = await getText("/blocks/tip/height", opts);
+    const height = Number(tip);
+    return {
+      ok: Number.isFinite(height) && height > 0,
+      provider: "bitcoin-esplora",
+      network: network(opts),
+      baseUrl: baseUrl(opts),
+      tipHeight: height,
+      exec: false,
+      signing: "user-wallet",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      provider: "bitcoin-esplora",
+      network: network(opts),
+      baseUrl: baseUrl(opts),
+      error: String(error?.message || error),
+      exec: false,
+    };
+  }
+}
+
+export async function btcTipHeight(opts = {}) {
+  const tip = await getText("/blocks/tip/height", opts);
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    tipHeight: Number(tip),
+  };
+}
+
+export async function btcFees(opts = {}) {
+  // mempool.space recommended fees; Blockstream may 404 — fall back empty
+  try {
+    const fees = await getJson("/v1/fees/recommended", opts);
+    return {
+      provider: "bitcoin-esplora",
+      network: network(opts),
+      fastestFee: fees.fastestFee ?? null,
+      halfHourFee: fees.halfHourFee ?? null,
+      hourFee: fees.hourFee ?? null,
+      economyFee: fees.economyFee ?? null,
+      minimumFee: fees.minimumFee ?? null,
+      raw: fees,
+    };
+  } catch {
+    return {
+      provider: "bitcoin-esplora",
+      network: network(opts),
+      fastestFee: null,
+      halfHourFee: null,
+      hourFee: null,
+      note: "fee endpoint unavailable on this Esplora host",
+    };
+  }
+}
+
+export async function btcAddressInfo(args = {}, opts = {}) {
+  const address = btcAddress(args.address || args.addr, "address");
+  const info = await getJson(`/address/${address}`, opts);
+  const chain = info.chain_stats || {};
+  const mempool = info.mempool_stats || {};
+  const funded = Number(chain.funded_txo_sum || 0) + Number(mempool.funded_txo_sum || 0);
+  const spent = Number(chain.spent_txo_sum || 0) + Number(mempool.spent_txo_sum || 0);
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    address,
+    balanceSats: String(funded - spent),
+    chainStats: chain,
+    mempoolStats: mempool,
+    raw: info,
+  };
+}
+
+export async function btcUtxos(args = {}, opts = {}) {
+  const address = btcAddress(args.address || args.addr, "address");
+  const utxos = await getJson(`/address/${address}/utxo`, opts);
+  const list = Array.isArray(utxos) ? utxos : [];
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    address,
+    count: list.length,
+    totalSats: String(list.reduce((n, u) => n + Number(u.value || 0), 0)),
+    utxos: list.map((u) => ({
+      txid: u.txid,
+      vout: u.vout,
+      value: Number(u.value || 0),
+      status: u.status || null,
+    })),
+  };
+}
+
+export async function btcTx(args = {}, opts = {}) {
+  const txid = String(args.txid || args.txId || "").trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(txid)) throw new Error("bitcoin-esplora: txid must be 64-char hex");
+  const tx = await getJson(`/tx/${txid}`, opts);
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    txid,
+    confirmed: Boolean(tx.status?.confirmed),
+    fee: tx.fee ?? null,
+    size: tx.size ?? null,
+    weight: tx.weight ?? null,
+    vinCount: Array.isArray(tx.vin) ? tx.vin.length : null,
+    voutCount: Array.isArray(tx.vout) ? tx.vout.length : null,
+    raw: tx,
+  };
+}
+
+export async function btcDecodeTxHex(args = {}, opts = {}) {
+  const txHex = btcTxHex(args.txHex || args.hex || args.transaction, "txHex");
+  // Esplora has no universal decode; return structural summary from hex length + optional /tx/hex reverse via broadcast dry path.
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    encoding: "hex",
+    txHex,
+    byteLength: txHex.length / 2,
+    note: "full decode is wallet/client-side or via bitcoinjs; Esplora returns broadcast acceptance only",
+  };
+}
+
+/**
+ * Broadcast a fully signed raw transaction hex.
+ *
+ * Posture: broadcasting is ARMED whenever the caller has signed bytes to send —
+ * possessing a signed transaction IS the authorization. What is still required
+ * is that the SEND be asked for: `execute:true` marks a user-initiated
+ * broadcast, so nothing goes out as a side effect of a read path. Oracle never
+ * signs here; the caller supplies the bytes.
+ */
+export async function btcBroadcast(args = {}, opts = {}) {
+  if (args.execute !== true) {
+    throw new Error("bitcoin-esplora: broadcast requires execute:true — refusing an implicit send");
+  }
+  const txHex = btcTxHex(args.txHex || args.hex || args.signedTransaction, "txHex");
+  const txid = await postText("/tx", txHex, opts);
+  if (!/^[0-9a-f]{64}$/i.test(txid)) {
+    throw new Error(`bitcoin-esplora: unexpected broadcast response ${String(txid).slice(0, 80)}`);
+  }
+  return {
+    provider: "bitcoin-esplora",
+    network: network(opts),
+    sent: true,
+    txid: txid.toLowerCase(),
+    signedTransactionHex: txHex,
+  };
+}
+
+// Keep httpJson import usable for Core RPC optional path later without circular deps.
+void httpJson;