openbroker 1.9.2 → 1.9.4

package/scripts/auto/loader.ts

@@ -4,7 +4,14 @@ import { existsSync, readdirSync, mkdirSync } from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
-import type { AutomationFactory, AutomationConfig } from './types.js';
+import { resolveAutomationGuardrails } from './guardrails.js';
+import type {
+  AutomationFactory,
+  AutomationConfig,
+  AutomationGuardrailContext,
+  AutomationGuardrailsExport,
+  LoadedAutomation,
+} from './types.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -117,8 +124,27 @@ function resolveAutomationConfig(mod: Record<string, unknown>): AutomationConfig
   return null;
 }
 
-/** Load an automation module and validate the default export */
-export async function loadAutomation(scriptPath: string): Promise<AutomationFactory> {
+function resolveGuardrailsExport(mod: Record<string, unknown>): AutomationGuardrailsExport | null {
+  const candidates = [
+    mod.guardrails,
+    (mod.default as Record<string, unknown> | undefined)?.guardrails,
+    (mod["module.exports"] as Record<string, unknown> | undefined)?.guardrails,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && (typeof candidate === 'object' || typeof candidate === 'function')) {
+      return candidate as AutomationGuardrailsExport;
+    }
+  }
+
+  return null;
+}
+
+/** Load an automation module and validate its factory plus required guardrails export. */
+export async function loadAutomation(
+  scriptPath: string,
+  context: AutomationGuardrailContext = { config: {} },
+): Promise<LoadedAutomation> {
   const absolutePath = path.resolve(scriptPath);
 
   // Dynamic import — tsx handles TypeScript transpilation
@@ -132,7 +158,18 @@ export async function loadAutomation(scriptPath: string): Promise<AutomationFact
     );
   }
 
-  return factory as AutomationFactory;
+  const guardrailsExport = resolveGuardrailsExport(mod as Record<string, unknown>);
+  if (!guardrailsExport) {
+    throw new Error(
+      `Automation script must export "guardrails".\n` +
+      `Use { mode: "read-only" } for monitoring-only scripts or a validated trading policy.`,
+    );
+  }
+
+  return {
+    factory: factory as AutomationFactory,
+    guardrails: resolveAutomationGuardrails(guardrailsExport, context),
+  };
 }
 
 /** List available automation scripts in ~/.openbroker/automations/ */

package/scripts/auto/realtime.test.ts

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { HyperliquidClient } from '../core/client.js';
+import type { WebSocketManager, WsEventMap, WsEventType } from '../core/ws.js';
+import { AutomationRealtimeData } from './realtime.js';
+
+class FakeWebSocket {
+  connected = true;
+  private handlers = new Map<WsEventType, Set<(value: unknown) => void>>();
+
+  on(event: WsEventType, handler: (value: unknown) => void): void {
+    const set = this.handlers.get(event) ?? new Set();
+    set.add(handler);
+    this.handlers.set(event, set);
+  }
+
+  emit<E extends WsEventType>(event: E, value: WsEventMap[E]): void {
+    for (const handler of this.handlers.get(event) ?? []) handler(value);
+  }
+
+  async subscribeL2Book(coin: string): Promise<unknown> {
+    queueMicrotask(() => this.emit('l2Book', {
+      coin,
+      time: Date.now(),
+      levels: [
+        [{ px: '99', sz: '2', n: 1 }],
+        [{ px: '101', sz: '3', n: 1 }],
+      ],
+    }));
+    return {};
+  }
+}
+
+const ADDRESS = '0x0000000000000000000000000000000000000001';
+
+test('realtime cache serves subscribed market/account data and seeds books on demand', async () => {
+  const ws = new FakeWebSocket();
+  const mergedState = {
+    assetPositions: [],
+    marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+    crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+    crossMaintenanceMarginUsed: '0',
+  };
+  const client = {
+    userStateAllFromWs: () => mergedState,
+  } as unknown as HyperliquidClient;
+  const cache = new AutomationRealtimeData(ws as unknown as WebSocketManager, client, ADDRESS, true);
+
+  ws.emit('allMids', { mids: { HYPE: '100' } });
+  ws.emit('allDexsAssetCtxs', { ctxs: [['', [{ funding: '0.0001', openInterest: '1', dayNtlVlm: '2', premium: '0', oraclePx: '100', markPx: '100', prevDayPx: '99' }]]] });
+  ws.emit('spotState', { balances: [{ coin: 'USDC', token: 0, total: '100', hold: '0' }] });
+  ws.emit('openOrders', { user: ADDRESS, dex: '', orders: [] });
+  ws.emit('allDexsClearinghouseState', {
+    user: ADDRESS,
+    clearinghouseStates: [['', {
+      assetPositions: [],
+      marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+      crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+      crossMaintenanceMarginUsed: '0',
+      withdrawable: '100',
+    }]],
+  });
+
+  assert.equal(await cache.waitUntilReady(20), true);
+  assert.equal(cache.getAllMids()?.HYPE, '100');
+  assert.equal(cache.getMainAssetCtxs()?.[0]?.funding, '0.0001');
+  assert.equal(cache.getSpotBalances(ADDRESS)?.balances[0]?.entryNtl, '0');
+  assert.deepEqual(cache.getOpenOrders(ADDRESS), []);
+  assert.equal(cache.getUserState(ADDRESS)?.marginSummary.accountValue, '100');
+  assert.equal(cache.getUserStateAll(ADDRESS)?.marginSummary.accountValue, '100');
+
+  const book = await cache.getL2Book('HYPE');
+  assert.equal(book?.levels[0][0]?.px, '99');
+  assert.equal(book?.levels[1][0]?.px, '101');
+});
+
+test('realtime cache declines reads while disconnected so the client can fall back to REST', () => {
+  const ws = new FakeWebSocket();
+  const client = { userStateAllFromWs: () => null } as unknown as HyperliquidClient;
+  const cache = new AutomationRealtimeData(ws as unknown as WebSocketManager, client, ADDRESS, false);
+  ws.emit('allMids', { mids: { HYPE: '100' } });
+  ws.connected = false;
+  assert.equal(cache.getAllMids(), null);
+});

