@oracle-agent/oracle 0.11.0 → 0.12.0

package/src/data/providers/satflow.mjs

@@ -1,341 +0,0 @@
-// Satflow Marketplace API — Bitcoin ordinals + runes market plane.
-// Docs: https://docs.satflow.com  Base: https://api.satflow.com/v1
-// Auth: x-api-key header (SATFLOW_API_KEY).
-//
-// Magic Eden BTC marketplace is DEAD (sunset 2026). Satflow docs mark
-// magiceden external intents deprecated/blocked. Do not use ME for ordinals.
-
-import { btcAddress } from "./bitcoin-esplora.mjs";
-import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
-import { assertNoSignedMaterial } from "./signed-material-guard.mjs";
-
-export const SATFLOW_BASE = "https://api.satflow.com/v1";
-
-function endpoint(opts = {}) {
-  return resolveProviderEndpoint({
-    provider: "satflow",
-    defaultUrl: SATFLOW_BASE,
-    hosts: ["api.satflow.com"],
-    url: opts.baseUrl || process.env.SATFLOW_API_URL,
-  });
-}
-
-function baseUrl(opts = {}) {
-  return endpoint(opts).baseUrl;
-}
-
-function apiKey(opts = {}) {
-  return String(opts.apiKey || process.env.SATFLOW_API_KEY || process.env.BTC_SATFLOW_API_KEY || "").trim();
-}
-
-function headers(opts = {}) {
-  // The API key travels ONLY to a pinned Satflow host. Redirecting baseUrl
-  // elsewhere drops the credential instead of forwarding it.
-  return credentialedHeaders(
-    {
-      accept: "application/json",
-      "content-type": "application/json",
-      "user-agent": "oracle-btc-satflow/0.1",
-    },
-    { "x-api-key": apiKey(opts) },
-    endpoint(opts).trusted
-  );
-}
-
-async function sfFetch(path, { method = "GET", body, opts = {} } = {}) {
-  const key = apiKey(opts);
-  if (!key) {
-    throw new Error("satflow: SATFLOW_API_KEY not set (request key via Satflow docs form)");
-  }
-  const url = `${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`;
-  const fetchImpl = opts.fetchImpl || fetch;
-  const res = await fetchImpl(url, {
-    method,
-    headers: headers(opts),
-    body: body != null ? JSON.stringify(body) : undefined,
-    signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
-  });
-  const text = await res.text();
-  let data;
-  try {
-    data = JSON.parse(text);
-  } catch {
-    data = text;
-  }
-  if (!res.ok) {
-    throw new Error(`satflow ${method} ${path}: HTTP ${res.status} ${String(text).slice(0, 200)}`);
-  }
-  return data;
-}
-
-export async function satflowHealth(opts = {}) {
-  const keyPresent = Boolean(apiKey(opts));
-  if (!keyPresent) {
-    return {
-      ok: false,
-      provider: "satflow",
-      baseUrl: baseUrl(opts),
-      apiKeyPresent: false,
-      marketplace: "satflow",
-      magicEdenOrdinals: "deprecated-dead",
-      note: "Set SATFLOW_API_KEY. Magic Eden BTC ordinals marketplace is shut down — do not use ME.",
-    };
-  }
-  try {
-    // lightweight authenticated probe
-    await sfFetch("/collection/stats/floors?type=ordinals", { opts });
-    return {
-      ok: true,
-      provider: "satflow",
-      baseUrl: baseUrl(opts),
-      apiKeyPresent: true,
-      marketplace: "satflow",
-      magicEdenOrdinals: "deprecated-dead",
-      capabilities: {
-        floors: true,
-        walletContents: true,
-        purchaseIntent: true,
-        listIntent: true,
-        bidIntent: true,
-      },
-    };
-  } catch (e) {
-    return {
-      ok: false,
-      provider: "satflow",
-      baseUrl: baseUrl(opts),
-      apiKeyPresent: true,
-      error: String(e?.message || e).slice(0, 200),
-      magicEdenOrdinals: "deprecated-dead",
-    };
-  }
-}
-
-/** Collection floor stats. type: ordinals | runes */
-export async function satflowCollectionFloors(args = {}, opts = {}) {
-  const type = String(args.type || "ordinals").toLowerCase();
-  if (!["ordinals", "runes"].includes(type)) throw new Error("satflow: type must be ordinals|runes");
-  const q = new URLSearchParams({ type });
-  if (args.ids) q.set("ids", Array.isArray(args.ids) ? args.ids.join(",") : String(args.ids));
-  const data = await sfFetch(`/collection/stats/floors?${q}`, { opts });
-  return { provider: "satflow", type, floors: data, magicEdenOrdinals: "deprecated-dead" };
-}
-
-export async function satflowCollectionStats(args = {}, opts = {}) {
-  const id = String(args.collectionId || args.id || args.slug || "").trim();
-  if (!id) throw new Error("satflow: collectionId required");
-  const q = new URLSearchParams({ id });
-  if (args.type) q.set("type", args.type);
-  const data = await sfFetch(`/collection/stats?${q}`, { opts });
-  return { provider: "satflow", collectionId: id, stats: data };
-}
-
-export async function satflowItem(args = {}, opts = {}) {
-  const id = String(args.inscriptionId || args.id || "").trim();
-  if (!id) throw new Error("satflow: inscriptionId required");
-  const q = new URLSearchParams({ id });
-  const data = await sfFetch(`/item?${q}`, { opts });
-  return { provider: "satflow", item: data };
-}
-
-export async function satflowWalletContents(args = {}, opts = {}) {
-  const address = btcAddress(args.address || args.addr, "address");
-  const q = new URLSearchParams({ address });
-  if (args.type) q.set("type", args.type);
-  if (args.limit != null) q.set("limit", String(args.limit));
-  if (args.offset != null) q.set("offset", String(args.offset));
-  const data = await sfFetch(`/address/wallet-contents?${q}`, { opts });
-  return { provider: "satflow", address, contents: data };
-}
-
-export async function satflowFloorListings(args = {}, opts = {}) {
-  const ids = args.collectionIds || args.ids || args.collectionId;
-  if (!ids) throw new Error("satflow: collectionIds required");
-  const q = new URLSearchParams({
-    ids: Array.isArray(ids) ? ids.join(",") : String(ids),
-  });
-  if (args.limit != null) q.set("limit", String(args.limit));
-  const data = await sfFetch(`/orders/floor?${q}`, { opts });
-  return { provider: "satflow", listings: data };
-}
-
-// Oracle-internal keys that must never be forwarded to the marketplace.
-const SATFLOW_INTERNAL_KEYS = new Set([
-  "body",
-  "execute",
-  "fetchImpl",
-  "opts",
-  "apiKey",
-  "baseUrl",
-  "timeoutMs",
-  "maxSats",
-  "operator",
-]);
-
-/**
- * Build an outbound Satflow body from caller args.
- *
- * Spreading `...args` straight into a third-party request is how Oracle-internal
- * control fields (and anything a prompt-injected model appends) leak to an
- * external venue. Only explicitly-named fields cross the boundary.
- */
-function satflowBody(args = {}, allowed = null) {
-  // The `body` branch used to return the caller's object wholesale after
-  // stripping internal names, which meant the field allowlist below was never
-  // consulted for it. A prompt-injected model could then put an arbitrary
-  // payload — including a swapped buyer/receive address — into a marketplace
-  // intent the user is asked to sign. Both branches now go through the SAME
-  // allowlist.
-  const source = args.body && typeof args.body === "object" ? args.body : args;
-  const out = {};
-  for (const [k, v] of Object.entries(source)) {
-    if (SATFLOW_INTERNAL_KEYS.has(k)) continue;
-    if (allowed && !allowed.has(k)) continue;
-    if (v === undefined) continue;
-    out[k] = v;
-  }
-  return out;
-}
-
-const SATFLOW_PURCHASE_FIELDS = new Set([
-  "listing_id",
-  "listingId",
-  "inscription_id",
-  "inscriptionId",
-  "runes_output",
-  "runesOutput",
-  "buyer_address",
-  "buyerAddress",
-  "ord_address",
-  "receive_address",
-  "payment_address",
-  "pay_address",
-  "tap_key",
-  "public_key",
-  "publicKey",
-  "fee_rate",
-  "feeRate",
-  "price",
-  "quantity",
-  "slug",
-  "collection_slug",
-]);
-
-const SATFLOW_LIST_FIELDS = new Set([
-  "inscription_id",
-  "inscriptionId",
-  "runes_output",
-  "runesOutput",
-  "ord_address",
-  "receive_address",
-  "price",
-  "tap_key",
-  "collection_slug",
-  "expires_at",
-]);
-
-/**
- * Create unsigned PSBT for buying on Satflow.
- * Returns PSBT for wallet/local sign — does not broadcast.
- */
-/**
- * Pull an authoritative sat price out of a Satflow body or intent response.
- * Returns null when no price can be determined, so callers fail closed.
- */
-function purchasePriceSats(obj) {
-  if (!obj || typeof obj !== "object") return null;
-  const candidates = [
-    obj.price,
-    obj.priceSats,
-    obj.price_sats,
-    obj.totalSats,
-    obj.total_sats,
-    obj.amount,
-    obj.satoshis,
-  ];
-  for (const c of candidates) {
-    if (c == null) continue;
-    const text = String(c).trim();
-    if (!/^\d+$/.test(text)) continue;
-    return BigInt(text);
-  }
-  return null;
-}
-
-export async function satflowPreparePurchase(args = {}, opts = {}) {
-  const body = satflowBody(args, SATFLOW_PURCHASE_FIELDS);
-  if (!body || Object.keys(body).length === 0) {
-    throw new Error("satflow: purchase body required (see docs.satflow.com intent/satflow-purchase)");
-  }
-
-  // maxSats is a SPEND CEILING, and it was previously stripped as an internal
-  // field and then never compared to anything — the caller believed a cap was
-  // in force while the returned PSBT could pay any price. Require it, and
-  // enforce it against the authoritative price on the intent Satflow returns,
-  // not just the price the caller asked for.
-  const rawMax = args.maxSats ?? args.body?.maxSats;
-  if (rawMax == null) {
-    throw new Error("satflow: maxSats is required to prepare a purchase — an uncapped buy has no spend ceiling");
-  }
-  const maxSats = BigInt(String(rawMax).trim());
-  if (maxSats <= 0n) throw new Error("satflow: maxSats must be a positive integer sat amount");
-
-  const requested = purchasePriceSats(body);
-  if (requested != null && requested > maxSats) {
-    throw new Error(`satflow: requested price ${requested} sats exceeds maxSats cap ${maxSats}`);
-  }
-
-  const data = await sfFetch("/intent/satflow-purchase", { method: "POST", body, opts });
-
-  const settled = purchasePriceSats(data) ?? purchasePriceSats(data?.intent);
-  if (settled == null) {
-    throw new Error("satflow: purchase intent did not report a price — refusing to return an unverifiable PSBT");
-  }
-  if (settled > maxSats) {
-    throw new Error(`satflow: purchase price ${settled} sats exceeds maxSats cap ${maxSats} — PSBT withheld`);
-  }
-
-  assertNoSignedMaterial("satflow", data);
-
-  return stampPrepared({
-    provider: "satflow",
-    kind: "purchase-intent",
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    marketplace: "satflow",
-    magicEdenOrdinals: "deprecated-dead",
-    priceSats: settled.toString(),
-    maxSats: maxSats.toString(),
-    intent: data,
-    // common field names across versions
-    unsignedPsbt:
-      data?.unsignedPSBTBase64 ||
-      data?.unsignedPsbtBase64 ||
-      data?.unsigned_psbt ||
-      null,
-    note: "Sign PSBT in a Bitcoin wallet. Broadcast only through the user's wallet or an explicitly armed Bitcoin execution plane.",
-  });
-}
-
-/** List intent — unsigned listing PSBTs */
-export async function satflowPrepareList(args = {}, opts = {}) {
-  const body = satflowBody(args, SATFLOW_LIST_FIELDS);
-  if (!body.inscription_id && !body.runes_output && !body.inscriptionId && !body.runesOutput) {
-    throw new Error("satflow: list requires inscription_id or runes_output");
-  }
-  const data = await sfFetch("/intent/sell", { method: "POST", body, opts });
-  assertNoSignedMaterial("satflow", data);
-  return stampPrepared({
-    provider: "satflow",
-    kind: "list-intent",
-    requiresUserSignature: true,
-    marketplace: "satflow",
-    listingRequest: body,
-    intent: data,
-    unsignedPsbt: data?.unsignedListingPSBTBase64 || data?.unsigned_psbt || null,
-    note: "Sign listing PSBTs in a Bitcoin wallet; listing broadcast is outside the data plane.",
-  });
-}

