@oracle-agent/oracle 0.11.0 → 0.13.0

package/src/sell-simulation.mjs

@@ -1,167 +0,0 @@
-// Sell simulation: can you get OUT of this token before you ape in?
-//
-// The single most expensive failure in memecoin trading is not a bad entry, it
-// is an entry you cannot exit. A honeypot lets you buy and then blocks the
-// sell, or taxes it to zero, or lets only allowlisted wallets out. Every one of
-// those looks identical to a healthy token on a chart and on a buy-side quote.
-//
-// The ONLY reliable test is to simulate the round trip: quote buy, then quote
-// the sell of what that buy would give you, and compare what comes back. This
-// module turns that into a verdict.
-//
-// It is deliberately venue-agnostic: pass in a quote function and it works on
-// any chain and any DEX Oracle supports.
-
-export const SELL_SIM = Object.freeze({
-  SAFE: "SAFE",
-  CAUTION: "CAUTION",
-  HONEYPOT: "HONEYPOT",
-  UNKNOWN: "UNKNOWN",
-});
-
-// Round-trip loss above this is a hard refusal: no honest fee structure eats
-// this much, so it means a sell tax or a rigged curve.
-const HONEYPOT_LOSS_BPS = 5000; // 50%
-// Above this, allow the trade but make the user look at it.
-const CAUTION_LOSS_BPS = 1500; // 15%
-
-function bps(part, whole) {
-  if (whole === 0n) return null;
-  return Number(((whole - part) * 10000n) / whole);
-}
-
-function toBig(value, label) {
-  if (value == null || value === "") throw new Error(`sell-sim: ${label} required`);
-  if (typeof value === "bigint") return value;
-  const text = String(value).trim();
-  if (!/^\d+$/.test(text)) throw new Error(`sell-sim: ${label} must be an integer base-unit amount`);
-  return BigInt(text);
-}
-
-/**
- * Simulate the full round trip: base -> token -> base.
- *
- * @param {object} args
- * @param {string} args.token        token contract being evaluated
- * @param {string} args.base         the asset you pay with (WETH, USDC, SOL...)
- * @param {string|bigint} args.amountIn  base amount, in base units
- * @param {number} [args.chainId]
- * @param {object} opts
- * @param {(q:object)=>Promise<{outAmount:string|bigint}>} opts.quote
- *        A quote function. Called twice: buy leg, then sell leg.
- *
- * @returns verdict + the numbers behind it. NEVER a bare boolean: the caller
- *          must be able to show the user why.
- */
-export async function simulateSell(args = {}, opts = {}) {
-  const { token, base, chainId = null } = args;
-  if (!token) throw new Error("sell-sim: token required");
-  if (!base) throw new Error("sell-sim: base asset required");
-  if (typeof opts.quote !== "function") throw new Error("sell-sim: opts.quote function required");
-
-  const amountIn = toBig(args.amountIn, "amountIn");
-
-  let buy;
-  try {
-    buy = await opts.quote({ chainId, inputMint: base, outputMint: token, amount: amountIn.toString(), side: "buy" });
-  } catch (err) {
-    return verdict(SELL_SIM.UNKNOWN, `buy leg could not be quoted: ${short(err)}`, { chainId, token, base });
-  }
-
-  const tokensOut = safeBig(buy?.outAmount);
-  if (tokensOut == null || tokensOut === 0n) {
-    return verdict(SELL_SIM.UNKNOWN, "buy leg returned no output — no route or no liquidity", { chainId, token, base });
-  }
-
-  let sell;
-  try {
-    sell = await opts.quote({ chainId, inputMint: token, outputMint: base, amount: tokensOut.toString(), side: "sell" });
-  } catch (err) {
-    // A buy that routes and a sell that will not is the classic honeypot shape.
-    return verdict(
-      SELL_SIM.HONEYPOT,
-      `buy routes but the SELL leg fails to quote (${short(err)}) — you would not be able to exit`,
-      { chainId, token, base, tokensOut: tokensOut.toString() }
-    );
-  }
-
-  const backOut = safeBig(sell?.outAmount);
-  if (backOut == null || backOut === 0n) {
-    return verdict(SELL_SIM.HONEYPOT, "sell leg returns zero — the position cannot be exited for value", {
-      chainId,
-      token,
-      base,
-      tokensOut: tokensOut.toString(),
-    });
-  }
-
-  const lossBps = bps(backOut, amountIn);
-  const detail = {
-    chainId,
-    token,
-    base,
-    amountIn: amountIn.toString(),
-    tokensOut: tokensOut.toString(),
-    roundTripOut: backOut.toString(),
-    roundTripLossBps: lossBps,
-  };
-
-  if (lossBps == null) return verdict(SELL_SIM.UNKNOWN, "could not compute round-trip loss", detail);
-  if (lossBps >= HONEYPOT_LOSS_BPS) {
-    return verdict(
-      SELL_SIM.HONEYPOT,
-      `round trip loses ${(lossBps / 100).toFixed(1)}% — a sell tax or rigged curve, not normal slippage`,
-      detail
-    );
-  }
-  if (lossBps >= CAUTION_LOSS_BPS) {
-    return verdict(SELL_SIM.CAUTION, `round trip loses ${(lossBps / 100).toFixed(1)}% — high tax or thin liquidity`, detail);
-  }
-  return verdict(SELL_SIM.SAFE, `round trip loses ${(lossBps / 100).toFixed(1)}% — exit path looks normal`, detail);
-}
-
-function verdict(status, reason, detail) {
-  return {
-    status,
-    safe: status === SELL_SIM.SAFE,
-    tradable: status === SELL_SIM.SAFE || status === SELL_SIM.CAUTION,
-    reason,
-    ...detail,
-  };
-}
-
-function safeBig(v) {
-  if (v == null) return null;
-  try {
-    const text = String(v).trim();
-    if (!/^\d+$/.test(text)) return null;
-    return BigInt(text);
-  } catch {
-    return null;
-  }
-}
-
-function short(err) {
-  return String(err?.message || err).slice(0, 120);
-}
-
-/**
- * Refuse to proceed unless the token can actually be sold.
- *
- * Fails CLOSED on UNKNOWN: "we could not verify you can exit" must never read
- * as "safe to ape". Pass allowUnknown only for research surfaces where no money
- * moves.
- */
-export async function assertSellable(args = {}, opts = {}) {
-  const result = await simulateSell(args, opts);
-  const acceptable =
-    result.status === SELL_SIM.SAFE ||
-    (result.status === SELL_SIM.CAUTION && opts.allowCaution !== false) ||
-    (result.status === SELL_SIM.UNKNOWN && opts.allowUnknown === true);
-  if (!acceptable) {
-    const err = new Error(`sell-sim ${result.status}: ${result.reason}`);
-    err.sellSim = result;
-    throw err;
-  }
-  return result;
-}

