@oracle-agent/oracle 0.1.0

package/src/sell-simulation.mjs

@@ -0,0 +1,167 @@
+// 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/token-transfer-guard.mjs

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

package/src/vault-attestation.mjs

@@ -0,0 +1,145 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Interface, isAddress } from "ethers";
+import { routeCalldataHash } from "./route-attestation.mjs";
+import { resolveAttestationSecret } from "./attestation-secret.mjs";
+import { assertFreshWindow } from "./fresh-window.mjs";
+
+const DEFAULT_VAULT_ATTESTATION_TTL_MS = 20_000;
+const ERC20 = new Interface(["function approve(address spender,uint256 amount) returns (bool)"]);
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+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 = "vault amount") {
+  try {
+    const n = BigInt(String(value));
+    if (n <= 0n) throw new Error("nonpositive");
+    return n.toString();
+  } catch {
+    throw new Error(`${label} must be a positive integer string`);
+  }
+}
+
+function decodeApproveCalldata(data) {
+  const hex = String(data || "").toLowerCase();
+  if (!hex.startsWith("0x095ea7b3")) throw new Error("approval calldata required");
+  const [spender, amount] = ERC20.decodeFunctionData("approve", hex);
+  return { spender: normalAddress(spender, "approval spender"), amount: amountString(amount, "approval amount") };
+}
+
+function hmac(secret, payload) {
+  return `0x${createHmac("sha256", String(secret)).update(payload).digest("hex")}`;
+}
+
+function sameSignature(a, b) {
+  const left = Buffer.from(String(a || "").replace(/^0x/, ""), "hex");
+  const right = Buffer.from(String(b || "").replace(/^0x/, ""), "hex");
+  return left.length === right.length && left.length > 0 && timingSafeEqual(left, right);
+}
+
+function attestationSecret(secret) {
+  return resolveAttestationSecret(
+    secret,
+    "ORACLE_ROUTE_ATTESTATION_SECRET",
+    "MAD_ROUTE_ATTESTATION_SECRET",
+  );
+}
+
+function unsigned(attestation) {
+  const { signature: _signature, ...payload } = attestation;
+  return payload;
+}
+
+export function createVaultAttestation({
+  provider = "morpho",
+  chainId,
+  action,
+  vault,
+  asset,
+  owner,
+  receiver,
+  amount,
+  data,
+  calldataHash,
+  minSharesOut,
+  maxSharesIn,
+  totalAssetsUsd,
+  nowMs = Date.now(),
+  ttlMs = DEFAULT_VAULT_ATTESTATION_TTL_MS,
+  secret,
+} = {}) {
+  const normalizedAction = String(action || "").trim().toLowerCase();
+  if (!["deposit", "withdraw"].includes(normalizedAction)) throw new Error("vault attestation action must be deposit or withdraw");
+  const attestation = {
+    mode: "vault-attestation",
+    version: 1,
+    provider: String(provider || "").trim() || "morpho",
+    chainId: Number(chainId),
+    action: normalizedAction,
+    vault: normalAddress(vault, "vault"),
+    asset: normalAddress(asset, "vault asset"),
+    owner: normalAddress(owner, "vault owner"),
+    receiver: normalAddress(receiver || owner, "vault receiver"),
+    amount: amountString(amount),
+    calldataHash: data ? routeCalldataHash(data) : calldataHash,
+    value: "0",
+    issuedAtMs: Number(nowMs),
+    expiresAtMs: Number(nowMs) + Number(ttlMs),
+  };
+  if (!Number.isFinite(attestation.chainId)) throw new Error("vault attestation chainId required");
+  if (minSharesOut != null) attestation.minSharesOut = amountString(minSharesOut, "minSharesOut");
+  if (maxSharesIn != null) attestation.maxSharesIn = amountString(maxSharesIn, "maxSharesIn");
+  if (totalAssetsUsd != null) attestation.totalAssetsUsd = Number(totalAssetsUsd);
+  const payload = canonicalJson(attestation);
+  return { ...attestation, signature: hmac(attestationSecret(secret), payload) };
+}
+
+export function assertVaultAttestation(attestation, tx = {}, { chainId, nowMs = Date.now(), secret } = {}) {
+  // Time is a security parameter: an unusable clock must fail CLOSED,
+  // otherwise NaN/null/-Infinity silently makes this attestation eternal.
+  assertFreshWindow(attestation || {}, nowMs, "vault attestation");
+  if (!attestation || attestation.mode !== "vault-attestation") throw new Error("vault attestation required");
+  if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("vault attestation expired");
+  const txChainId = Number(chainId ?? tx.chainId);
+  if (Number(attestation.chainId) !== txChainId) throw new Error("vault attestation chain mismatch");
+  const to = normalAddress(tx.to, "vault tx.to");
+  if (normalAddress(attestation.vault, "vault") !== to) throw new Error("vault attestation destination mismatch");
+  if (tx.from && normalAddress(attestation.owner, "vault owner") !== normalAddress(tx.from, "vault tx.from")) {
+    throw new Error("vault attestation owner mismatch");
+  }
+  const value = tx.value == null ? "0" : String(BigInt(String(tx.value).startsWith("0x") ? String(tx.value) : String(tx.value)));
+  if (value !== "0") throw new Error("vault attestation value mismatch");
+  if (attestation.calldataHash !== routeCalldataHash(tx.data || "0x")) throw new Error("vault attestation calldata mismatch");
+  const expected = hmac(attestationSecret(secret), canonicalJson(unsigned(attestation)));
+  if (!sameSignature(attestation.signature, expected)) throw new Error("vault attestation signature mismatch");
+  return true;
+}
+
+export function assertVaultApprovalAttestation(attestation, tx = {}, guard = {}, { chainId, nowMs = Date.now(), secret } = {}) {
+  if (!attestation || attestation.mode !== "vault-attestation") throw new Error("vault attestation required");
+  if (String(attestation.action) !== "deposit") throw new Error("vault approval requires deposit attestation");
+  if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("vault attestation expired");
+  const expected = hmac(attestationSecret(secret), canonicalJson(unsigned(attestation)));
+  if (!sameSignature(attestation.signature, expected)) throw new Error("vault attestation signature mismatch");
+  const txChainId = Number(tx.chainId ?? chainId);
+  if (Number(attestation.chainId) !== txChainId) throw new Error("vault attestation chain mismatch");
+  const decoded = decodeApproveCalldata(tx.data);
+  if (normalAddress(attestation.asset, "vault asset") !== normalAddress(tx.to, "approval token")) throw new Error("vault attestation asset mismatch");
+  if (normalAddress(attestation.vault, "vault") !== decoded.spender) throw new Error("vault attestation spender mismatch");
+  if (String(attestation.amount) !== decoded.amount || String(guard.amount) !== decoded.amount) {
+    throw new Error("vault attestation amount mismatch");
+  }
+  if (guard.provider && String(guard.provider) !== String(attestation.provider)) throw new Error("vault attestation provider mismatch");
+  return true;
+}