package/scripts/auto/realtime.ts

@@ -0,0 +1,194 @@
+import type { AssetCtx, ClearinghouseState, OpenOrder } from '../core/types.js';
+import type {
+  HyperliquidClient,
+  RealtimeBookSnapshot,
+  RealtimeDataProvider,
+} from '../core/client.js';
+import { WebSocketManager, type WsEventMap } from '../core/ws.js';
+
+interface Timed<T> {
+  value: T;
+  timestamp: number;
+}
+
+const MARKET_DATA_STALE_MS = 45_000;
+const BOOK_STALE_MS = 10_000;
+const BOOK_SEED_TIMEOUT_MS = 1_500;
+
+/**
+ * Runtime-owned WebSocket cache used transparently by HyperliquidClient read
+ * methods. While the socket is healthy, automation code calling getAllMids,
+ * getUserState(All), getSpotBalances, getMetaAndAssetCtxs, or getL2Book reads
+ * this cache. Missing/stale data returns null so the client falls back to REST.
+ */
+export class AutomationRealtimeData implements RealtimeDataProvider {
+  private mids: Timed<Record<string, string>> | null = null;
+  private assetCtxs: Timed<WsEventMap['allDexsAssetCtxs']['ctxs']> | null = null;
+  private clearinghouse: Timed<WsEventMap['allDexsClearinghouseState']['clearinghouseStates']> | null = null;
+  private spot: Timed<WsEventMap['spotState']> | null = null;
+  private books = new Map<string, Timed<RealtimeBookSnapshot>>();
+  private openOrders = new Map<string, Timed<OpenOrder[]>>();
+  private bookSubscriptions = new Set<string>();
+  private bookWaiters = new Map<string, Set<() => void>>();
+
+  constructor(
+    private readonly ws: WebSocketManager,
+    private readonly client: HyperliquidClient,
+    private readonly user: string,
+    private readonly unified: boolean | null,
+    private readonly expectedOrderDexes: string[] = [''],
+  ) {
+    ws.on('allMids', (data) => { this.mids = { value: data.mids, timestamp: Date.now() }; });
+    ws.on('allDexsAssetCtxs', (data) => { this.assetCtxs = { value: data.ctxs, timestamp: Date.now() }; });
+    ws.on('allDexsClearinghouseState', (data) => {
+      this.clearinghouse = { value: data.clearinghouseStates, timestamp: Date.now() };
+    });
+    ws.on('spotState', (data) => { this.spot = { value: data, timestamp: Date.now() }; });
+    ws.on('openOrders', (data) => {
+      if (this.sameUser(data.user)) this.openOrders.set(data.dex || '', { value: data.orders, timestamp: Date.now() });
+    });
+    ws.on('l2Book', (data) => {
+      this.books.set(data.coin, { value: data, timestamp: Date.now() });
+      const waiters = this.bookWaiters.get(data.coin);
+      if (waiters) {
+        for (const resolve of waiters) resolve();
+        waiters.clear();
+      }
+    });
+  }
+
+  get connected(): boolean {
+    return this.ws.connected;
+  }
+
+  getAllMids(): Record<string, string> | null {
+    return this.fresh(this.mids, MARKET_DATA_STALE_MS)?.value ?? null;
+  }
+
+  getMainAssetCtxs(): AssetCtx[] | null {
+    const groups = this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value;
+    if (!groups) return null;
+    const main = groups.find(([dex]) => !dex || dex === 'main') ?? groups[0];
+    return (main?.[1] as unknown as AssetCtx[] | undefined) ?? null;
+  }
+
+  getAllDexsAssetCtxs(): WsEventMap['allDexsAssetCtxs']['ctxs'] | null {
+    return this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value ?? null;
+  }
+
+  getUserState(user: string, dex?: string): ClearinghouseState | null {
+    if (!this.sameUser(user)) return null;
+    const groups = this.clearinghouse?.value;
+    if (!groups) return null;
+    const targetDex = dex ?? '';
+    const raw = groups.find(([name]) => (name || '') === targetDex)?.[1];
+    if (!raw) return null;
+    const withdrawable = raw.withdrawable;
+    return {
+      ...raw,
+      marginSummary: raw.marginSummary && withdrawable != null
+        ? { ...raw.marginSummary, withdrawable }
+        : raw.marginSummary,
+      crossMarginSummary: raw.crossMarginSummary && withdrawable != null
+        ? { ...raw.crossMarginSummary, withdrawable }
+        : raw.crossMarginSummary,
+    };
+  }
+
+  getUserStateAll(user: string): ClearinghouseState | null {
+    if (!this.sameUser(user) || !this.clearinghouse || this.unified === null) return null;
+    return this.client.userStateAllFromWs(
+      this.clearinghouse.value,
+      this.unified,
+      this.spot ? { balances: this.spot.value.balances } : undefined,
+    );
+  }
+
+  getSpotBalances(user: string): ReturnType<RealtimeDataProvider['getSpotBalances']> {
+    if (!this.sameUser(user) || !this.spot) return null;
+    return {
+      balances: this.spot.value.balances.map((balance) => ({
+        ...balance,
+        entryNtl: balance.entryNtl ?? '0',
+      })),
+    };
+  }
+
+  getOpenOrders(user: string): OpenOrder[] | null {
+    if (!this.sameUser(user) || !this.connected) return null;
+    const orders: OpenOrder[] = [];
+    for (const dex of new Set(['', ...this.expectedOrderDexes])) {
+      const entry = this.openOrders.get(dex);
+      if (!entry) return null;
+      orders.push(...entry.value);
+    }
+    return orders;
+  }
+
+  async getL2Book(coin: string): Promise<RealtimeBookSnapshot | null> {
+    const cached = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+    if (cached) return cached.value;
+    if (!this.connected) return null;
+
+    if (!this.bookSubscriptions.has(coin)) {
+      this.bookSubscriptions.add(coin);
+      try {
+        await this.ws.subscribeL2Book(coin);
+      } catch {
+        this.bookSubscriptions.delete(coin);
+        return null;
+      }
+    }
+
+    const seeded = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+    if (seeded) return seeded.value;
+
+    await new Promise<void>((resolve) => {
+      const waiters = this.bookWaiters.get(coin) ?? new Set<() => void>();
+      this.bookWaiters.set(coin, waiters);
+      const done = () => {
+        clearTimeout(timer);
+        waiters.delete(done);
+        resolve();
+      };
+      const timer = setTimeout(done, BOOK_SEED_TIMEOUT_MS);
+      waiters.add(done);
+    });
+
+    return this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS)?.value ?? null;
+  }
+
+  /** Wait briefly for initial subscription snapshots before the first strategy hook runs. */
+  async waitUntilReady(timeoutMs = 10_000): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.coreFeedsReady()) return true;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return this.coreFeedsReady();
+  }
+
+  readinessSummary(): { expectedOrderDexes: number; seededOrderDexes: number; missingOrderDexes: string[] } {
+    const expected = [...new Set(['', ...this.expectedOrderDexes])];
+    return {
+      expectedOrderDexes: expected.length,
+      seededOrderDexes: expected.filter((dex) => this.openOrders.has(dex)).length,
+      missingOrderDexes: expected.filter((dex) => !this.openOrders.has(dex)),
+    };
+  }
+
+  private coreFeedsReady(): boolean {
+    const ordersReady = [...new Set(['', ...this.expectedOrderDexes])]
+      .every((dex) => this.openOrders.has(dex));
+    return Boolean(this.mids && this.assetCtxs && this.clearinghouse && this.spot && ordersReady);
+  }
+
+  private sameUser(user: string): boolean {
+    return user.toLowerCase() === this.user.toLowerCase();
+  }
+
+  private fresh<T>(entry: Timed<T> | null, maxAgeMs: number): Timed<T> | null {
+    if (!this.connected || !entry || Date.now() - entry.timestamp > maxAgeMs) return null;
+    return entry;
+  }
+}