@perpscope/percolator-adapter 0.4.0

package/src/lib/read-only-rpc-fetcher.js

@@ -0,0 +1,232 @@
+import { normalizePercolatorSnapshot } from "./percolator-adapter.js";
+
+const PERP_SCOPE_MAGIC_HEX = "50455243";
+const MIN_SLAB_DATA_LENGTH = 128;
+const MUTATING_KEYS = new Set([
+  "instruction",
+  "instructions",
+  "order",
+  "orders",
+  "send",
+  "sendtransaction",
+  "sign",
+  "secretkey",
+  "signature",
+  "signer",
+  "signtransaction",
+  "transaction",
+  "transactions",
+  "wallet",
+  "walletadapter",
+  "walletpath"
+]);
+
+export function validateReadOnlyRpcRequest(request) {
+  const checked = validateReadOnlyRpcTarget(request);
+  const account = request.account || request.accountInfo || {};
+  const owner = stringOf(account.owner || account.programId);
+  const dataLength = numberOf(account.dataLength ?? account.dataLen ?? account.space);
+  const magic = stringOf(account.magic || account.discriminator || account.decoded?.header?.magic);
+
+  if (!owner) throw new Error("Read-only RPC request requires account owner.");
+  if (!dataLength) throw new Error("Read-only RPC request requires account data length.");
+  if (!magic) throw new Error("Read-only RPC request requires account magic.");
+  if (owner && owner !== checked.programId) {
+    throw new Error("RPC account owner does not match the requested program id.");
+  }
+  if (dataLength && dataLength < MIN_SLAB_DATA_LENGTH) {
+    throw new Error("RPC account data length is too small for a Percolator slab.");
+  }
+  if (magic && normalizeHex(magic) !== PERP_SCOPE_MAGIC_HEX) {
+    throw new Error("RPC account magic does not match a Percolator slab.");
+  }
+
+  return {
+    ...checked,
+    owner,
+    dataLength,
+    magic
+  };
+}
+
+function validateReadOnlyRpcTarget(request) {
+  if (!request || typeof request !== "object") {
+    throw new Error("Read-only RPC request must be an object.");
+  }
+
+  assertNoMutatingFields(request);
+
+  const slab = stringOf(request.slab || request.slabAddress || request.pubkey);
+  const programId = stringOf(request.programId || request.program || request.owner);
+
+  if (!slab) throw new Error("Read-only RPC request requires a slab address.");
+  if (!programId) throw new Error("Read-only RPC request requires a program id.");
+
+  return {
+    slab,
+    programId
+  };
+}
+
+export function buildReadOnlyRpcSnapshot(request) {
+  const checked = validateReadOnlyRpcRequest(request);
+  const account = request.account || request.accountInfo || {};
+  const decoded = account.decoded || {};
+  if (!Object.keys(decoded).length) {
+    throw new Error("Read-only RPC fixture requires decoded slab data.");
+  }
+
+  const market = {
+    ...(request.market || decoded.market || {}),
+    slab: checked.slab,
+    program: checked.programId
+  };
+  const commands = [
+    {
+      command: "slab:get",
+      output: {
+        slab: checked.slab,
+        dataLen: checked.dataLength,
+        header: decoded.header || {},
+        config: decoded.config || {},
+        market
+      }
+    }
+  ];
+
+  if (decoded.params) commands.push({ command: "slab:params", output: decoded.params });
+  if (decoded.engine) commands.push({ command: "slab:engine", output: decoded.engine });
+  if (decoded.bestPrice) commands.push({ command: "best-price", output: decoded.bestPrice });
+  if (decoded.accounts) commands.push({ command: "slab:accounts", output: decoded.accounts });
+  if (decoded.bitmap) commands.push({ command: "slab:bitmap", output: decoded.bitmap });
+
+  return normalizePercolatorSnapshot({
+    label: request.label || "Read-only RPC slab fixture",
+    cluster: request.cluster || "rpc fixture",
+    currentSlot: request.currentSlot || decoded.currentSlot,
+    market,
+    account: decoded.accountUsd,
+    commands
+  });
+}
+
+export function summarizeReadOnlyRpcDeployment(request) {
+  const checked = validateReadOnlyRpcRequest(request);
+  const account = request.account || request.accountInfo || {};
+  const decoded = account.decoded || {};
+  const expectations = request.expectations || {};
+  const requiredDecodedSections = Array.isArray(expectations.requiredDecodedSections)
+    ? expectations.requiredDecodedSections
+    : ["header", "config"];
+  const missingSections = requiredDecodedSections.filter((section) => !decoded[section]);
+  if (missingSections.length) {
+    throw new Error(`Read-only deployment fixture is missing decoded sections: ${missingSections.join(", ")}`);
+  }
+
+  const expectedOwner = stringOf(expectations.owner);
+  const expectedDataLength = numberOf(expectations.dataLength);
+  const expectedMagic = stringOf(expectations.magic);
+  if (expectedOwner && expectedOwner !== checked.owner) {
+    throw new Error("Read-only deployment owner expectation does not match account owner.");
+  }
+  if (expectedDataLength && expectedDataLength !== checked.dataLength) {
+    throw new Error("Read-only deployment data length expectation does not match account data length.");
+  }
+  if (expectedMagic && normalizeHex(expectedMagic) !== normalizeHex(checked.magic)) {
+    throw new Error("Read-only deployment magic expectation does not match account magic.");
+  }
+
+  const maxOracleAgeSec = firstNumber(
+    maybeNumber(expectations.maxOracleAgeSec),
+    maybeNumber(decoded.config?.maxStalenessSecs),
+    maybeNumber(decoded.config?.maxOracleAgeSec)
+  );
+  const oracleAgeSec = firstNumber(
+    maybeNumber(decoded.bestPrice?.oracle?.ageSecs),
+    maybeNumber(decoded.bestPrice?.oracle?.publishAgeSec),
+    maybeNumber(decoded.bestPrice?.oracle?.ageSec)
+  );
+  if (maxOracleAgeSec && oracleAgeSec > maxOracleAgeSec) {
+    throw new Error("Read-only deployment oracle freshness expectation failed.");
+  }
+
+  return {
+    label: request.label || "Read-only RPC slab fixture",
+    cluster: request.cluster || "rpc fixture",
+    slab: checked.slab,
+    programId: checked.programId,
+    owner: checked.owner,
+    dataLength: checked.dataLength,
+    magic: checked.magic,
+    market: request.market?.symbol || request.market?.name || "PERP",
+    method: request.rpcRead?.method || "getAccountInfo",
+    fixture: request.fixture || "",
+    maxOracleAgeSec,
+    oracleAgeSec,
+    freshness: maxOracleAgeSec
+      ? Math.max(0, Math.round((1 - oracleAgeSec / maxOracleAgeSec) * 100))
+      : 0
+  };
+}
+
+export async function fetchReadOnlyRpcSnapshot(request, client) {
+  if (!client || typeof client.getAccountInfo !== "function") {
+    throw new Error("Read-only RPC fetcher requires a client with getAccountInfo().");
+  }
+  const checked = validateReadOnlyRpcTarget(request);
+  const accountInfo = await client.getAccountInfo(checked.slab);
+  return buildReadOnlyRpcSnapshot({
+    ...request,
+    slab: checked.slab,
+    account: {
+      ...(request.account || {}),
+      ...accountInfo
+    }
+  });
+}
+
+function assertNoMutatingFields(value, path = "request") {
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    const normalized = normalizeKey(key);
+    if (isMutatingKey(normalized)) {
+      throw new Error(`Refusing mutating field in read-only RPC request: ${path}.${key}`);
+    }
+    if (child && typeof child === "object") assertNoMutatingFields(child, `${path}.${key}`);
+  }
+}
+
+function isMutatingKey(key) {
+  if (MUTATING_KEYS.has(key)) return true;
+  return key.endsWith("secret") || key.endsWith("privatekey") || key.endsWith("keypair");
+}
+
+function stringOf(value) {
+  if (value === undefined || value === null) return "";
+  return String(value);
+}
+
+function numberOf(value) {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : 0;
+}
+
+function maybeNumber(value) {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : undefined;
+}
+
+function firstNumber(...values) {
+  for (const value of values) {
+    if (Number.isFinite(value)) return value;
+  }
+  return 0;
+}
+
+function normalizeHex(value) {
+  return String(value).toLowerCase().replace(/^0x/, "");
+}
+
+function normalizeKey(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/g, "");
+}

