@oracle-agent/oracle 0.9.7 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
   "license": "Apache-2.0",
   "type": "module",

package/public/oracle-splash/index.html

@@ -401,6 +401,18 @@ main{position:relative;z-index:2;padding-top:84px}
 }
 .evolve-pill.on{border-color:rgba(124,196,255,.35);color:var(--blue2)}
 
+.venue-rail-head{
+ font-family:var(--mono);font-size:10px;letter-spacing:.14em;text-transform:uppercase;
+ color:var(--cool);text-align:center;padding:14px 16px 0;opacity:.75;
+}
+.venue-rail-head b{color:var(--blue2);font-weight:600}
+.venue-rail{padding:10px 16px 4px;max-height:96px;overflow:hidden;position:relative}
+.venue-rail .evolve-pill{font-size:9px;padding:6px 10px;opacity:.9}
+.venue-rail::after{
+ content:"";position:absolute;left:0;right:0;bottom:0;height:34px;pointer-events:none;
+ background:linear-gradient(to bottom,transparent,var(--bg));
+}
+
 .wires{height:40px;position:relative}
 .wires svg{width:100%;height:100%;display:block;overflow:visible}
 .wires path{
@@ -735,6 +747,98 @@ footer{margin-top:clamp(72px,12vh,120px);border-top:1px solid var(--line);paddin
    <span class="evolve-pill on">more chains</span>
   </div>
 
+  <div class="venue-rail-head">solana venues routed · <b id="sol-count">101</b> programs verified on-chain · 88 venues</div>
+  <div class="evolve-rail venue-rail" id="sol-venue-rail">
+   <span class="evolve-pill on">1DEX</span>
+   <span class="evolve-pill on">Aldrin</span>
+   <span class="evolve-pill on">AlphaQ</span>
+   <span class="evolve-pill on">Aquifer</span>
+   <span class="evolve-pill on">BinaryFi</span>
+   <span class="evolve-pill on">BisonFi</span>
+   <span class="evolve-pill on">Bonkswap</span>
+   <span class="evolve-pill on">Boop.fun</span>
+   <span class="evolve-pill on">Byreal</span>
+   <span class="evolve-pill on">Carrot</span>
+   <span class="evolve-pill on">Crema</span>
+   <span class="evolve-pill on">Cropper</span>
+   <span class="evolve-pill on">DefiTuna</span>
+   <span class="evolve-pill on">Denali</span>
+   <span class="evolve-pill on">Deriverse</span>
+   <span class="evolve-pill on">DexLab</span>
+   <span class="evolve-pill on">Dynamic Bonding Curve</span>
+   <span class="evolve-pill on">Flint</span>
+   <span class="evolve-pill on">Flux</span>
+   <span class="evolve-pill on">FluxBeam</span>
+   <span class="evolve-pill on">GatorSwap</span>
+   <span class="evolve-pill on">Gavel</span>
+   <span class="evolve-pill on">GoonFi</span>
+   <span class="evolve-pill on">GooseFX GAMMA</span>
+   <span class="evolve-pill on">Guacswap</span>
+   <span class="evolve-pill on">Hadron</span>
+   <span class="evolve-pill on">Heaven</span>
+   <span class="evolve-pill on">Helium Network</span>
+   <span class="evolve-pill on">Huma</span>
+   <span class="evolve-pill on">HumidiFi</span>
+   <span class="evolve-pill on">Hylo Exchange</span>
+   <span class="evolve-pill on">Hylo Stability</span>
+   <span class="evolve-pill on">Invariant</span>
+   <span class="evolve-pill on">Jupiter Lend</span>
+   <span class="evolve-pill on">JupiterRfqV2</span>
+   <span class="evolve-pill on">JupLend</span>
+   <span class="evolve-pill on">Kipseli</span>
+   <span class="evolve-pill on">LemmingsFi</span>
+   <span class="evolve-pill on">M Swap</span>
+   <span class="evolve-pill on">Manifest</span>
+   <span class="evolve-pill on">Mercurial</span>
+   <span class="evolve-pill on">MetaDAO</span>
+   <span class="evolve-pill on">Meteora</span>
+   <span class="evolve-pill on">Meteora DAMM</span>
+   <span class="evolve-pill on">Metric</span>
+   <span class="evolve-pill on">Moonit</span>
+   <span class="evolve-pill on">Obric</span>
+   <span class="evolve-pill on">Obsidian</span>
+   <span class="evolve-pill on">Omnipair</span>
+   <span class="evolve-pill on">OpenBook</span>
+   <span class="evolve-pill on">Orca</span>
+   <span class="evolve-pill on">PancakeSwap</span>
+   <span class="evolve-pill on">Penguin</span>
+   <span class="evolve-pill on">Perena</span>
+   <span class="evolve-pill on">Perena Star</span>
+   <span class="evolve-pill on">Perps</span>
+   <span class="evolve-pill on">Phoenix</span>
+   <span class="evolve-pill on">Pump.fun</span>
+   <span class="evolve-pill on">Quantum</span>
+   <span class="evolve-pill on">Raydium</span>
+   <span class="evolve-pill on">Riptide</span>
+   <span class="evolve-pill on">RunnerRodeo</span>
+   <span class="evolve-pill on">Saber</span>
+   <span class="evolve-pill on">Saber (Decimals)</span>
+   <span class="evolve-pill on">Sanctum</span>
+   <span class="evolve-pill on">Sanctum Infinity</span>
+   <span class="evolve-pill on">Saros</span>
+   <span class="evolve-pill on">Scale</span>
+   <span class="evolve-pill on">Scale Vmm</span>
+   <span class="evolve-pill on">Scorch</span>
+   <span class="evolve-pill on">Solayer</span>
+   <span class="evolve-pill on">SolFi</span>
+   <span class="evolve-pill on">Stabble</span>
+   <span class="evolve-pill on">Stabble Stable Swap</span>
+   <span class="evolve-pill on">Stabble Weighted Swap</span>
+   <span class="evolve-pill on">StepN</span>
+   <span class="evolve-pill on">TaurusFi</span>
+   <span class="evolve-pill on">TesseraV</span>
+   <span class="evolve-pill on">Token Swap</span>
+   <span class="evolve-pill on">Trends</span>
+   <span class="evolve-pill on">VaultLiquidUnstake</span>
+   <span class="evolve-pill on">Virtuals</span>
+   <span class="evolve-pill on">Voltr</span>
+   <span class="evolve-pill on">WhaleStreet</span>
+   <span class="evolve-pill on">Whirlpool</span>
+   <span class="evolve-pill on">Woofi</span>
+   <span class="evolve-pill on">XOrca</span>
+   <span class="evolve-pill on">ZeroFi</span>
+  </div>
+
   <div class="graph-canvas">
    <div class="orch" aria-label="Oracle multi-profile graph">
     <div class="row">
@@ -807,7 +911,7 @@ footer{margin-top:clamp(72px,12vh,120px);border-top:1px solid var(--line);paddin
       <div class="tag">profile</div>
       <div class="name">solana agent</div>
       <div class="sub">jup · nfts · dexs</div>
-      <div class="chains"><span class="ch">Solana <img src="https://icons.llamao.fi/icons/chains/rsz_solana?w=24&h=24" alt="" loading="lazy"></span></div>
+      <div class="chains"><span class="ch">Solana <img src="https://icons.llamao.fi/icons/chains/rsz_solana?w=24&h=24" alt="" loading="lazy"></span><span class="ch" id="sol-venue-count">88 venues routed</span></div>
      </div>
      <div class="node route p-btc">
       <div class="tag">profile</div>

package/src/cards.mjs

@@ -0,0 +1,369 @@
+// Telegram card TEXT renderers.
+//
+// Implements skills/oracle-chain-graphs-telegram-cards/SKILL.md. That spec has
+// existed with no code behind it, so Oracle users were getting raw JSON instead
+// of readable alert cards. This module is the text half only: chart/image
+// rendering lives elsewhere and MUST NOT be required for a card to send.
+//
+// Contract for every exported renderer:
+//   - pure, synchronous, string in / string out
+//   - NO network, NO signing, NO filesystem, NO env reads, NO mutation of input
+//   - unknown data renders as the literal string UNKNOWN — never blank, never
+//     guessed, never interpolated from a neighbouring field
+//   - the only identifier (contract address / mint / market id) is NEVER
+//     truncated: a half-address is worse than no address because it still looks
+//     actionable
+//   - chart failure is cosmetic: the text card always returns
+//   - buy/sell affordances only when a valid local grant/session is supplied
+//
+// Markdown dialect: Telegram *legacy* Markdown. Values are escaped for `_`,
+// `*`, `[`, `]` and backtick; card chrome supplies its own markers. We never
+// emit `$` at all (the spec calls out repeated `$` spans as a formatting trap)
+// — amounts are suffixed with USD instead.
+
+import { chainById } from "./chains.mjs";
+
+/** The one and only stand-in for missing data. */
+export const UNKNOWN = "UNKNOWN";
+
+export const CARD_KINDS = Object.freeze(["token", "launch", "hip3", "hip4", "polymarket"]);
+
+const LEGACY_MD_SPECIALS = /[_*[\]`]/g;
+
+/**
+ * Escape Telegram legacy-Markdown control characters in a *value*.
+ * Card chrome (bold headers) is written unescaped by the renderers themselves.
+ * @param {unknown} value
+ * @returns {string} escaped text, or UNKNOWN when there is nothing to show
+ */
+export function escapeMd(value) {
+  if (!isPresent(value)) return UNKNOWN;
+  return String(value).replace(LEGACY_MD_SPECIALS, (c) => `\\${c}`);
+}
+
+function isPresent(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value === "string") return value.trim() !== "";
+  return true;
+}
+
+/** A value that must survive verbatim (addresses, mints, market ids). */
+function code(value) {
+  if (!isPresent(value)) return UNKNOWN;
+  // Backticks would close the span; strip rather than truncate the identifier.
+  const raw = String(value).replace(/`/g, "");
+  return raw === "" ? UNKNOWN : `\`${raw}\``;
+}
+
+function num(value, { decimals = 2 } = {}) {
+  if (!isPresent(value)) return UNKNOWN;
+  const n = typeof value === "bigint" ? Number(value) : Number(value);
+  if (!Number.isFinite(n)) return UNKNOWN;
+  return n.toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: decimals });
+}
+
+/** Money. Deliberately no `$` — repeated dollar spans break Telegram parsing. */
+function usd(value, { decimals = 2 } = {}) {
+  const n = num(value, { decimals });
+  return n === UNKNOWN ? UNKNOWN : `${n} USD`;
+}
+
+function pct(value, { decimals = 2 } = {}) {
+  const n = num(value, { decimals });
+  return n === UNKNOWN ? UNKNOWN : `${n}%`;
+}
+
+function bps(value) {
+  const n = num(value, { decimals: 0 });
+  return n === UNKNOWN ? UNKNOWN : `${n} bps`;
+}
+
+/**
+ * Exact base-unit -> decimal string. BigInt only: a raw quote like
+ * 24325001237995579150138 loses precision the moment it touches a float.
+ */
+export function formatUnits(raw, decimals) {
+  if (!isPresent(raw)) return UNKNOWN;
+  const d = Number(decimals);
+  if (!Number.isInteger(d) || d < 0 || d > 77) return UNKNOWN;
+  let value;
+  try {
+    value = BigInt(typeof raw === "string" ? raw.trim() : raw);
+  } catch {
+    return UNKNOWN;
+  }
+  const neg = value < 0n;
+  const abs = neg ? -value : value;
+  const base = 10n ** BigInt(d);
+  const whole = (abs / base).toString();
+  const frac = (abs % base).toString().padStart(d, "0").replace(/0+$/, "");
+  return `${neg ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
+}
+
+/** Normalize confidence to a stated band. Every card must state one. */
+export function normalizeConfidence(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (value < 0 || value > 1) return UNKNOWN;
+    if (value >= 0.75) return "HIGH";
+    if (value >= 0.4) return "MEDIUM";
+    return "LOW";
+  }
+  if (typeof value === "string") {
+    const v = value.trim().toUpperCase();
+    if (v === "HIGH" || v === "MEDIUM" || v === "LOW") return v;
+  }
+  return UNKNOWN;
+}
+
+function chainLine(data = {}) {
+  const id = data.chainId;
+  if (!isPresent(id) || !Number.isFinite(Number(id))) {
+    return isPresent(data.chain) ? escapeMd(data.chain) : UNKNOWN;
+  }
+  const known = chainById(id);
+  const name = known?.name || (isPresent(data.chain) ? String(data.chain) : UNKNOWN);
+  return `${escapeMd(name)} (chainId ${Number(id)})`;
+}
+
+function venueLine(data = {}) {
+  return escapeMd(data.venue ?? data.dex ?? data.pool?.venue);
+}
+
+/**
+ * Chart status. A graph is evidence, not a dependency — if the image failed we
+ * say so and the text card still stands.
+ */
+function chartLine(chart) {
+  if (chart === null || chart === undefined) return "NONE (text card only)";
+  if (typeof chart === "string") return chart.trim() ? code(chart) : "NONE (text card only)";
+  if (chart.error || chart.ok === false || chart.available === false) {
+    const why = isPresent(chart.error) ? ` — ${escapeMd(chart.error)}` : "";
+    return `UNAVAILABLE${why} (text card stands)`;
+  }
+  if (isPresent(chart.url)) return code(chart.url);
+  return "NONE (text card only)";
+}
+
+/**
+ * Buy/sell affordances are gated on a valid LOCAL grant or session. Absent or
+ * expired grant => prepare-only. This function is the single gate; renderers
+ * never decide on their own.
+ * @returns {{ allowed: boolean, reason: string, actions: string[] }}
+ */
+export function cardActions(data = {}, { now = Date.now() } = {}) {
+  const grant = data.grant ?? data.session ?? null;
+  if (!grant || typeof grant !== "object") {
+    return { allowed: false, reason: "no local grant/session", actions: [] };
+  }
+  if (grant.local === false) {
+    return { allowed: false, reason: "grant is not local", actions: [] };
+  }
+  if (grant.revoked === true) {
+    return { allowed: false, reason: "grant revoked", actions: [] };
+  }
+  const expiry = grant.expiresAt ?? grant.expiry;
+  if (isPresent(expiry)) {
+    const at = typeof expiry === "number" ? expiry : Date.parse(expiry);
+    if (!Number.isFinite(at)) return { allowed: false, reason: "grant expiry unreadable", actions: [] };
+    if (at <= now) return { allowed: false, reason: "grant expired", actions: [] };
+  }
+  const actions = Array.isArray(grant.actions) && grant.actions.length ? grant.actions.slice() : ["BUY", "SELL"];
+  return { allowed: true, reason: "valid local grant", actions };
+}
+
+function actionsLine(data) {
+  const gate = cardActions(data);
+  return gate.allowed
+    ? `${gate.actions.map((a) => escapeMd(a)).join(" / ")} (${escapeMd(gate.reason)})`
+    : `prepare-only — ${escapeMd(gate.reason)}`;
+}
+
+function build(title, rows, data = {}) {
+  const lines = [`*${title}*`];
+  for (const [label, value] of rows) {
+    // Labels are authored here and contain no markdown specials by construction.
+    lines.push(`${label}: ${value === undefined || value === null || value === "" ? UNKNOWN : value}`);
+  }
+  lines.push(`Chart: ${chartLine(data.chart)}`);
+  lines.push(`Actions: ${actionsLine(data)}`);
+  if (Array.isArray(data.warnings) && data.warnings.length) {
+    lines.push(`Warnings: ${data.warnings.map((w) => escapeMd(w)).join("; ")}`);
+  }
+  if (isPresent(data.source) || isPresent(data.fetchedAt)) {
+    lines.push(`Source: ${escapeMd(data.source)} at ${escapeMd(data.fetchedAt)}`);
+  }
+  return lines.join("\n");
+}
+
+function confidenceRow(data) {
+  return ["Confidence", normalizeConfidence(data.confidence)];
+}
+
+function quoteRows(data) {
+  const q = data.quote;
+  if (!q || typeof q !== "object") return [];
+  const human = isPresent(q.decimals) ? formatUnits(q.amountOutRaw ?? q.out ?? q.raw, q.decimals) : UNKNOWN;
+  return [
+    ["Quote out (raw)", code(q.amountOutRaw ?? q.out ?? q.raw)],
+    ["Quote out", human === UNKNOWN ? UNKNOWN : `${escapeMd(human)} ${escapeMd(q.symbol ?? "")}`.trim()],
+  ];
+}
+
+function slippageRow(data) {
+  const s = data.autoSlippage;
+  if (!s || typeof s !== "object") return ["Auto-slippage", UNKNOWN];
+  const sel = bps(s.selectedBps);
+  const cap = bps(s.capBps);
+  return ["Auto-slippage", sel === UNKNOWN && cap === UNKNOWN ? UNKNOWN : `${sel} selected, cap ${cap}`];
+}
+
+/** Per-chain token card: price, volume, liquidity, market cap, age, venue. */
+export function renderTokenCard(data = {}) {
+  const d = data || {};
+  return build(
+    `ORACLE TOKEN — ${escapeMd(d.symbol ?? d.token ?? d.name)}`,
+    [
+      ["Chain", chainLine(d)],
+      ["Venue", venueLine(d)],
+      ["Name", escapeMd(d.name)],
+      ["Address", code(d.address ?? d.mint ?? d.contract)],
+      ["Price", usd(d.priceUsd, { decimals: 8 })],
+      ["Market cap", usd(d.marketCapUsd)],
+      ["Liquidity", usd(d.liquidityUsd)],
+      ["Volume 24h", usd(d.volume24hUsd)],
+      ["Change 24h", pct(d.priceChange24h)],
+      ["Fee tier", isPresent(d.feeTier) ? `${bps(Number(d.feeTier) / 100)} (${num(d.feeTier, { decimals: 0 })})` : UNKNOWN],
+      ["Age", escapeMd(d.age)],
+      ...quoteRows(d),
+      slippageRow(d),
+      confidenceRow(d),
+    ],
+    d,
+  );
+}
+
+/** Launch/sniper card: route readiness, sellability, overlap, risk, ticket. */
+export function renderLaunchCard(data = {}) {
+  const d = data || {};
+  return build(
+    `ORACLE LAUNCH — ${escapeMd(d.symbol ?? d.token ?? d.name)}`,
+    [
+      ["Chain", chainLine(d)],
+      ["Venue", venueLine(d)],
+      ["Address", code(d.address ?? d.mint ?? d.contract)],
+      ["Pool", code(d.pool?.address ?? d.poolAddress ?? d.pool)],
+      ["Liquidity", usd(d.liquidityUsd)],
+      ["Route ready", escapeMd(d.routeReady)],
+      ["Sellable", escapeMd(d.sellable)],
+      ["Sell sim", escapeMd(d.sellSimulation ?? d.sellSim)],
+      ["Smart wallets", escapeMd(d.smartWalletOverlap)],
+      ["Risk", escapeMd(d.risk ?? d.riskStatus)],
+      ["Prepared ticket", escapeMd(d.preparedTicket ?? d.ticketStatus)],
+      slippageRow(d),
+      confidenceRow(d),
+    ],
+    d,
+  );
+}
+
+/** Hyperliquid HIP-3 builder-dex card. Requires perpDexs + metaAndAssetCtxs. */
+export function renderHip3Card(data = {}) {
+  const d = data || {};
+  return build(
+    `ORACLE HIP-3 — ${escapeMd(d.market ?? d.coin ?? d.name)}`,
+    [
+      ["Venue", `Hyperliquid builder-dex ${escapeMd(d.dex)}`],
+      ["Market", escapeMd(d.market ?? d.coin)],
+      ["Mark", usd(d.markPx, { decimals: 6 })],
+      ["Oracle", usd(d.oraclePx, { decimals: 6 })],
+      ["Funding", pct(d.funding, { decimals: 6 })],
+      ["Open interest", usd(d.openInterestUsd)],
+      ["Depth", escapeMd(d.depth)],
+      ["Liquidation notes", escapeMd(d.liquidationNotes ?? d.riskNotes)],
+      ["Account context", escapeMd(d.accountContext)],
+      confidenceRow(d),
+    ],
+    d,
+  );
+}
+
+/** Hyperliquid HIP-4 outcome-market card. Public reads are keyless. */
+export function renderHip4Card(data = {}) {
+  const d = data || {};
+  return build(
+    `ORACLE HIP-4 — ${escapeMd(d.event ?? d.market ?? d.name)}`,
+    [
+      ["Venue", `Hyperliquid HIP-4 ${escapeMd(d.dex ?? "outcome")}`],
+      ["Event", escapeMd(d.event)],
+      ["Outcome", escapeMd(d.outcome)],
+      ["Market id", code(d.marketId ?? d.market)],
+      ["Bid", usd(d.bid, { decimals: 6 })],
+      ["Ask", usd(d.ask, { decimals: 6 })],
+      ["Depth", escapeMd(d.depth)],
+      ["Edge", pct(d.edge)],
+      ["Position", escapeMd(d.position)],
+      confidenceRow(d),
+    ],
+    d,
+  );
+}
+
+/** Polymarket card. Public reads keyless; orders stay prepared/user-signed. */
+export function renderPolymarketCard(data = {}) {
+  const d = data || {};
+  return build(
+    `ORACLE POLYMARKET — ${escapeMd(d.event ?? d.market ?? d.name)}`,
+    [
+      ["Venue", "Polymarket CLOB"],
+      ["Event", escapeMd(d.event)],
+      ["Market", escapeMd(d.market)],
+      ["Market id", code(d.marketId ?? d.conditionId ?? d.tokenId)],
+      ["Yes", usd(d.yesPrice, { decimals: 4 })],
+      ["No", usd(d.noPrice, { decimals: 4 })],
+      ["Best bid / ask", `${usd(d.bestBid, { decimals: 4 })} / ${usd(d.bestAsk, { decimals: 4 })}`],
+      ["Volume", usd(d.volumeUsd)],
+      ["Resolution risk", escapeMd(d.resolutionRisk)],
+      ["Order intent", escapeMd(d.orderIntent)],
+      confidenceRow(d),
+    ],
+    d,
+  );
+}
+
+const RENDERERS = Object.freeze({
+  token: renderTokenCard,
+  launch: renderLaunchCard,
+  hip3: renderHip3Card,
+  hip4: renderHip4Card,
+  polymarket: renderPolymarketCard,
+});
+
+/**
+ * Dispatch by surface kind.
+ * @param {"token"|"launch"|"hip3"|"hip4"|"polymarket"} kind
+ */
+export function renderCard(kind, data = {}) {
+  const fn = RENDERERS[String(kind)];
+  if (!fn) throw new Error(`unknown card kind: ${kind} (expected one of ${CARD_KINDS.join(", ")})`);
+  return fn(data);
+}
+
+/**
+ * Total soft-fail wrapper. An alert that cannot render is still an alert the
+ * user needs to see, so a malformed payload degrades to a minimal card rather
+ * than throwing and dropping the notification.
+ */
+export function safeRenderCard(kind, data = {}) {
+  try {
+    return renderCard(kind, data);
+  } catch (error) {
+    return [
+      `*ORACLE CARD — DEGRADED*`,
+      `Kind: ${escapeMd(kind)}`,
+      `Chain: ${UNKNOWN}`,
+      `Confidence: ${UNKNOWN}`,
+      `Render error: ${escapeMd(error?.message)}`,
+    ].join("\n");
+  }
+}

package/src/router/best-execution.mjs

@@ -99,6 +99,111 @@ export function normalizeRoute(raw) {
   };
 }
 
+/**
+ * Measure how badly a route's price decays with size.
+ *
+ * WHY THIS EXISTS: a quote against a drained pool is indistinguishable, in shape,
+ * from a quote against a deep one -- same fields, no error, just a smaller number.
+ * Verified on Robinhood 2026-08-02: a dead Uniswap V3 SQUEEZE pool holding 7.03
+ * USDG happily quoted a 205,374-token sell, and every layer downstream treated
+ * that as truth. `minOut` does NOT protect against this: it guards the price
+ * MOVING between quote and fill, so against a garbage quote it faithfully locks
+ * in the garbage.
+ *
+ * The probe: quote a small slice of the same trade, compare per-unit prices. Real
+ * slippage decays smoothly with size; a drained pool falls off a cliff.
+ *
+ * `probeFn(amountIn) -> amountOut | null`. Returns null when the comparison could
+ * not be made, which callers MUST treat as unproven rather than as a pass.
+ */
+export async function measurePriceImpact(probeFn, amountIn, { divisor = 1000n } = {}) {
+  const full = bn(amountIn);
+  if (full == null || full <= 0n) return null;
+
+  const probeAmt = full / divisor > 0n ? full / divisor : 1n;
+  if (probeAmt >= full) return null; // too small to compare against itself
+
+  let smallOut;
+  let fullOut;
+  try {
+    [smallOut, fullOut] = await Promise.all([probeFn(probeAmt), probeFn(full)]);
+  } catch {
+    return null;
+  }
+
+  const s = bn(smallOut);
+  const f = bn(fullOut);
+  if (s == null || f == null || s <= 0n) return null;
+
+  // Scale to compare per-unit prices without floating point until the last step.
+  const smallPx = Number(s) / Number(probeAmt);
+  const fullPx = Number(f) / Number(full);
+  if (!Number.isFinite(smallPx) || !Number.isFinite(fullPx) || smallPx <= 0) return null;
+
+  return {
+    impactPct: (1 - fullPx / smallPx) * 100,
+    probeAmountIn: probeAmt.toString(),
+    probeAmountOut: s.toString(),
+    fullAmountOut: f.toString(),
+  };
+}
+
+/**
+ * Reject routes whose price impact exceeds a ceiling.
+ *
+ * Applied AFTER ranking so the rejection is visible: a caller can see that the
+ * nominal winner was dropped and why, rather than silently receiving second place.
+ * A route with no impact measurement is NOT dropped here -- absence of evidence is
+ * surfaced through `unmeasured` so the caller decides, but it is never presented
+ * as a passing measurement.
+ */
+export function applyImpactCeiling(ranked, impacts, { maxImpactPct = 25 } = {}) {
+  const rejected = [];
+  const unmeasured = [];
+
+  const kept = (ranked.routes ?? []).filter((r) => {
+    const m = impacts?.[r.source];
+    if (!m) {
+      unmeasured.push(r.source);
+      return true;
+    }
+    if (m.impactPct > maxImpactPct) {
+      rejected.push({
+        source: r.source,
+        impactPct: Number(m.impactPct.toFixed(2)),
+        reason:
+          `price impact ${m.impactPct.toFixed(1)}% exceeds ${maxImpactPct}% ceiling -- ` +
+          "the venue cannot absorb this size near the quoted price",
+      });
+      return false;
+    }
+    return true;
+  });
+
+  const warnings = [...(ranked.warnings ?? [])];
+  if (rejected.length) {
+    warnings.push(
+      `dropped ${rejected.length} route(s) on price impact: ` +
+        rejected.map((r) => `${r.source} (${r.impactPct}%)`).join(", "),
+    );
+  }
+  if (unmeasured.length) {
+    warnings.push(
+      `price impact NOT measured for: ${unmeasured.join(", ")}. These are unproven ` +
+        "against thin liquidity, not proven safe.",
+    );
+  }
+
+  return {
+    ...ranked,
+    routes: kept,
+    best: kept[0] ?? null,
+    impactRejected: rejected,
+    impactUnmeasured: unmeasured,
+    warnings,
+  };
+}
+
 /**
  * Rank normalized routes by NET output.
  *

package/src/router/index.mjs

@@ -5,7 +5,9 @@
 // a one-source "best route" is not a comparison at all, so that case is labelled
 // rather than presented as if it beat something.
 
-import { gatherRoutes, rankRoutes, QUALITY } from "./best-execution.mjs";
+import {
+  gatherRoutes, rankRoutes, QUALITY, measurePriceImpact, applyImpactCeiling,
+} from "./best-execution.mjs";
 import { swapCandidates, bridgeCandidates, nativeUsd } from "./route-sources.mjs";
 import { llamaPrices } from "../data/providers/defillama.mjs";
 
@@ -93,6 +95,45 @@ export async function bestSwapRoute(p, opts = {}) {
     destDecimals: p.decimalsOut ?? dest.decimals,
   });
 
+  // Liquidity check. Ranking alone will happily crown a quote taken against a
+  // drained pool, because a thin venue returns a well-formed number rather than
+  // an error. Re-quote the winner at 1/1000th size and compare per-unit price:
+  // real slippage decays smoothly, a dead pool falls off a cliff.
+  //
+  // Opt out with `maxImpactPct: null` for callers that genuinely want the raw
+  // ranking (analytics, spread display) rather than an executable route.
+  const maxImpactPct = opts.maxImpactPct === undefined ? 25 : opts.maxImpactPct;
+  if (maxImpactPct != null && ranked.best) {
+    const winner = ranked.best.source;
+    const probe = async (amt) => {
+      const sub = swapCandidates({
+        ...p,
+        amountIn: amt.toString(),
+        nativePriceUsd: nativePricePromise,
+        decimalsOut: p.decimalsOut,
+        destDecimalsPromise: destPromise,
+        opts,
+      }).filter((c) => c.source === winner);
+      if (!sub.length) return null;
+      const got = await gatherRoutes(sub, { timeoutMs: opts.timeoutMs ?? 12_000 });
+      return got?.[0]?.amountOut ?? null;
+    };
+
+    const impact = await measurePriceImpact(probe, amountIn);
+    if (impact) {
+      const guarded = applyImpactCeiling(ranked, { [winner]: impact }, { maxImpactPct });
+      return {
+        kind: "swap",
+        chainId,
+        tokenIn,
+        tokenOut,
+        amountIn: String(amountIn),
+        ...guarded,
+        priceImpact: { [winner]: Number(impact.impactPct.toFixed(2)) },
+      };
+    }
+  }
+
   return {
     kind: "swap",
     chainId,

package/src/router/prepare-route.mjs

@@ -196,7 +196,18 @@ export async function prepareBestRoute(p, opts = {}) {
 
   const comparison = await bestSwapRoute(p, opts);
   if (!comparison.best) {
-    return { ok: false, reason: "no source returned a usable route", comparison };
+    // A liquidity rejection is a DIFFERENT failure from "nobody answered", and
+    // conflating them hides the reason a live venue was refused.
+    const blocked = comparison.impactRejected ?? [];
+    return {
+      ok: false,
+      reason: blocked.length
+        ? blocked[0].reason
+        : "no source returned a usable route",
+      priceImpactBlocked: blocked.length > 0,
+      impactRejected: blocked,
+      comparison,
+    };
   }
 
   // Honour an explicit override, but never silently: picking a non-winner is a
@@ -331,6 +342,11 @@ export async function prepareBestRoute(p, opts = {}) {
       grossOut: chosen.grossOut,
       gasUsd: chosen.gasUsd,
     },
+    // Carry the liquidity measurement through to the caller. Without this the
+    // guard runs but its result is invisible, so a consumer cannot tell a route
+    // that PASSED the ceiling from one that was never measured at all.
+    priceImpact: comparison.priceImpact ?? null,
+    impactUnmeasured: comparison.impactUnmeasured ?? [],
     ...prepared,
     unsigned: true,
     signedBy: "user-wallet",

package/protocols/templates/safe-erc20/README.md

@@ -1,9 +0,0 @@
-# safe-erc20
-
-```bash
-forge install foundry-rs/forge-std --no-git
-forge install OpenZeppelin/openzeppelin-contracts@v5.0.2 --no-git
-forge test
-```
-
-Libs are not vendored. Gate auto-installs when missing.