@oracle-agent/oracle 0.13.0 → 0.14.0

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

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

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

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