openbroker 1.9.6 → 1.12.0

package/scripts/guardian/rules.ts

@@ -0,0 +1,265 @@
+// Guardian rule engine — pure arithmetic over in-memory target + price state,
+// zero API cost per tick. Ported 1:1 from openbroker-copilot src/watcher/risk.ts
+// (same thresholds, hysteresis, and cooldowns); position lifecycle events are
+// emitted by the engine's snapshot diff, not here. Alerts are suppressed while
+// the price feed is stale.
+
+import type {
+  GuardianAlert,
+  GuardianPriceView,
+  GuardianTargetState,
+  GuardianThresholds,
+} from './types.js';
+import { DEFAULT_GUARDIAN_THRESHOLDS } from './types.js';
+
+const HOURS_PER_YEAR = 24 * 365;
+
+interface FiredState { firedAt: number; armed: boolean }
+
+export type GuardianAlertHandler = (alert: GuardianAlert) => void;
+
+export class GuardianRiskEngine {
+  private readonly thresholds: GuardianThresholds;
+  /** address:coin:threshold → state */
+  private liqState = new Map<string, FiredState>();
+  /** address → state */
+  private marginState = new Map<string, FiredState>();
+  /** address:coin → alerted */
+  private tpslState = new Set<string>();
+  /** address:oid → last fired */
+  private staleOrderState = new Map<string, number>();
+  /** address:coin → { since, firedAt } */
+  private fundingState = new Map<string, { since: number; firedAt: number | null }>();
+  private evaluations = 0;
+
+  constructor(
+    private readonly prices: GuardianPriceView,
+    private readonly onAlert: GuardianAlertHandler,
+    thresholds?: Partial<GuardianThresholds>,
+  ) {
+    this.thresholds = { ...DEFAULT_GUARDIAN_THRESHOLDS, ...thresholds };
+  }
+
+  getStats() {
+    return { evaluations: this.evaluations };
+  }
+
+  /** One evaluation pass over the given targets. */
+  tick(targets: Iterable<GuardianTargetState>, now = Date.now()): void {
+    const stale = this.prices.stale;
+
+    for (const target of targets) {
+      if (!target.seeded) continue;
+      this.updateLiqDistance(target);
+      if (stale) continue; // keep distances fresh, but never alert on stale prices
+      this.evaluations++;
+      this.evalLiqProximity(target, now);
+      this.evalMarginUsage(target, now);
+      this.evalNoTpsl(target, now);
+      this.evalStaleOrders(target, now);
+      this.evalFundingBleed(target, now);
+      this.gcClosedPositions(target);
+    }
+  }
+
+  /** Distance = (mark − liqPx) / mark, signed by side. */
+  private liqDistance(target: GuardianTargetState, coin: string): number | null {
+    const pos = target.positions.get(coin);
+    if (!pos || pos.liquidationPx === null || pos.liquidationPx <= 0) return null;
+    const entry = this.prices.get(coin);
+    const mark = entry?.mark ?? entry?.mid;
+    if (!mark || mark <= 0) return null;
+    return pos.side === 'long'
+      ? (mark - pos.liquidationPx) / mark
+      : (pos.liquidationPx - mark) / mark;
+  }
+
+  private updateLiqDistance(target: GuardianTargetState): void {
+    let min: number | null = null;
+    for (const coin of target.positions.keys()) {
+      const d = this.liqDistance(target, coin);
+      if (d !== null && (min === null || d < min)) min = d;
+    }
+    target.minLiqDist = min;
+  }
+
+  private evalLiqProximity(target: GuardianTargetState, now: number): void {
+    const t = this.thresholds;
+    for (const [coin, pos] of target.positions) {
+      const dist = this.liqDistance(target, coin);
+      if (dist === null) continue;
+
+      for (const { pct, severity } of t.liqThresholds) {
+        const key = `${target.address}:${coin}:${pct}`;
+        const state = this.liqState.get(key) ?? { firedAt: 0, armed: true };
+
+        if (!state.armed && dist >= pct * t.liqRearmFactor) {
+          state.armed = true; // hysteresis re-arm
+        }
+
+        if (state.armed && dist <= pct && now - state.firedAt >= t.liqCooldownMs) {
+          state.armed = false;
+          state.firedAt = now;
+          const entry = this.prices.get(coin);
+          const mark = entry?.mark ?? entry?.mid;
+          this.onAlert({
+            time: now,
+            address: target.address,
+            rule: 'liq_proximity',
+            coin,
+            severity,
+            dedupKey: String(pct),
+            message:
+              `Liquidation risk on ${coin}: mark $${mark} is ${(dist * 100).toFixed(2)}% from ` +
+              `liquidation price $${pos.liquidationPx} (${pos.side}, ${pos.leverage}x)`,
+            payload: { coin, distancePct: dist * 100, thresholdPct: pct * 100, mark, liquidationPx: pos.liquidationPx, side: pos.side },
+          });
+        }
+        this.liqState.set(key, state);
+      }
+    }
+  }
+
+  private evalMarginUsage(target: GuardianTargetState, now: number): void {
+    const t = this.thresholds;
+    const key = target.address;
+    const state = this.marginState.get(key) ?? { firedAt: 0, armed: true };
+
+    if (!state.armed && target.marginUsedPct < t.marginRearmPct) state.armed = true;
+
+    if (state.armed && target.marginUsedPct > t.marginThresholdPct && now - state.firedAt >= t.marginCooldownMs) {
+      state.armed = false;
+      state.firedAt = now;
+      this.onAlert({
+        time: now,
+        address: target.address,
+        rule: 'margin_usage',
+        coin: null,
+        severity: 'warning',
+        dedupKey: String(t.marginThresholdPct),
+        message: `Margin usage at ${target.marginUsedPct.toFixed(1)}% of equity ($${target.equity.toFixed(2)})`,
+        payload: { marginUsedPct: target.marginUsedPct, equity: target.equity, thresholdPct: t.marginThresholdPct },
+      });
+    }
+    this.marginState.set(key, state);
+  }
+
+  private evalNoTpsl(target: GuardianTargetState, now: number): void {
+    if (target.lastOrdersAt === null || target.orders === null) return; // no order data yet
+
+    for (const [coin, pos] of target.positions) {
+      const key = `${target.address}:${coin}`;
+      const openedAt = target.firstSeen.get(coin) ?? now;
+
+      const hasProtection = target.orders.some(
+        (o) => o.coin === coin && o.isTrigger && o.reduceOnly,
+      );
+      if (hasProtection) {
+        this.tpslState.delete(key);
+        continue;
+      }
+      if (this.tpslState.has(key)) continue;
+      if (now - openedAt < this.thresholds.noTpslAfterMs) continue;
+
+      this.tpslState.add(key);
+      this.onAlert({
+        time: now,
+        address: target.address,
+        rule: 'no_tpsl',
+        coin,
+        severity: 'info',
+        dedupKey: 'no_tpsl',
+        message: `${coin} ${pos.side} position has been open ${Math.round((now - openedAt) / 60_000)} min with no TP/SL orders`,
+        payload: { coin, side: pos.side, size: pos.szi, openMinutes: Math.round((now - openedAt) / 60_000) },
+      });
+    }
+  }
+
+  private evalStaleOrders(target: GuardianTargetState, now: number): void {
+    if (!target.orders) return;
+    const t = this.thresholds;
+
+    for (const order of target.orders) {
+      if (order.isTrigger) continue; // resting limit orders only
+      if (now - order.timestamp < t.staleOrderAgeMs) continue;
+
+      const entry = this.prices.get(order.coin);
+      const mid = entry?.mid ?? entry?.mark;
+      const limitPx = parseFloat(order.limitPx);
+      if (!mid || mid <= 0 || !Number.isFinite(limitPx)) continue;
+
+      const dist = Math.abs(limitPx - mid) / mid;
+      if (dist <= t.staleOrderDist) continue;
+
+      const key = `${target.address}:${order.oid}`;
+      const lastFired = this.staleOrderState.get(key) ?? 0;
+      if (now - lastFired < t.staleOrderCooldownMs) continue;
+
+      this.staleOrderState.set(key, now);
+      const ageH = Math.round((now - order.timestamp) / 3600_000);
+      this.onAlert({
+        time: now,
+        address: target.address,
+        rule: 'stale_order',
+        coin: order.coin,
+        severity: 'info',
+        dedupKey: String(order.oid),
+        message:
+          `Stale ${order.side === 'B' ? 'buy' : 'sell'} order on ${order.coin}: resting ${ageH}h, ` +
+          `limit $${order.limitPx} is ${(dist * 100).toFixed(1)}% from mid $${mid}`,
+        payload: { coin: order.coin, oid: order.oid, limitPx, mid, distancePct: dist * 100, ageHours: ageH },
+      });
+    }
+  }
+
+  private evalFundingBleed(target: GuardianTargetState, now: number): void {
+    const t = this.thresholds;
+    for (const [coin, pos] of target.positions) {
+      const funding = this.prices.get(coin)?.funding;
+      const key = `${target.address}:${coin}`;
+      if (funding === null || funding === undefined) continue;
+
+      // Longs pay when funding > 0; shorts pay when funding < 0. Funding is hourly.
+      const paying = pos.side === 'long' ? funding > 0 : funding < 0;
+      const aprPct = Math.abs(funding) * HOURS_PER_YEAR * 100;
+
+      if (!paying || aprPct <= t.fundingBleedAprPct) {
+        this.fundingState.delete(key);
+        continue;
+      }
+
+      const state = this.fundingState.get(key) ?? { since: now, firedAt: null };
+      this.fundingState.set(key, state);
+
+      const bleedingFor = now - state.since;
+      const cooledDown = state.firedAt === null || now - state.firedAt >= t.fundingCooldownMs;
+      if (bleedingFor >= t.fundingBleedForMs && cooledDown) {
+        state.firedAt = now;
+        this.onAlert({
+          time: now,
+          address: target.address,
+          rule: 'funding_bleed',
+          coin,
+          severity: 'warning',
+          dedupKey: 'funding_bleed',
+          message:
+            `Funding bleed on ${coin}: paying ~${aprPct.toFixed(1)}% APR against your ${pos.side} ` +
+            `for over ${Math.round(bleedingFor / 60_000)} min`,
+          payload: { coin, side: pos.side, fundingHourly: funding, aprPct, bleedingMinutes: Math.round(bleedingFor / 60_000) },
+        });
+      }
+    }
+  }
+
+  /** Drop per-position rule state when positions close (prevents unbounded growth). */
+  private gcClosedPositions(target: GuardianTargetState): void {
+    for (const key of this.tpslState) {
+      const [addr, coin] = [key.slice(0, 42), key.slice(43)];
+      if (addr === target.address && coin && !target.positions.has(coin)) this.tpslState.delete(key);
+    }
+    for (const key of this.fundingState.keys()) {
+      const [addr, coin] = [key.slice(0, 42), key.slice(43)];
+      if (addr === target.address && coin && !target.positions.has(coin)) this.fundingState.delete(key);
+    }
+  }
+}