package/src/signals/engine.mjs

@@ -1,146 +0,0 @@
-const SIGNAL_TYPES = Object.freeze([
-  "wallet",
-  "pool",
-  "nft_floor",
-  "hl_flow",
-  "prediction_market",
-]);
-
-const TYPE_ALIASES = Object.freeze({
-  wallets: "wallet",
-  smart_wallet: "wallet",
-  pools: "pool",
-  new_pool: "pool",
-  nft: "nft_floor",
-  nft_floors: "nft_floor",
-  hyperliquid: "hl_flow",
-  prediction: "prediction_market",
-  prediction_markets: "prediction_market",
-});
-
-const clamp = (value, min = 0, max = 1) => Math.min(max, Math.max(min, value));
-const finite = (value) => (Number.isFinite(Number(value)) ? Number(value) : null);
-const round = (value) => Math.round(value * 10_000) / 10_000;
-
-function typeOf(event) {
-  const raw = String(event?.type ?? event?.surface ?? event?.kind ?? "").toLowerCase();
-  return TYPE_ALIASES[raw] ?? raw;
-}
-
-function idOf(event, index) {
-  return String(event?.id ?? event?.signalId ?? event?.asset ?? event?.market ?? event?.pool ?? event?.collection ?? `${typeOf(event)}:${index}`);
-}
-
-function add(contributions, feature, value, observed = true) {
-  if (!observed || value === null || !Number.isFinite(value)) return;
-  contributions.push({ feature, value: round(value) });
-}
-
-function walletFeatures(event, out) {
-  const buys = finite(event.repeatBuys ?? event.repeat_buys ?? event.buyCount);
-  const winRate = finite(event.walletWinRate ?? event.winRate);
-  add(out, "repeat_buys", buys === null ? null : clamp((buys - 1) / 4) * 0.38);
-  add(out, "wallet_win_rate", winRate === null ? null : (clamp(winRate) - 0.5) * 0.5);
-}
-
-function poolFeatures(event, out) {
-  const age = finite(event.ageHours ?? event.poolAgeHours);
-  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
-  const locked = event.liquidityLocked ?? event.locked;
-  add(out, "pool_age", age === null ? null : age < 24 ? -0.42 : clamp(age / 720) * 0.12);
-  add(out, "liquidity", liquidity === null ? null : (clamp(Math.log10(Math.max(1, liquidity)) / 7) - 0.5) * 0.28);
-  add(out, "liquidity_lock", locked == null ? null : locked ? 0.12 : -0.28);
-}
-
-function nftFeatures(event, out) {
-  const change = finite(event.floorChange ?? event.floorChangePct);
-  const sales = finite(event.sales ?? event.saleCount);
-  add(out, "floor_change", change === null ? null : clamp(change, -1, 1) * 0.35);
-  add(out, "sales_depth", sales === null ? null : clamp(sales / 50) * 0.18);
-}
-
-function hlFeatures(event, out) {
-  const imbalance = finite(event.flowImbalance ?? event.imbalance);
-  const funding = finite(event.fundingRate ?? event.funding);
-  add(out, "flow_imbalance", imbalance === null ? null : clamp(imbalance, -1, 1) * 0.42);
-  add(out, "funding", funding === null ? null : -clamp(funding * 100, -1, 1) * 0.12);
-}
-
-function predictionFeatures(event, out) {
-  const market = finite(event.marketProbability ?? event.marketPrice ?? event.probability);
-  const fair = finite(event.fairProbability ?? event.referenceProbability ?? event.fairValue);
-  add(out, "probability_mispricing", market === null || fair === null ? null : clamp(fair - market, -1, 1) * 0.65);
-  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
-  add(out, "market_liquidity", liquidity === null ? null : clamp(Math.log10(Math.max(1, liquidity)) / 6) * 0.12);
-}
-
-const FEATURE_BUILDERS = Object.freeze({
-  wallet: walletFeatures,
-  pool: poolFeatures,
-  nft_floor: nftFeatures,
-  hl_flow: hlFeatures,
-  prediction_market: predictionFeatures,
-});
-
-function markoutFor(event, id, markouts) {
-  const rows = markouts.filter((row) => {
-    const target = row?.signalId ?? row?.eventId ?? row?.id ?? row?.asset ?? row?.market;
-    return target != null && String(target) === id;
-  });
-  if (rows.length === 0) return null;
-  const values = rows.map((row) => finite(row.return ?? row.markout ?? row.pnl ?? row.value)).filter((value) => value !== null);
-  if (values.length === 0) return null;
-  return values.reduce((sum, value) => sum + value, 0) / values.length;
-}
-
-/** Pure, deterministic scoring of observed onchain events. It never fetches data or executes. */
-export function scoreSignals(events = [], markouts = [], options = {}) {
-  if (!Array.isArray(events) || !Array.isArray(markouts)) throw new TypeError("events and markouts must be arrays");
-  const minimumCoverage = clamp(finite(options.minimumCoverage) ?? 0.5);
-
-  return events.map((event, index) => {
-    const type = typeOf(event);
-    const id = idOf(event, index);
-    const builder = FEATURE_BUILDERS[type];
-    const contributions = [];
-    if (builder) builder(event, contributions);
-
-    const expected = type === "wallet" ? 2 : type === "pool" ? 3 : 2;
-    const coverage = round(clamp(contributions.length / expected));
-    const rawFeatureScore = contributions.reduce((sum, item) => sum + item.value, 0);
-    const markout = markoutFor(event, id, markouts);
-    const markoutContribution = markout === null ? 0 : clamp(markout, -1, 1) * 0.35;
-    if (markout !== null) add(contributions, "shadow_markout", markoutContribution);
-    const score = round(clamp(0.5 + rawFeatureScore + markoutContribution));
-    const markoutFactor = markout === null ? 0.8 : clamp(0.85 + markout * 0.3, 0.35, 1);
-    const confidence = round(clamp(coverage * markoutFactor));
-    const flags = ["COLD_INTELLIGENCE_ONLY", "NO_HOT_EXECUTION"];
-    if (!builder) flags.push("UNSUPPORTED_SIGNAL_TYPE");
-    if (coverage < minimumCoverage) flags.push("LOW_COVERAGE", "NO_TRADE");
-    if (confidence < 0.5) flags.push("LOW_CONFIDENCE", "NO_TRADE");
-    if (type === "pool" && (finite(event.ageHours ?? event.poolAgeHours) ?? Infinity) < 24) flags.push("NEW_POOL_RISK", "NO_TRADE");
-    if (markout !== null && markout < 0) flags.push("NEGATIVE_MARKOUT");
-
-    return {
-      id,
-      type,
-      score,
-      confidence,
-      coverage,
-      contributions,
-      flags: [...new Set(flags)],
-      noTrade: flags.includes("NO_TRADE"),
-      executionAllowed: false,
-    };
-  }).sort((a, b) => b.score - a.score || b.confidence - a.confidence || a.id.localeCompare(b.id));
-}
-
-export function createSignalsEngine(defaults = {}) {
-  return Object.freeze({
-    score(events, markouts = [], options = {}) {
-      return scoreSignals(events, markouts, { ...defaults, ...options });
-    },
-  });
-}
-
-export { SIGNAL_TYPES };