package/src/data/providers/signed-material-guard.mjs

@@ -1,108 +0,0 @@
-// Shared refusal for pre-signed material returned by an upstream marketplace or
-// aggregator API. Every prepare path calls this before selecting unsigned bytes
-// or binding the upstream response into a stamped envelope.
-
-const MAX_DEPTH = 16;
-const MAX_NODES = 2048;
-
-const UNSIGNED_PREFIXES = ["unsigned", "notsigned", "tosign", "signable"];
-
-const STATUS_KEYS = new Set([
-  "requiresusersignature",
-  "requiressignature",
-  "needssignature",
-  "signaturerequired",
-  "signaturesrequired",
-  "signingready",
-  "signaturecount",
-  "signaturethreshold",
-  "requiredsignatures",
-  "signatureneeded",
-  "hassignature",
-  "allowsignatures",
-  "requestsignature",
-  "multisig",
-  "cosig",
-  "msig",
-]);
-
-const MATERIAL_KEYS = new Set([
-  "sig",
-  "sigs",
-  "scriptsig",
-  "witness",
-  "psbt",
-  "finalizedpsbt",
-  "completepsbt",
-  "finalpsbt",
-  "psbtfinalized",
-  "serializedtransaction",
-]);
-
-function normalizeKey(key) {
-  return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
-}
-
-function isUnsignedField(norm) {
-  return UNSIGNED_PREFIXES.some((prefix) => norm.startsWith(prefix)) || STATUS_KEYS.has(norm);
-}
-
-function isSignedMaterialKey(key) {
-  const raw = String(key);
-  if (!/^[\x20-\x7e]+$/.test(raw)) return true;
-  const norm = normalizeKey(raw);
-  if (isUnsignedField(norm)) return false;
-  if (MATERIAL_KEYS.has(norm)) return true;
-  return norm.includes("signed") || norm.includes("signature") || norm.endsWith("sig") || norm.endsWith("sigs");
-}
-
-function isSignatureTuple(value) {
-  const v = Number(value?.v);
-  const r = String(value?.r || "");
-  const s = String(value?.s || "");
-  return [0, 1, 27, 28].includes(v) && /^0x[0-9a-f]{2,64}$/i.test(r) && /^0x[0-9a-f]{2,64}$/i.test(s);
-}
-
-/** Find signed-material field names anywhere in an upstream response. */
-export function findSignedFields(value, depth = 0, seen = new Set(), state = { nodes: 0 }) {
-  if (value == null || typeof value !== "object") return [];
-  if (depth > MAX_DEPTH) return ["<max-depth>"];
-  if (seen.has(value)) return [];
-  state.nodes += 1;
-  if (state.nodes > MAX_NODES) return ["<max-nodes>"];
-  seen.add(value);
-
-  if (Array.isArray(value)) {
-    return value.flatMap((item) => findSignedFields(item, depth + 1, seen, state));
-  }
-
-  const hits = [];
-  for (const [key, child] of Object.entries(value)) {
-    if (isSignedMaterialKey(key)) {
-      hits.push(key);
-      continue;
-    }
-    hits.push(...findSignedFields(child, depth + 1, seen, state));
-  }
-
-  const keys = Object.keys(value).map(normalizeKey);
-  const hasPsbt = keys.some((key) => key.endsWith("psbt") || key.endsWith("psbtbase64"));
-  const claimsComplete = Object.entries(value).some(
-    ([key, child]) => /complete|finalized|isfinal/.test(normalizeKey(key)) && child === true,
-  );
-  if (hasPsbt && claimsComplete) hits.push("psbt(complete)");
-  if (isSignatureTuple(value)) hits.push("v/r/s");
-
-  return hits;
-}
-
-/** Refuse an upstream response that carries pre-signed material. */
-export function assertNoSignedMaterial(provider, raw) {
-  const hits = findSignedFields(raw);
-  if (hits.length) {
-    throw new Error(
-      `${provider}: refused a pre-signed transaction payload from the API (fields: ${[...new Set(hits)].join(", ")}) — ` +
-        `@oracle-agent/oracle is prepare-only and will not bind signed material into a prepared envelope`,
-    );
-  }
-}

