@oracle-agent/oracle 0.14.1 → 0.16.0

package/src/data/providers/magiceden-sol.mjs

@@ -1,406 +0,0 @@
-// Magic Eden Solana NFT lane. Read + prepare only.
-//
-// Reads (collection stats, listings, activities) are keyless on the public
-// mainnet API. The instruction builders (buy_now, list, mint) require a Magic
-// Eden API key and return an UNSIGNED transaction the user's wallet signs.
-// Nothing here signs or broadcasts.
-
-import { httpJson } from "../http.mjs";
-import { solanaPubkey } from "./solana-rpc.mjs";
-import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
-import { assertNoSignedMaterial } from "./signed-material-guard.mjs";
-
-export const MAGICEDEN_SOL_API = "https://api-mainnet.magiceden.dev/v2";
-export const LAMPORTS_PER_SOL = 1_000_000_000;
-
-function endpoint(opts = {}) {
-  return resolveProviderEndpoint({
-    provider: "magiceden",
-    defaultUrl: MAGICEDEN_SOL_API,
-    hosts: ["api-mainnet.magiceden.dev", "api-devnet.magiceden.dev"],
-    url: opts.baseUrl || process.env.MAGICEDEN_API_URL,
-  });
-}
-
-function base(opts = {}) {
-  return endpoint(opts).baseUrl;
-}
-
-function apiKey(opts = {}) {
-  return opts.apiKey || process.env.MAGICEDEN_API_KEY || "";
-}
-
-function headers(opts = {}) {
-  // Bearer token goes only to a pinned Magic Eden host.
-  const key = apiKey(opts);
-  return credentialedHeaders(
-    { accept: "application/json" },
-    { Authorization: key ? `Bearer ${key}` : "" },
-    endpoint(opts).trusted
-  );
-}
-
-function symbolArg(value) {
-  const symbol = String(value || "").trim();
-  if (!/^[a-z0-9_]{1,64}$/i.test(symbol)) throw new Error("magiceden: symbol must be a collection slug");
-  return symbol;
-}
-
-/**
- * Number() accepts "1e2", "0x10", " 12 " and Infinity. A price that parses
- * differently from how it reads is a spend-control bug: the UI shows one value
- * and the wallet is asked for another. Require a plain decimal.
- */
-function positiveNumber(value, label) {
-  if (typeof value === "number") {
-    if (!Number.isFinite(value) || value <= 0) throw new Error(`magiceden: ${label} must be a positive number`);
-    return value;
-  }
-  const text = String(value ?? "").trim();
-  if (!/^\d+(\.\d+)?$/.test(text)) {
-    throw new Error(`magiceden: ${label} must be a plain decimal number (no hex, exponent, or sign)`);
-  }
-  const n = Number(text);
-  if (!Number.isFinite(n) || n <= 0) throw new Error(`magiceden: ${label} must be a positive number`);
-  return n;
-}
-
-/** Pull the launchpad's quoted mint price (SOL) out of an API response. */
-function mintPriceSol(raw) {
-  const candidates = [
-    raw?.price,
-    raw?.mintPrice,
-    raw?.priceSol,
-    raw?.v0?.price,
-    raw?.launchStageInfo?.price,
-    raw?.stage?.price,
-  ];
-  for (const c of candidates) {
-    if (c == null) continue;
-    const n = Number(c);
-    if (Number.isFinite(n) && n >= 0) return n;
-  }
-  // A free mint legitimately quotes zero.
-  if (raw?.isFree === true) return 0;
-  return null;
-}
-
-function lamports(sol) {
-  return Math.round(positiveNumber(sol, "priceSol") * LAMPORTS_PER_SOL);
-}
-
-function listingExpiry(value) {
-  if (value == null || value === "") throw new Error("magiceden: listing expiry is required and must be in the future");
-  const expiry = Number(value);
-  if (!Number.isSafeInteger(expiry) || expiry <= 0) {
-    throw new Error("magiceden: expiry must be a future Unix timestamp in seconds");
-  }
-  if (expiry <= Math.floor(Date.now() / 1000)) {
-    throw new Error("magiceden: expiry must be in the future");
-  }
-  return expiry;
-}
-
-function listConfirmation({ tokenMint, priceSol, expiry }) {
-  return `list ${tokenMint} on magiceden-sol for ${priceSol} SOL until ${expiry}`;
-}
-
-function requireListingConfirmation(args, fields) {
-  if (args.userConfirmed !== true) {
-    throw new Error("magiceden: listing requires userConfirmed=true after reviewing tokenMint, priceSol, and expiry");
-  }
-  const expected = listConfirmation(fields);
-  const actual = String(args.confirmation || args.confirmationPhrase || "").trim();
-  if (actual !== expected) {
-    throw new Error(`magiceden: confirmation must equal ${JSON.stringify(expected)}`);
-  }
-  return expected;
-}
-
-export async function magicEdenSolHealth(opts = {}) {
-  try {
-    const stats = await magicEdenSolStats({ symbol: "mad_lads" }, opts);
-    return {
-      ok: true,
-      provider: "magiceden-sol",
-      keyed: Boolean(apiKey(opts)),
-      readTier: "keyless",
-      prepareTier: apiKey(opts) ? "keyed" : "requires MAGICEDEN_API_KEY",
-      floorPriceSol: stats.floorPriceSol,
-      exec: false,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "magiceden-sol",
-      keyed: Boolean(apiKey(opts)),
-      error: String(error?.message || error).slice(0, 160),
-      exec: false,
-    };
-  }
-}
-
-export async function magicEdenSolStats(args = {}, opts = {}) {
-  const symbol = symbolArg(args.symbol || args.collection);
-  const raw = await httpJson(`${base(opts)}/collections/${encodeURIComponent(symbol)}/stats`, {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-  const floorLamports = Number(raw?.floorPrice ?? 0);
-  return {
-    provider: "magiceden-sol",
-    chain: "solana-mainnet-beta",
-    symbol,
-    floorPriceLamports: floorLamports || null,
-    floorPriceSol: floorLamports ? floorLamports / LAMPORTS_PER_SOL : null,
-    listedCount: raw?.listedCount ?? null,
-    volume24hrSol: raw?.volume24hr != null ? Number(raw.volume24hr) / LAMPORTS_PER_SOL : null,
-    avgPrice24hrSol: raw?.avgPrice24hr != null ? Number(raw.avgPrice24hr) / LAMPORTS_PER_SOL : null,
-    exec: false,
-    raw,
-  };
-}
-
-function normalizeListing(item = {}) {
-  const priceSol = Number(item.price ?? 0);
-  return {
-    tokenMint: item.tokenMint ?? null,
-    tokenATA: item.tokenAddress ?? null,
-    seller: item.seller ?? null,
-    sellerReferral: item.sellerReferral ?? null,
-    auctionHouse: item.auctionHouse ?? null,
-    pdaAddress: item.pdaAddress ?? null,
-    priceSol: priceSol || null,
-    priceLamports: priceSol ? Math.round(priceSol * LAMPORTS_PER_SOL) : null,
-    tokenSize: item.tokenSize ?? 1,
-  };
-}
-
-export async function magicEdenSolListings(args = {}, opts = {}) {
-  const symbol = symbolArg(args.symbol || args.collection);
-  const limit = Math.min(Math.max(Number(args.limit ?? 20) || 20, 1), 100);
-  const offset = Math.max(Number(args.offset ?? 0) || 0, 0);
-  const url = new URL(`${base(opts)}/collections/${encodeURIComponent(symbol)}/listings`);
-  url.searchParams.set("offset", String(offset));
-  url.searchParams.set("limit", String(limit));
-  if (args.sort) url.searchParams.set("sort", String(args.sort));
-  const raw = await httpJson(url.toString(), {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-  const listings = (Array.isArray(raw) ? raw : []).map(normalizeListing);
-  return {
-    provider: "magiceden-sol",
-    chain: "solana-mainnet-beta",
-    symbol,
-    count: listings.length,
-    listings,
-    exec: false,
-  };
-}
-
-export async function magicEdenSolTokenListing(args = {}, opts = {}) {
-  const mint = solanaPubkey(args.tokenMint || args.mint, "tokenMint");
-  const raw = await httpJson(`${base(opts)}/tokens/${encodeURIComponent(mint)}/listings`, {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 12_000,
-  });
-  const listings = (Array.isArray(raw) ? raw : []).map(normalizeListing);
-  return { provider: "magiceden-sol", chain: "solana-mainnet-beta", tokenMint: mint, listings, exec: false };
-}
-
-/**
- * Build an UNSIGNED buy_now transaction for a listed Solana NFT.
- * Requires MAGICEDEN_API_KEY. Returns base64 tx for the user's wallet.
- */
-export async function magicEdenSolPrepareBuy(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a buy instruction");
-  const buyer = solanaPubkey(args.buyer || args.userPublicKey, "buyer");
-  const seller = solanaPubkey(args.seller, "seller");
-  const tokenMint = solanaPubkey(args.tokenMint, "tokenMint");
-  const tokenATA = solanaPubkey(args.tokenATA || args.tokenAddress, "tokenATA");
-  const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
-  const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
-  const maxPriceSol = args.maxPriceSol == null ? priceSol : positiveNumber(args.maxPriceSol, "maxPriceSol");
-  if (priceSol > maxPriceSol) {
-    throw new Error(`magiceden: listing price ${priceSol} SOL exceeds maxPriceSol cap ${maxPriceSol} SOL`);
-  }
-  const url = new URL(`${base(opts)}/instructions/buy_now`);
-  url.searchParams.set("buyer", buyer);
-  url.searchParams.set("seller", seller);
-  url.searchParams.set("auctionHouseAddress", auctionHouse);
-  url.searchParams.set("tokenMint", tokenMint);
-  url.searchParams.set("tokenATA", tokenATA);
-  url.searchParams.set("price", String(priceSol));
-  if (args.sellerReferral) url.searchParams.set("sellerReferral", String(args.sellerReferral));
-  if (args.buyerReferral) url.searchParams.set("buyerReferral", String(args.buyerReferral));
-  const raw = await httpJson(url.toString(), {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-  // Refuse pre-signed material by PRESENCE, before selecting unsigned bytes.
-  // A mixed payload (valid unsigned bytes plus a signed sibling) previously
-  // skipped this check entirely and bound the signed field into the envelope.
-  assertNoSignedMaterial("magiceden", raw);
-  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
-  // Accept ONLY the documented unsigned instruction field. A pre-signed payload
-  // (txSigned) from a compromised or impersonated API must never be laundered
-  // into a "prepare" result — the user would be signing bytes Oracle never
-  // validated against the price cap.
-  if (!Array.isArray(data)) {
-    if (raw?.txSigned) throw new Error("magiceden: refused a pre-signed transaction payload from the API");
-    throw new Error("magiceden: buy_now returned no unsigned transaction payload");
-  }
-  const transaction = Buffer.from(data).toString("base64");
-  return stampPrepared({
-    provider: "magiceden-sol",
-    chain: "solana-mainnet-beta",
-    kind: "nft-buy",
-    prepareReady: true,
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    buyer,
-    seller,
-    tokenMint,
-    priceSol,
-    maxPriceSol,
-    lamports: lamports(priceSol),
-    transaction,
-    transactionEncoding: "base64",
-    raw,
-  });
-}
-
-/**
- * Build an UNSIGNED list instruction so a holder can list their own NFT.
- * Requires MAGICEDEN_API_KEY. User wallet signs; Oracle never broadcasts.
- */
-export async function magicEdenSolPrepareList(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a list instruction");
-  const seller = solanaPubkey(args.seller || args.userPublicKey, "seller");
-  const tokenMint = solanaPubkey(args.tokenMint, "tokenMint");
-  const tokenATA = solanaPubkey(args.tokenATA || args.tokenAddress, "tokenATA");
-  const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
-  const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
-  const expiry = listingExpiry(args.expiry);
-  const confirmation = requireListingConfirmation(args, { tokenMint, priceSol, expiry });
-  const url = new URL(`${base(opts)}/instructions/sell`);
-  url.searchParams.set("seller", seller);
-  url.searchParams.set("auctionHouseAddress", auctionHouse);
-  url.searchParams.set("tokenMint", tokenMint);
-  url.searchParams.set("tokenAccount", tokenATA);
-  url.searchParams.set("price", String(priceSol));
-  if (args.sellerReferral) url.searchParams.set("sellerReferral", solanaPubkey(args.sellerReferral, "sellerReferral"));
-  if (expiry != null) url.searchParams.set("expiry", String(expiry));
-  const raw = await httpJson(url.toString(), {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-  // Refuse pre-signed material by PRESENCE, before selecting unsigned bytes.
-  // A mixed payload (valid unsigned bytes plus a signed sibling) previously
-  // skipped this check entirely and bound the signed field into the envelope.
-  assertNoSignedMaterial("magiceden", raw);
-  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
-  if (!Array.isArray(data)) {
-    if (raw?.txSigned) throw new Error("magiceden: refused a pre-signed transaction payload from the API");
-    throw new Error("magiceden: sell returned no unsigned transaction payload");
-  }
-  const transaction = Buffer.from(data).toString("base64");
-  return stampPrepared({
-    provider: "magiceden-sol",
-    chain: "solana-mainnet-beta",
-    kind: "nft-list",
-    prepareReady: true,
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    seller,
-    tokenMint,
-    priceSol,
-    expiry,
-    confirmation,
-    transaction,
-    transactionEncoding: "base64",
-    raw,
-  });
-}
-
-/**
- * Launchpad mint instruction. Requires MAGICEDEN_API_KEY. Unsigned only.
- */
-export async function magicEdenSolPrepareMint(args = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("magiceden: MAGICEDEN_API_KEY required to build a mint instruction");
-  const buyer = solanaPubkey(args.buyer || args.userPublicKey, "buyer");
-  const symbol = symbolArg(args.symbol || args.collection);
-  // A mint debits the buyer, so the cap is mandatory. Recording it without
-  // enforcing it is worse than having none: the caller believes a ceiling held.
-  if (args.maxPriceSol == null) {
-    throw new Error("magiceden: maxPriceSol is required to prepare a mint — an uncapped mint has no spend ceiling");
-  }
-  const maxPriceSol = positiveNumber(args.maxPriceSol, "maxPriceSol");
-  const nftAmount = args.nftAmount == null ? 1 : positiveNumber(args.nftAmount, "nftAmount");
-  if (!Number.isInteger(nftAmount)) throw new Error("magiceden: nftAmount must be a whole number");
-
-  const url = new URL(`${base(opts)}/instructions/mint`);
-  url.searchParams.set("symbol", symbol);
-  url.searchParams.set("wallet", buyer);
-  url.searchParams.set("nftAmount", String(nftAmount));
-  const raw = await httpJson(url.toString(), {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-
-  // Enforce the cap against the price the launchpad actually quotes. If the
-  // price cannot be determined, fail closed rather than return an unbounded
-  // mint the caller thinks is capped.
-  const quoted = mintPriceSol(raw);
-  if (quoted == null) {
-    throw new Error("magiceden: mint price not present in the API response — refusing to prepare an unverifiable spend");
-  }
-  const totalSol = quoted * nftAmount;
-  if (totalSol > maxPriceSol) {
-    throw new Error(
-      `magiceden: mint cost ${totalSol} SOL exceeds maxPriceSol cap ${maxPriceSol} SOL`
-    );
-  }
-
-  // Refuse pre-signed material by PRESENCE, before selecting unsigned bytes.
-  // A mixed payload (valid unsigned bytes plus a signed sibling) previously
-  // skipped this check entirely and bound the signed field into the envelope.
-  assertNoSignedMaterial("magiceden", raw);
-  const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
-  if (!Array.isArray(data)) {
-    if (raw?.txSigned) throw new Error("magiceden: refused a pre-signed transaction payload from the API");
-    throw new Error("magiceden: mint returned no unsigned transaction payload");
-  }
-  const transaction = Buffer.from(data).toString("base64");
-  return stampPrepared({
-    provider: "magiceden-sol",
-    chain: "solana-mainnet-beta",
-    kind: "nft-mint",
-    prepareReady: true,
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    buyer,
-    symbol,
-    nftAmount,
-    priceSol: quoted,
-    totalSol,
-    maxPriceSol,
-    transaction,
-    transactionEncoding: "base64",
-    raw,
-  });
-}

package/src/data/providers/mempool-lightning.mjs

@@ -1,144 +0,0 @@
-// Lightning Network topology via mempool.space /api/v1/lightning — keyless.
-//
-// Verified live:
-//   GET /api/v1/lightning/statistics/latest             200
-//   GET /api/v1/lightning/nodes/rankings/connectivity   200
-//   GET /api/v1/lightning/nodes/countries               200
-//
-// STALENESS CAVEAT (measured, not hypothetical): mempool.space's Lightning
-// crawler runs on its own schedule and the `statistics/latest` snapshot has
-// been observed WEEKS behind wall clock. Every op below therefore reports
-// `ageDays` / `stale` alongside the data so a caller cannot mistake an old
-// snapshot for a live one. Treat these numbers as a trend, not a tick.
-
-import { httpJson } from "../http.mjs";
-
-export const MEMPOOL_API = "https://mempool.space/api";
-/** Snapshots older than this are flagged stale in every response. */
-export const LN_STALE_AFTER_DAYS = 7;
-
-function baseUrl(opts = {}) {
-  return String(opts.baseUrl || process.env.MEMPOOL_API_URL || MEMPOOL_API).replace(/\/$/, "");
-}
-
-function get(path, opts = {}) {
-  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-}
-
-function ageOf(when) {
-  if (!when) return { ageDays: null, stale: null };
-  const t = new Date(when).getTime();
-  if (!Number.isFinite(t)) return { ageDays: null, stale: null };
-  const ageDays = (Date.now() - t) / 86_400_000;
-  return { ageDays: Math.round(ageDays * 10) / 10, stale: ageDays > LN_STALE_AFTER_DAYS };
-}
-
-export async function lightningHealth(opts = {}) {
-  try {
-    const res = await get("/v1/lightning/statistics/latest", opts);
-    const latest = res?.latest || {};
-    const { ageDays, stale } = ageOf(latest.added);
-    return {
-      // ok = the endpoint answered with a usable snapshot. Staleness is
-      // reported, not treated as an outage — the API is up either way.
-      ok: Number(latest.node_count || 0) > 0,
-      provider: "mempool-lightning",
-      baseUrl: baseUrl(opts),
-      snapshotAt: latest.added ?? null,
-      ageDays,
-      stale,
-      nodeCount: latest.node_count ?? null,
-      exec: false,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "mempool-lightning",
-      baseUrl: baseUrl(opts),
-      error: String(error?.message || error),
-      exec: false,
-    };
-  }
-}
-
-export async function lightningStatistics(_args = {}, opts = {}) {
-  const res = await get("/v1/lightning/statistics/latest", opts);
-  const s = res?.latest || {};
-  const { ageDays, stale } = ageOf(s.added);
-  return {
-    provider: "mempool-lightning",
-    snapshotAt: s.added ?? null,
-    ageDays,
-    stale,
-    staleNote: stale
-      ? `mempool.space Lightning snapshot is ${ageDays} days old — trend only, not live state`
-      : undefined,
-    nodeCount: s.node_count ?? null,
-    channelCount: s.channel_count ?? null,
-    totalCapacitySats: s.total_capacity == null ? null : String(s.total_capacity),
-    totalCapacityBtc: s.total_capacity == null ? null : Number(s.total_capacity) / 1e8,
-    avgCapacitySats: s.avg_capacity == null ? null : String(s.avg_capacity),
-    avgFeeRatePpm: s.avg_fee_rate ?? null,
-    avgBaseFeeMsat: s.avg_base_fee_mtokens ?? null,
-    torNodes: s.tor_nodes ?? null,
-    clearnetNodes: s.clearnet_nodes ?? null,
-    unannouncedNodes: s.unannounced_nodes ?? null,
-    raw: s,
-  };
-}
-
-/**
- * Node rankings. `metric` selects the mempool.space ranking route:
- *   connectivity (default) | liquidity | channels
- */
-export async function lightningNodeRankings(args = {}, opts = {}) {
-  const metric = String(args.metric || args.ranking || "connectivity").trim().toLowerCase();
-  const allowed = new Set(["connectivity", "liquidity", "channels"]);
-  if (!allowed.has(metric)) {
-    throw new Error(`mempool-lightning: metric must be one of ${[...allowed].join(", ")}`);
-  }
-  const rows = await get(`/v1/lightning/nodes/rankings/${metric}`, opts);
-  const list = Array.isArray(rows) ? rows : [];
-  const limit = Math.min(100, Math.max(1, Number(args.limit || list.length || 1)));
-  return {
-    provider: "mempool-lightning",
-    metric,
-    count: list.length,
-    nodes: list.slice(0, limit).map((n) => ({
-      publicKey: n.publicKey ?? null,
-      alias: n.alias ?? null,
-      channels: n.channels ?? null,
-      capacitySats: n.capacity == null ? null : String(n.capacity),
-      firstSeen: n.firstSeen ?? null,
-      updatedAt: n.updatedAt ?? null,
-      city: n.city?.en ?? n.city ?? null,
-      country: n.country?.en ?? n.country ?? null,
-      iso: n.iso_code ?? null,
-    })),
-  };
-}
-
-/** Node distribution by country — the decentralization read. */
-export async function lightningNodeCountries(args = {}, opts = {}) {
-  const rows = await get("/v1/lightning/nodes/countries", opts);
-  const list = Array.isArray(rows) ? rows : [];
-  const limit = Math.min(250, Math.max(1, Number(args.limit || list.length || 1)));
-  const totalNodes = list.reduce((n, c) => n + Number(c.count || 0), 0);
-  return {
-    provider: "mempool-lightning",
-    countryCount: list.length,
-    totalNodes,
-    topCountrySharePct: list[0]?.share ?? null,
-    countries: list.slice(0, limit).map((c) => ({
-      // Names arrive as a multi-language object; pick English, keep the rest.
-      name: c.name?.en ?? c.name ?? null,
-      iso: c.iso ?? null,
-      count: c.count ?? null,
-      sharePct: c.share ?? null,
-      capacitySats: c.capacity == null ? null : String(c.capacity),
-    })),
-  };
-}

package/src/data/providers/mempool-mining.mjs

@@ -1,142 +0,0 @@
-// Bitcoin mining telemetry via mempool.space /api/v1/mining — keyless.
-//
-// Distinct from bitcoin-esplora (which is the Esplora address/tx/UTXO surface):
-// this module answers network-security and miner-economics questions —
-// difficulty retarget, pool concentration, hashrate trend, subsidy vs fee split.
-//
-// Verified live:
-//   GET /api/v1/difficulty-adjustment    200
-//   GET /api/v1/mining/pools/1w          200
-//   GET /api/v1/mining/hashrate/3d       200
-//   GET /api/v1/mining/reward-stats/144  200
-
-import { httpJson } from "../http.mjs";
-
-export const MEMPOOL_API = "https://mempool.space/api";
-
-// mempool.space only serves these window tokens; anything else 400s.
-const VALID_WINDOWS = new Set(["24h", "3d", "1w", "1m", "3m", "6m", "1y", "2y", "3y", "all"]);
-
-function baseUrl(opts = {}) {
-  return String(opts.baseUrl || process.env.MEMPOOL_API_URL || MEMPOOL_API).replace(/\/$/, "");
-}
-
-function window_(value, fallback) {
-  const w = String(value || fallback).trim().toLowerCase();
-  if (!VALID_WINDOWS.has(w)) {
-    throw new Error(`mempool-mining: window must be one of ${[...VALID_WINDOWS].join(", ")}`);
-  }
-  return w;
-}
-
-function get(path, opts = {}) {
-  return httpJson(`${baseUrl(opts)}${path.startsWith("/") ? path : `/${path}`}`, {
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-}
-
-export async function miningHealth(opts = {}) {
-  try {
-    const d = await get("/v1/difficulty-adjustment", opts);
-    return {
-      ok: Number.isFinite(Number(d?.nextRetargetHeight)) && Number(d.nextRetargetHeight) > 0,
-      provider: "mempool-mining",
-      baseUrl: baseUrl(opts),
-      nextRetargetHeight: d?.nextRetargetHeight ?? null,
-      exec: false,
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      provider: "mempool-mining",
-      baseUrl: baseUrl(opts),
-      error: String(error?.message || error),
-      exec: false,
-    };
-  }
-}
-
-export async function miningDifficulty(_args = {}, opts = {}) {
-  const d = await get("/v1/difficulty-adjustment", opts);
-  return {
-    provider: "mempool-mining",
-    progressPercent: d.progressPercent ?? null,
-    difficultyChangePct: d.difficultyChange ?? null,
-    estimatedRetargetDate: d.estimatedRetargetDate ?? null,
-    remainingBlocks: d.remainingBlocks ?? null,
-    remainingTimeMs: d.remainingTime ?? null,
-    previousRetargetPct: d.previousRetarget ?? null,
-    nextRetargetHeight: d.nextRetargetHeight ?? null,
-    timeAvgMs: d.timeAvg ?? null,
-    raw: d,
-  };
-}
-
-/**
- * Pool share over a window. Emits an explicit concentration read (top-1 and
- * top-3 share) because "is any pool near 51%?" is the reason to ask at all.
- */
-export async function miningPoolShare(args = {}, opts = {}) {
-  const w = window_(args.window || args.timeframe, "1w");
-  const res = await get(`/v1/mining/pools/${w}`, opts);
-  const pools = Array.isArray(res?.pools) ? res.pools : [];
-  const totalBlocks = pools.reduce((n, p) => n + Number(p.blockCount || 0), 0);
-  const share = (p) => (totalBlocks > 0 ? (Number(p.blockCount || 0) / totalBlocks) * 100 : null);
-  const ranked = [...pools].sort((a, b) => Number(b.blockCount || 0) - Number(a.blockCount || 0));
-  const limit = Math.min(200, Math.max(1, Number(args.limit || ranked.length || 1)));
-  return {
-    provider: "mempool-mining",
-    window: w,
-    totalBlocks,
-    blockCount: res?.blockCount ?? null,
-    lastEstimatedHashrate: res?.lastEstimatedHashrate ?? null,
-    topPoolSharePct: ranked[0] ? share(ranked[0]) : null,
-    top3SharePct: ranked.slice(0, 3).reduce((n, p) => n + (share(p) || 0), 0) || null,
-    pools: ranked.slice(0, limit).map((p) => ({
-      name: p.name ?? null,
-      slug: p.slug ?? null,
-      blockCount: p.blockCount ?? null,
-      rank: p.rank ?? null,
-      sharePct: share(p),
-      emptyBlocks: p.emptyBlocks ?? null,
-      avgMatchRate: p.avgMatchRate ?? null,
-    })),
-  };
-}
-
-export async function miningHashrate(args = {}, opts = {}) {
-  const w = window_(args.window || args.timeframe, "3d");
-  const res = await get(`/v1/mining/hashrate/${w}`, opts);
-  const series = Array.isArray(res?.hashrates) ? res.hashrates : [];
-  return {
-    provider: "mempool-mining",
-    window: w,
-    currentHashrate: res?.currentHashrate ?? null,
-    currentHashrateEhs: res?.currentHashrate == null ? null : Number(res.currentHashrate) / 1e18,
-    currentDifficulty: res?.currentDifficulty ?? null,
-    points: series.length,
-    hashrates: series,
-    difficulty: Array.isArray(res?.difficulty) ? res.difficulty : [],
-  };
-}
-
-/** Subsidy vs fee split over the last N blocks (default 144 ≈ one day). */
-export async function miningRewardStats(args = {}, opts = {}) {
-  const n = Math.min(10_000, Math.max(1, Number(args.blockCount || args.blocks || 144)));
-  const r = await get(`/v1/mining/reward-stats/${n}`, opts);
-  const totalReward = Number(r.totalReward || 0);
-  const totalFee = Number(r.totalFee || 0);
-  return {
-    provider: "mempool-mining",
-    blockCount: n,
-    startBlock: r.startBlock ?? null,
-    endBlock: r.endBlock ?? null,
-    totalRewardSats: String(r.totalReward ?? ""),
-    totalFeeSats: String(r.totalFee ?? ""),
-    totalSubsidySats: String(totalReward - totalFee),
-    feeSharePct: totalReward > 0 ? (totalFee / totalReward) * 100 : null,
-    totalTx: r.totalTx ?? null,
-    raw: r,
-  };
-}