@oracle-agent/oracle 0.1.0

package/src/chains.mjs

@@ -0,0 +1,62 @@
+// EVM chain registry — the desk is multi-chain by design (any EVM chain).
+// A "venue" (rh/poly/hl) is a product surface; a "chain" is where a tx settles.
+// One agent wallet can sign on ANY EVM chain — same key, different
+// provider/RPC. This registry keeps chainIds first-class so adapters never
+// hardcode a single chain (a real bug we unwound once: an inline chainId===1
+// special case in a mint path).
+
+// Known chains the desk touches today. Extensible: add an entry, nothing else changes.
+export const CHAINS = {
+  robinhood: { chainId: 4663, name: "Robinhood Chain", rpcEnv: ["RH_CHAIN_RPC"], evm: true },
+  ethereum:  { chainId: 1,    name: "Ethereum",        rpcEnv: ["ETH_RPC_URL", "ETHEREUM_RPC_URL", "MAINNET_RPC_URL"], evm: true },
+  polygon:   { chainId: 137,  name: "Polygon",         rpcEnv: ["POLYGON_RPC_URL", "POLYGON_RPC"], evm: true },
+  arbitrum:  { chainId: 42161, name: "Arbitrum One",   rpcEnv: ["ARBITRUM_RPC_URL", "ARB_RPC_URL"], evm: true },
+  base:      { chainId: 8453, name: "Base",            rpcEnv: ["BASE_RPC_URL"], evm: true },
+  hyperevm:  { chainId: 999,  name: "HyperEVM",        rpcEnv: ["HYPEREVM_RPC_URL", "HYPER_EVM_RPC"], evm: true },
+  bsc:       { chainId: 56,   name: "BNB Smart Chain", rpcEnv: ["BSC_RPC_URL", "BNB_RPC_URL"], evm: true },
+  avalanche: { chainId: 43114, name: "Avalanche C-Chain", rpcEnv: ["AVALANCHE_RPC_URL", "AVAX_RPC_URL"], evm: true },
+  optimism:  { chainId: 10,   name: "OP Mainnet",       rpcEnv: ["OPTIMISM_RPC_URL", "OP_RPC_URL"], evm: true },
+  abstract:  { chainId: 2741, name: "Abstract",         rpcEnv: ["ABSTRACT_RPC_URL", "ABS_RPC_URL"], evm: true },
+  // Tether/Bitfinex-linked Stable L1 — gas = USDT0/gUSDT; FEFER-class memes (Dyor)
+  stable:    { chainId: 988,  name: "Stable Mainnet",  rpcEnv: ["STABLE_RPC_URL", "STABLE_RPC"], evm: true },
+};
+
+const BY_ID = new Map(Object.values(CHAINS).map((c) => [c.chainId, c]));
+
+/** Look up a chain by numeric chainId. Returns null if unknown (never throws here). */
+export function chainById(chainId) {
+  return BY_ID.get(Number(chainId)) || null;
+}
+
+/**
+ * Register (or override) an EVM chain at runtime so the desk supports ANY EVM
+ * chain without a code change. Idempotent.
+ * @param {{ key:string, chainId:number, name?:string, rpcEnv?:string[] }} def
+ */
+export function registerChain({ key, chainId, name, rpcEnv = [] }) {
+  if (!key) throw new Error("registerChain requires a key");
+  if (!Number.isInteger(Number(chainId))) throw new Error("registerChain requires a numeric chainId");
+  const entry = { chainId: Number(chainId), name: name || key, rpcEnv, evm: true };
+  CHAINS[key] = entry;
+  BY_ID.set(entry.chainId, entry);
+  return entry;
+}
+
+/**
+ * Resolve a usable RPC URL for a chainId from the environment, trying each
+ * candidate env var in order. Returns null if none set (caller decides if fatal).
+ */
+export function rpcUrlFor(chainId, env = process.env) {
+  const c = chainById(chainId);
+  if (!c) return null;
+  for (const name of c.rpcEnv) {
+    const v = (env[name] || "").trim();
+    if (v) return v;
+  }
+  return null;
+}
+
+/** True if we recognize this chainId as a supported EVM chain. */
+export function isSupportedChain(chainId) {
+  return BY_ID.has(Number(chainId));
+}

package/src/data/catalog.mjs

