openbroker 1.10.0 → 1.12.0

package/dist/guardian/cli.js

@@ -0,0 +1,288 @@
+// CLI entry point for `openbroker guardian` — read-only position risk
+// monitoring with Telegram / agent-hook delivery. The CLI counterpart of the
+// hosted guardian at /markets/guardian.
+import { parseArgs } from '../core/utils.js';
+import { getClient } from '../core/client.js';
+import { getConfigPath } from '../core/config.js';
+import { startGuardian } from './engine.js';
+import { generateLinkCode, getTelegramBotInfo, loadTelegramSettings, saveEnvVar, sendTelegramMessage, waitForTelegramLink, } from './telegram.js';
+import { GUARDIAN_RULE_IDS, GUARDIAN_RULE_LABELS, } from './types.js';
+function printUsage() {
+    console.log(`
+OpenBroker Guardian — read-only position risk monitoring
+
+Watches Hyperliquid addresses for liquidation risk, missing TP/SL, funding
+bleed and more. Never touches your keys or places orders. Alerts go to the
+console and (once connected) Telegram; if an OpenClaw agent gateway is
+configured, alerts also wake the agent.
+
+Usage:
+  openbroker guardian run [options]         Start watching (long-running)
+  openbroker guardian connect               Link a Telegram chat for alerts
+  openbroker guardian test                  Send a test Telegram message
+  openbroker guardian status                Show guardian configuration
+  openbroker guardian rules                 List alert rules
+
+Options (for run):
+  --address <0x..[,0x..]>   Address(es) to watch (default: configured account)
+  --min-severity <level>    info | warning | critical (default: info)
+  --disable <rules>         CSV of rules to turn off (see: guardian rules)
+  --only <rules>            CSV of rules to run exclusively
+  --poll <ms>               Position poll interval (default: 30000; 15000 near liquidation)
+  --orders-poll <ms>        Open-orders poll interval (default: 120000)
+  --liq-warn <pct>          Liq-distance warning threshold (default: 10)
+  --liq-critical <pct>      Liq-distance critical threshold (default: 5)
+  --margin-pct <pct>        Margin-usage warning threshold (default: 80)
+  --funding-apr <pct>       Funding-bleed APR threshold (default: 15)
+  --tpsl-minutes <min>      Minutes unprotected before no-TP/SL alert (default: 15)
+  --stale-hours <h>         Hours resting before stale-order alert (default: 12)
+  --no-telegram             Don't deliver to Telegram even if linked
+  --no-ws                   Disable the WebSocket liquidation fast lane
+  --json                    Print alerts as JSON lines (agent-friendly)
+  --verbose                 Show debug output
+
+Telegram setup (one-time):
+  1. Message @BotFather on Telegram, send /newbot, and copy the bot token
+  2. Put it in your config:  TELEGRAM_BOT_TOKEN=123456:ABC-...
+  3. Run: openbroker guardian connect   (then tap the printed link)
+
+Examples:
+  openbroker guardian run
+  openbroker guardian run --address 0xabc...,0xdef... --min-severity warning
+  openbroker guardian run --disable position_lifecycle,stale_order
+  openbroker guardian run --json --no-telegram
+`);
+}
+const SEVERITIES = ['info', 'warning', 'critical'];
+function parseRuleCsv(raw, flag) {
+    const rules = raw.split(',').map((r) => r.trim()).filter(Boolean);
+    for (const rule of rules) {
+        if (!GUARDIAN_RULE_IDS.includes(rule)) {
+            console.error(`Error: unknown rule '${rule}' in ${flag}. Valid rules: ${GUARDIAN_RULE_IDS.join(', ')}`);
+            process.exit(1);
+        }
+    }
+    return rules;
+}
+function parseNum(args, key) {
+    const raw = args[key];
+    if (raw === undefined || raw === true)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        console.error(`Error: --${key} must be a positive number`);
+        process.exit(1);
+    }
+    return n;
+}
+async function runCommand(args) {
+    const addresses = typeof args.address === 'string'
+        ? args.address.split(',').map((a) => a.trim()).filter(Boolean)
+        : undefined;
+    const prefs = {};
+    if (typeof args['min-severity'] === 'string') {
+        const sev = args['min-severity'];
+        if (!SEVERITIES.includes(sev)) {
+            console.error(`Error: --min-severity must be one of: ${SEVERITIES.join(', ')}`);
+            process.exit(1);
+        }
+        prefs.minSeverity = sev;
+    }
+    if (typeof args.disable === 'string') {
+        prefs.rules = Object.fromEntries(parseRuleCsv(args.disable, '--disable').map((r) => [r, false]));
+    }
+    if (typeof args.only === 'string') {
+        const only = new Set(parseRuleCsv(args.only, '--only'));
+        prefs.rules = Object.fromEntries(GUARDIAN_RULE_IDS.map((r) => [r, only.has(r)]));
+    }
+    const thresholds = {};
+    const liqWarn = parseNum(args, 'liq-warn');
+    const liqCritical = parseNum(args, 'liq-critical');
+    if (liqWarn !== undefined || liqCritical !== undefined) {
+        const warn = (liqWarn ?? 10) / 100;
+        const crit = (liqCritical ?? 5) / 100;
+        thresholds.liqThresholds = [
+            { pct: warn, severity: 'warning' },
+            { pct: crit, severity: 'critical' },
+            { pct: crit / 2.5, severity: 'critical' },
+        ];
+    }
+    const marginPct = parseNum(args, 'margin-pct');
+    if (marginPct !== undefined) {
+        thresholds.marginThresholdPct = marginPct;
+        thresholds.marginRearmPct = marginPct * 0.9;
+    }
+    const fundingApr = parseNum(args, 'funding-apr');
+    if (fundingApr !== undefined)
+        thresholds.fundingBleedAprPct = fundingApr;
+    const tpslMinutes = parseNum(args, 'tpsl-minutes');
+    if (tpslMinutes !== undefined)
+        thresholds.noTpslAfterMs = tpslMinutes * 60_000;
+    const staleHours = parseNum(args, 'stale-hours');
+    if (staleHours !== undefined)
+        thresholds.staleOrderAgeMs = staleHours * 3600_000;
+    const options = {
+        addresses,
+        prefs,
+        thresholds,
+        pollIntervalMs: parseNum(args, 'poll'),
+        ordersIntervalMs: parseNum(args, 'orders-poll'),
+        useWebSocket: args['no-ws'] !== true,
+        telegram: args['no-telegram'] === true ? false : undefined,
+        json: args.json === true,
+        verbose: args.verbose === true,
+    };
+    const guardian = await startGuardian(options);
+    const stats = guardian.getStats();
+    const disabled = GUARDIAN_RULE_IDS.filter((r) => prefs.rules?.[r] === false);
+    if (!options.json) {
+        console.log('OpenBroker Guardian — watching (read-only, Ctrl+C to stop)');
+        console.log(`  Addresses:    ${stats.addresses.join(', ')}`);
+        console.log(`  Min severity: ${prefs.minSeverity ?? 'info'}`);
+        console.log(`  Rules off:    ${disabled.length > 0 ? disabled.join(', ') : 'none'}`);
+        console.log(`  Channels:     ${stats.channels.join(', ')}`);
+        if (!stats.channels.includes('telegram')) {
+            console.log('  Tip: run `openbroker guardian connect` to get alerts in Telegram.');
+        }
+        console.log('');
+        for (const target of guardian.getTargets()) {
+            const positions = [...target.positions.values()];
+            if (positions.length === 0) {
+                console.log(`  ${target.address}: no open positions`);
+                continue;
+            }
+            console.log(`  ${target.address}: equity $${target.equity.toFixed(2)}, margin ${target.marginUsedPct.toFixed(1)}%`);
+            for (const pos of positions) {
+                const liq = pos.liquidationPx !== null ? `liq $${pos.liquidationPx}` : 'no liq px';
+                console.log(`    ${pos.side} ${Math.abs(pos.szi)} ${pos.coin} @ $${pos.entryPx ?? '?'} (${pos.leverage}x, ${liq}, uPnL $${pos.unrealizedPnl.toFixed(2)})`);
+            }
+        }
+        console.log('');
+    }
+    const shutdown = async () => {
+        if (!options.json)
+            console.log('\nStopping guardian...');
+        await guardian.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await new Promise(() => { });
+}
+async function connectCommand(args) {
+    const settings = loadTelegramSettings();
+    const token = typeof args.token === 'string' ? args.token : settings.token;
+    if (!token) {
+        console.log('No Telegram bot token configured.\n');
+        console.log('One-time setup:');
+        console.log('  1. Open Telegram and message @BotFather');
+        console.log('  2. Send /newbot and follow the prompts (any name, e.g. "my-guardian-bot")');
+        console.log('  3. Copy the bot token BotFather gives you');
+        console.log(`  4. Add it to your config (${getConfigPath()}):`);
+        console.log('       TELEGRAM_BOT_TOKEN=123456789:AAF...');
+        console.log('  5. Re-run: openbroker guardian connect');
+        process.exit(1);
+    }
+    let bot;
+    try {
+        bot = await getTelegramBotInfo(token);
+    }
+    catch (err) {
+        console.error(`Could not reach the Telegram bot: ${err instanceof Error ? err.message : String(err)}`);
+        console.error('Check TELEGRAM_BOT_TOKEN.');
+        process.exit(1);
+    }
+    const code = generateLinkCode();
+    console.log(`Bot: @${bot.username}`);
+    console.log('\nOpen this link in Telegram and tap START (or send the code to the bot):\n');
+    console.log(`  https://t.me/${bot.username}?start=${code}`);
+    console.log(`\n  code: ${code}`);
+    console.log('\nWaiting for the link (10 min timeout, Ctrl+C to abort)...');
+    const chatId = await waitForTelegramLink(token, code);
+    if (chatId === null) {
+        console.error('\nTimed out waiting for the Telegram link. Re-run: openbroker guardian connect');
+        process.exit(1);
+    }
+    const savedTo = saveEnvVar('TELEGRAM_CHAT_ID', String(chatId));
+    if (typeof args.token === 'string')
+        saveEnvVar('TELEGRAM_BOT_TOKEN', args.token);
+    console.log(`\nLinked chat ${chatId} — saved TELEGRAM_CHAT_ID to ${savedTo}`);
+    console.log('Guardian alerts will now be delivered to Telegram. Try: openbroker guardian test');
+}
+async function testCommand() {
+    const { token, chatId } = loadTelegramSettings();
+    if (!token || !chatId) {
+        console.error('Telegram not connected. Run: openbroker guardian connect');
+        process.exit(1);
+    }
+    await sendTelegramMessage(token, chatId, '<b>[TEST]</b> OpenBroker guardian is connected. Risk alerts will arrive here.');
+    console.log('Test message sent.');
+}
+async function statusCommand() {
+    const { token, chatId } = loadTelegramSettings();
+    let address = 'not configured';
+    try {
+        address = getClient().address;
+    }
+    catch { /* read-only mode without an address */ }
+    console.log('OpenBroker Guardian — status\n');
+    console.log(`  Default address:  ${address}`);
+    console.log(`  Config file:      ${getConfigPath()}`);
+    console.log(`  Telegram token:   ${token ? 'set' : 'NOT SET (see: openbroker guardian connect)'}`);
+    console.log(`  Telegram chat:    ${chatId ? `linked (${chatId})` : 'not linked'}`);
+    console.log(`  Agent hook:       ${process.env.OPENCLAW_HOOKS_TOKEN ? 'configured' : 'not configured'}`);
+    console.log('\nRules (all on by default):');
+    for (const rule of GUARDIAN_RULE_IDS) {
+        console.log(`  ${rule.padEnd(20)} ${GUARDIAN_RULE_LABELS[rule]}`);
+    }
+}
+function rulesCommand() {
+    console.log('Guardian alert rules:\n');
+    const details = {
+        liq_proximity: 'warning at 10% from liquidation price, critical at 5% and 2% (--liq-warn/--liq-critical)',
+        no_tpsl: 'info when a position is open 15+ min with no reduce-only trigger orders (--tpsl-minutes)',
+        stale_order: 'info for limit orders resting 12h+ and 3%+ from mid (--stale-hours)',
+        margin_usage: 'warning when margin used exceeds 80% of equity (--margin-pct)',
+        funding_bleed: 'warning when paying 15%+ APR funding for 60+ min (--funding-apr)',
+        position_lifecycle: 'info on position open / close / resize',
+    };
+    for (const rule of GUARDIAN_RULE_IDS) {
+        console.log(`  ${rule.padEnd(20)} ${GUARDIAN_RULE_LABELS[rule]}`);
+        console.log(`  ${''.padEnd(20)} ${details[rule]}\n`);
+    }
+    console.log('Disable rules with --disable <csv>, or run a subset with --only <csv>.');
+}
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h') {
+        printUsage();
+        process.exit(0);
+    }
+    const subcommand = rawArgs[0];
+    const args = parseArgs(rawArgs.slice(1));
+    switch (subcommand) {
+        case 'run':
+            await runCommand(args);
+            break;
+        case 'connect':
+            await connectCommand(args);
+            break;
+        case 'test':
+            await testCommand();
+            break;
+        case 'status':
+            await statusCommand();
+            break;
+        case 'rules':
+            rulesCommand();
+            break;
+        default:
+            console.error(`Unknown subcommand: ${subcommand}`);
+            console.log('Run "openbroker guardian --help" for usage');
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/guardian/engine.d.ts

@@ -0,0 +1,107 @@
+import { type HyperliquidClient } from '../core/client.js';
+import type { GuardianAlert, GuardianPrefs, GuardianTargetState, GuardianThresholds } from './types.js';
+export interface GuardianTelegramChannel {
+    token: string;
+    chatId: string;
+}
+export interface GuardianAgentHookChannel {
+    hooksToken: string;
+    gatewayPort?: number;
+}
+export interface GuardianOptions {
+    /** Addresses to watch. Default: the configured account address. */
+    addresses?: string[];
+    /** Min severity + per-rule opt-out (same contract as the hosted guardian). */
+    prefs?: GuardianPrefs;
+    /** Rule threshold overrides. */
+    thresholds?: Partial<GuardianThresholds>;
+    /** clearinghouseState cadence (ms). Default 30s; drops to 15s near liquidation. */
+    pollIntervalMs?: number;
+    /** frontendOpenOrders cadence (ms). Default 120s. */
+    ordersIntervalMs?: number;
+    /** Price (mids + main-dex ctxs) cadence (ms). Default 30s. */
+    pricesIntervalMs?: number;
+    /** HIP-3 mark/funding cadence (ms), fetched only while HIP-3 positions exist. Default 5m. */
+    hip3PricesIntervalMs?: number;
+    /** Rule-engine tick (ms), pure in-memory. Default 5s. */
+    riskIntervalMs?: number;
+    /**
+     * Subscribe WS userEvents for instant liquidation alerts and fill-triggered
+     * re-polls. Only active when exactly one address is watched (the feed is not
+     * tagged per user). Default true.
+     */
+    useWebSocket?: boolean;
+    /** Telegram channel. Default: from TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID env. Pass false to disable. */
+    telegram?: GuardianTelegramChannel | false;
+    /** OpenClaw agent hook channel. Default: from OPENCLAW_HOOKS_TOKEN/OPENCLAW_GATEWAY_PORT env. Pass false to disable. */
+    agentHook?: GuardianAgentHookChannel | false;
+    /** Print alerts as JSON lines instead of human-readable text. */
+    json?: boolean;
+    /** Suppress console alert output entirely (library consumers). */
+    quiet?: boolean;
+    verbose?: boolean;
+    /** Callback fired for every alert that passes prefs. */
+    onAlert?: (alert: GuardianAlert) => void;
+    /** Injectable client (tests / plugin). Default getClient(). */
+    client?: HyperliquidClient;
+}
+export interface GuardianStats {
+    addresses: string[];
+    statePolls: number;
+    orderPolls: number;
+    alertsFired: number;
+    alertsDelivered: number;
+    deliveryErrors: number;
+    evaluations: number;
+    pricesAt: number | null;
+    channels: string[];
+}
+export interface GuardianHandle {
+    stop(): Promise<void>;
+    getStats(): GuardianStats;
+    getTargets(): GuardianTargetState[];
+}
+export declare class Guardian {
+    private readonly client;
+    private readonly targets;
+    private readonly prices;
+    private readonly risk;
+    private readonly prefs;
+    private readonly telegram;
+    private readonly agentHook;
+    private readonly opts;
+    private timers;
+    private wsSubs;
+    private wsUsed;
+    private stopped;
+    private polling;
+    private statePolls;
+    private orderPolls;
+    private alertsFired;
+    private alertsDelivered;
+    private deliveryErrors;
+    private lastPricesAt;
+    constructor(addresses: string[], opts?: GuardianOptions);
+    channels(): string[];
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStats(): GuardianStats;
+    getTargets(): GuardianTargetState[];
+    private startWebSocket;
+    private hasHip3Positions;
+    private refreshPrices;
+    /** HIP-3 mark/funding — heavier (per-dex metaAndAssetCtxs), only while HIP-3 positions exist. */
+    private refreshHip3Prices;
+    private pollAllStates;
+    private pollAllOrders;
+    private pollState;
+    private pollOrders;
+    /** Snapshot diff → position lifecycle alerts (mirrors the hosted poller). */
+    private diff;
+    private passesPrefs;
+    private dispatch;
+    private log;
+}
+/** Start watching. Resolves once the first snapshot is seeded. */
+export declare function startGuardian(opts?: GuardianOptions): Promise<GuardianHandle>;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../scripts/guardian/engine.ts"],"names":[],"mappings":"AAMA,OAAO,EAAa,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAStE,OAAO,KAAK,EACV,aAAa,EAEb,aAAa,EAEb,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACzC,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,EAAE,uBAAuB,GAAG,KAAK,CAAC;IAC3C,wHAAwH;IACxH,SAAS,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;IAC7C,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACzC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,IAAI,aAAa,CAAC;IAC1B,UAAU,IAAI,mBAAmB,EAAE,CAAC;CACrC;AA6BD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IAEvC,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAuB;gBAE/B,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB;IAuD3D,QAAQ,IAAI,MAAM,EAAE;IAQd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,QAAQ,IAAI,aAAa;IAczB,UAAU,IAAI,mBAAmB,EAAE;YAMrB,cAAc;IAmD5B,OAAO,CAAC,gBAAgB;YASV,aAAa;IAgC3B,iGAAiG;YACnF,iBAAiB;YA0BjB,aAAa;YAkBb,aAAa;YAMb,SAAS;YAgCT,UAAU;IAyBxB,6EAA6E;IAC7E,OAAO,CAAC,IAAI;IAyDZ,OAAO,CAAC,WAAW;YAML,QAAQ;IA0DtB,OAAO,CAAC,GAAG;CAGZ;AAED,kEAAkE;AAClE,wBAAsB,aAAa,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAcvF"}