@oracle-agent/oracle 0.5.0 → 0.7.0

package/src/rfq/intent.mjs

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { getAddress, isAddress } from "ethers";
+
+export const NATIVE_TOKEN = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+export const DEFAULT_SAME_CHAIN_SOURCES = Object.freeze(["lifi", "paraswap", "0x", "cow", "uniswap-v3"]);
+export const DEFAULT_CROSS_CHAIN_SOURCES = Object.freeze(["lifi"]);
+const HEX32 = /^0x[0-9a-fA-F]{64}$/;
+const INT = /^\d+$/;
+
+function fail(label, message = "invalid") {
+  throw new Error(`rfq: ${label} ${message}`);
+}
+
+function chainId(value, label) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) fail(label, "must be a positive chainId");
+  return n;
+}
+
+function amount(value, label) {
+  const s = String(value ?? "").trim();
+  if (!INT.test(s) || BigInt(s) <= 0n) fail(label, "must be a positive integer string");
+  return s;
+}
+
+function optionalAmount(value, label) {
+  if (value == null || value === "") return null;
+  return amount(value, label);
+}
+
+function token(value, label) {
+  const s = String(value ?? "").trim();
+  if (s.toLowerCase() === NATIVE_TOKEN.toLowerCase()) return NATIVE_TOKEN;
+  if (!isAddress(s)) fail(label, "must be an EVM address or native token sentinel");
+  return getAddress(s);
+}
+
+function address(value, label) {
+  const s = String(value ?? "").trim();
+  if (!isAddress(s)) fail(label, "must be an EVM address");
+  return getAddress(s);
+}
+
+function optionalAddress(value, label) {
+  if (value == null || value === "") return null;
+  return address(value, label);
+}
+
+function stringList(value, label, defaults) {
+  if (value === undefined) return [...defaults];
+  if (!Array.isArray(value)) fail(label, "must be an array");
+  return value.map((x) => String(x).trim()).filter(Boolean);
+}
+
+function deadline(value, { nowMs, maxDeadlineMs }, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) fail(label, "must be a finite millisecond timestamp");
+  if (n <= nowMs) fail(label, "expired");
+  if (n > nowMs + maxDeadlineMs) fail(label, "exceeds maxDeadlineMs");
+  return Math.floor(n);
+}
+
+function plain(value) {
+  if (Array.isArray(value)) return value.map(plain);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      if (value[key] !== undefined) out[key] = plain(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(plain(value));
+}
+
+export function sha256Hex(value) {
+  return `0x${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+function withoutHash(value, keys) {
+  const out = { ...value };
+  for (const key of keys) delete out[key];
+  return out;
+}
+
+export function hashRfqIntent(intent) {
+  return sha256Hex(withoutHash(intent, ["intentHash"]));
+}
+
+export function hashFirmQuote(quote) {
+  return sha256Hex(withoutHash(quote, ["firmQuoteHash"]));
+}
+
+export function normalizeRfqIntent(input = {}, opts = {}) {
+  const nowMs = Number(opts.nowMs ?? Date.now());
+  const maxDeadlineMs = Number(opts.maxDeadlineMs ?? 30 * 60 * 1000);
+  if (!Number.isFinite(nowMs) || !Number.isFinite(maxDeadlineMs) || maxDeadlineMs <= 0) fail("time", "is invalid");
+  const fromChainId = chainId(input.fromChainId ?? input.fromChain, "fromChainId");
+  const toChainId = chainId(input.toChainId ?? input.toChain, "toChainId");
+  const sameChain = fromChainId === toChainId;
+  const defaults = sameChain ? DEFAULT_SAME_CHAIN_SOURCES : DEFAULT_CROSS_CHAIN_SOURCES;
+  const intent = {
+    kind: "rfq-intent",
+    version: 1,
+    fromChainId,
+    toChainId,
+    sellToken: token(input.sellToken ?? input.tokenIn ?? input.fromToken, "sellToken"),
+    buyToken: token(input.buyToken ?? input.tokenOut ?? input.toToken, "buyToken"),
+    sellAmount: amount(input.sellAmount ?? input.amountIn ?? input.fromAmount, "sellAmount"),
+    receiver: address(input.receiver ?? input.recipient ?? input.to, "receiver"),
+    deadlineMs: deadline(input.deadlineMs ?? input.deadline ?? input.expiresAtMs, { nowMs, maxDeadlineMs }, "deadline"),
+    minBuyAmount: optionalAmount(input.minBuyAmount ?? input.minOut ?? input.amountOutMin, "minBuyAmount"),
+    allowedSources: stringList(input.allowedSources, "allowedSources", defaults),
+    allowedRouters: stringList(input.allowedRouters, "allowedRouters", []),
+    slippageBps: Number.isFinite(Number(input.slippageBps)) ? Number(input.slippageBps) : null,
+    partialFill: input.partialFill === true,
+    metadata: input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata) ? plain(input.metadata) : {},
+  };
+  if (intent.slippageBps != null && (!Number.isInteger(intent.slippageBps) || intent.slippageBps < 0 || intent.slippageBps > 10_000)) fail("slippageBps", "must be 0 to 10000");
+  intent.intentId = input.intentId ? String(input.intentId) : sha256Hex({ seed: "rfq-intent", intent }).slice(0, 34);
+  intent.intentHash = hashRfqIntent(intent);
+  return Object.freeze(intent);
+}
+
+function artifact(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("artifact", "required");
+  if (value.typedDataHash != null && !HEX32.test(String(value.typedDataHash))) fail("artifact.typedDataHash", "must be bytes32");
+  if (value.calldataHash != null && !HEX32.test(String(value.calldataHash))) fail("artifact.calldataHash", "must be bytes32");
+  if (value.to != null && !isAddress(String(value.to))) fail("artifact.to", "must be an address");
+  if (value.data != null && !/^0x(?:[0-9a-fA-F]{2})*$/.test(String(value.data))) fail("artifact.data", "must be hex");
+  return plain(value);
+}
+
+export function normalizeFirmQuote(intent, quote = {}, opts = {}) {
+  if (!intent || intent.kind !== "rfq-intent") fail("intent", "required");
+  const nowMs = Number(opts.nowMs ?? Date.now());
+  const expiryMs = Number(quote.expiryMs ?? quote.expiresAtMs ?? quote.validUntilMs);
+  if (!Number.isFinite(expiryMs)) fail("quote expiry", "required");
+  if (expiryMs <= nowMs) fail("quote", "expired");
+  if (expiryMs > intent.deadlineMs) fail("quote expiry", "exceeds intent deadline");
+  const source = String(quote.source ?? quote.provider ?? "").trim();
+  if (!source) fail("source", "required");
+  if (!intent.allowedSources.includes(source)) fail("source", "not allowed by intent");
+  const amountOut = amount(quote.amountOut ?? quote.buyAmount, "amountOut");
+  const minBuyAmount = amount(quote.minBuyAmount ?? quote.minOut ?? amountOut, "minBuyAmount");
+  if (BigInt(minBuyAmount) > BigInt(amountOut)) fail("minBuyAmount", "exceeds amountOut");
+  const artifactValue = artifact(quote.artifact ?? quote.executableArtifact ?? quote.transaction ?? quote.typedData);
+  const quotedAtMs = Number(quote.quotedAtMs ?? quote.timestampMs ?? opts.nowMs ?? Date.now());
+  if (!Number.isFinite(quotedAtMs)) fail("quotedAtMs", "must be finite");
+  const router = optionalAddress(quote.router ?? quote.settlementRouter ?? artifactValue.to, "router");
+  const out = {
+    kind: "rfq-firm-quote",
+    provider: "rfq",
+    surface: "rfq",
+    version: 1,
+    quoteId: String(quote.quoteId ?? quote.id ?? "").trim(),
+    source,
+    intentHash: intent.intentHash,
+    fromChainId: intent.fromChainId,
+    toChainId: intent.toChainId,
+    sellToken: intent.sellToken,
+    buyToken: intent.buyToken,
+    sellAmount: intent.sellAmount,
+    receiver: intent.receiver,
+    router,
+    amountOut,
+    minBuyAmount,
+    quotedAtMs: Math.floor(quotedAtMs),
+    expiryMs: Math.floor(expiryMs),
+    artifact: artifactValue,
+    maker: quote.maker ? String(quote.maker) : null,
+    metadata: quote.metadata && typeof quote.metadata === "object" && !Array.isArray(quote.metadata) ? plain(quote.metadata) : {},
+  };
+  if (!out.quoteId) out.quoteId = sha256Hex({ seed: "rfq-quote", out }).slice(0, 34);
+  out.firmQuoteHash = hashFirmQuote(out);
+  return Object.freeze(out);
+}

package/src/rfq/sources.mjs

@@ -0,0 +1,181 @@
+import { lifiQuote } from "../data/providers/lifi.mjs";
+import { paraswapPrice } from "../data/providers/paraswap.mjs";
+import { zeroxQuote } from "../data/providers/zerox.mjs";
+import { cowQuote } from "../data/providers/cowswap.mjs";
+import { uniV3QuoteExactIn, UNI_V3_CHAINS } from "../data/providers/uniswap-v3.mjs";
+import { normalizeFirmQuote } from "./intent.mjs";
+
+function allowed(intent, source) {
+  return Array.isArray(intent?.allowedSources) && intent.allowedSources.includes(source);
+}
+
+function envValue(env, key) {
+  return String(env?.[key] ?? "").trim();
+}
+
+function candidate(source, run) {
+  return Object.freeze({ source, run });
+}
+
+export function sourceCandidates(intent, opts = {}) {
+  if (!intent || intent.kind !== "rfq-intent") throw new Error("rfq: intent required");
+  const env = opts.env ?? process.env;
+  const providers = opts.providers ?? {};
+  const uniChains = opts.supportedUniV3Chains ?? UNI_V3_CHAINS;
+  const sameChain = Number(intent.fromChainId) === Number(intent.toChainId);
+  const out = [];
+  if (allowed(intent, "lifi")) {
+    out.push(candidate("lifi", async () => {
+      const fn = providers.lifiQuote ?? lifiQuote;
+      const q = await fn({
+        fromChain: intent.fromChainId,
+        toChain: intent.toChainId,
+        fromToken: intent.sellToken,
+        toToken: intent.buyToken,
+        fromAmount: intent.sellAmount,
+        fromAddress: intent.receiver,
+      }, opts);
+      const est = q?.estimate ?? q?.[0]?.estimate ?? q;
+      return {
+        quoteId: q?.id ?? q?.routeId ?? null,
+        amountOut: est?.toAmount ?? q?.toAmount,
+        minBuyAmount: est?.toAmountMin ?? q?.toAmountMin ?? est?.toAmount ?? q?.toAmount,
+        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
+        artifact: { type: "lifi-route", calldataHash: q?.transactionRequest?.data ? await hashMaybe(opts, q.transactionRequest.data) : undefined, route: q },
+        metadata: { tool: q?.tool ?? q?.toolDetails?.name ?? null },
+      };
+    }));
+  }
+  if (!sameChain) return out;
+  if (allowed(intent, "paraswap")) {
+    out.push(candidate("paraswap", async () => {
+      const fn = providers.paraswapPrice ?? paraswapPrice;
+      const q = await fn({
+        chainId: intent.fromChainId,
+        srcToken: intent.sellToken,
+        destToken: intent.buyToken,
+        amount: intent.sellAmount,
+        srcDecimals: opts.decimalsIn,
+        destDecimals: opts.decimalsOut,
+      }, opts);
+      const pr = q?.priceRoute ?? q;
+      return {
+        quoteId: pr?.id ?? null,
+        amountOut: pr?.destAmount,
+        minBuyAmount: q?.amountOutMinimum ?? pr?.destAmount,
+        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
+        artifact: { type: "paraswap-price-route", route: pr },
+        metadata: { contractAddress: pr?.contractAddress ?? null },
+      };
+    }));
+  }
+  if (allowed(intent, "0x") && (envValue(env, "ZEROX_API_KEY") || envValue(env, "0X_API_KEY") || providers.zeroxQuote)) {
+    out.push(candidate("0x", async () => {
+      const fn = providers.zeroxQuote ?? zeroxQuote;
+      const q = await fn({ chainId: intent.fromChainId, sellToken: intent.sellToken, buyToken: intent.buyToken, sellAmount: intent.sellAmount, taker: intent.receiver }, opts);
+      return {
+        quoteId: q?.id ?? null,
+        amountOut: q?.buyAmount ?? q?.grossBuyAmount,
+        minBuyAmount: q?.minBuyAmount ?? q?.buyAmount,
+        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
+        artifact: { type: "0x-transaction", to: q?.transaction?.to, data: q?.transaction?.data, value: q?.transaction?.value ?? "0" },
+        metadata: { route: q?.route ?? null },
+      };
+    }));
+  }
+  if (allowed(intent, "cow")) {
+    out.push(candidate("cow", async () => {
+      const fn = providers.cowQuote ?? cowQuote;
+      const q = await fn({ chainId: intent.fromChainId, sellToken: intent.sellToken, buyToken: intent.buyToken, sellAmountBeforeFee: intent.sellAmount, from: intent.receiver, signingScheme: "eip712" }, opts);
+      const quote = q?.quote ?? q;
+      return {
+        quoteId: q?.id ?? null,
+        amountOut: quote?.buyAmount,
+        minBuyAmount: quote?.buyAmount,
+        expiryMs: Math.min(Number(quote?.validTo ?? 0) * 1000 || Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000), intent.deadlineMs),
+        artifact: { type: "cow-order", order: quote },
+        metadata: { solver: true },
+      };
+    }));
+  }
+  if (allowed(intent, "uniswap-v3") && uniChains[Number(intent.fromChainId)]) {
+    out.push(candidate("uniswap-v3", async () => {
+      const fn = providers.uniV3QuoteExactIn ?? uniV3QuoteExactIn;
+      const q = await fn({ chainId: intent.fromChainId, tokenIn: intent.sellToken, tokenOut: intent.buyToken, amountIn: intent.sellAmount }, opts);
+      return {
+        quoteId: q?.id ?? null,
+        amountOut: q?.amountOut,
+        minBuyAmount: q?.minOut ?? q?.amountOutMinimum ?? q?.amountOut,
+        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
+        artifact: { type: "uniswap-v3-quote", quoter: q?.quoter, fee: q?.fee },
+        metadata: { onchain: true },
+      };
+    }));
+  }
+  return out;
+}
+
+async function hashMaybe(opts, value) {
+  const crypto = await import("node:crypto");
+  return `0x${crypto.createHash("sha256").update(String(value)).digest("hex")}`;
+}
+
+async function runWithTimeout(c, timeoutMs) {
+  return Promise.race([
+    Promise.resolve().then(c.run),
+    new Promise((_, reject) => setTimeout(() => reject(new Error(`${c.source}: timeout`)), timeoutMs)),
+  ]);
+}
+
+export async function executeRfqCandidates(intent, candidates, opts = {}) {
+  const timeoutMs = Number(opts.timeoutMs ?? 12_000);
+  const settled = await Promise.allSettled(candidates.map((c) => runWithTimeout(c, timeoutMs)));
+  const quotes = [];
+  const failed = [];
+  for (let i = 0; i < settled.length; i++) {
+    const c = candidates[i];
+    const r = settled[i];
+    if (r.status === "rejected") {
+      failed.push({ source: c.source, error: String(r.reason?.message || r.reason) });
+      continue;
+    }
+    try {
+      quotes.push(normalizeFirmQuote(intent, { ...r.value, source: c.source }, opts));
+    } catch (e) {
+      failed.push({ source: c.source, error: String(e?.message || e) });
+    }
+  }
+  return { quotes, failed };
+}
+
+export function rankRfqQuotes(quotes = [], opts = {}) {
+  const nowMs = Number(opts.nowMs ?? Date.now());
+  const usable = quotes.filter((q) => Number(q.expiryMs ?? 0) > nowMs);
+  usable.sort((a, b) => {
+    const floor = BigInt(b.minBuyAmount ?? 0) - BigInt(a.minBuyAmount ?? 0);
+    if (floor !== 0n) return floor > 0n ? 1 : -1;
+    const gross = BigInt(b.amountOut ?? 0) - BigInt(a.amountOut ?? 0);
+    return gross > 0n ? 1 : gross < 0n ? -1 : 0;
+  });
+  const ranked = usable.map((q) => ({ ...q, scoreBasis: "minBuyAmount" }));
+  const warnings = [];
+  if (!ranked.length) warnings.push("no RFQ source returned a usable firm quote");
+  if (quotes.length !== ranked.length) warnings.push("expired RFQ quotes were excluded from ranking");
+  return { best: ranked[0] ?? null, quotes: ranked, failed: [], warnings };
+}
+
+export async function requestRfqQuotes(intent, opts = {}) {
+  const candidates = sourceCandidates(intent, opts);
+  const { quotes, failed } = await executeRfqCandidates(intent, candidates, opts);
+  const ranked = rankRfqQuotes(quotes, opts);
+  return {
+    kind: "rfq-result",
+    intent,
+    best: ranked.best,
+    quotes: ranked.quotes,
+    failed,
+    warnings: [...ranked.warnings],
+    sourcesTried: candidates.length,
+    sourcesAnswered: quotes.length,
+  };
+}