@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/data/providers/lifi.mjs

@@ -0,0 +1,166 @@
+// 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

@@ -0,0 +1,152 @@
+// 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

@@ -0,0 +1,141 @@
+// 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.",
+    };
+  }
+}