package/src/signals/index.mjs

@@ -1 +0,0 @@
-export { SIGNAL_TYPES, createSignalsEngine, scoreSignals } from "./engine.mjs";

package/src/token-transfer-guard.mjs

@@ -1,188 +0,0 @@
-import { Interface, MaxUint256, isAddress } from "ethers";
-
-const TRANSFER_SELECTOR = "0xa9059cbb";
-const TRANSFER_FROM_SELECTOR = "0x23b872dd";
-const DEFAULT_TOKEN_TRANSFER_TTL_MS = 20_000;
-
-const ERC20_TRANSFER = new Interface([
-  "function transfer(address to,uint256 amount) returns (bool)",
-  "function transferFrom(address from,address to,uint256 amount) returns (bool)",
-]);
-
-function normalAddress(value, label) {
-  const text = String(value || "").trim();
-  if (!isAddress(text)) throw new Error(`${label} must be an address`);
-  return text.toLowerCase();
-}
-
-function amountString(value, label = "token transfer amount", { allowZero = false } = {}) {
-  // A JS number cannot represent every uint256, and above 2^53 it silently
-  // rounds — usually UPWARD, which would widen a spending cap past what the
-  // user asked for. `9007199254740995` arrives as `...996` and authorizes one
-  // more token than intended. Refuse unsafe numbers instead of quietly
-  // accepting a different value than the caller wrote.
-  if (typeof value === "number") {
-    if (!Number.isInteger(value)) {
-      throw new Error(`${label} must be an integer`);
-    }
-    if (!Number.isSafeInteger(value)) {
-      throw new Error(
-        `${label} exceeds safe integer precision — pass it as a decimal string or BigInt so the exact value is preserved`
-      );
-    }
-  }
-  let amount;
-  try {
-    amount = BigInt(String(value));
-  } catch {
-    throw new Error(`${label} must be an integer string`);
-  }
-  if (allowZero ? amount < 0n : amount <= 0n) throw new Error(`${label} must be positive`);
-  if (amount >= MaxUint256) throw new Error("unbounded token transfer amount refused");
-  return amount.toString();
-}
-
-function txValue(tx = {}) {
-  const raw = tx.value == null ? "0" : String(tx.value);
-  return BigInt(raw);
-}
-
-export function isTokenTransferCall(data) {
-  const hex = String(data || "").toLowerCase();
-  return hex.startsWith(TRANSFER_SELECTOR) || hex.startsWith(TRANSFER_FROM_SELECTOR);
-}
-
-export function decodeTokenTransferCalldata(data) {
-  const hex = String(data || "").toLowerCase();
-  try {
-    if (hex.startsWith(TRANSFER_SELECTOR)) {
-      const [recipient, amount] = ERC20_TRANSFER.decodeFunctionData("transfer", data);
-      return {
-        kind: "transfer",
-        recipient: normalAddress(recipient, "token transfer recipient"),
-        amount: amountString(amount),
-      };
-    }
-    if (hex.startsWith(TRANSFER_FROM_SELECTOR)) {
-      const [from, recipient, amount] = ERC20_TRANSFER.decodeFunctionData("transferFrom", data);
-      return {
-        kind: "transferFrom",
-        from: normalAddress(from, "token transfer source"),
-        recipient: normalAddress(recipient, "token transfer recipient"),
-        amount: amountString(amount),
-      };
-    }
-  } catch (error) {
-    if (/token transfer/.test(String(error?.message || error))) throw error;
-    throw new Error("invalid token transfer calldata");
-  }
-  throw new Error("token transfer calldata required");
-}
-
-export function createTokenTransferGuard({
-  chainId,
-  token,
-  kind = "transfer",
-  from,
-  recipient,
-  amount,
-  maxAmount,
-  provider,
-  purpose,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_TOKEN_TRANSFER_TTL_MS,
-} = {}) {
-  const guard = {
-    mode: "token-transfer",
-    chainId: Number(chainId),
-    token: normalAddress(token, "token transfer token"),
-    kind: String(kind || "transfer"),
-    recipient: normalAddress(recipient, "token transfer recipient"),
-    issuedAtMs: Number(nowMs),
-    expiresAtMs: Number(nowMs) + Number(ttlMs || DEFAULT_TOKEN_TRANSFER_TTL_MS),
-  };
-  if (guard.kind !== "transfer" && guard.kind !== "transferFrom") {
-    throw new Error("token transfer kind must be transfer or transferFrom");
-  }
-  if (guard.kind === "transferFrom") guard.from = normalAddress(from, "token transfer source");
-  if (amount != null) guard.amount = amountString(amount);
-  if (maxAmount != null) guard.maxAmount = amountString(maxAmount);
-  if (!guard.amount && !guard.maxAmount) throw new Error("token transfer guard requires exact amount or maxAmount");
-  if (provider) guard.provider = String(provider).trim();
-  if (purpose) guard.purpose = String(purpose).trim();
-  if (!Number.isFinite(guard.chainId)) throw new Error("token transfer chainId required");
-  if (!Number.isFinite(guard.issuedAtMs) || !Number.isFinite(guard.expiresAtMs) || guard.expiresAtMs <= guard.issuedAtMs) {
-    throw new Error("token transfer guard expiry invalid");
-  }
-  return guard;
-}
-
-export function assertTokenTransferGuard(guard, tx = {}, { chainId, nowMs = Date.now() } = {}) {
-  if (!guard || guard.mode !== "token-transfer") throw new Error("token transfer guard required");
-
-  // Time is a security parameter here, so an unusable clock must fail CLOSED.
-  // A NaN/Infinity `nowMs` made every `now > expiresAtMs` comparison false and
-  // silently disabled expiry; a guard missing its timestamps skipped the TTL
-  // check entirely. Both turn a short-lived authorization into a permanent one.
-  const now = Number(nowMs);
-  if (!Number.isFinite(now)) {
-    throw new Error("token transfer guard: current time must be a finite number");
-  }
-  const issuedAtMs = Number(guard.issuedAtMs);
-  const expiresAtMs = Number(guard.expiresAtMs);
-  if (!Number.isFinite(issuedAtMs) || !Number.isFinite(expiresAtMs)) {
-    throw new Error("token transfer guard: issuedAtMs and expiresAtMs are required and must be finite");
-  }
-  if (expiresAtMs <= issuedAtMs) {
-    throw new Error("token transfer guard: expiry must be after issuance");
-  }
-  if (now > expiresAtMs) {
-    throw new Error(`token transfer guard expired at ${expiresAtMs}, now ${now}`);
-  }
-
-  const txChainId = Number(tx.chainId ?? chainId);
-  if (Number(guard.chainId) !== txChainId) throw new Error(`token transfer chain mismatch: expected ${txChainId}, got ${guard.chainId}`);
-  const token = normalAddress(tx.to, "token transfer token");
-  if (normalAddress(guard.token, "token transfer token") !== token) throw new Error("token transfer token mismatch");
-  const decoded = decodeTokenTransferCalldata(tx.data);
-  if (String(guard.kind) !== decoded.kind) throw new Error("token transfer kind mismatch");
-  if (normalAddress(guard.recipient, "token transfer recipient") !== decoded.recipient) throw new Error("token transfer recipient mismatch");
-  if (decoded.kind === "transferFrom" && normalAddress(guard.from, "token transfer source") !== decoded.from) {
-    throw new Error("token transfer source mismatch");
-  }
-  // An amount ceiling is MANDATORY. Both checks below were conditional on the
-  // field being present, so a guard omitting BOTH `amount` and `maxAmount`
-  // skipped every amount check and authorized a transfer of any size — the
-  // final ERC-20 gate was effectively unbounded. A guard with no cap is not a
-  // guard.
-  if (guard.amount == null && guard.maxAmount == null) {
-    throw new Error("token transfer guard must bind an amount or a maxAmount — a capless guard authorizes any size");
-  }
-  // Coherence first: a guard whose own fields contradict each other is
-  // malformed, and saying so is more useful than reporting whichever bound
-  // happened to trip.
-  if (guard.amount != null && guard.maxAmount != null) {
-    if (BigInt(amountString(guard.amount)) > BigInt(amountString(guard.maxAmount))) {
-      throw new Error("token transfer guard amount exceeds its own maxAmount");
-    }
-  }
-  if (guard.amount != null && amountString(guard.amount) !== decoded.amount) {
-    throw new Error("token transfer amount mismatch");
-  }
-  if (guard.maxAmount != null && BigInt(decoded.amount) > BigInt(amountString(guard.maxAmount))) {
-    throw new Error("token transfer amount exceeds guard maxAmount");
-  }
-  if (txValue(tx) !== 0n) throw new Error("token transfer tx value must be zero");
-  if (Number(guard.expiresAtMs) <= Number(nowMs)) throw new Error("token transfer guard expired");
-  if (Number(guard.issuedAtMs) > Number(nowMs) + 5_000) throw new Error("token transfer guard issued in the future");
-  return {
-    chainId: txChainId,
-    token,
-    kind: decoded.kind,
-    from: decoded.from || null,
-    recipient: decoded.recipient,
-    amount: decoded.amount,
-    provider: guard.provider || null,
-    purpose: guard.purpose || null,
-  };
-}