@oracle-agent/oracle 0.14.1 → 0.15.0

package/src/data/providers/lifi.mjs

@@ -1,166 +0,0 @@
-// LI.FI public quote API — no API key required for basic quotes.
-
-import { httpJson } from "../http.mjs";
-import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
-import { QUOTE_PLACEHOLDER_ADDRESS, quoteAddress } from "../quote-placeholder.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
-
-import { resolveFee, lifiFeeParams } from "../../router/integrator-fee.mjs";
-
-export const LIFI_API = "https://li.quest/v1";
-
-function base(opts = {}) {
-  return (opts.baseUrl || process.env.LIFI_API_URL || LIFI_API).replace(/\/$/, "");
-}
-
-const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
-const ZERO = "0x0000000000000000000000000000000000000000";
-
-function isNativeToken(value) {
-  const token = String(value || NATIVE).toLowerCase();
-  return token === NATIVE.toLowerCase() || token === ZERO;
-}
-
-function address(value, label) {
-  const text = String(value || "").trim();
-  if (!/^0x[0-9a-fA-F]{40}$/.test(text)) throw new Error(`lifi: ${label} must be a 20-byte address`);
-  return text.toLowerCase();
-}
-
-export async function lifiHealth(opts = {}) {
-  // cheap chains list
-  const chains = await httpJson(`${base(opts)}/chains`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-  const n = Array.isArray(chains) ? chains.length : chains?.chains?.length || 0;
-  return { ok: n > 0, chainCount: n };
-}
-
-/**
- * @param {object} q
- * @param {number|string} q.fromChain
- * @param {number|string} q.toChain
- * @param {string} q.fromToken
- * @param {string} q.toToken
- * @param {string} q.fromAmount  wei/base units
- * @param {string} [q.fromAddress]
- */
-export async function lifiQuote(q = {}, opts = {}) {
-  const {
-    fromChain,
-    toChain = fromChain,
-    fromToken = NATIVE,
-    toToken,
-    fromAmount,
-    fromAddress = QUOTE_PLACEHOLDER_ADDRESS,
-  } = q;
-  if (fromChain == null || !toToken || !fromAmount) {
-    throw new Error("lifiQuote requires fromChain, toToken, fromAmount");
-  }
-  const params = new URLSearchParams({
-    fromChain: String(fromChain),
-    toChain: String(toChain),
-    fromToken,
-    toToken,
-    fromAmount: String(fromAmount),
-    fromAddress,
-  });
-  const selected = resolveAutoSlippage({
-    liquidityUsd: q.liquidityUsd,
-    priceChange5m: q.priceChange5m,
-    crossChain: Number(toChain) !== Number(fromChain),
-    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
-  });
-  if (!selected.executable) {
-    throw new Error(`lifi: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
-  }
-  // LI.FI expects a decimal fraction: 0.005 = 50 bps.
-  params.set("slippage", String(selected.selectedBps / 10_000));
-  // Integrator fee. Off unless configured, and always zero for Locals Only
-  // holders — see router/integrator-fee.mjs for why the policy lives in one
-  // place instead of per-provider.
-  const fee = resolveFee({ isHolder: q.isHolder, action: q.feeAction || "swap" });
-  for (const [k, v] of Object.entries(lifiFeeParams(fee))) params.set(k, v);
-  const result = await httpJson(`${base(opts)}/quote?${params}`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 20_000,
-  });
-  const amountOut = result?.estimate?.toAmount || result?.toAmount;
-  if (!amountOut) return { ...result, autoSlippagePolicy: selected, oracleFee: fee };
-  const venue = result?.transactionRequest?.to || result?.estimate?.approvalAddress || "lifi";
-  const guarded = attachAutoSlippage(result, {
-    chainId: Number(fromChain),
-    venue,
-    amountOut,
-    liquidityUsd: q.liquidityUsd,
-    priceChange5m: q.priceChange5m,
-    crossChain: Number(toChain) !== Number(fromChain),
-    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
-  });
-  const providerMin = result?.estimate?.toAmountMin || result?.toAmountMin;
-  if (providerMin != null && BigInt(providerMin) < BigInt(guarded.amountOutMinimum)) {
-    throw new Error("lifi: provider transaction is under-protected versus bounded auto-slippage floor");
-  }
-  return { ...guarded, oracleFee: fee };
-}
-
-export async function lifiPrepare(q = {}, opts = {}) {
-  const quote = await lifiQuote(q, opts);
-  const tx = quote?.transactionRequest;
-  if (!tx?.to || !tx?.data) throw new Error("lifi: quote did not return an executable transactionRequest");
-  const chainId = Number(q.fromChain);
-  if (tx.chainId != null && Number(tx.chainId) !== chainId) throw new Error("lifi: transaction chain mismatch");
-  if (q.fromAddress && tx.from && String(tx.from).toLowerCase() !== String(q.fromAddress).toLowerCase()) {
-    throw new Error("lifi: transaction sender mismatch");
-  }
-  let requiresApproval = null;
-  if (!isNativeToken(q.fromToken)) {
-    const spender = quote?.estimate?.approvalAddress || quote?.approvalAddress;
-    if (!spender) throw new Error("lifi: ERC20 route missing approvalAddress");
-    // q.fromToken may be a SYMBOL ("WETH") -- LI.FI's API accepts symbols, and the
-    // router passes the user's raw CLI argument straight through. The approval
-    // must name a real 20-byte token, so prefer the resolved address LI.FI echoes
-    // back in its own action/estimate before falling back to the input.
-    const resolvedToken =
-      quote?.action?.fromToken?.address ||
-      quote?.estimate?.fromToken?.address ||
-      q.fromToken;
-    requiresApproval = {
-      token: address(resolvedToken, "approval token"),
-      spender: address(spender, "approval spender"),
-      amount: String(q.fromAmount),
-    };
-  }
-  return stampPrepared({
-    provider: "lifi",
-    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,
-    transaction: {
-      chainId,
-      from: tx.from || q.fromAddress,
-      to: tx.to,
-      data: tx.data,
-      value: tx.value ?? "0x0",
-      ...(tx.gasLimit != null ? { gasLimit: tx.gasLimit } : {}),
-      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
-    },
-  }, { provider: "lifi", kind: "lifi-tx" });
-}
-
-export async function lifiChains(opts = {}) {
-  return httpJson(`${base(opts)}/chains`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-}

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

@@ -1,152 +0,0 @@
-// Liquid Network (Blockstream sidechain) via Esplora HTTP — keyless.
-//
-// Same Esplora schema as bitcoin-esplora, different chain and one extra
-// concept: Liquid is multi-asset, so balances are per-asset-id and the
-// /asset/{id} endpoint carries peg-in/peg-out issuance stats that have no
-// Bitcoin L1 equivalent.
-//
-// Verified live:
-//   GET /liquid/api/blocks/tip/height   200 (plain text height)
-//   GET /liquid/api/address/{addr}      200
-//   GET /liquid/api/asset/{asset_id}    200
-//
-// Liquid address forms, all accepted below:
-//   Q…            unconfidential p2pkh/p2sh (base58)
-//   VJL… / VTp…   confidential (base58, long)
-//   ex1… / lq1…   unconfidential / confidential bech32(m)
-//
-// Read-only. Peg-outs and transfers are user-wallet operations; nothing here
-// signs or broadcasts.
-
-import { httpJson } from "../http.mjs";
-
-export const LIQUID_ESPLORA_URL = "https://blockstream.info/liquid/api";
-// Policy asset: L-BTC. Used as the default for balance reads.
-export const LIQUID_LBTC_ASSET_ID = "6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d";
-
-function baseUrl(opts = {}) {
-  return String(opts.baseUrl || process.env.LIQUID_ESPLORA_URL || LIQUID_ESPLORA_URL).replace(/\/$/, "");
-}
-
-export function liquidAddress(value, label = "address") {
-  const text = String(value || "").trim();
-  const bech32 = /^(ex1|lq1|el1|tex1|tlq1)[a-z0-9]{20,200}$/i.test(text);
-  const base58 = /^[QVGH][a-km-zA-HJ-NP-Z1-9]{25,110}$/.test(text);
-  if (!bech32 && !base58) {
-    throw new Error(`liquid-esplora: ${label} must look like a Liquid address (Q…, VJL…, ex1…, lq1…)`);
-  }
-  return text;
-}
-
-export function liquidAssetId(value, label = "assetId") {
-  const text = String(value || "").trim().toLowerCase().replace(/^0x/, "");
-  if (!/^[0-9a-f]{64}$/.test(text)) throw new Error(`liquid-esplora: ${label} must be 64-char 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(`liquid-esplora GET ${path}: HTTP ${res.status} ${text.slice(0, 160)}`);
-  return text;
-}
-
-function getJson(path, opts = {}) {
-  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-}
-
-export async function liquidHealth(opts = {}) {
-  try {
-    const tip = await getText("/blocks/tip/height", opts);
-    const height = Number(tip);
-    return {
-      ok: Number.isFinite(height) && height > 0,
-      provider: "liquid-esplora",
-      baseUrl: baseUrl(opts),
-      tipHeight: height,
-      exec: false,
-      signing: "user-wallet",
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "liquid-esplora",
-      baseUrl: baseUrl(opts),
-      error: String(error?.message || error),
-      exec: false,
-    };
-  }
-}
-
-export async function liquidTipHeight(_args = {}, opts = {}) {
-  const tip = await getText("/blocks/tip/height", opts);
-  return { provider: "liquid-esplora", tipHeight: Number(tip) };
-}
-
-/**
- * Address stats. NOTE: Liquid is confidential by default — a confidential
- * address returns TXO COUNTS, not amounts, because the amounts are blinded on
- * chain. Only unblinded/unconfidential outputs carry values. The response says
- * so explicitly rather than reporting a misleading zero balance.
- */
-export async function liquidAddressInfo(args = {}, opts = {}) {
-  const address = liquidAddress(args.address || args.addr, "address");
-  const info = await getJson(`/address/${address}`, opts);
-  const chain = info.chain_stats || {};
-  const mempool = info.mempool_stats || {};
-  const hasAmounts = chain.funded_txo_sum != null;
-  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: "liquid-esplora",
-    address,
-    txCount: Number(chain.tx_count || 0) + Number(mempool.tx_count || 0),
-    balanceSats: hasAmounts ? String(funded - spent) : null,
-    confidential: !hasAmounts,
-    note: hasAmounts
-      ? undefined
-      : "Liquid amounts are blinded — Esplora returns TXO counts only for confidential outputs. Unblind with the wallet's blinding key for values.",
-    chainStats: chain,
-    mempoolStats: mempool,
-    raw: info,
-  };
-}
-
-/** Asset registry + issuance stats. Defaults to L-BTC (the policy asset). */
-export async function liquidAssetInfo(args = {}, opts = {}) {
-  const assetId = liquidAssetId(args.assetId || args.asset || LIQUID_LBTC_ASSET_ID, "assetId");
-  const info = await getJson(`/asset/${assetId}`, opts);
-  const chain = info.chain_stats || {};
-  return {
-    provider: "liquid-esplora",
-    assetId,
-    isPolicyAsset: assetId === LIQUID_LBTC_ASSET_ID,
-    name: info.name ?? info.entity?.domain ?? null,
-    ticker: info.ticker ?? null,
-    precision: info.precision ?? null,
-    issuanceTxid: info.issuance_txin?.txid ?? null,
-    txCount: chain.tx_count ?? null,
-    // Peg fields exist only for the policy asset; issued assets carry
-    // issued_amount / burned_amount instead.
-    pegInAmount: chain.peg_in_amount == null ? null : String(chain.peg_in_amount),
-    pegOutAmount: chain.peg_out_amount == null ? null : String(chain.peg_out_amount),
-    issuedAmount: chain.issued_amount == null ? null : String(chain.issued_amount),
-    burnedAmount: chain.burned_amount == null ? null : String(chain.burned_amount),
-    circulatingAmount:
-      chain.peg_in_amount != null
-        ? String(Number(chain.peg_in_amount) - Number(chain.peg_out_amount || 0) - Number(chain.burned_amount || 0))
-        : chain.issued_amount != null
-          ? String(Number(chain.issued_amount) - Number(chain.burned_amount || 0))
-          : null,
-    raw: info,
-  };
-}

package/src/data/providers/magiceden-ordinals.mjs

@@ -1,141 +0,0 @@
-// Magic Eden ordinals market stats (api-mainnet.magiceden.dev/v2/ord/btc).
-//
-// UPSTREAM STATUS — measured, not assumed. As of the last verification pass
-// EVERY call to this host returned:
-//     HTTP 503  "no healthy upstream"
-// across repeated attempts, on the keyless (.dev) host. The keyed host
-// (api-mainnet.magiceden.us) answers 401 without a key, so the outage is on
-// Magic Eden's side, not a local networking problem.
-//
-// This module is therefore wired as a BEST-EFFORT source that reports the
-// outage honestly instead of masking it:
-//   - health() returns ok:false with the real status while the upstream is
-//     down. It does not report a green light for a dead endpoint.
-//   - collectionStat() surfaces a typed `upstreamDown` result rather than
-//     throwing an opaque HTTP error, so a caller can fall back to `satflow`
-//     (Oracle's primary BTC NFT market provider) without special-casing text.
-//
-// SCOPE: only /v2/ord/btc/stat is wired. The other ord routes (collections,
-// tokens, activities) were unreachable, so wiring them would be speculative.
-//
-// RATE LIMIT: Magic Eden documents 600 requests/minute (10 rps) on this API.
-// http.mjs already honours Retry-After on 429.
-//
-// Read-only. No listing, no bidding, no PSBT construction here.
-
-import { httpJson } from "../http.mjs";
-
-export const MAGICEDEN_ORD_API = "https://api-mainnet.magiceden.dev/v2/ord/btc";
-/** Documented ceiling: 600 req/min. */
-export const MAGICEDEN_RATE_LIMIT_RPM = 600;
-
-function baseUrl(opts = {}) {
-  return String(opts.baseUrl || process.env.MAGICEDEN_ORD_API_URL || MAGICEDEN_ORD_API).replace(/\/$/, "");
-}
-
-function headers(opts = {}) {
-  const h = { Accept: "application/json" };
-  // Optional. The keyless .dev host needs no auth; a key is only meaningful
-  // against the keyed host and is never required by this module.
-  const key = opts.apiKey || process.env.MAGICEDEN_API_KEY;
-  if (key) h.Authorization = `Bearer ${key}`;
-  return h;
-}
-
-export function collectionSymbol(value, label = "collectionSymbol") {
-  const text = String(value || "").trim().toLowerCase();
-  if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(text)) {
-    throw new Error(`magiceden-ordinals: ${label} must be a slug like "nodemonkes"`);
-  }
-  return text;
-}
-
-function get(path, opts = {}) {
-  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-    headers: headers(opts),
-    // The upstream 503s are a hard outage, not transient congestion. Retrying
-    // twice per call just multiplies latency during the outage window.
-    retries: opts.retries ?? 1,
-  });
-}
-
-/**
- * Probe the /stat route with a known collection. Reports the upstream's real
- * state — a 503 is surfaced as ok:false, never smoothed over.
- */
-export async function magicEdenOrdHealth(opts = {}) {
-  const probe = collectionSymbol(opts.probeCollection || process.env.MAGICEDEN_PROBE_COLLECTION || "nodemonkes");
-  try {
-    const stat = await get(`/stat?collectionSymbol=${encodeURIComponent(probe)}`, opts);
-    return {
-      ok: stat != null && typeof stat === "object",
-      provider: "magiceden-ordinals",
-      baseUrl: baseUrl(opts),
-      probeCollection: probe,
-      rateLimitRpm: MAGICEDEN_RATE_LIMIT_RPM,
-      exec: false,
-    };
-  } catch (error) {
-    const status = error?.status ?? null;
-    return {
-      ok: false,
-      provider: "magiceden-ordinals",
-      baseUrl: baseUrl(opts),
-      probeCollection: probe,
-      status,
-      upstreamDown: status === 503 || status === 502 || status === 504,
-      error: String(error?.message || error),
-      fallback: "satflow",
-      note:
-        status === 503
-          ? "Magic Eden ordinals API returned 503 'no healthy upstream'. Use the satflow provider for BTC NFT market data."
-          : undefined,
-      exec: false,
-    };
-  }
-}
-
-/**
- * Floor / volume / listed counts for one ordinals collection.
- * Returns { ok:false, upstreamDown:true } instead of throwing when Magic Eden
- * is unavailable, so a caller can degrade to satflow deterministically.
- */
-export async function magicEdenOrdCollectionStat(args = {}, opts = {}) {
-  const symbol = collectionSymbol(args.collectionSymbol || args.symbol || args.collection, "collectionSymbol");
-  try {
-    const s = await get(`/stat?collectionSymbol=${encodeURIComponent(symbol)}`, opts);
-    const floorSats = s?.floorPrice == null ? null : Number(s.floorPrice);
-    return {
-      ok: true,
-      provider: "magiceden-ordinals",
-      collectionSymbol: symbol,
-      floorPriceSats: floorSats == null ? null : String(s.floorPrice),
-      floorPriceBtc: floorSats == null ? null : floorSats / 1e8,
-      totalVolumeSats: s?.totalVolume == null ? null : String(s.totalVolume),
-      totalVolumeBtc: s?.totalVolume == null ? null : Number(s.totalVolume) / 1e8,
-      totalListed: s?.totalListed ?? null,
-      owners: s?.owners ?? null,
-      supply: s?.supply ?? null,
-      pendingTransactions: s?.pendingTransactions ?? null,
-      inscriptionNumberMin: s?.inscriptionNumberMin ?? null,
-      inscriptionNumberMax: s?.inscriptionNumberMax ?? null,
-      raw: s,
-    };
-  } catch (error) {
-    const status = error?.status ?? null;
-    const down = status === 502 || status === 503 || status === 504;
-    if (!down) throw error;
-    return {
-      ok: false,
-      provider: "magiceden-ordinals",
-      collectionSymbol: symbol,
-      status,
-      upstreamDown: true,
-      error: String(error?.message || error),
-      fallback: "satflow",
-      note: "Magic Eden ordinals API is returning 5xx ('no healthy upstream'). Query the satflow provider for floors and listings.",
-    };
-  }
-}