@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/data/providers/meteora-dlmm.mjs

@@ -0,0 +1,168 @@
+// Meteora — Solana AMM pool discovery (dynamic AMM, DLMM-adjacent, LST, farms).
+//
+// This is a POOL INVENTORY surface, not a router: it answers "where is the
+// liquidity and what does it yield", which Jupiter's quote endpoint does not.
+// Read-only — no position or swap preparation.
+//
+// Upstream query-string quirks that are easy to get wrong:
+//   - text search is `filter=`, NOT `search_term=`/`q=`/`name=` (those are
+//     accepted and then silently IGNORED, returning the unfiltered top pools)
+//   - sort_key is an enum: tvl | volume | fee_tvl_ratio | l_m
+//   - pool_type is an enum: dynamic | multitoken | lst | farms
+//   Anything outside those enums 400s.
+
+import { httpJson } from "../http.mjs";
+
+export const METEORA_AMM_API = "https://amm-v2.meteora.ag";
+
+const SORT_KEYS = new Set(["tvl", "volume", "fee_tvl_ratio", "l_m"]);
+const POOL_TYPES = new Set(["dynamic", "multitoken", "lst", "farms"]);
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+function base(opts = {}) {
+  return String(opts.baseUrl || process.env.METEORA_API_URL || METEORA_AMM_API).replace(/\/$/, "");
+}
+
+function num(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function normalizePool(pool = {}) {
+  return {
+    address: pool.pool_address || null,
+    name: pool.pool_name || null,
+    type: pool.pool_type || null,
+    version: pool.pool_version ?? null,
+    mints: pool.pool_token_mints || [],
+    tokenAmounts: pool.pool_token_amounts || [],
+    tokenUsdAmounts: pool.pool_token_usd_amounts || [],
+    lpMint: pool.lp_mint || null,
+    lpDecimals: pool.lp_decimal ?? null,
+    lpPriceUsd: num(pool.pool_lp_price_in_usd),
+    tvlUsd: num(pool.pool_tvl),
+    farmTvlUsd: num(pool.farm_tvl),
+    volume24hUsd: num(pool.trading_volume),
+    volume7dUsd: num(pool.weekly_trading_volume),
+    fee24hUsd: num(pool.fee_volume),
+    fee7dUsd: num(pool.weekly_fee_volume),
+    // trade_apy is fee yield; farming_apy is emissions. They are additive.
+    tradeApyPct: num(pool.trade_apy),
+    weeklyTradeApyPct: num(pool.weekly_trade_apy),
+    baseApyPct: num(pool.daily_base_apy),
+    farmingApyPct: num(pool.farming_apy),
+    totalApyPct: (num(pool.trade_apy) ?? 0) + (num(pool.farming_apy) ?? 0),
+    aprPct: num(pool.apr),
+    feePct: num(pool.total_fee_pct),
+    farmingPool: pool.farming_pool || null,
+    isLst: Boolean(pool.is_lst),
+    isMeme: Boolean(pool.is_meme),
+    permissioned: Boolean(pool.permissioned),
+    // Meteora's own "we don't recognise these tokens" flag — treat as risk.
+    unknownTokens: Boolean(pool.unknown),
+    createdAt: pool.created_at ?? null,
+  };
+}
+
+function buildSearchUrl(args = {}, opts = {}) {
+  const url = new URL(`${base(opts)}/pools/search`);
+  const page = Math.max(0, Number(args.page) || 0);
+  const size = Math.max(1, Math.min(Number(args.size ?? args.limit) || 20, 100));
+  url.searchParams.set("page", String(page));
+  url.searchParams.set("size", String(size));
+
+  if (args.sortKey != null) {
+    const key = String(args.sortKey);
+    if (!SORT_KEYS.has(key)) {
+      throw new Error(`meteora-dlmm: sortKey must be one of ${[...SORT_KEYS].join(", ")}`);
+    }
+    url.searchParams.set("sort_key", key);
+    url.searchParams.set("order_by", args.orderBy === "asc" ? "asc" : "desc");
+  }
+  if (args.poolType != null) {
+    const type = String(args.poolType);
+    if (!POOL_TYPES.has(type)) {
+      throw new Error(`meteora-dlmm: poolType must be one of ${[...POOL_TYPES].join(", ")}`);
+    }
+    url.searchParams.set("pool_type", type);
+  }
+  const filter = args.filter ?? args.query ?? args.search;
+  if (filter != null && String(filter).trim()) url.searchParams.set("filter", String(filter).trim());
+  const mints = args.mints || args.includeTokenMints;
+  if (mints) {
+    const list = (Array.isArray(mints) ? mints : [mints]).map((m) => String(m).trim());
+    for (const mint of list) {
+      if (!BASE58.test(mint)) throw new Error(`meteora-dlmm: mint ${mint} is not a base58 public key`);
+    }
+    url.searchParams.set("include_token_mints", list.join(","));
+  }
+  return { url, page, size };
+}
+
+async function search(args = {}, opts = {}) {
+  const { url, page, size } = buildSearchUrl(args, opts);
+  const data = await httpJson(url.toString(), {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  const pools = (Array.isArray(data?.data) ? data.data : []).map(normalizePool);
+  return { pools, totalCount: data?.total_count ?? null, page, size };
+}
+
+export async function meteoraHealth(opts = {}) {
+  try {
+    const { pools, totalCount } = await search({ size: 3 }, opts);
+    return {
+      ok: pools.length > 0,
+      provider: "meteora-dlmm",
+      poolsIndexed: totalCount,
+      sample: pools.length,
+      exec: false,
+    };
+  } catch (error) {
+    return { ok: false, provider: "meteora-dlmm", error: String(error?.message || error), exec: false };
+  }
+}
+
+/** Top pools, ranked. Defaults to highest TVL. */
+export async function meteoraPools(args = {}, opts = {}) {
+  const result = await search({ sortKey: args.sortKey || "tvl", orderBy: args.orderBy || "desc", ...args }, opts);
+  let pools = result.pools;
+  const minTvl = Number(args.minTvlUsd);
+  if (Number.isFinite(minTvl)) pools = pools.filter((p) => (p.tvlUsd ?? 0) >= minTvl);
+  if (args.excludeUnknown === true) pools = pools.filter((p) => !p.unknownTokens);
+  return {
+    provider: "meteora-dlmm",
+    chain: "solana-mainnet-beta",
+    page: result.page,
+    size: result.size,
+    totalCount: result.totalCount,
+    count: pools.length,
+    tvlUsd: pools.reduce((a, p) => a + (p.tvlUsd ?? 0), 0),
+    pools,
+  };
+}
+
+/**
+ * Search pools by token symbol/name text or by exact mint.
+ * Prefer `mints` — text search matches pool names, which meme tokens spoof.
+ */
+export async function meteoraPoolSearch(args = {}, opts = {}) {
+  const filter = args.filter ?? args.query ?? args.search;
+  const mints = args.mints || args.includeTokenMints;
+  if ((filter == null || !String(filter).trim()) && !mints) {
+    throw new Error("meteora-dlmm: poolSearch requires filter text or mints[]");
+  }
+  const result = await search({ sortKey: args.sortKey || "tvl", orderBy: "desc", ...args }, opts);
+  return {
+    provider: "meteora-dlmm",
+    chain: "solana-mainnet-beta",
+    filter: filter ?? null,
+    mints: mints ? (Array.isArray(mints) ? mints : [mints]) : [],
+    page: result.page,
+    size: result.size,
+    totalCount: result.totalCount,
+    count: result.pools.length,
+    pools: result.pools,
+  };
+}

package/src/data/providers/morpho.mjs

@@ -0,0 +1,177 @@
+// Morpho public GraphQL API — markets/vaults, no key. ERC-4626 vault
+// prepare returns a guarded intent only; dynamic vault tx signing/submission is a
+// later, separately gated execution step.
+
+import { Interface, getAddress, isAddress, keccak256, toUtf8Bytes } from "ethers";
+import { httpJson } from "../http.mjs";
+import { rpcCall as defaultRpcCall } from "./evm-rpc.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
+
+export const MORPHO_API = "https://api.morpho.org/graphql";
+
+const ERC4626 = new Interface([
+  "function asset() view returns (address)",
+  "function maxDeposit(address owner) view returns (uint256)",
+  "function previewDeposit(uint256 assets) view returns (uint256)",
+  "function deposit(uint256 assets,address receiver) returns (uint256)",
+  "function maxWithdraw(address owner) view returns (uint256)",
+  "function previewWithdraw(uint256 assets) view returns (uint256)",
+  "function withdraw(uint256 assets,address receiver,address owner) returns (uint256)",
+]);
+
+const endpoint = (o = {}) => o.baseUrl || process.env.MORPHO_API_URL || MORPHO_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 MARKET_QUERY = `query Markets($first: Int, $where: MarketFilters) { markets(first: $first, where: $where) { items { marketId lltv listed loanAsset { address symbol decimals } collateralAsset { address symbol decimals } state { supplyAssetsUsd borrowAssetsUsd } } } }`;
+const VAULT_QUERY = `query Vaults($first: Int, $where: VaultFilters) { vaults(first: $first, where: $where) { items { address name symbol listed asset { address symbol decimals } state { totalAssets totalAssetsUsd apy } } } }`;
+
+function normalAddress(value, label) {
+  const text = String(value || "").trim();
+  if (!isAddress(text)) throw new Error(`morpho: ${label} must be an address`);
+  return getAddress(text).toLowerCase();
+}
+
+function amountString(value, label = "amount") {
+  try {
+    const n = BigInt(String(value));
+    if (n <= 0n) throw new Error("nonpositive");
+    return n.toString();
+  } catch {
+    throw new Error(`morpho: ${label} must be a positive integer string`);
+  }
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+async function callVault(chainId, vault, fn, args, opts = {}) {
+  const data = ERC4626.encodeFunctionData(fn, args);
+  const call = opts.rpcCall || defaultRpcCall;
+  const result = await call(Number(chainId), "eth_call", [{ to: vault, data }, "latest"], opts);
+  return ERC4626.decodeFunctionResult(fn, result);
+}
+
+function listedVault(items, vault) {
+  const target = vault.toLowerCase();
+  return (items || []).find((item) => String(item?.address || "").toLowerCase() === target) || null;
+}
+
+export async function morphoMarkets(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chainIds = (args.chainIds || [args.chainId || 1]).map(Number);
+  return gql(MARKET_QUERY, { first, chainIds, where: { chainId_in: chainIds } }, opts);
+}
+
+export async function morphoVaults(args = {}, opts = {}) {
+  const first = Math.min(100, Math.max(1, Number(args.first || 20)));
+  const chainIds = (args.chainIds || [args.chainId || 1]).map(Number);
+  return gql(VAULT_QUERY, { first, chainIds, where: { chainId_in: chainIds } }, opts);
+}
+
+export async function morphoHealth(opts = {}) {
+  const data = await gql("query { __typename }", {}, opts);
+  return { ok: data?.data?.__typename === "Query" };
+}
+
+export async function morphoPrepareVault(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? 8453);
+  const action = String(args.action || "deposit").toLowerCase();
+  if (!["deposit", "withdraw"].includes(action)) throw new Error("morpho: action must be deposit or withdraw");
+  const vault = normalAddress(args.vault || args.vaultAddress, "vault");
+  const owner = normalAddress(args.owner || args.from || args.sender, "owner");
+  const receiver = normalAddress(args.receiver || owner, "receiver");
+  const amount = amountString(args.amount || args.assets, "amount");
+  const minTotalAssetsUsd = Number(args.minTotalAssetsUsd ?? 100_000);
+
+  const vaults = await morphoVaults({ chainId, first: 100 }, opts);
+  const info = listedVault(vaults?.data?.vaults?.items, vault);
+  if (!info) throw new Error("morpho: vault not found in public Morpho vault registry");
+  if (info.listed === false) throw new Error("morpho: vault is not listed");
+  const totalAssetsUsd = Number(info?.state?.totalAssetsUsd ?? 0);
+  if (Number.isFinite(minTotalAssetsUsd) && totalAssetsUsd < minTotalAssetsUsd) {
+    throw new Error(`morpho: vault totalAssetsUsd ${totalAssetsUsd} below minimum ${minTotalAssetsUsd}`);
+  }
+
+  const [assetOnchain] = await callVault(chainId, vault, "asset", [], opts);
+  const asset = normalAddress(assetOnchain, "vault asset");
+  const apiAsset = info?.asset?.address ? normalAddress(info.asset.address, "api vault asset") : asset;
+  if (apiAsset !== asset) throw new Error("morpho: API asset and on-chain asset mismatch");
+
+  let data;
+  let floor;
+  if (action === "deposit") {
+    const [maxDeposit] = await callVault(chainId, vault, "maxDeposit", [owner], opts);
+    if (BigInt(amount) > BigInt(maxDeposit.toString())) throw new Error("morpho: amount exceeds maxDeposit");
+    const [sharesOut] = await callVault(chainId, vault, "previewDeposit", [amount], opts);
+    if (BigInt(sharesOut.toString()) <= 0n) throw new Error("morpho: previewDeposit returned zero shares");
+    floor = { minSharesOut: sharesOut.toString() };
+    data = ERC4626.encodeFunctionData("deposit", [amount, receiver]);
+  } else {
+    const [maxWithdraw] = await callVault(chainId, vault, "maxWithdraw", [owner], opts);
+    if (BigInt(amount) > BigInt(maxWithdraw.toString())) throw new Error("morpho: amount exceeds maxWithdraw");
+    const [sharesIn] = await callVault(chainId, vault, "previewWithdraw", [amount], opts);
+    if (BigInt(sharesIn.toString()) <= 0n) throw new Error("morpho: previewWithdraw returned zero shares");
+    floor = { maxSharesIn: sharesIn.toString() };
+    data = ERC4626.encodeFunctionData("withdraw", [amount, receiver, owner]);
+  }
+
+  const vaultGuard = {
+    mode: "erc4626-vault",
+    version: 1,
+    provider: "morpho",
+    chainId,
+    action,
+    vault,
+    asset,
+    owner,
+    receiver,
+    amount,
+    totalAssetsUsd,
+    ...floor,
+    calldataHash: keccak256(toUtf8Bytes(data)),
+    issuedAtMs: Date.now(),
+    expiresAtMs: Date.now() + 20_000,
+  };
+  vaultGuard.guardHash = keccak256(toUtf8Bytes(canonicalJson(vaultGuard)));
+
+  return stampPrepared({
+    provider: "morpho",
+    protocol: "erc4626-vault",
+    vaultReady: true,
+    executionReady: false,
+    signingReady: false,
+    broadcastReady: false,
+    requiresUserSignature: true,
+    chainId,
+    action,
+    vault,
+    asset,
+    owner,
+    receiver,
+    amount,
+    vaultInfo: info,
+    vaultGuard,
+    requiresApproval: action === "deposit" ? { token: asset, spender: vault, amount } : null,
+    transaction: {
+      chainId,
+      from: owner,
+      to: vault,
+      data,
+      value: "0x0",
+      madVault: vaultGuard,
+    },
+  }, { provider: "morpho", kind: "erc4626-vault" });
+}

package/src/data/providers/nft-gallery.mjs

@@ -0,0 +1,163 @@
+// Raster-only NFT contact sheets returned as SVG image content.
+
+import { timed } from "../http.mjs";
+
+const ALLOWED_IMAGE_HOSTS = Object.freeze([
+  "i.seadn.io",
+  "openseauserdata.com",
+  "arweave.net",
+  "ipfs.io",
+  "nftstorage.link",
+  "dweb.link",
+  "cloudflare-ipfs.com",
+  "ordinals.com",
+  "ordinals.g.com",
+  "cdn.helius-rpc.com",
+  "shdw-drive.genesysgo.net",
+]);
+
+const RASTER_MIME = new Set(["image/jpeg", "image/png", "image/webp"]);
+
+function allowedHost(hostname) {
+  const host = String(hostname || "").toLowerCase();
+  return ALLOWED_IMAGE_HOSTS.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
+}
+
+function gatewayUrl(value) {
+  const text = String(value || "").trim();
+  if (text.startsWith("ipfs://")) return `https://ipfs.io/ipfs/${text.slice(7).replace(/^ipfs\//, "")}`;
+  if (text.startsWith("ar://")) return `https://arweave.net/${text.slice(5)}`;
+  return text;
+}
+
+function safeImageUrl(value) {
+  const text = gatewayUrl(value);
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username || url.password || !allowedHost(url.hostname)) return null;
+  return url;
+}
+
+async function fetchRaster(value, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("gallery fetch unavailable");
+  let url = safeImageUrl(value);
+  if (!url) throw new Error("image host is not on the raster gallery allowlist");
+  const maxBytes = Math.min(Math.max(Number(opts.maxImageBytes ?? 1_500_000), 50_000), 4_000_000);
+
+  for (let redirect = 0; redirect <= 3; redirect += 1) {
+    const attempt = await timed(() => fetchImpl(url.toString(), {
+      method: "GET",
+      redirect: "manual",
+      headers: { accept: "image/jpeg,image/png,image/webp" },
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 12_000),
+    }));
+    if (!attempt.ok) throw new Error(attempt.error);
+    const response = attempt.data;
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers?.get?.("location");
+      if (!location) throw new Error("image redirect missing location");
+      const next = safeImageUrl(new URL(location, url).toString());
+      if (!next) throw new Error("image redirect left the host allowlist");
+      url = next;
+      continue;
+    }
+    if (!response.ok) throw new Error(`image HTTP ${response.status}`);
+    const mimeType = String(response.headers?.get?.("content-type") || "").split(";", 1)[0].toLowerCase();
+    if (!RASTER_MIME.has(mimeType)) throw new Error(`unsafe or unsupported image type ${mimeType || "unknown"}`);
+    const length = Number(response.headers?.get?.("content-length") || 0);
+    if (length > maxBytes) throw new Error("image exceeds gallery byte cap");
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (!bytes.length || bytes.length > maxBytes) throw new Error("image exceeds gallery byte cap");
+    return { mimeType, data: bytes.toString("base64"), sourceUrl: url.toString(), bytes: bytes.length };
+  }
+  throw new Error("too many image redirects");
+}
+
+function xml(value) {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function label(item, index) {
+  return item.name || item.collection || item.tokenId || `NFT ${index + 1}`;
+}
+
+export async function nftGallery(args = {}, opts = {}) {
+  const allItems = Array.isArray(args.items) ? args.items : [];
+  if (!allItems.length) throw new Error("nft gallery requires inventory items");
+  const pageSize = Math.min(Math.max(Number(args.pageSize ?? 12) || 12, 1), 12);
+  const page = Math.max(Number(args.page ?? 1) || 1, 1);
+  const totalPages = Math.max(Math.ceil(allItems.length / pageSize), 1);
+  if (page > totalPages) throw new Error(`nft gallery page ${page} exceeds ${totalPages}`);
+  const items = allItems.slice((page - 1) * pageSize, page * pageSize);
+  const loaded = [];
+  let totalBytes = 0;
+  const maxTotalBytes = Math.min(Math.max(Number(args.maxTotalBytes ?? 8_000_000), 250_000), 12_000_000);
+
+  for (const item of items) {
+    if (totalBytes >= maxTotalBytes) {
+      loaded.push({ item, image: null, error: "gallery page byte cap reached" });
+      continue;
+    }
+    try {
+      const image = await fetchRaster(item.imageUrl || item.originalImageUrl, {
+        ...opts,
+        maxImageBytes: Math.min(Number(args.maxImageBytes ?? 1_500_000), maxTotalBytes - totalBytes),
+      });
+      totalBytes += image.bytes;
+      loaded.push({ item, image, error: null });
+    } catch (error) {
+      loaded.push({ item, image: null, error: String(error?.message || error).slice(0, 180) });
+    }
+  }
+
+  const columns = 3;
+  const tileWidth = 340;
+  const tileHeight = 400;
+  const headerHeight = 76;
+  const rows = Math.ceil(items.length / columns);
+  const width = columns * tileWidth;
+  const height = headerHeight + rows * tileHeight;
+  const body = loaded.map(({ item, image, error }, index) => {
+    const column = index % columns;
+    const row = Math.floor(index / columns);
+    const x = column * tileWidth;
+    const y = headerHeight + row * tileHeight;
+    const art = image
+      ? `<image x="${x + 14}" y="${y + 14}" width="312" height="312" preserveAspectRatio="xMidYMid slice" href="data:${image.mimeType};base64,${image.data}"/>`
+      : `<rect x="${x + 14}" y="${y + 14}" width="312" height="312" rx="14" fill="#151820"/><text x="${x + 170}" y="${y + 165}" text-anchor="middle" fill="#76808f" font-size="16">image unavailable</text>`;
+    const title = xml(label(item, index).slice(0, 34));
+    const chain = xml(item.chain || "unknown chain");
+    return `${art}<text x="${x + 16}" y="${y + 350}" fill="#f3f5f7" font-size="17" font-weight="600">${title}</text><text x="${x + 16}" y="${y + 376}" fill="#8d98a8" font-size="13">${chain}${error ? " · placeholder" : ""}</text>`;
+  }).join("");
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><rect width="100%" height="100%" fill="#090b10"/><text x="24" y="34" fill="#ffffff" font-size="24" font-weight="700">NFT INVENTORY</text><text x="24" y="58" fill="#8d98a8" font-size="14">page ${page} of ${totalPages} · ${allItems.length} assets · generated ${xml(new Date().toISOString())}</text>${body}</svg>`;
+
+  return {
+    provider: "nft-portfolio",
+    operation: "gallery",
+    mimeType: "image/svg+xml",
+    dataBase64: Buffer.from(svg).toString("base64"),
+    page,
+    pageSize,
+    totalPages,
+    totalItems: allItems.length,
+    renderedItems: loaded.filter((row) => row.image).length,
+    placeholders: loaded.filter((row) => !row.image).map((row) => ({
+      assetKey: row.item.assetKey || null,
+      name: row.item.name || null,
+      sourceUrl: row.item.imageUrl || null,
+      error: row.error,
+    })),
+    rasterOnly: true,
+    externalScripts: false,
+  };
+}