openbroker 1.9.6 → 1.12.0

package/dist/guardian/engine.js

@@ -0,0 +1,526 @@
+// Guardian engine: REST poll (clearinghouseState + frontendOpenOrders) + price
+// feed + rule engine + alert dispatch. Read-only — never places orders. This is
+// the CLI/library counterpart of the hosted guardian's watcher: same rules and
+// cadences, scaled down from a multi-tenant fleet to the handful of addresses a
+// CLI user or agent watches, so no weight budget or tier queue is needed.
+import { getClient } from '../core/client.js';
+import { getWebSocket, resetWebSocket } from '../core/ws.js';
+import { GuardianRiskEngine } from './rules.js';
+import { formatTelegramAlert, loadTelegramSettings, sendTelegramMessage, } from './telegram.js';
+import { GUARDIAN_SEVERITY_RANK } from './types.js';
+/** Price entries older than this are stale — alerts are suppressed. */
+const PRICE_STALE_MS = 120_000;
+/** Poll clearinghouseState this often when a position is within 10% of liquidation. */
+const HOT_STATE_INTERVAL_MS = 15_000;
+const HOT_LIQ_DIST = 0.10;
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+function num(v) {
+    if (v === null || v === undefined)
+        return null;
+    const n = parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+}
+function parsePositions(state) {
+    const out = new Map();
+    for (const ap of state.assetPositions ?? []) {
+        const p = ap.position;
+        const szi = num(p.szi);
+        if (szi === null || szi === 0)
+            continue;
+        out.set(p.coin, {
+            coin: p.coin,
+            szi,
+            side: szi > 0 ? 'long' : 'short',
+            entryPx: num(p.entryPx),
+            positionValue: num(p.positionValue) ?? 0,
+            unrealizedPnl: num(p.unrealizedPnl) ?? 0,
+            liquidationPx: num(p.liquidationPx ?? null),
+            leverage: p.leverage?.value ?? 0,
+            marginUsed: num(p.marginUsed) ?? 0,
+        });
+    }
+    return out;
+}
+export class Guardian {
+    client;
+    targets = new Map();
+    prices = new Map();
+    risk;
+    prefs;
+    telegram;
+    agentHook;
+    opts;
+    timers = [];
+    wsSubs = [];
+    wsUsed = false;
+    stopped = false;
+    polling = false;
+    statePolls = 0;
+    orderPolls = 0;
+    alertsFired = 0;
+    alertsDelivered = 0;
+    deliveryErrors = 0;
+    lastPricesAt = null;
+    constructor(addresses, opts = {}) {
+        this.opts = opts;
+        this.client = opts.client ?? getClient();
+        this.prefs = opts.prefs ?? {};
+        for (const address of addresses) {
+            this.targets.set(address, {
+                address,
+                positions: new Map(),
+                equity: 0,
+                marginUsedPct: 0,
+                seeded: false,
+                lastStateAt: null,
+                orders: null,
+                lastOrdersAt: null,
+                firstSeen: new Map(),
+                minLiqDist: null,
+            });
+        }
+        const self = this;
+        const priceView = {
+            get: (coin) => self.prices.get(coin),
+            // Stale when nothing has refreshed within the window (or nothing seeded yet).
+            get stale() {
+                return self.lastPricesAt === null || Date.now() - self.lastPricesAt > PRICE_STALE_MS;
+            },
+        };
+        this.risk = new GuardianRiskEngine(priceView, (alert) => void this.dispatch(alert), opts.thresholds);
+        if (opts.telegram === false) {
+            this.telegram = null;
+        }
+        else if (opts.telegram) {
+            this.telegram = opts.telegram;
+        }
+        else {
+            const settings = loadTelegramSettings();
+            this.telegram = settings.token && settings.chatId
+                ? { token: settings.token, chatId: settings.chatId }
+                : null;
+        }
+        if (opts.agentHook === false) {
+            this.agentHook = null;
+        }
+        else if (opts.agentHook) {
+            this.agentHook = opts.agentHook;
+        }
+        else {
+            const hooksToken = process.env.OPENCLAW_HOOKS_TOKEN;
+            const portStr = process.env.OPENCLAW_GATEWAY_PORT;
+            const gatewayPort = portStr ? parseInt(portStr, 10) : undefined;
+            this.agentHook = hooksToken
+                ? { hooksToken, gatewayPort: gatewayPort && !isNaN(gatewayPort) ? gatewayPort : undefined }
+                : null;
+        }
+    }
+    channels() {
+        const out = ['console'];
+        if (this.telegram)
+            out.push('telegram');
+        if (this.agentHook)
+            out.push('agent-hook');
+        if (this.opts.onAlert)
+            out.push('callback');
+        return out;
+    }
+    async start() {
+        const pollMs = this.opts.pollIntervalMs ?? 30_000;
+        const ordersMs = this.opts.ordersIntervalMs ?? 120_000;
+        const pricesMs = this.opts.pricesIntervalMs ?? 30_000;
+        const hip3Ms = this.opts.hip3PricesIntervalMs ?? 300_000;
+        const riskMs = this.opts.riskIntervalMs ?? 5_000;
+        // Seed everything once before the intervals so the first risk tick has data.
+        await this.refreshPrices();
+        await this.refreshHip3Prices();
+        for (const target of this.targets.values()) {
+            await this.pollState(target);
+            await this.pollOrders(target);
+        }
+        this.timers.push(setInterval(() => void this.pollAllStates(pollMs), Math.min(pollMs, HOT_STATE_INTERVAL_MS)));
+        this.timers.push(setInterval(() => void this.pollAllOrders(), ordersMs));
+        this.timers.push(setInterval(() => void this.refreshPrices(), pricesMs));
+        this.timers.push(setInterval(() => void this.refreshHip3Prices(), hip3Ms));
+        this.timers.push(setInterval(() => this.risk.tick(this.targets.values()), riskMs));
+        if ((this.opts.useWebSocket ?? true) && this.targets.size === 1) {
+            await this.startWebSocket();
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        for (const timer of this.timers)
+            clearInterval(timer);
+        this.timers = [];
+        for (const sub of this.wsSubs) {
+            try {
+                await sub.unsubscribe();
+            }
+            catch { /* ignore */ }
+        }
+        this.wsSubs = [];
+        if (this.wsUsed) {
+            try {
+                await resetWebSocket();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    getStats() {
+        return {
+            addresses: [...this.targets.keys()],
+            statePolls: this.statePolls,
+            orderPolls: this.orderPolls,
+            alertsFired: this.alertsFired,
+            alertsDelivered: this.alertsDelivered,
+            deliveryErrors: this.deliveryErrors,
+            evaluations: this.risk.getStats().evaluations,
+            pricesAt: this.lastPricesAt,
+            channels: this.channels(),
+        };
+    }
+    getTargets() {
+        return [...this.targets.values()];
+    }
+    // ── WebSocket fast lane (single-address runs) ─────────────────────
+    async startWebSocket() {
+        const address = [...this.targets.keys()][0];
+        try {
+            const ws = getWebSocket();
+            this.wsUsed = true;
+            if (!ws.connected)
+                await ws.connect();
+            ws.on('userEvent', (data) => {
+                if (this.stopped)
+                    return;
+                if ('liquidation' in data && data.liquidation) {
+                    const liq = data.liquidation;
+                    void this.dispatch({
+                        time: Date.now(),
+                        address,
+                        rule: 'liq_proximity',
+                        coin: null,
+                        severity: 'critical',
+                        dedupKey: `liquidated:${liq.lid ?? Date.now()}`,
+                        message: `LIQUIDATED: account was liquidated (account value $${liq.liquidated_account_value ?? '?'})`,
+                        payload: { kind: 'liquidation', ...liq },
+                    });
+                    void this.pollState(this.targets.get(address));
+                }
+                else if ('fills' in data && Array.isArray(data.fills)) {
+                    for (const fill of data.fills) {
+                        const liq = fill.liquidation;
+                        if (liq) {
+                            void this.dispatch({
+                                time: Date.now(),
+                                address,
+                                rule: 'liq_proximity',
+                                coin: fill.coin ?? null,
+                                severity: 'critical',
+                                dedupKey: `liq-fill:${fill.tid ?? Date.now()}`,
+                                message: `LIQUIDATED: forced ${fill.dir ?? 'close'} on ${fill.coin ?? '?'} at mark $${liq.markPx ?? '?'}`,
+                                payload: { kind: 'liquidation_fill', fill },
+                            });
+                        }
+                    }
+                    // Any fill: re-poll state now so lifecycle diffs land fast.
+                    void this.pollState(this.targets.get(address));
+                }
+            });
+            ws.on('error', () => { });
+            this.wsSubs.push(await ws.subscribeUserEvents(address));
+            this.log(`WS userEvents subscribed for ${address}`);
+        }
+        catch (err) {
+            this.log(`WS unavailable, continuing REST-only: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── Price feed (REST) ─────────────────────────────────────────────
+    hasHip3Positions() {
+        for (const target of this.targets.values()) {
+            for (const coin of target.positions.keys()) {
+                if (coin.includes(':'))
+                    return true;
+            }
+        }
+        return false;
+    }
+    async refreshPrices() {
+        const now = Date.now();
+        try {
+            const [mids, meta] = await Promise.all([
+                this.client.getAllMids(),
+                this.client.getMetaAndAssetCtxs(),
+            ]);
+            for (const [coin, mid] of Object.entries(mids)) {
+                const entry = this.prices.get(coin) ?? { mid: null, mark: null, funding: null, updatedAt: 0 };
+                entry.mid = num(mid);
+                entry.updatedAt = now;
+                this.prices.set(coin, entry);
+            }
+            for (let i = 0; i < meta.meta.universe.length; i++) {
+                const coin = meta.meta.universe[i].name;
+                const ctx = meta.assetCtxs[i];
+                if (!ctx)
+                    continue;
+                const entry = this.prices.get(coin) ?? { mid: null, mark: null, funding: null, updatedAt: 0 };
+                entry.mark = num(ctx.markPx);
+                entry.funding = num(ctx.funding);
+                entry.updatedAt = now;
+                this.prices.set(coin, entry);
+            }
+            this.lastPricesAt = now;
+        }
+        catch (err) {
+            this.log(`price refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** HIP-3 mark/funding — heavier (per-dex metaAndAssetCtxs), only while HIP-3 positions exist. */
+    async refreshHip3Prices() {
+        if (!this.hasHip3Positions())
+            return;
+        const now = Date.now();
+        try {
+            const allPerps = await this.client.getAllPerpMetas();
+            for (const dexData of allPerps) {
+                if (!dexData.dexName)
+                    continue; // main dex handled by refreshPrices
+                for (let i = 0; i < dexData.meta.universe.length; i++) {
+                    const coin = dexData.meta.universe[i].name; // already dex-prefixed, e.g. "hyna:XMR"
+                    const ctx = dexData.assetCtxs[i];
+                    if (!ctx)
+                        continue;
+                    const entry = this.prices.get(coin) ?? { mid: null, mark: null, funding: null, updatedAt: 0 };
+                    entry.mark = num(ctx.markPx);
+                    entry.funding = num(ctx.funding);
+                    if (entry.mid === null)
+                        entry.mid = num(ctx.midPx ?? ctx.markPx);
+                    entry.updatedAt = now;
+                    this.prices.set(coin, entry);
+                }
+            }
+        }
+        catch (err) {
+            this.log(`HIP-3 price refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── State + orders polling ────────────────────────────────────────
+    async pollAllStates(baseIntervalMs) {
+        if (this.polling)
+            return; // don't overlap slow cycles
+        this.polling = true;
+        try {
+            const now = Date.now();
+            for (const target of this.targets.values()) {
+                // Hot cadence near liquidation, base cadence otherwise. The interval
+                // fires at min(base, 15s); skip targets whose cadence isn't due.
+                const nearLiq = target.minLiqDist !== null && target.minLiqDist < HOT_LIQ_DIST;
+                const interval = nearLiq ? Math.min(baseIntervalMs, HOT_STATE_INTERVAL_MS) : baseIntervalMs;
+                if (target.lastStateAt !== null && now - target.lastStateAt < interval - 500)
+                    continue;
+                await this.pollState(target);
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    async pollAllOrders() {
+        for (const target of this.targets.values()) {
+            await this.pollOrders(target);
+        }
+    }
+    async pollState(target) {
+        const now = Date.now();
+        try {
+            const state = await this.client.getUserStateAll(target.address);
+            const positions = parsePositions(state);
+            const events = target.seeded ? this.diff(target, positions) : [];
+            // Maintain firstSeen for the no-TP/SL rule.
+            for (const coin of positions.keys()) {
+                if (!target.firstSeen.has(coin))
+                    target.firstSeen.set(coin, now);
+            }
+            for (const coin of [...target.firstSeen.keys()]) {
+                if (!positions.has(coin))
+                    target.firstSeen.delete(coin);
+            }
+            const equity = num(state.marginSummary?.accountValue) ?? 0;
+            const marginUsed = num(state.marginSummary?.totalMarginUsed) ?? 0;
+            target.positions = positions;
+            target.equity = equity;
+            target.marginUsedPct = equity > 0 ? (marginUsed / equity) * 100 : 0;
+            target.seeded = true;
+            target.lastStateAt = now;
+            this.statePolls++;
+            for (const event of events)
+                void this.dispatch(event);
+        }
+        catch (err) {
+            this.log(`state poll failed for ${target.address}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async pollOrders(target) {
+        try {
+            const orders = await this.client.getFrontendOpenOrders(target.address);
+            // HIP-3 positions rest their TP/SL on their own dex — include those books
+            // so the no-TP/SL rule doesn't false-positive.
+            const dexes = new Set();
+            for (const coin of target.positions.keys()) {
+                const idx = coin.indexOf(':');
+                if (idx > 0)
+                    dexes.add(coin.slice(0, idx));
+            }
+            for (const dex of dexes) {
+                try {
+                    orders.push(...await this.client.getFrontendOpenOrders(target.address, dex));
+                }
+                catch (err) {
+                    this.log(`orders poll failed for dex ${dex}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            target.orders = orders;
+            target.lastOrdersAt = Date.now();
+            this.orderPolls++;
+        }
+        catch (err) {
+            this.log(`orders poll failed for ${target.address}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Snapshot diff → position lifecycle alerts (mirrors the hosted poller). */
+    diff(target, current) {
+        const now = Date.now();
+        const events = [];
+        const prev = target.positions;
+        for (const [coin, pos] of current) {
+            if (!prev.has(coin)) {
+                events.push({
+                    time: now,
+                    address: target.address,
+                    rule: 'position_lifecycle',
+                    coin,
+                    severity: 'info',
+                    dedupKey: `opened:${now}`,
+                    message: `Position opened: ${pos.side} ${Math.abs(pos.szi)} ${coin} at $${pos.entryPx ?? '?'}`,
+                    payload: { kind: 'opened', coin, side: pos.side, size: pos.szi, entryPx: pos.entryPx },
+                });
+            }
+        }
+        for (const [coin, pos] of prev) {
+            if (!current.has(coin)) {
+                events.push({
+                    time: now,
+                    address: target.address,
+                    rule: 'position_lifecycle',
+                    coin,
+                    severity: 'info',
+                    dedupKey: `closed:${now}`,
+                    message: `Position closed: ${coin} (was ${pos.szi} at $${pos.entryPx ?? '?'}, last uPnL $${pos.unrealizedPnl.toFixed(2)})`,
+                    payload: { kind: 'closed', coin, previousSize: pos.szi, entryPx: pos.entryPx, lastPnl: pos.unrealizedPnl },
+                });
+            }
+        }
+        for (const [coin, pos] of current) {
+            const prevPos = prev.get(coin);
+            if (!prevPos || prevPos.szi === pos.szi)
+                continue;
+            const change = pos.szi - prevPos.szi;
+            const action = Math.abs(pos.szi) > Math.abs(prevPos.szi) ? 'increased' : 'decreased';
+            events.push({
+                time: now,
+                address: target.address,
+                rule: 'position_lifecycle',
+                coin,
+                severity: 'info',
+                dedupKey: `size:${now}`,
+                message: `Position ${coin} size ${action}: ${prevPos.szi} → ${pos.szi} (${change > 0 ? '+' : ''}${change.toFixed(6)})`,
+                payload: { kind: 'size_changed', coin, previousSize: prevPos.szi, newSize: pos.szi, change },
+            });
+        }
+        return events;
+    }
+    // ── Dispatch ──────────────────────────────────────────────────────
+    passesPrefs(alert) {
+        if (this.prefs.rules?.[alert.rule] === false)
+            return false;
+        const min = this.prefs.minSeverity ?? 'info';
+        return GUARDIAN_SEVERITY_RANK[alert.severity] >= GUARDIAN_SEVERITY_RANK[min];
+    }
+    async dispatch(alert) {
+        if (!this.passesPrefs(alert))
+            return;
+        this.alertsFired++;
+        if (!this.opts.quiet) {
+            if (this.opts.json) {
+                console.log(JSON.stringify(alert));
+            }
+            else {
+                const time = new Date(alert.time).toISOString().slice(11, 19);
+                const scope = alert.coin ? ` ${alert.coin}` : '';
+                console.log(`[${time}] ${alert.severity.toUpperCase()} ${alert.rule}${scope} — ${alert.message}`);
+            }
+        }
+        try {
+            this.opts.onAlert?.(alert);
+        }
+        catch (err) {
+            this.log(`onAlert callback threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (this.telegram) {
+            try {
+                await sendTelegramMessage(this.telegram.token, this.telegram.chatId, formatTelegramAlert(alert));
+                this.alertsDelivered++;
+            }
+            catch (err) {
+                this.deliveryErrors++;
+                this.log(`telegram delivery failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (this.agentHook) {
+            try {
+                const port = this.agentHook.gatewayPort ?? 18789;
+                const res = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.agentHook.hooksToken}`,
+                    },
+                    body: JSON.stringify({
+                        message: `[guardian] [${alert.severity}] ${alert.message}`,
+                        name: 'openbroker-guardian',
+                        wakeMode: 'now',
+                    }),
+                    signal: AbortSignal.timeout(5_000),
+                });
+                if (res.ok)
+                    this.alertsDelivered++;
+                else {
+                    this.deliveryErrors++;
+                    this.log(`agent hook delivery failed: HTTP ${res.status}`);
+                }
+            }
+            catch (err) {
+                this.deliveryErrors++;
+                this.log(`agent hook delivery failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    log(message) {
+        if (this.opts.verbose)
+            console.error(`[guardian] ${message}`);
+    }
+}
+/** Start watching. Resolves once the first snapshot is seeded. */
+export async function startGuardian(opts = {}) {
+    const client = opts.client ?? getClient();
+    const addresses = (opts.addresses && opts.addresses.length > 0 ? opts.addresses : [client.address])
+        .map((a) => a.toLowerCase());
+    for (const address of addresses) {
+        if (!ADDR_RE.test(address)) {
+            throw new Error(`Invalid address: ${address}. Pass --address 0x... or configure HYPERLIQUID_ACCOUNT_ADDRESS.`);
+        }
+    }
+    const guardian = new Guardian(addresses, { ...opts, client });
+    await guardian.start();
+    return guardian;
+}

package/dist/guardian/rules.d.ts

@@ -0,0 +1,35 @@
+import type { GuardianAlert, GuardianPriceView, GuardianTargetState, GuardianThresholds } from './types.js';
+export type GuardianAlertHandler = (alert: GuardianAlert) => void;
+export declare class GuardianRiskEngine {
+    private readonly prices;
+    private readonly onAlert;
+    private readonly thresholds;
+    /** address:coin:threshold → state */
+    private liqState;
+    /** address → state */
+    private marginState;
+    /** address:coin → alerted */
+    private tpslState;
+    /** address:oid → last fired */
+    private staleOrderState;
+    /** address:coin → { since, firedAt } */
+    private fundingState;
+    private evaluations;
+    constructor(prices: GuardianPriceView, onAlert: GuardianAlertHandler, thresholds?: Partial<GuardianThresholds>);
+    getStats(): {
+        evaluations: number;
+    };
+    /** One evaluation pass over the given targets. */
+    tick(targets: Iterable<GuardianTargetState>, now?: number): void;
+    /** Distance = (mark − liqPx) / mark, signed by side. */
+    private liqDistance;
+    private updateLiqDistance;
+    private evalLiqProximity;
+    private evalMarginUsage;
+    private evalNoTpsl;
+    private evalStaleOrders;
+    private evalFundingBleed;
+    /** Drop per-position rule state when positions close (prevents unbounded growth). */
+    private gcClosedPositions;
+}
+//# sourceMappingURL=rules.d.ts.map

package/dist/guardian/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../scripts/guardian/rules.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAOpB,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAElE,qBAAa,kBAAkB;IAe3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAiC;IACjD,sBAAsB;IACtB,OAAO,CAAC,WAAW,CAAiC;IACpD,6BAA6B;IAC7B,OAAO,CAAC,SAAS,CAAqB;IACtC,+BAA+B;IAC/B,OAAO,CAAC,eAAe,CAA6B;IACpD,wCAAwC;IACxC,OAAO,CAAC,YAAY,CAAgE;IACpF,OAAO,CAAC,WAAW,CAAK;gBAGL,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,oBAAoB,EAC9C,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAK1C,QAAQ;;;IAIR,kDAAkD;IAClD,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,GAAG,SAAa,GAAG,IAAI;IAiBpE,wDAAwD;IACxD,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,gBAAgB;IAqCxB,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,UAAU;IA+BlB,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,gBAAgB;IAuCxB,qFAAqF;IACrF,OAAO,CAAC,iBAAiB;CAU1B"}