package/scripts/guardian/telegram.ts

@@ -0,0 +1,147 @@
+// Telegram delivery for the guardian via raw fetch — no SDK. Unlike the hosted
+// guardian (shared bot + DB-backed link codes), the CLI uses the user's OWN bot:
+// TELEGRAM_BOT_TOKEN comes from @BotFather, and `openbroker guardian connect`
+// runs a one-shot getUpdates loop that captures the chat id from a
+// `/start <code>` deep link and persists TELEGRAM_CHAT_ID to the config file.
+//
+// Caveat: getUpdates conflicts with any other consumer of the same bot token
+// (including a set webhook) — use a dedicated bot for the CLI guardian.
+
+import fs from 'fs';
+import crypto from 'crypto';
+import { ensureConfigDir, getConfigPath } from '../core/config.js';
+import type { GuardianAlert } from './types.js';
+
+export interface TelegramSettings {
+  token: string | null;
+  chatId: string | null;
+}
+
+/** Read TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID (dotenv is loaded by core/config on import). */
+export function loadTelegramSettings(): TelegramSettings {
+  return {
+    token: process.env.TELEGRAM_BOT_TOKEN || null,
+    chatId: process.env.TELEGRAM_CHAT_ID || null,
+  };
+}
+
+function api(token: string, method: string): string {
+  return `https://api.telegram.org/bot${token}/${method}`;
+}
+
+async function call<T>(token: string, method: string, body: Record<string, unknown>, timeoutMs = 10_000): Promise<T> {
+  const res = await fetch(api(token, method), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const data = (await res.json().catch(() => null)) as { ok?: boolean; result?: T; description?: string } | null;
+  if (!res.ok || !data?.ok) {
+    throw new Error(`telegram ${method} failed: HTTP ${res.status}${data?.description ? ` — ${data.description}` : ''}`);
+  }
+  return data.result as T;
+}
+
+export async function sendTelegramMessage(token: string, chatId: string | number, text: string): Promise<void> {
+  await call(token, 'sendMessage', {
+    chat_id: chatId,
+    text,
+    parse_mode: 'HTML',
+    disable_web_page_preview: true,
+  });
+}
+
+export async function getTelegramBotInfo(token: string): Promise<{ id: number; username: string }> {
+  return call(token, 'getMe', {});
+}
+
+function shortAddr(address: string): string {
+  return `${address.slice(0, 6)}…${address.slice(-4)}`;
+}
+
+/** Same message shape as the hosted guardian's Telegram channel. */
+export function formatTelegramAlert(alert: GuardianAlert): string {
+  const tag = alert.severity === 'critical' ? 'CRITICAL' : alert.severity === 'warning' ? 'WARNING' : 'INFO';
+  const scope = alert.coin ? `${alert.coin} — ` : '';
+  return `<b>[${tag}]</b> ${scope}${shortAddr(alert.address)}\n${alert.message}`;
+}
+
+export function generateLinkCode(): string {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/**
+ * Long-poll getUpdates until someone sends `/start <code>` (or the bare code)
+ * to the bot, then confirm in-chat and return the chat id. Returns null on
+ * timeout. Drains the update backlog first so old messages can't match.
+ */
+export async function waitForTelegramLink(
+  token: string,
+  code: string,
+  timeoutMs = 10 * 60_000,
+): Promise<number | null> {
+  const deadline = Date.now() + timeoutMs;
+  let offset = -1; // -1 = skip backlog, start from the next incoming update
+
+  while (Date.now() < deadline) {
+    let updates: Array<{ update_id: number; message?: { chat: { id: number }; text?: string } }>;
+    try {
+      updates = await call(token, 'getUpdates', {
+        offset,
+        timeout: 25,
+        allowed_updates: ['message'],
+      }, 35_000);
+    } catch (err) {
+      if (Date.now() >= deadline) break;
+      await new Promise((r) => setTimeout(r, 3_000));
+      continue;
+    }
+
+    for (const update of updates ?? []) {
+      offset = update.update_id + 1;
+      const msg = update.message;
+      const text = msg?.text?.trim();
+      if (!msg || !text) continue;
+
+      const m = text.match(/^\/start(?:\s+(\S+))?$/);
+      const supplied = m ? m[1] : text;
+      if (supplied === code) {
+        try {
+          await sendTelegramMessage(
+            token,
+            msg.chat.id,
+            'Linked. This chat will receive OpenBroker guardian alerts (liquidation proximity, missing TP/SL, funding bleed and more).',
+          );
+        } catch { /* link still succeeded */ }
+        return msg.chat.id;
+      }
+      if (m && !supplied) {
+        try {
+          await sendTelegramMessage(token, msg.chat.id, 'OpenBroker guardian bot. Run <code>openbroker guardian connect</code> in the terminal and follow the link it prints.');
+        } catch { /* ignore */ }
+      }
+    }
+  }
+  return null;
+}
+
+/** Persist a key=value into the active openbroker config file (creates it if missing). */
+export function saveEnvVar(key: string, value: string): string {
+  ensureConfigDir();
+  const configPath = getConfigPath();
+  const line = `${key}=${value}`;
+  let content = '';
+  if (fs.existsSync(configPath)) {
+    content = fs.readFileSync(configPath, 'utf8');
+  }
+  const re = new RegExp(`^${key}=.*$`, 'm');
+  if (re.test(content)) {
+    content = content.replace(re, line);
+  } else {
+    content = content.length > 0 && !content.endsWith('\n') ? `${content}\n${line}\n` : `${content}${line}\n`;
+  }
+  fs.writeFileSync(configPath, content, { mode: 0o600 });
+  process.env[key] = value;
+  return configPath;
+}

package/scripts/guardian/types.ts

@@ -0,0 +1,160 @@
+// Guardian — read-only position risk monitoring for Hyperliquid addresses.
+// CLI/library port of the hosted copilot guardian (openbroker-copilot
+// src/watcher): same six rules, same default thresholds, same severity
+// contract, minus the multi-tenant DB. Alerts are delivered to the console,
+// Telegram, an OpenClaw agent hook, and/or an onAlert callback.
+
+import type { FrontendOpenOrder } from '../core/types.js';
+
+export type GuardianRuleId =
+  | 'liq_proximity'
+  | 'no_tpsl'
+  | 'stale_order'
+  | 'margin_usage'
+  | 'funding_bleed'
+  | 'position_lifecycle';
+
+export const GUARDIAN_RULE_IDS: GuardianRuleId[] = [
+  'liq_proximity',
+  'no_tpsl',
+  'stale_order',
+  'margin_usage',
+  'funding_bleed',
+  'position_lifecycle',
+];
+
+export const GUARDIAN_RULE_LABELS: Record<GuardianRuleId, string> = {
+  liq_proximity: 'Liquidation proximity',
+  no_tpsl: 'No TP/SL protection',
+  stale_order: 'Stale limit orders',
+  margin_usage: 'High margin usage',
+  funding_bleed: 'Funding bleed',
+  position_lifecycle: 'Position open / close / resize',
+};
+
+export type GuardianSeverity = 'info' | 'warning' | 'critical';
+
+export const GUARDIAN_SEVERITY_RANK: Record<GuardianSeverity, number> = {
+  info: 0,
+  warning: 1,
+  critical: 2,
+};
+
+export interface GuardianAlert {
+  time: number;
+  address: string;
+  rule: GuardianRuleId;
+  coin: string | null;
+  severity: GuardianSeverity;
+  /** Dedup discriminator within address+rule+coin (e.g. threshold pct). */
+  dedupKey: string;
+  message: string;
+  payload: Record<string, unknown>;
+}
+
+/** Per-run alert preferences — same contract as the hosted guardian's alert_prefs. */
+export interface GuardianPrefs {
+  /** Minimum severity to deliver. Default 'info'. */
+  minSeverity?: GuardianSeverity;
+  /** Per-rule opt-out, e.g. { position_lifecycle: false }. Default: all on. */
+  rules?: Partial<Record<GuardianRuleId, boolean>>;
+}
+
+/** Rule thresholds. Defaults mirror the hosted guardian. */
+export interface GuardianThresholds {
+  /** Liquidation-distance tiers (fraction of mark), tightest last. */
+  liqThresholds: Array<{ pct: number; severity: GuardianSeverity }>;
+  /** Re-arm only after moving this multiple past a fired threshold. */
+  liqRearmFactor: number;
+  liqCooldownMs: number;
+
+  marginThresholdPct: number;
+  marginRearmPct: number;
+  marginCooldownMs: number;
+
+  /** Alert when a position has no reduce-only trigger after this long. */
+  noTpslAfterMs: number;
+
+  staleOrderAgeMs: number;
+  /** Distance from mid (fraction) before a resting order counts as stale. */
+  staleOrderDist: number;
+  staleOrderCooldownMs: number;
+
+  /** Annualized funding APR (%) the position must be paying to count as bleed. */
+  fundingBleedAprPct: number;
+  /** How long the bleed must persist before alerting. */
+  fundingBleedForMs: number;
+  fundingCooldownMs: number;
+}
+
+export const DEFAULT_GUARDIAN_THRESHOLDS: GuardianThresholds = {
+  liqThresholds: [
+    { pct: 0.10, severity: 'warning' },
+    { pct: 0.05, severity: 'critical' },
+    { pct: 0.02, severity: 'critical' },
+  ],
+  liqRearmFactor: 1.5,
+  liqCooldownMs: 30 * 60_000,
+
+  marginThresholdPct: 80,
+  marginRearmPct: 72,
+  marginCooldownMs: 60 * 60_000,
+
+  noTpslAfterMs: 15 * 60_000,
+
+  staleOrderAgeMs: 12 * 3600_000,
+  staleOrderDist: 0.03,
+  staleOrderCooldownMs: 12 * 3600_000,
+
+  fundingBleedAprPct: 15,
+  fundingBleedForMs: 60 * 60_000,
+  fundingCooldownMs: 6 * 3600_000,
+};
+
+export interface GuardianPositionSnap {
+  coin: string;
+  szi: number;
+  side: 'long' | 'short';
+  entryPx: number | null;
+  positionValue: number;
+  unrealizedPnl: number;
+  liquidationPx: number | null;
+  leverage: number;
+  marginUsed: number;
+}
+
+/** In-memory state per watched address. */
+export interface GuardianTargetState {
+  address: string;
+
+  // clearinghouseState snapshot
+  positions: Map<string, GuardianPositionSnap>;
+  equity: number;
+  marginUsedPct: number;
+  seeded: boolean;
+  lastStateAt: number | null;
+
+  // frontendOpenOrders snapshot
+  orders: FrontendOpenOrder[] | null;
+  lastOrdersAt: number | null;
+
+  /** First time each open position (coin) was observed — for the no-TP/SL rule. */
+  firstSeen: Map<string, number>;
+  /** Min liquidation distance (fraction) across open positions; set by the risk engine. */
+  minLiqDist: number | null;
+}
+
+/** Live price entry maintained by the guardian's price feed. */
+export interface GuardianPriceEntry {
+  mid: number | null;
+  mark: number | null;
+  /** Hourly funding rate (decimal, e.g. 0.0000125). */
+  funding: number | null;
+  updatedAt: number;
+}
+
+/** Narrow price view the rule engine reads — tests can pass plain fakes. */
+export interface GuardianPriceView {
+  get(coin: string): GuardianPriceEntry | undefined;
+  readonly stale: boolean;
+}

package/scripts/lib.ts

@@ -47,7 +47,10 @@ export {
   generateCloid,
   orderToWire,
   checkBuilderFeeApproval,
+  MIN_ORDER_NOTIONAL_USD,
+  parseOrderStatus,
 } from './core/utils.js';
+export type { ParsedOrderStatus } from './core/utils.js';
 
 export type * from './core/types.js';
 
@@ -101,3 +104,36 @@ export {
 } from './auto/registry.js';
 
 export type * from './auto/types.js';
+
+// ── Guardian (read-only position risk monitoring) ───────────────────
+
+export { startGuardian, Guardian } from './guardian/engine.js';
+export type {
+  GuardianOptions,
+  GuardianHandle,
+  GuardianStats,
+  GuardianTelegramChannel,
+  GuardianAgentHookChannel,
+} from './guardian/engine.js';
+
+export { GuardianRiskEngine } from './guardian/rules.js';
+export type { GuardianAlertHandler } from './guardian/rules.js';
+
+export {
+  sendTelegramMessage,
+  getTelegramBotInfo,
+  formatTelegramAlert,
+  loadTelegramSettings,
+  waitForTelegramLink,
+  generateLinkCode,
+  saveEnvVar,
+} from './guardian/telegram.js';
+export type { TelegramSettings } from './guardian/telegram.js';
+
+export {
+  GUARDIAN_RULE_IDS,
+  GUARDIAN_RULE_LABELS,
+  GUARDIAN_SEVERITY_RANK,
+  DEFAULT_GUARDIAN_THRESHOLDS,
+} from './guardian/types.js';
+export type * from './guardian/types.js';