@reefclaw/openclaw-plugin 0.1.0

package/live/user-data-stream-controller.d.ts

@@ -0,0 +1,200 @@
+import { EventEmitter } from 'node:events';
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import { UserDataStream } from './user-data-stream.js';
+import type { ParsedAlgoUpdate } from './user-data-stream.js';
+import { LiveStateStore } from './live-state-store.js';
+import type { RestSnapshot, StateDrift } from './live-state-store.js';
+import type { UserDataStreamMode, UserDataStreamTunables } from '../config/user-data-stream-config.js';
+import type { CcxtBalance } from '../types.js';
+import type { TradeStoreClient } from '../ingest/trade-store-client.js';
+import type { TouchedSymbolsStore } from '../ingest/touched-symbols-store.js';
+import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
+/**
+ * Rewrite `balance.total[asset]` from CCXT's marginBalance-equivalent (wallet
+ * + unrealizedProfit for Binance Futures) to raw walletBalance only, so the
+ * REST snapshot aligns with what the WS ACCOUNT_UPDATE frames deliver. The
+ * raw walletBalance field lives under `balance.info.assets[i].walletBalance`
+ * — an array of per-asset records Binance Futures always returns alongside
+ * the top-level totals. Exported for unit testing.
+ *
+ * Falls back to the unmodified balance if `info.assets` is missing or
+ * malformed (e.g. mock responses in unit tests without the info envelope).
+ * Only `total` is rewritten; `free` and `used` are left untouched because
+ * the WS store computes them separately from position-lock state.
+ */
+export declare function normalizeBinanceFuturesBalance(balance: CcxtBalance): CcxtBalance;
+/**
+ * Thrown by `buildSnapshot` when ANY of the three REST fetches returned
+ * `null` — i.e. the fetch FAILED (Binance 429 / weight-paced / transient
+ * network), state is UNKNOWN. It does NOT mean "the account is flat / has no
+ * orders". `LiveStateStore.applySnapshot` replaces positions + orders +
+ * balances WHOLESALE, so applying a snapshot built from a failed fetch would
+ * wipe still-live positions and bracket SL/TP from the store — which is the
+ * AUTHORITATIVE read path in observe/enforce mode — blinding the agent into
+ * the documented phantom-naked spiral.
+ *
+ * Subclass of `Error` so the existing `.catch()` sites absorb it unchanged;
+ * callers detect the type to skip the apply, leave the store intact, and let
+ * WS deltas + the next reconnect/resync repair state. Same null≠empty rule as
+ * `getOpenOrders` / `getPositions` / `closePosition` / the bracket reconciler.
+ */
+export declare class UntrustedSnapshotError extends Error {
+    constructor(message: string);
+}
+export interface ControllerTimerDeps {
+    setInterval: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
+    clearInterval: (handle: ReturnType<typeof setInterval>) => void;
+    now: () => number;
+}
+export interface UserDataStreamControllerOptions {
+    mode: UserDataStreamMode;
+    testnet: boolean;
+    tunables: UserDataStreamTunables;
+    /** If absent, a real WS stream is built from `defaultWebSocketFactory`.
+     *  Tests inject a prebuilt stream to avoid touching the network. */
+    stream?: UserDataStream;
+    /** If absent, a fresh LiveStateStore is constructed. */
+    store?: LiveStateStore;
+    /** 60_000 by default. Shorter values allowed for post-drift tightening. */
+    truthCheckIntervalMs?: number;
+    /** Timer injection for unit tests. */
+    timers?: Partial<ControllerTimerDeps>;
+    /** Audit-trail ingest path (TRADE_AUDIT_TRAIL_PLAN Phase 1).  When present
+     *  AND mode≠'off', the controller starts a WsIngest alongside the stream
+     *  that POSTs every TRADE event to the webapp's /api/internal/trades.
+     *  Caller decides whether to pass this in based on userDataStream.dbWrite. */
+    tradeIngest?: {
+        client: TradeStoreClient;
+        userId: string;
+        exchange?: string;
+        /** Optional override for the gap-filler's persistent touched-symbols
+         *  store. Pass `null` to disable cross-restart persistence (tests).
+         *  Production callers leave this undefined to get the file-backed
+         *  default under ~/.reefclaw/touched-symbols-<userId>.json. */
+        touchedSymbolsStore?: TouchedSymbolsStore | null;
+    };
+    /** Position-decision auto-capture context. When provided alongside
+     *  tradeIngest, the controller passes it to WsIngest so every TRADE event
+     *  is also routed through `onWsFillObserved` (limit-order entries +
+     *  scale-ins). When omitted, ws-ingest only records to the audit trail
+     *  (the legacy PR1 behaviour). */
+    autoCapture?: AutoCaptureContext;
+}
+export type ControllerEvents = {
+    /** Emitted after every REST snapshot has been applied. */
+    snapshotApplied: (snap: RestSnapshot) => void;
+    /** Emitted when the 60s drift check finds anything (minor or major). */
+    drift: (drift: StateDrift) => void;
+    /** Emitted when a major drift triggered a forced resync. */
+    forcedResync: (cause: string) => void;
+    /** Emitted when the stream reports a reconnect — observability. */
+    reconnecting: (attempt: number, delayMs: number) => void;
+    /** Pass-through of advisory events from the stream. */
+    marginCall: (ev: unknown) => void;
+    /** Pass-through of ALGO_UPDATE (conditional/bracket order lifecycle).
+     *  LiveAdapter consumes this as the AUTHORITATIVE bracket-state signal —
+     *  Binance pushes EXPIRED when it auto-cancels a sibling on position
+     *  close, CANCELED only on an explicit cancel, TRIGGERED/FINISHED on
+     *  fire. Replaces REST-audit guessing. */
+    algoUpdate: (ev: ParsedAlgoUpdate) => void;
+};
+export declare class UserDataStreamController extends EventEmitter {
+    readonly mode: UserDataStreamMode;
+    private readonly api;
+    private readonly stream;
+    private readonly store;
+    private readonly truthCheckIntervalMs;
+    private readonly staleStoreThresholdMs;
+    private readonly timers;
+    private truthCheckTimer;
+    private algoRefreshTimer;
+    private reconnectRateTimer;
+    private readonly algoRefreshMs;
+    private readonly wsIngest;
+    private readonly restGapFiller;
+    private readonly activeProbe;
+    /** Count of stale-forced + other reconnects in the current hourly window.
+     *  Checked every hour; a spike above RECONNECT_RATE_ALERT_THRESHOLD logs
+     *  a WARN so operator can spot Binance-side trouble or network flaps. */
+    private reconnectCountThisHour;
+    private running;
+    private snapshotInFlight;
+    /** Serialises snapshot applies so WS events don't race with a snapshot
+     *  we're in the middle of fetching. WS events that arrive during a
+     *  snapshot are buffered here and drained after apply. */
+    private bufferedDuringSnapshot;
+    private consecutiveMajorDrifts;
+    constructor(api: BinancePrivateApi, options: UserDataStreamControllerOptions);
+    getStore(): LiveStateStore;
+    getStream(): UserDataStream;
+    /** True when the in-memory store is safe to serve as the authoritative
+     *  source for positions/orders reads. Two independent conditions, BOTH
+     *  required — each guards a distinct failure in the null≠empty class
+     *  (same class as the getOpenOrders / getPositions / closePosition /
+     *  bracket-reconciler / UntrustedSnapshotError rules):
+     *
+     *  (1) **Seeded.** A trusted REST snapshot has run at least once
+     *      (`lastSnapshotAt !== null`). False during startup before the
+     *      `connected` handler's initial snapshot lands and the gap after
+     *      `reset()`. An unseeded `[]` is indistinguishable from "no
+     *      positions/orders" and would trip naked-bracket / orphan-cancel
+     *      paths against real exchange state.
+     *
+     *  (2) **Fresh.** We've received SOME incoming frame within
+     *      `staleStoreThresholdMs` — the SAME calibrated threshold
+     *      (`staleEventWatchdogMs`, default 6 min) and the SAME signal
+     *      (`lastFrameAt`, any frame incl. Binance's 3-min server pings) the
+     *      dead-socket watchdog itself uses to declare the socket dead.
+     *      Beyond it the watchdog is already forcing a reconnect; serving a
+     *      seeded-but-stale store as authoritative there would present stale
+     *      state as truth on a destructive-action-gating read — the residual
+     *      a reviewer flagged. Deliberately NOT a bare `isConnected()` check:
+     *      a brief reconnect (listenKey rotation ~25 min, 1 s→60 s backoff)
+     *      keeps `lastFrameAt` recent, so the common case is NOT pushed onto
+     *      the weight-heavy / rate-limit-poisoned REST path — that would just
+     *      trade one failure in this class for another. When the reconnect +
+     *      resync completes, `lastFrameAt` refreshes and the store is trusted
+     *      again. `lastFrameAt === null` (seeded but never a frame — an odd
+     *      state) is conservatively treated as untrusted. */
+    isStoreTrusted(): boolean;
+    /** Start the stream + run the initial REST snapshot + seed the store.
+     *  No-op if mode is 'off'. Throws if already running. */
+    start(): Promise<void>;
+    /** Graceful shutdown. */
+    stop(): Promise<void>;
+    /** Force a full snapshot + re-seed. Used by operator tools for manual resync. */
+    forceResync(cause: string): Promise<void>;
+    private buildStreamOptions;
+    private attachStreamHandlers;
+    /** Fetch REST positions/balance/orders and normalise symbols so the store
+     *  keys match WS events regardless of which write path landed first.
+     *  CCXT returns `BTC/USDT:USDT`; our WS parser produces `BTC/USDT`. */
+    private buildSnapshot;
+    private takeAndApplySnapshot;
+    private startTruthCheckLoop;
+    private stopTruthCheckLoop;
+    /** Start the algo-order refresh loop — REST-polls open orders and replaces
+     *  the algo (bracket SL/TP) subset in the store. Fills the gap left by
+     *  Binance's WS not emitting ORDER_TRADE_UPDATE for algo orders until they
+     *  trigger. Disabled when algoRefreshMs === 0. */
+    private startAlgoRefreshLoop;
+    private stopAlgoRefreshLoop;
+    /** Alert threshold — hourly reconnect count that logs a WARN. Set at
+     *  10/hour because the natural baseline on a quiet account (listenKey
+     *  rotation every 25 min + occasional stale-watchdog firing) is
+     *  3-4/hour; anything consistently above that is unexpected. Does NOT
+     *  auto-pause or take action — operator investigates when they see
+     *  the log line land. */
+    private static readonly RECONNECT_RATE_ALERT_THRESHOLD;
+    private static readonly RECONNECT_RATE_WINDOW_MS;
+    /** Start the reconnect-rate monitor. Runs hourly; resets the counter
+     *  after each check whether or not it alerted. */
+    private startReconnectRateMonitor;
+    private stopReconnectRateMonitor;
+    /** One pass of algo-order refresh: fetch open orders (merges regular + algo
+     *  via BinancePrivateApi), filter to algo-bracket cids, and hand them to the
+     *  store's replaceAlgoOrders. No mutation if WS isn't connected (we'd be
+     *  polluting state the reconnect snapshot is about to replace anyway). */
+    private runAlgoRefresh;
+    private runTruthCheck;
+}