@@ -0,0 +1,495 @@
+// Provider catalog — DATA plane registry. Wallet keys never live here.
+
+/** @typedef {{ id: string, venue: string, chainIds: number[], auth: 'none'|'apiKey'|'agentKey', ops: string[], baseEnv?: string[], description?: string }} ProviderMeta */
+
+const REGISTRY = new Map();
+
+export function registerProvider(meta) {
+  if (!meta?.id) throw new Error("registerProvider requires id");
+  if (!meta.venue) throw new Error("registerProvider requires venue");
+  if (!Array.isArray(meta.ops)) throw new Error("registerProvider requires ops[]");
+  REGISTRY.set(meta.id, {
+    chainIds: meta.chainIds || [],
+    auth: meta.auth || "none",
+    description: meta.description || "",
+    baseEnv: meta.baseEnv || [],
+    ...meta,
+  });
+  return REGISTRY.get(meta.id);
+}
+
+export function getProvider(id) {
+  return REGISTRY.get(id) || null;
+}
+
+export function listProviders({ venue, op } = {}) {
+  let all = [...REGISTRY.values()];
+  if (venue) all = all.filter((p) => p.venue === venue);
+  if (op) all = all.filter((p) => p.ops.includes(op));
+  return all;
+}
+
+export function clearProvidersForTest() {
+  REGISTRY.clear();
+}
+
+// ── Built-in providers ──────────────────────────────────────────────────────
+
+registerProvider({
+  id: "hl-info",
+  venue: "hl",
+  chainIds: [],
+  auth: "none",
+  ops: [
+    "health",
+    "allMids",
+    "l2Book",
+    "outcomeMeta",
+    "clearinghouse",
+    "userFills",
+    "meta",
+    "metaAndAssetCtxs",
+    "candleSnapshot",
+    "openOrders",
+    "frontendOpenOrders",
+    "userState",
+    "spotMeta",
+  ],
+  baseEnv: ["HL_INFO_URL", "HL_API_URL"],
+  description: "Hyperliquid public /info",
+});
+
+registerProvider({
+  id: "poly-public",
+  venue: "poly",
+  chainIds: [137],
+  auth: "none",
+  ops: ["health", "time", "markets", "book", "midpoint", "spread", "price", "events"],
+  baseEnv: ["POLY_CLOB_URL", "POLY_GAMMA_URL"],
+  description: "Polymarket CLOB + Gamma public REST",
+});
+
+registerProvider({
+  id: "rh-agent",
+  venue: "rh",
+  chainIds: [4663, 1],
+  auth: "none",
+  ops: [
+    "health",
+    "policy",
+    "chainConfig",
+    "chainGas",
+    "swapsConfig",
+    "swapsPresets",
+    "tradingStatus",
+    "nftDrops",
+    "feeEstimate",
+  ],
+  baseEnv: ["RH_AGENT_BASE_URL", "RH_AGENT_URL"],
+  description: "RH agent local HTTP (unauthenticated read routes)",
+});
+
+registerProvider({
+  id: "evm-rpc",
+  venue: "evm",
+  chainIds: [1, 137, 42161, 8453, 10, 4663, 999],
+  auth: "none",
+  ops: ["health", "healthAll", "blockNumber", "chainId", "getBalance", "call", "erc20Allowance", "erc20Balance", "transactionReceipt"],
+  baseEnv: ["ETH_RPC_URL", "POLYGON_RPC_URL", "RH_CHAIN_RPC", "BASE_RPC_URL", "ARBITRUM_RPC_URL"],
+  description: "EVM JSON-RPC multi-chain (env RPC or public fallbacks)",
+});
+
+registerProvider({
+  id: "solana-rpc",
+  venue: "solana",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "latestBlockhash", "getBalance", "tokenAccounts", "simulate"],
+  baseEnv: ["SOLANA_RPC_URL"],
+  description: "Solana mainnet JSON-RPC read/prepare surface (no key, no signing, no broadcast)",
+});
+
+registerProvider({
+  id: "bitcoin-esplora",
+  venue: "bitcoin",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "tipHeight", "fees", "address", "utxos", "tx", "decode"],
+  execution: "read-only",
+  baseEnv: ["BTC_ESPLORA_URL", "BTC_NETWORK"],
+  description:
+    "Bitcoin L1 via Esplora (mempool.space/Blockstream). Reads only on data plane. User-signed broadcast is bitcoin_send on exec MCP. No Core RPC, no house keys. Wallets: Xverse/UniSat/Leather/OKX/Phantom",
+});
+
+registerProvider({
+  id: "bitcoin-meta",
+  venue: "bitcoin-metaprotocol",
+  chainIds: [],
+  auth: "optionalApiKey",
+  ops: [
+    "health",
+    "runeBalances",
+    "inscriptions",
+    "inscriptionInfo",
+    "inscriptionChildren",
+    "ordBlockInfo",
+  ],
+  execution: "read-only",
+  baseEnv: ["BTC_META_API_URL", "UNISAT_API_KEY", "BESTINSLOT_API_KEY"],
+  description:
+    "Bitcoin ordinals/runes reads. Keyless tier via ordinals.com recursive (inscriptionInfo/children/blockInfo); address-indexed ops (inscriptions, runeBalances) need a keyed indexer. Hiro is deprecated (410) and Magic Eden BTC is dead — use satflow for market.",
+});
+
+registerProvider({
+  id: "satflow",
+  venue: "bitcoin-marketplace",
+  chainIds: [],
+  auth: "apiKey",
+  ops: [
+    "health",
+    "collectionFloors",
+    "collectionStats",
+    "item",
+    "walletContents",
+    "floorListings",
+    "preparePurchase",
+    "prepareList",
+  ],
+  execution: "prepare",
+  baseEnv: ["SATFLOW_API_KEY", "SATFLOW_API_URL"],
+  description:
+    "Satflow ordinals+runes marketplace (api.satflow.com). Primary BTC NFT market after Magic Eden BTC sunset. PSBT intents for buy/list; key via x-api-key.",
+});
+
+registerProvider({
+  id: "jupiter",
+  venue: "solana-dex",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["JUPITER_SWAP_API_URL"],
+  description: "Jupiter Swap API v1 quote + unsigned user-signature swap transaction preparation",
+});
+
+registerProvider({
+  id: "hl-perps",
+  venue: "hyperliquid",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "assetInfo", "prepareOrder", "prepareCancel", "prepareLeverage", "prepareIsolatedMargin", "prepareBracket"],
+  notes: "Hyperliquid perp orders/leverage. PREPARE-ONLY: returns signable actions, never submits.",
+});
+
+registerProvider({
+  id: "hl-markets",
+  venue: "hyperliquid",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "markets", "leaderboards", "coin", "spot"],
+  notes: "Joined Hyperliquid market datapoints for the Hyperliquid agent. Read-only.",
+});
+
+registerProvider({
+  id: "hl-staking",
+  venue: "hypercore-staking",
+  chainIds: [],
+  auth: "none",
+  ops: [
+    "health",
+    "validators",
+    "delegatorSummary",
+    "delegations",
+    "rewards",
+    "history",
+    "preflight",
+    "prepareStakeDeposit",
+    "prepareStakeWithdraw",
+    "prepareDelegate",
+  ],
+  execution: "prepare",
+  baseEnv: ["HL_INFO_URL", "HL_EXCHANGE_URL", "HL_TESTNET"],
+  description:
+    "Hyperliquid HyperCore HYPE staking. Public reads (validators, delegations, rewards) plus EIP-712 prepare for cDeposit / cWithdraw / tokenDelegate. Prepare-only: the user's wallet signs and submits, Oracle never posts to /exchange.",
+});
+
+registerProvider({
+  id: "magiceden-sol",
+  venue: "solana-nft",
+  chainIds: [],
+  auth: "optionalApiKey",
+  ops: ["health", "stats", "listings", "tokenListings", "prepareBuy", "prepareList", "prepareMint"],
+  execution: "prepare",
+  baseEnv: ["MAGICEDEN_API_KEY", "MAGICEDEN_API_URL"],
+  description:
+    "Magic Eden Solana NFT market. Reads (stats/listings) are keyless; buy/list/mint instruction builders need MAGICEDEN_API_KEY and return an unsigned base64 transaction for the user's Solana wallet. Never signs or broadcasts.",
+});
+
+registerProvider({
+  id: "defillama",
+  venue: "prices",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "prices", "pricesBySymbol", "protocols", "yields", "stablecoins", "dexVolumes"],
+  baseEnv: ["DEFILLAMA_COINS_URL", "DEFILLAMA_API_URL"],
+  description: "DeFiLlama public prices + protocols TVL",
+});
+
+registerProvider({
+  id: "lifi",
+  venue: "dex",
+  chainIds: [1, 10, 56, 137, 988, 999, 2741, 4663, 8453, 42161, 43114],
+  auth: "none",
+  ops: ["health", "quote", "prepare", "chains"],
+  execution: "prepare",
+  baseEnv: ["LIFI_API_URL"],
+  description: "LI.FI public cross-chain / DEX aggregator quotes (no key)",
+});
+
+registerProvider({
+  id: "dexscreener",
+  venue: "dex",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "token", "search", "pair"],
+  baseEnv: ["DEXSCREENER_API_URL"],
+  description: "DexScreener public token/pair discovery",
+});
+
+registerProvider({
+  id: "uniswap-v3",
+  venue: "dex",
+  chainIds: [1, 8453, 42161],
+  auth: "none",
+  ops: ["health", "quote", "prepare", "quotePath", "ethUsdc", "chains"],
+  execution: "prepare",
+  baseEnv: [
+    "ETH_RPC_URL",
+    "BASE_RPC_URL",
+    "ARBITRUM_RPC_URL",
+  ],
+  description: "Uniswap V3 QuoterV2 exact-in quotes via eth_call (ETH/Base/Arb, no key)",
+});
+
+registerProvider({
+  id: "aerodrome",
+  venue: "dex",
+  chainIds: [8453],
+  auth: "none",
+  ops: ["health", "quote", "prepare", "chains"],
+  execution: "prepare",
+  baseEnv: ["BASE_RPC_URL"],
+  description:
+    "Aerodrome Slipstream CL on Base — QuoterV2 + SwapRouter exact-input via eth_call (tickSpacing, no key)",
+});
+
+registerProvider({
+  id: "zerox",
+  venue: "dex",
+  chainIds: [1, 10, 137, 8453, 42161],
+  auth: "apiKey",
+  ops: ["health", "price", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["ZEROX_API_KEY", "ZEROX_API_URL"],
+  description:
+    "0x Swap API v2 price/quote/prepare — requires ZEROX_API_KEY (unconfigured without key; no Oracle key shipped)",
+});
+
+registerProvider({
+  id: "across",
+  venue: "bridge",
+  chainIds: [1, 10, 137, 42161, 8453],
+  auth: "none",
+  ops: ["health", "suggestedFees"],
+  baseEnv: ["ACROSS_API_URL"],
+  description: "Across bridge suggested-fees (public)",
+});
+
+registerProvider({
+  id: "hop",
+  venue: "bridge",
+  chainIds: [1, 10, 137, 42161],
+  auth: "none",
+  ops: ["health", "quote"],
+  baseEnv: ["HOP_API_URL"],
+  description: "Hop Protocol bridge quotes (public)",
+});
+
+registerProvider({
+  id: "relay",
+  venue: "bridge",
+  chainIds: [1, 10, 137, 8453, 42161],
+  auth: "none",
+  ops: ["health", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["RELAY_API_URL"],
+  description: "Relay.link bridge/swap quotes (public)",
+});
+
+registerProvider({
+  id: "cowswap",
+  venue: "dex",
+  chainIds: [1, 100, 42161, 8453],
+  auth: "none",
+  ops: ["health", "quote", "prepareOrder", "order", "status", "chains"],
+  execution: "intent",
+  baseEnv: [],
+  description: "CowSwap batch auction quotes + guarded EIP-712 order intents (public)",
+});
+
+registerProvider({
+  id: "oneinch",
+  venue: "dex",
+  chainIds: [1, 10, 137, 8453, 42161],
+  auth: "apiKey",
+  ops: ["health", "quote", "prepare", "approveSpender"],
+  execution: "prepare",
+  baseEnv: ["ONEINCH_API_KEY", "ONEINCH_API_URL"],
+  description:
+    "1inch Swap API v6 quote/prepare — requires ONEINCH_API_KEY (unconfigured without key; no Oracle key shipped)",
+});
+
+registerProvider({
+  id: "hl-ws",
+  venue: "hl",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "allMids", "l2Book", "snapshot"],
+  baseEnv: ["HL_WS_URL"],
+  description: "Hyperliquid short-lived WS snapshots (allMids/l2Book)",
+});
+
+registerProvider({
+  id: "poly-ws",
+  venue: "poly",
+  chainIds: [137],
+  auth: "none",
+  ops: ["health", "book", "snapshot"],
+  baseEnv: ["POLY_WS_URL"],
+  description: "Polymarket CLOB short-lived WS market snapshots",
+});
+
+registerProvider({
+  id: "opensea-nft",
+  venue: "nft",
+  chainIds: [1],
+  auth: "apiKey",
+  ops: ["health", "collection", "floor"],
+  baseEnv: ["OPENSEA_API_KEY", "OPENSEA_ENV_FILE"],
+  description: "OpenSea collection + floor (OPENSEA_API_KEY)",
+});
+
+registerProvider({
+  id: "hyperevm-dex",
+  venue: "hyperevm",
+  chainIds: [999],
+  auth: "none",
+  ops: ["health", "search", "token"],
+  baseEnv: ["HYPEREVM_RPC_URL"],
+  description: "HyperEVM pair discovery via DexScreener + optional RPC",
+});
+
+registerProvider({
+  id: "geckoterminal",
+  venue: "dex-data",
+  chainIds: [],
+  auth: "none",
+  ops: ["health", "networks", "pool", "token", "ohlcv"],
+  baseEnv: ["GECKOTERMINAL_API_URL"],
+  description: "GeckoTerminal public networks, pools, tokens, and OHLCV",
+});
+
+registerProvider({
+  id: "curve",
+  venue: "dex",
+  chainIds: [1, 10, 56, 137, 988, 999, 4663, 8453, 42161, 43114],
+  auth: "none",
+  ops: ["health", "openapi", "pools", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["CURVE_API_URL"],
+  description: "Curve public pool registry API + RouterNG validated single-hop prepare",
+});
+
+registerProvider({
+  id: "gmx",
+  venue: "perps-data",
+  chainIds: [42161, 43114],
+  auth: "none",
+  ops: ["health", "tickers", "markets", "marketsInfo", "tokens", "prepareOrder", "positions", "orderStatus", "verifyOrder"],
+  execution: "intent",
+  baseEnv: [],
+  description: "GMX v2 public oracle/markets plus guarded async order intents on Arbitrum and Avalanche",
+});
+
+registerProvider({
+  id: "morpho",
+  venue: "lending-data",
+  chainIds: [1, 10, 137, 2741, 8453, 42161, 4663, 999, 988],
+  auth: "none",
+  ops: ["health", "markets", "vaults", "prepareVault"],
+  execution: "intent",
+  baseEnv: ["MORPHO_API_URL"],
+  description: "Morpho public GraphQL markets/vaults + guarded ERC-4626 vault intents",
+});
+
+registerProvider({
+  id: "balancer",
+  venue: "dex",
+  chainIds: [1, 10, 137, 42161, 43114, 8453],
+  auth: "none",
+  ops: ["health", "pools", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["BALANCER_API_URL"],
+  description: "Balancer public GraphQL pool data + v3 Router exact-input prepare (Polygon read-only)",
+});
+
+registerProvider({
+  id: "pendle",
+  venue: "yield",
+  chainIds: [1, 10, 56, 8453, 42161, 999],
+  auth: "none",
+  ops: ["health", "markets", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["PENDLE_API_URL"],
+  description: "Pendle public yield-market API + Hosted SDK direct Convert prepare",
+});
+
+registerProvider({
+  id: "odos",
+  venue: "dex",
+  chainIds: [1, 10, 56, 137, 8453, 42161, 43114],
+  auth: "none",
+  ops: ["health", "chains", "quote", "prepare"],
+  // Tier is the honest signal here: the API returns HTTP 410 Gone as of
+  // 2026-07-30, so it can no longer read or prepare anything. Leaving it as
+  // "prepare" would advertise a capability that is provably dead.
+  execution: "unavailable",
+  deprecated: {
+    since: "2026-07-30",
+    reason: "Odos sunset the public SOR API; /sor/quote/v2 and v3 both return 410 Gone",
+    evidence: "sunset: Thu, 30 Jul 2026 12:00:00 GMT response header",
+  },
+  baseEnv: ["ODOS_API_URL"],
+  description: "Odos public SOR (DEPRECATED upstream 2026-07-30 -- endpoint returns 410)",
+});
+
+registerProvider({
+  id: "blockscout",
+  venue: "explorer",
+  chainIds: [1, 10, 137, 8453, 42161],
+  auth: "none",
+  ops: ["health", "stats", "address", "token"],
+  baseEnv: [],
+  description: "Verified public Blockscout REST v2 instances",
+});
+
+registerProvider({
+  id: "paraswap",
+  venue: "dex",
+  chainIds: [1, 10, 56, 137, 8453, 42161, 43114],
+  auth: "none",
+  ops: ["health", "tokens", "price", "quote", "prepare"],
+  execution: "prepare",
+  baseEnv: ["PARASWAP_API_URL"],
+  description: "ParaSwap/Velora public price routes + validated transaction builder",
+});