package/src/data/providers/solana-rpc.mjs

@@ -1,197 +0,0 @@
-// Solana JSON-RPC read/prepare support. No keys, no signing, no broadcast.
-
-import { httpJson } from "../http.mjs";
-import { createHash } from "node:crypto";
-
-export const SOLANA_CLUSTER = "mainnet-beta";
-export const SOLANA_MAINNET_RPC = "https://api.mainnet-beta.solana.com";
-export const SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-
-function rpcUrl(opts = {}) {
-  return String(opts.rpcUrl || process.env.SOLANA_RPC_URL || SOLANA_MAINNET_RPC).trim();
-}
-
-export function solanaPubkey(value, label = "address") {
-  const text = String(value || "").trim();
-  if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(text)) throw new Error(`solana-rpc: ${label} must be a base58 public key`);
-  return text;
-}
-
-function paramsWithCommitment(params, commitment) {
-  if (!commitment) return params;
-  return [...params, { commitment }];
-}
-
-export async function solanaRpc(method, params = [], opts = {}) {
-  const methodName = String(method || "");
-  if (
-    methodName === "sendTransaction" ||
-    methodName === "sendRawTransaction" ||
-    methodName === "requestAirdrop" ||
-    methodName === "requestAirDrop" ||
-    /airdrop/i.test(methodName) ||
-    /^send/i.test(methodName)
-  ) {
-    throw new Error(`solana-rpc: ${methodName} refused — @oracle-agent/oracle is prepare-only (no broadcast/airdrop)`);
-  }
-  const result = await httpJson(rpcUrl(opts), {
-    method: "POST",
-    body: {
-      jsonrpc: "2.0",
-      id: opts.id || 1,
-      method,
-      params,
-    },
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-  if (result?.error) throw new Error(`solana-rpc ${method}: ${result.error.message || JSON.stringify(result.error)}`);
-  return result?.result;
-}
-
-export async function solanaLatestBlockhash(args = {}, opts = {}) {
-  const params = args.commitment ? [{ commitment: args.commitment }] : [];
-  const result = await solanaRpc("getLatestBlockhash", params, opts);
-  return {
-    provider: "solana-rpc",
-    cluster: SOLANA_CLUSTER,
-    blockhash: result?.value?.blockhash || null,
-    lastValidBlockHeight: result?.value?.lastValidBlockHeight ?? null,
-    slot: result?.context?.slot ?? null,
-    raw: result,
-  };
-}
-
-export async function solanaHealth(opts = {}) {
-  try {
-    const [health, latestBlockhash] = await Promise.all([
-      solanaRpc("getHealth", [], opts),
-      solanaLatestBlockhash({}, opts),
-    ]);
-    return {
-      ok: health === "ok",
-      provider: "solana-rpc",
-      cluster: SOLANA_CLUSTER,
-      health,
-      latestBlockhash,
-      exec: false,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "solana-rpc",
-      cluster: SOLANA_CLUSTER,
-      error: String(error?.message || error),
-      exec: false,
-    };
-  }
-}
-
-export async function solanaGetBalance(args = {}, opts = {}) {
-  const address = solanaPubkey(args.address || args.owner, "address");
-  const result = await solanaRpc("getBalance", paramsWithCommitment([address], args.commitment), opts);
-  return {
-    provider: "solana-rpc",
-    cluster: SOLANA_CLUSTER,
-    address,
-    lamports: String(result?.value ?? 0),
-    slot: result?.context?.slot ?? null,
-    raw: result,
-  };
-}
-
-function normalizeTokenAccount(item = {}) {
-  const info = item.account?.data?.parsed?.info || {};
-  const amount = info.tokenAmount || {};
-  return {
-    pubkey: item.pubkey,
-    mint: info.mint || null,
-    owner: info.owner || null,
-    amount: String(amount.amount ?? "0"),
-    decimals: amount.decimals ?? null,
-    uiAmount: amount.uiAmount ?? null,
-    uiAmountString: amount.uiAmountString ?? null,
-    raw: item,
-  };
-}
-
-export async function solanaTokenAccounts(args = {}, opts = {}) {
-  const owner = solanaPubkey(args.owner || args.address, "owner");
-  const filter = args.mint
-    ? { mint: solanaPubkey(args.mint, "mint") }
-    : { programId: solanaPubkey(args.programId || SPL_TOKEN_PROGRAM_ID, "token program") };
-  const config = { encoding: "jsonParsed" };
-  if (args.commitment) config.commitment = args.commitment;
-  const result = await solanaRpc("getTokenAccountsByOwner", [owner, filter, config], opts);
-  const accounts = Array.isArray(result?.value) ? result.value.map(normalizeTokenAccount) : [];
-  return {
-    provider: "solana-rpc",
-    cluster: SOLANA_CLUSTER,
-    owner,
-    filter,
-    slot: result?.context?.slot ?? null,
-    accounts,
-    raw: result,
-  };
-}
-
-function base64Tx(value) {
-  const text = String(value || "").trim();
-  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(text) || text.length % 4 !== 0) {
-    throw new Error("solana-rpc: transaction must be base64");
-  }
-  return text;
-}
-
-function readShortvec(buffer, offset) {
-  let value = 0;
-  let shift = 0;
-  let cursor = offset;
-  for (let i = 0; i < 3; i++) {
-    if (cursor >= buffer.length) throw new Error("solana-rpc: transaction shortvec truncated");
-    const byte = buffer[cursor++];
-    value |= (byte & 0x7f) << shift;
-    if ((byte & 0x80) === 0) return { value, offset: cursor };
-    shift += 7;
-  }
-  throw new Error("solana-rpc: transaction shortvec too long");
-}
-
-function transactionMessageHash(transaction) {
-  const raw = Buffer.from(transaction, "base64");
-  try {
-    const sigCount = readShortvec(raw, 0);
-    const messageOffset = sigCount.offset + sigCount.value * 64;
-    if (messageOffset >= raw.length) throw new Error("missing message");
-    return createHash("sha256").update(raw.subarray(messageOffset)).digest("hex");
-  } catch {
-    // Unit tests may pass dummy base64 to a mocked RPC. Real Solana RPC rejects
-    // invalid transactions before this becomes signable; the signer separately
-    // decodes and binds the message hash before producing an executable artifact.
-    return createHash("sha256").update(raw).digest("hex");
-  }
-}
-
-export async function solanaSimulateTransaction(args = {}, opts = {}) {
-  const transaction = base64Tx(args.transaction || args.swapTransaction);
-  const config = {
-    encoding: "base64",
-    sigVerify: Boolean(args.sigVerify),
-    replaceRecentBlockhash: args.replaceRecentBlockhash !== false,
-  };
-  if (args.commitment) config.commitment = args.commitment;
-  const result = await solanaRpc("simulateTransaction", [transaction, config], opts);
-  const value = result?.value || {};
-  return {
-    provider: "solana-rpc",
-    cluster: SOLANA_CLUSTER,
-    ok: value.err == null,
-    transactionHash: transactionMessageHash(transaction),
-    err: value.err ?? null,
-    logs: value.logs || [],
-    unitsConsumed: value.unitsConsumed ?? null,
-    replacementBlockhash: value.replacementBlockhash || null,
-    slot: result?.context?.slot ?? null,
-    raw: result,
-  };
-}