@oracle-agent/oracle 0.14.1 → 0.15.0

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

@@ -1,216 +0,0 @@
-// Bitcoin L1 read/broadcast via Esplora HTTP (mempool.space / Blockstream).
-// No Bitcoin Core RPC required. No keys, no signing.
-
-import { httpJson } from "../http.mjs";
-
-export const BTC_NETWORK_MAINNET = "mainnet";
-export const BTC_ESPLORA_MAINNET = "https://mempool.space/api";
-export const BTC_ESPLORA_TESTNET = "https://mempool.space/testnet/api";
-
-function network(opts = {}) {
-  const n = String(opts.network || process.env.BTC_NETWORK || BTC_NETWORK_MAINNET).trim().toLowerCase();
-  return n === "testnet" ? "testnet" : "mainnet";
-}
-
-function baseUrl(opts = {}) {
-  if (opts.baseUrl) return String(opts.baseUrl).replace(/\/$/, "");
-  if (process.env.BTC_ESPLORA_URL) return String(process.env.BTC_ESPLORA_URL).replace(/\/$/, "");
-  return network(opts) === "testnet" ? BTC_ESPLORA_TESTNET : BTC_ESPLORA_MAINNET;
-}
-
-export function btcAddress(value, label = "address") {
-  const text = String(value || "").trim();
-  // bech32 / bech32m / legacy / p2sh — loose shape check, not full BIP validation
-  if (!/^(bc1|tb1|bcrt1)[a-z0-9]{20,90}$/i.test(text) && !/^[13mn2][a-km-zA-HJ-NP-Z1-9]{25,34}$/.test(text)) {
-    throw new Error(`bitcoin-esplora: ${label} must look like a Bitcoin address`);
-  }
-  return text;
-}
-
-export function btcTxHex(value, label = "txHex") {
-  const text = String(value || "").trim().toLowerCase().replace(/^0x/, "");
-  if (!/^[0-9a-f]+$/.test(text) || text.length < 20 || text.length % 2 !== 0) {
-    throw new Error(`bitcoin-esplora: ${label} must be even-length 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(`bitcoin-esplora GET ${path}: HTTP ${res.status} ${text.slice(0, 160)}`);
-  return text;
-}
-
-async function getJson(path, opts = {}) {
-  const text = await getText(path, opts);
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-async function postText(path, body, opts = {}) {
-  const url = `${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`;
-  const fetchImpl = opts.fetchImpl || fetch;
-  const res = await fetchImpl(url, {
-    method: "POST",
-    headers: { "content-type": "text/plain", accept: "application/json,text/plain;q=0.9,*/*;q=0.8" },
-    body: String(body || ""),
-    signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
-  });
-  const text = await res.text();
-  if (!res.ok) throw new Error(`bitcoin-esplora POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
-  return text.trim();
-}
-
-export async function btcHealth(opts = {}) {
-  try {
-    const tip = await getText("/blocks/tip/height", opts);
-    const height = Number(tip);
-    return {
-      ok: Number.isFinite(height) && height > 0,
-      provider: "bitcoin-esplora",
-      network: network(opts),
-      baseUrl: baseUrl(opts),
-      tipHeight: height,
-      exec: false,
-      signing: "user-wallet",
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "bitcoin-esplora",
-      network: network(opts),
-      baseUrl: baseUrl(opts),
-      error: String(error?.message || error),
-      exec: false,
-    };
-  }
-}
-
-export async function btcTipHeight(opts = {}) {
-  const tip = await getText("/blocks/tip/height", opts);
-  return {
-    provider: "bitcoin-esplora",
-    network: network(opts),
-    tipHeight: Number(tip),
-  };
-}
-
-export async function btcFees(opts = {}) {
-  // mempool.space recommended fees; Blockstream may 404 — fall back empty
-  try {
-    const fees = await getJson("/v1/fees/recommended", opts);
-    return {
-      provider: "bitcoin-esplora",
-      network: network(opts),
-      fastestFee: fees.fastestFee ?? null,
-      halfHourFee: fees.halfHourFee ?? null,
-      hourFee: fees.hourFee ?? null,
-      economyFee: fees.economyFee ?? null,
-      minimumFee: fees.minimumFee ?? null,
-      raw: fees,
-    };
-  } catch {
-    return {
-      provider: "bitcoin-esplora",
-      network: network(opts),
-      fastestFee: null,
-      halfHourFee: null,
-      hourFee: null,
-      note: "fee endpoint unavailable on this Esplora host",
-    };
-  }
-}
-
-export async function btcAddressInfo(args = {}, opts = {}) {
-  const address = btcAddress(args.address || args.addr, "address");
-  const info = await getJson(`/address/${address}`, opts);
-  const chain = info.chain_stats || {};
-  const mempool = info.mempool_stats || {};
-  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: "bitcoin-esplora",
-    network: network(opts),
-    address,
-    balanceSats: String(funded - spent),
-    chainStats: chain,
-    mempoolStats: mempool,
-    raw: info,
-  };
-}
-
-export async function btcUtxos(args = {}, opts = {}) {
-  const address = btcAddress(args.address || args.addr, "address");
-  const utxos = await getJson(`/address/${address}/utxo`, opts);
-  const list = Array.isArray(utxos) ? utxos : [];
-  return {
-    provider: "bitcoin-esplora",
-    network: network(opts),
-    address,
-    count: list.length,
-    totalSats: String(list.reduce((n, u) => n + Number(u.value || 0), 0)),
-    utxos: list.map((u) => ({
-      txid: u.txid,
-      vout: u.vout,
-      value: Number(u.value || 0),
-      status: u.status || null,
-    })),
-  };
-}
-
-export async function btcTx(args = {}, opts = {}) {
-  const txid = String(args.txid || args.txId || "").trim().toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(txid)) throw new Error("bitcoin-esplora: txid must be 64-char hex");
-  const tx = await getJson(`/tx/${txid}`, opts);
-  return {
-    provider: "bitcoin-esplora",
-    network: network(opts),
-    txid,
-    confirmed: Boolean(tx.status?.confirmed),
-    fee: tx.fee ?? null,
-    size: tx.size ?? null,
-    weight: tx.weight ?? null,
-    vinCount: Array.isArray(tx.vin) ? tx.vin.length : null,
-    voutCount: Array.isArray(tx.vout) ? tx.vout.length : null,
-    raw: tx,
-  };
-}
-
-export async function btcDecodeTxHex(args = {}, opts = {}) {
-  const txHex = btcTxHex(args.txHex || args.hex || args.transaction, "txHex");
-  // Esplora has no universal decode; return structural summary from hex length + optional /tx/hex reverse via broadcast dry path.
-  return {
-    provider: "bitcoin-esplora",
-    network: network(opts),
-    encoding: "hex",
-    txHex,
-    byteLength: txHex.length / 2,
-    note: "full decode is wallet/client-side or via bitcoinjs; Esplora returns broadcast acceptance only",
-  };
-}
-
-/**
- * Broadcast a fully signed raw transaction hex.
- *
- * Posture: broadcasting is ARMED whenever the caller has signed bytes to send —
- * possessing a signed transaction IS the authorization. What is still required
- * is that the SEND be asked for: `execute:true` marks a user-initiated
- * broadcast, so nothing goes out as a side effect of a read path. Oracle never
- * signs here; the caller supplies the bytes.
- */
-export async function btcBroadcast(_a = {}, _o = {}) {
-  throw new Error("bitcoin-esplora.btcBroadcast refused: @oracle-agent/oracle is prepare-only. Broadcast from the user wallet or a local operator process.");
-}
-
-// Keep httpJson import usable for Core RPC optional path later without circular deps.
-void httpJson;

package/src/data/providers/bitcoin-meta.mjs

@@ -1,378 +0,0 @@
-// Bitcoin metaprotocol reads (ordinals / runes).
-// Pluggable indexer base. No keys in repo — optional API keys via env.
-//
-// Free keyless tier: ordinals.com recursive ("/r/*") endpoints. Verified live
-// 2026-07: blockheight, blockhash, blockinfo, inscription metadata, children,
-// sat. These are the ord node's own recursive API and need no key.
-//
-// Indexer landscape as probed (do not re-litigate without re-probing):
-//   ordinals.com /r/*   200, keyless          -> wired below
-//   Hiro ordinals/brc20 410 GONE, deprecated  -> dead, do not use
-//   Ordiscan            402 payment required
-//   UniSat open-api     403 without Bearer
-//   BestInSlot          301 (moved; needs key)
-//   Magic Eden BTC      503 "no healthy upstream" -> dead
-//   Satflow             403 without x-api-key -> marketplace, separate provider
-//
-// Known gap: ordinals.com has NO address-indexed endpoint (/r/address 404).
-// Address -> inscriptions/runes REQUIRES a keyed indexer. Keyless mode can
-// answer "what is this inscription" but not "what does this wallet hold".
-
-import { btcAddress } from "./bitcoin-esplora.mjs";
-import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
-
-export const ORDINALS_RECURSIVE_BASE = "https://ordinals.com";
-
-function metaBase(opts = {}) {
-  return String(
-    opts.baseUrl ||
-      process.env.BTC_META_API_URL ||
-      process.env.UNISAT_API_URL ||
-      ""
-  )
-    .trim()
-    .replace(/\/$/, "");
-}
-
-// This provider has NO fixed default endpoint: the operator points it at their
-// own UniSat / Best-in-Slot deployment. Trust is therefore decided by an
-// explicit host allowlist rather than a built-in default.
-const BTC_META_HOSTS = [
-  "open-api.unisat.io",
-  "open-api-testnet.unisat.io",
-  "api.bestinslot.xyz",
-  "api.hiro.so",
-];
-
-function metaEndpoint(opts = {}) {
-  const url = metaBase(opts);
-  if (!url) return { baseUrl: "", trusted: false, host: null };
-  return resolveProviderEndpoint({
-    provider: "bitcoin-meta",
-    defaultUrl: url,
-    hosts: BTC_META_HOSTS,
-    url,
-  });
-}
-
-function headers(opts = {}) {
-  const key =
-    opts.apiKey ||
-    process.env.UNISAT_API_KEY ||
-    process.env.BESTINSLOT_API_KEY ||
-    process.env.BTC_META_API_KEY ||
-    "";
-  // An operator-configured base is only credentialed when its host is one of
-  // the known indexers; a redirected base gets the request without the key.
-  let trusted = false;
-  try {
-    const url = metaBase(opts);
-    if (url) {
-      const host = new URL(url).host;
-      const proto = new URL(url).protocol;
-      const loopback = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
-      trusted = BTC_META_HOSTS.includes(host) && (proto === "https:" || loopback);
-    }
-  } catch {
-    trusted = false;
-  }
-  return credentialedHeaders(
-    { accept: "application/json", "user-agent": "oracle-btc-meta/0.1" },
-    { authorization: key ? `Bearer ${key}` : "", "x-api-key": key },
-    trusted
-  );
-}
-
-async function getJson(url, opts = {}) {
-  const fetchImpl = opts.fetchImpl || fetch;
-  const res = await fetchImpl(url, {
-    method: "GET",
-    headers: headers(opts),
-    signal: AbortSignal.timeout(opts.timeoutMs ?? 12_000),
-  });
-  const text = await res.text();
-  let body;
-  try {
-    body = JSON.parse(text);
-  } catch {
-    body = text;
-  }
-  if (!res.ok) {
-    throw new Error(`bitcoin-meta GET ${url}: HTTP ${res.status} ${String(text).slice(0, 160)}`);
-  }
-  return body;
-}
-
-export async function btcMetaHealth(opts = {}) {
-  const base = metaBase(opts);
-  // Always can hit ordinals.com tip as chain liveness (not full meta)
-  let tip = null;
-  try {
-    const fetchImpl = opts.fetchImpl || fetch;
-    const r = await fetchImpl("https://ordinals.com/r/blockheight", {
-      signal: AbortSignal.timeout(8000),
-    });
-    tip = Number(await r.text());
-  } catch {
-    tip = null;
-  }
-
-  if (!base) {
-    return {
-      ok: tip != null,
-      provider: "bitcoin-meta",
-      indexerConfigured: false,
-      ordinalsComTip: tip,
-      note: "Set BTC_META_API_URL and/or UNISAT_API_KEY / BESTINSLOT_API_KEY for balances. Marketplace = Satflow (SATFLOW_API_KEY). Magic Eden BTC is dead.",
-      capabilities: {
-        tip: tip != null,
-        runeBalances: false,
-        inscriptions: false,
-        marketplace: false,
-      },
-    };
-  }
-
-  // Probe common paths; tolerate 404
-  let probe = { ok: false, path: null, status: null };
-  for (const path of ["/v1/indexer/brc20/best-height", "/v1/health", "/health", "/"]) {
-    try {
-      const fetchImpl = opts.fetchImpl || fetch;
-      const res = await fetchImpl(`${base}${path}`, {
-        headers: headers(opts),
-        signal: AbortSignal.timeout(8000),
-      });
-      probe = { ok: res.status > 0 && res.status < 500, path, status: res.status };
-      if (res.ok) break;
-    } catch {
-      /* try next */
-    }
-  }
-
-  return {
-    ok: probe.ok || tip != null,
-    provider: "bitcoin-meta",
-    indexerConfigured: true,
-    baseUrl: base,
-    probe,
-    ordinalsComTip: tip,
-    apiKeyPresent: Boolean(
-      process.env.UNISAT_API_KEY ||
-        process.env.BESTINSLOT_API_KEY ||
-        process.env.BTC_META_API_KEY
-    ),
-    capabilities: {
-      tip: tip != null,
-      runeBalances: true,
-      inscriptions: true,
-      marketplace: Boolean(process.env.SATFLOW_API_KEY),
-    },
-  };
-}
-
-/**
- * Rune balances for an address. Requires configured indexer.
- * Normalizes heterogeneous API shapes into a common list.
- */
-export async function btcRuneBalances(args = {}, opts = {}) {
-  const address = btcAddress(args.address || args.addr, "address");
-  const base = metaBase(opts);
-  if (!base) {
-    return {
-      provider: "bitcoin-meta",
-      address,
-      ok: false,
-      balances: [],
-      error: "no indexer configured (set BTC_META_API_URL or vendor API key env)",
-    };
-  }
-
-  // Try UniSat-shaped path first, then generic
-  const candidates = [
-    `${base}/v1/indexer/address/${address}/runes/balance-list?start=0&limit=100`,
-    `${base}/v1/runes/address/${address}`,
-    `${base}/runes/balance/${address}`,
-    `${base}/address/${address}/runes`,
-  ];
-
-  let lastErr = null;
-  for (const url of candidates) {
-    try {
-      const body = await getJson(url, opts);
-      const list = normalizeRuneBalances(body);
-      return {
-        provider: "bitcoin-meta",
-        address,
-        ok: true,
-        count: list.length,
-        balances: list,
-        source: url,
-      };
-    } catch (e) {
-      lastErr = e;
-    }
-  }
-  return {
-    provider: "bitcoin-meta",
-    address,
-    ok: false,
-    balances: [],
-    error: String(lastErr?.message || lastErr || "all indexer paths failed"),
-  };
-}
-
-function normalizeRuneBalances(body) {
-  const raw =
-    body?.data?.detail ||
-    body?.data?.list ||
-    body?.data ||
-    body?.balances ||
-    body?.results ||
-    body?.runes ||
-    (Array.isArray(body) ? body : []);
-  const arr = Array.isArray(raw) ? raw : [];
-  return arr.map((r) => ({
-    rune: r.rune || r.runeid || r.runeId || r.spacedRune || r.name || r.ticker || null,
-    runeId: r.runeid || r.runeId || r.id || null,
-    amount: String(r.amount ?? r.balance ?? r.total ?? r.qty ?? "0"),
-    symbol: r.symbol || null,
-    divisibility: r.divisibility ?? r.div ?? null,
-    raw: r,
-  }));
-}
-
-/**
- * Inscriptions controlled by an address.
- *
- * NOTE: requires a KEYED indexer. ordinals.com recursive has no address index
- * (verified: /r/address -> 404), so the free tier cannot answer this. We say so
- * explicitly rather than returning an empty list that reads like "you own
- * nothing" — a false negative here can get an inscription spent as fee change.
- */
-export async function btcInscriptions(args = {}, opts = {}) {
-  const address = btcAddress(args.address || args.addr, "address");
-  const base = metaBase(opts);
-  if (!base) {
-    return {
-      provider: "bitcoin-meta",
-      address,
-      ok: false,
-      inscriptions: [],
-      error:
-        "no indexer configured — address-indexed lookups need a keyed indexer " +
-        "(BTC_META_API_URL + UNISAT_API_KEY / BESTINSLOT_API_KEY). " +
-        "ordinals.com recursive is keyless but has no address index.",
-      unknownNotEmpty: true,
-      keylessAlternatives: ["btc_inscription_info (by inscription id)", "btc_meta_health"],
-    };
-  }
-  const limit = Math.min(Number(args.limit || 50), 200);
-  const candidates = [
-    `${base}/v1/indexer/address/${address}/inscription-data?cursor=0&size=${limit}`,
-    `${base}/v1/inscriptions/address/${address}?limit=${limit}`,
-    `${base}/address/${address}/inscriptions?limit=${limit}`,
-  ];
-  let lastErr = null;
-  for (const url of candidates) {
-    try {
-      const body = await getJson(url, opts);
-      const list = normalizeInscriptions(body);
-      return {
-        provider: "bitcoin-meta",
-        address,
-        ok: true,
-        count: list.length,
-        inscriptions: list,
-        source: url,
-      };
-    } catch (e) {
-      lastErr = e;
-    }
-  }
-  return {
-    provider: "bitcoin-meta",
-    address,
-    ok: false,
-    inscriptions: [],
-    error: String(lastErr?.message || lastErr || "all indexer paths failed"),
-  };
-}
-
-/**
- * Inscription metadata by inscription id — KEYLESS via ordinals.com recursive.
- * Verified live: returns content_type, content_length, height, sat, fee, etc.
- */
-export async function btcInscriptionInfo(args = {}, opts = {}) {
-  const id = String(args.inscriptionId || args.id || "").trim();
-  if (!/^[0-9a-f]{64}i\d+$/i.test(id)) {
-    throw new Error("bitcoin-meta: inscriptionId must look like <64-hex-txid>i<index>");
-  }
-  const base = opts.ordinalsBase || ORDINALS_RECURSIVE_BASE;
-  const info = await getJson(`${base}/r/inscription/${id}`, opts);
-  return {
-    provider: "bitcoin-meta",
-    source: "ordinals.com/r",
-    keyless: true,
-    inscriptionId: id,
-    info,
-  };
-}
-
-/**
- * Child inscriptions (collection/parent-child) — KEYLESS via ordinals.com.
- */
-export async function btcInscriptionChildren(args = {}, opts = {}) {
-  const id = String(args.inscriptionId || args.id || "").trim();
-  if (!/^[0-9a-f]{64}i\d+$/i.test(id)) {
-    throw new Error("bitcoin-meta: inscriptionId must look like <64-hex-txid>i<index>");
-  }
-  const base = opts.ordinalsBase || ORDINALS_RECURSIVE_BASE;
-  const page = Number(args.page || 0);
-  const body = await getJson(`${base}/r/children/${id}${page ? `/${page}` : ""}`, opts);
-  return {
-    provider: "bitcoin-meta",
-    source: "ordinals.com/r",
-    keyless: true,
-    inscriptionId: id,
-    page,
-    children: Array.isArray(body?.ids) ? body.ids : [],
-    more: Boolean(body?.more),
-  };
-}
-
-/**
- * Block info from the ord node itself — KEYLESS. Useful to confirm the ord
- * indexer is at the same tip as Esplora before trusting any metaprotocol read.
- */
-export async function btcOrdBlockInfo(args = {}, opts = {}) {
-  const base = opts.ordinalsBase || ORDINALS_RECURSIVE_BASE;
-  const height = args.height ?? (await getJson(`${base}/r/blockheight`, opts));
-  const info = await getJson(`${base}/r/blockinfo/${Number(height)}`, opts);
-  return {
-    provider: "bitcoin-meta",
-    source: "ordinals.com/r",
-    keyless: true,
-    height: Number(height),
-    info,
-  };
-}
-
-function normalizeInscriptions(body) {
-  const raw =
-    body?.data?.inscription ||
-    body?.data?.detail ||
-    body?.data?.list ||
-    body?.data ||
-    body?.inscriptions ||
-    body?.results ||
-    (Array.isArray(body) ? body : []);
-  const arr = Array.isArray(raw) ? raw : [];
-  return arr.map((i) => ({
-    id: i.inscriptionId || i.id || i.inscription_id || null,
-    number: i.inscriptionNumber ?? i.number ?? null,
-    sat: i.sat || i.satoshi || null,
-    contentType: i.contentType || i.content_type || null,
-    utxo: i.utxo || i.output || (i.txid != null ? `${i.txid}:${i.vout ?? i.n}` : null),
-    raw: i,
-  }));
-}

package/src/data/providers/blockscout.mjs

@@ -1,14 +0,0 @@
-// Blockscout REST API v2 — verified public explorer instances, no key.
-import { httpJson } from "../http.mjs";
-export const BLOCKSCOUT_CHAINS=Object.freeze({
-  1:"https://eth.blockscout.com",
-  10:"https://optimism.blockscout.com",
-  137:"https://polygon.blockscout.com",
-  42161:"https://arbitrum.blockscout.com",
-  8453:"https://base.blockscout.com",
-});
-function base(chainId,o={}) { const id=Number(chainId); const u=o.baseUrl || BLOCKSCOUT_CHAINS[id]; if(!u) throw new Error(`Blockscout not configured for chainId ${id}`); return u.replace(/\/$/,""); }
-export async function blockscoutStats(args={},opts={}) { return httpJson(`${base(args.chainId||1,opts)}/api/v2/stats`,{fetchImpl:opts.fetchImpl,timeoutMs:opts.timeoutMs}); }
-export async function blockscoutAddress(args={},opts={}) { if(!args.address)throw new Error("address required"); return httpJson(`${base(args.chainId||1,opts)}/api/v2/addresses/${encodeURIComponent(args.address)}`,{fetchImpl:opts.fetchImpl,timeoutMs:opts.timeoutMs}); }
-export async function blockscoutToken(args={},opts={}) { if(!args.address && !args.tokenAddress)throw new Error("token address required"); return httpJson(`${base(args.chainId||1,opts)}/api/v2/tokens/${encodeURIComponent(args.address||args.tokenAddress)}`,{fetchImpl:opts.fetchImpl,timeoutMs:opts.timeoutMs}); }
-export async function blockscoutHealth(opts={}) { const data=await blockscoutStats({chainId:8453},opts); return {ok:data?.total_blocks!=null || data?.total_transactions!=null,chainId:8453}; }