package/src/lib/watchtower-signals.js

@@ -0,0 +1,124 @@
+export function buildWatchtowerSignals(market, stress) {
+  const receipts = market.execution.receipts || [];
+  const avgMarkout5m = receipts.length ? mean(receipts.map((receipt) => receipt.markout5mBps)) : market.execution.markout5mBps;
+  const avgLatency = receipts.length ? mean(receipts.map((receipt) => receipt.routeLatencyMs)) : market.execution.routeLatencyMs;
+  const avgFee = receipts.length ? mean(receipts.map((receipt) => receipt.priorityFeeMicrolamports)) : market.execution.priorityFeeMicrolamports;
+  const freshnessScore = Math.min(market.price.freshnessScore, market.crank.freshnessScore);
+  const impact10kBps = Number(market.execution.impact10kBps) || 0;
+  const impact50kBps = Number(market.execution.impact50kBps) || 0;
+  const hasImpactRatio = impact10kBps > 0 && impact50kBps > 0;
+  const hasImpactSignal = Math.abs(impact10kBps) > 0 || Math.abs(impact50kBps) > 0;
+  const impactRatio = hasImpactRatio ? impact50kBps / impact10kBps : 0;
+  const impactScore = hasImpactRatio
+    ? clamp(100 - impactRatio * 16, 0, 100)
+    : hasImpactSignal
+      ? clamp(100 - Math.abs(impact50kBps) * 1.25, 0, 100)
+      : 50;
+  const impactTone = hasImpactRatio
+    ? impactRatio >= 4.2 ? "danger" : impactRatio >= 2.7 ? "warning" : "good"
+    : !hasImpactSignal ? "warning" : Math.abs(impact50kBps) >= 55 ? "danger" : Math.abs(impact50kBps) >= 25 ? "warning" : "good";
+  const carryDaily = Math.abs(market.funding.dailyUsd);
+  const runwayScore = clamp(market.account.liquidationDistancePct * 6, 0, 100);
+  const projectedBuffer = stress?.projectedBufferUsd ?? market.account.marginBufferUsd;
+
+  return [
+    {
+      id: "runway",
+      label: "runway",
+      value: pct(market.account.liquidationDistancePct),
+      detail: `${money(market.account.marginBufferUsd, 0)} buffer`,
+      subvalue: `${money(projectedBuffer, 0)} stress`,
+      score: runwayScore,
+      tone: scoreTone(runwayScore)
+    },
+    {
+      id: "freshness",
+      label: "freshness",
+      value: `${Math.round(freshnessScore)}%`,
+      detail: `${fmtInt(market.crank.ageSlots)} slots`,
+      subvalue: `${market.price.publishAgeSec.toFixed(1)}s oracle`,
+      score: freshnessScore,
+      tone: scoreTone(freshnessScore)
+    },
+    {
+      id: "execution",
+      label: "execution",
+      value: signedBps(avgMarkout5m),
+      detail: `${Math.round(avgLatency)} ms route`,
+      subvalue: feeLabel(avgFee),
+      score: clamp(100 - Math.max(Math.abs(Math.min(avgMarkout5m, 0)) * 1.8, Math.max(avgLatency - 150, 0) / 5), 0, 100),
+      tone: avgMarkout5m >= 0 && avgLatency <= 220 ? "good" : avgMarkout5m < -18 || avgLatency > 420 ? "danger" : "warning"
+    },
+    {
+      id: "impact",
+      label: "impact curve",
+      value: hasImpactRatio ? `${impactRatio.toFixed(1)}x` : hasImpactSignal ? `${impact50kBps.toFixed(1)} bps` : "n/a",
+      detail: `${impact50kBps.toFixed(1)} bps at $50k`,
+      subvalue: `${impact10kBps.toFixed(1)} bps at $10k`,
+      score: impactScore,
+      tone: impactTone
+    },
+    {
+      id: "carry",
+      label: "carry",
+      value: `${signedBps(market.funding.bpsPerHour)} / hr`,
+      detail: `${money(carryDaily, 0)} daily`,
+      subvalue: `${signedBps(market.marketStructure.oiSkewPct)} OI skew`,
+      score: clamp(100 - Math.abs(market.funding.bpsPerHour) * 14 - Math.abs(market.marketStructure.oiSkewPct) * 0.55, 0, 100),
+      tone: Math.abs(market.funding.bpsPerHour) >= 3.2 || Math.abs(market.marketStructure.oiSkewPct) >= 48 ? "danger" : Math.abs(market.funding.bpsPerHour) >= 1.4 || Math.abs(market.marketStructure.oiSkewPct) >= 24 ? "warning" : "good"
+    },
+    {
+      id: "solvency",
+      label: "solvency",
+      value: `${Math.round(market.solvency.coveragePct)}%`,
+      detail: `${money(market.solvency.insuranceUsd, 0)} insurance`,
+      subvalue: `${money(market.solvency.socialLossUsd, 0)} social loss`,
+      score: clamp(Math.min(market.solvency.coveragePct, 120) * 0.82, 0, 100),
+      tone: market.solvency.coveragePct < 28 || market.solvency.socialLossUsd > 0 ? "danger" : market.solvency.coveragePct < 55 ? "warning" : "good"
+    }
+  ];
+}
+
+function scoreTone(score) {
+  if (score >= 68) return "good";
+  if (score >= 42) return "warning";
+  return "danger";
+}
+
+function money(value, digits = 2) {
+  const amount = Number(value);
+  const abs = Math.abs(amount);
+  const sign = amount < 0 ? "-" : "";
+  if (abs >= 1000000) return `${sign}$${(abs / 1000000).toFixed(2)}m`;
+  if (abs >= 10000) return `${sign}$${Math.round(abs).toLocaleString("en-US")}`;
+  return `${sign}$${abs.toLocaleString("en-US", { minimumFractionDigits: digits, maximumFractionDigits: digits })}`;
+}
+
+function pct(value) {
+  return `${Number(value).toFixed(1)}%`;
+}
+
+function signedBps(value) {
+  const next = Number(value);
+  return `${next >= 0 ? "+" : ""}${next.toFixed(1)} bps`;
+}
+
+function feeLabel(value) {
+  const amount = Number(value) || 0;
+  if (Math.abs(amount) >= 1000) return `${(amount / 1000).toFixed(amount >= 10000 ? 0 : 1)}k uLamports`;
+  return `${Math.round(amount)} uLamports`;
+}
+
+function fmtInt(value) {
+  return Number(value).toLocaleString("en-US");
+}
+
+function mean(values) {
+  const numbers = values.map(Number).filter(Number.isFinite);
+  if (!numbers.length) return 0;
+  return numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}