@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/venues/hyperliquid/hl-balance.d.ts

@@ -0,0 +1,116 @@
+import type { CcxtBalance } from '../../types.js';
+import type { CloseReason } from '../../simulator/types.js';
+export interface HlClearinghouseState {
+    marginSummary?: {
+        accountValue?: string | number;
+        totalMarginUsed?: string | number;
+        totalNtlPos?: string | number;
+    };
+    withdrawable?: string | number;
+    assetPositions?: Array<{
+        position?: {
+            coin?: string;
+            szi?: string | number;
+            entryPx?: string | number;
+            unrealizedPnl?: string | number;
+            positionValue?: string | number;
+            liquidationPx?: string | number;
+            marginUsed?: string | number;
+        };
+    }>;
+}
+export interface HlNav {
+    /** accountValue — what the HL app's portfolio panel shows. */
+    equity: number;
+    /** equity − Σ uPnl. The Binance "wallet"/margin-balance analog. */
+    wallet: number;
+    totalUnrealizedPnl: number;
+    /** Free collateral (HL `withdrawable`). */
+    available: number;
+}
+/** Derive NAV/wallet from a clearinghouseState payload.
+ *
+ *  ★ Returns null when the payload is UNREADABLE — never a zeroed NAV. A phantom
+ *  "$0 equity" would trip risk limits and look like a catastrophic loss; null
+ *  means "unknown", which the caller must refuse to act on (null ≠ empty). */
+export declare function deriveHlNav(state: HlClearinghouseState | null | undefined): HlNav | null;
+/** CcxtBalance shape the rest of the plugin (KPI strip, sizing, LiveBalanceEnricher)
+ *  already consumes. USDC is HL's settlement asset. */
+export declare function toCcxtBalance(nav: HlNav): CcxtBalance;
+export interface HlFillForAnchor {
+    time: number;
+    closedPnl?: string | number;
+    fee?: string | number;
+    builderFee?: string | number;
+}
+export interface HlFundingForAnchor {
+    time: number;
+    /** HL funding deltas are signed USDC (negative = paid). */
+    usdc?: string | number;
+    delta?: {
+        usdc?: string | number;
+    };
+}
+/** Σ(closedPnl − fee − builderFee) + Σ funding, over rows at/after `sinceMs`.
+ *
+ *  This is the exact analog of Binance's `netNonTransfer` (REALIZED_PNL +
+ *  COMMISSION + FUNDING_FEE), and — critically — it is NET of fees. The Binance
+ *  lesson (the ledger was systematically gross, causing a visible KPI gap) applies
+ *  verbatim: a gross anchor WILL disagree with the HL app. */
+export declare function computeNetNonTransfer(args: {
+    fills: HlFillForAnchor[];
+    fundings: HlFundingForAnchor[];
+    sinceMs: number;
+}): {
+    netNonTransfer: number;
+    realizedPnlGross: number;
+    fees: number;
+    funding: number;
+};
+/** UTC-midnight epoch ms for a given instant (the Day-P&L boundary). */
+export declare function utcMidnightMs(now?: number): number;
+/** sessionStartNav = wallet_now − netNonTransfer_since_midnight.
+ *  dayPnl = NAV − sessionStartNav (computed by the caller each tick). */
+export declare function deriveSessionStartNav(args: {
+    walletNow: number;
+    netNonTransfer: number;
+}): number;
+/** A capital flow (deposit / withdraw / internal transfer) changes the wallet
+ *  WITHOUT being trading P&L — bump the anchor by the same signed amount so it
+ *  never shows up as Day-P&L (the DepositTracker rule).
+ *
+ *  T-3 note: the `delta.type` enum is OPEN (docs incomplete; only
+ *  `internalTransfer` observed so far). We therefore treat any ledger row that
+ *  carries a usdc delta as a capital flow rather than switch on a closed set — an
+ *  UNKNOWN type must never be silently dropped, or the anchor drifts. */
+export declare function applyLedgerDelta(args: {
+    sessionStartNav: number;
+    ledgerRows: Array<{
+        time: number;
+        delta?: {
+            usdc?: string | number;
+            type?: string;
+        };
+    }>;
+    sinceMs: number;
+    seenHashes?: Set<string>;
+}): {
+    sessionStartNav: number;
+    applied: number;
+};
+/** ★ Close-bypass mapping (§5.9) — HL signals → journal close reasons.
+ *
+ *  A position can leave our control without our close path running: a bracket
+ *  triggering, a LIQUIDATION, an ADL, or a delisting. Each must land in the
+ *  journal honestly (the KPI and the learning loop both read these), never as a
+ *  silent disappearance. */
+export declare function mapHlCloseReason(signal: {
+    /** Fill-level liquidation object (authoritative). */
+    liquidation?: {
+        method?: string;
+    } | null;
+    /** Order status from `orderUpdates`. */
+    orderStatus?: string;
+    /** Our own cloid role, when the closing order was one of our legs. */
+    bracketRole?: 'stop' | 'target';
+}): CloseReason | 'liquidated' | 'adl' | 'venue_delisted' | null;

package/venues/hyperliquid/hl-balance.js

@@ -0,0 +1,145 @@
+// Hyperliquid balance / NAV / Day-P&L anchor (plan §5.8) + close-bypass mapping
+// (§5.9). Pure functions — the adapter feeds them raw HL payloads.
+//
+// ★ THE INVARIANT THIS FILE EXISTS TO KEEP: "KPI must equal the exchange app to
+//   the cent." On Binance that meant anchoring Day-P&L to the UTC-midnight income
+//   endpoint (a multi-dollar gap there was ALWAYS a bug, never a formula quirk).
+//   HL has no income endpoint, so the anchor is RECONSTRUCTED:
+//
+//     wallet      = accountValue − Σ unrealizedPnl      (accountValue INCLUDES uPnl)
+//     NAV/equity  = accountValue                        (so equity = wallet + Σ uPnl
+//                                                        stays literally true)
+//     netNonTransfer(since UTC midnight)
+//                 = Σ closedPnl − Σ fee − Σ builderFee   (fills)
+//                   + Σ funding                          (userFunding)
+//     sessionStartNav = wallet_now − netNonTransfer
+//     dayPnl      = NAV − sessionStartNav
+//
+//   Deposits/withdrawals/transfers are NOT trading P&L: they bump the anchor
+//   instead (the DepositTracker rule), via `applyLedgerDelta`.
+//
+// ★ FILL-HISTORY SHALLOWNESS: only the 10,000 most recent fills exist server-side
+//   on HL (deep history is NOT queryable). The anchor must therefore be able to
+//   run off WS-captured fills persisted in our own `trades` table — which is why
+//   the WS-first audit-trail rule is a hard prerequisite here, not hygiene.
+const num = (v) => {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : 0;
+};
+/** Derive NAV/wallet from a clearinghouseState payload.
+ *
+ *  ★ Returns null when the payload is UNREADABLE — never a zeroed NAV. A phantom
+ *  "$0 equity" would trip risk limits and look like a catastrophic loss; null
+ *  means "unknown", which the caller must refuse to act on (null ≠ empty). */
+export function deriveHlNav(state) {
+    if (!state || typeof state !== 'object')
+        return null;
+    const accountValueRaw = state.marginSummary?.accountValue;
+    if (accountValueRaw === undefined || accountValueRaw === null)
+        return null;
+    const equity = num(accountValueRaw);
+    const totalUnrealizedPnl = (state.assetPositions ?? []).reduce((sum, ap) => sum + num(ap?.position?.unrealizedPnl), 0);
+    return {
+        equity,
+        wallet: equity - totalUnrealizedPnl,
+        totalUnrealizedPnl,
+        available: num(state.withdrawable),
+    };
+}
+/** CcxtBalance shape the rest of the plugin (KPI strip, sizing, LiveBalanceEnricher)
+ *  already consumes. USDC is HL's settlement asset. */
+export function toCcxtBalance(nav) {
+    const free = { USDC: nav.available };
+    const used = { USDC: Math.max(0, nav.wallet - nav.available) };
+    const total = { USDC: nav.wallet };
+    return {
+        free,
+        used,
+        total,
+        USDC: { free: nav.available, used: used.USDC, total: nav.wallet },
+    };
+}
+/** Σ(closedPnl − fee − builderFee) + Σ funding, over rows at/after `sinceMs`.
+ *
+ *  This is the exact analog of Binance's `netNonTransfer` (REALIZED_PNL +
+ *  COMMISSION + FUNDING_FEE), and — critically — it is NET of fees. The Binance
+ *  lesson (the ledger was systematically gross, causing a visible KPI gap) applies
+ *  verbatim: a gross anchor WILL disagree with the HL app. */
+export function computeNetNonTransfer(args) {
+    let realizedPnlGross = 0;
+    let fees = 0;
+    for (const f of args.fills) {
+        if (!Number.isFinite(f.time) || f.time < args.sinceMs)
+            continue;
+        realizedPnlGross += num(f.closedPnl);
+        fees += num(f.fee) + num(f.builderFee);
+    }
+    let funding = 0;
+    for (const f of args.fundings) {
+        if (!Number.isFinite(f.time) || f.time < args.sinceMs)
+            continue;
+        funding += num(f.usdc ?? f.delta?.usdc);
+    }
+    return {
+        netNonTransfer: realizedPnlGross - fees + funding,
+        realizedPnlGross,
+        fees,
+        funding,
+    };
+}
+/** UTC-midnight epoch ms for a given instant (the Day-P&L boundary). */
+export function utcMidnightMs(now = Date.now()) {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+/** sessionStartNav = wallet_now − netNonTransfer_since_midnight.
+ *  dayPnl = NAV − sessionStartNav (computed by the caller each tick). */
+export function deriveSessionStartNav(args) {
+    return args.walletNow - args.netNonTransfer;
+}
+/** A capital flow (deposit / withdraw / internal transfer) changes the wallet
+ *  WITHOUT being trading P&L — bump the anchor by the same signed amount so it
+ *  never shows up as Day-P&L (the DepositTracker rule).
+ *
+ *  T-3 note: the `delta.type` enum is OPEN (docs incomplete; only
+ *  `internalTransfer` observed so far). We therefore treat any ledger row that
+ *  carries a usdc delta as a capital flow rather than switch on a closed set — an
+ *  UNKNOWN type must never be silently dropped, or the anchor drifts. */
+export function applyLedgerDelta(args) {
+    let bump = 0;
+    let applied = 0;
+    for (const row of args.ledgerRows) {
+        if (!Number.isFinite(row.time) || row.time < args.sinceMs)
+            continue;
+        const usdc = num(row.delta?.usdc);
+        if (usdc === 0)
+            continue;
+        bump += usdc;
+        applied += 1;
+    }
+    return { sessionStartNav: args.sessionStartNav + bump, applied };
+}
+/** ★ Close-bypass mapping (§5.9) — HL signals → journal close reasons.
+ *
+ *  A position can leave our control without our close path running: a bracket
+ *  triggering, a LIQUIDATION, an ADL, or a delisting. Each must land in the
+ *  journal honestly (the KPI and the learning loop both read these), never as a
+ *  silent disappearance. */
+export function mapHlCloseReason(signal) {
+    if (signal.liquidation) {
+        // HL marks backstop (HLP vault) liquidations distinctly from market ones; ADL
+        // arrives as a liquidation of the OPPOSITE side hitting us.
+        const method = (signal.liquidation.method ?? '').toLowerCase();
+        return method.includes('adl') ? 'adl' : 'liquidated';
+    }
+    const status = (signal.orderStatus ?? '').toLowerCase();
+    if (status === 'liquidatedcanceled')
+        return 'liquidated';
+    if (status === 'delistedcanceled')
+        return 'venue_delisted';
+    if (signal.bracketRole === 'stop')
+        return 'exchange_stop';
+    if (signal.bracketRole === 'target')
+        return 'exchange_target';
+    return null;
+}

package/venues/hyperliquid/hl-bracket-coordinator.d.ts

@@ -0,0 +1,123 @@
+import { EventEmitter } from 'node:events';
+import type { CcxtOrder, CcxtPosition } from '../../types.js';
+import type { CloseReason } from '../../simulator/types.js';
+import type { BracketId, BracketRequest, BracketState } from '../../live/bracket-types.js';
+import type { BracketLedger } from '../../live/bracket-ledger.js';
+import type { HlOrderUpdateEvent } from './hl-user-stream.js';
+/** Narrow execution surface the coordinator needs — the HyperliquidLiveAdapter
+ *  implements it; tests mock it without a network. */
+export interface HlBracketExecutor {
+    attachBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+        stopPrice?: number;
+        targetPrice?: number;
+    }): Promise<{
+        orders: CcxtOrder[];
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    resizeBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+    }): Promise<{
+        resized: boolean;
+        slCid?: string;
+        tpCid?: string;
+    }>;
+    /** Cancel one leg by cloid. Idempotent — "already gone" must not throw. */
+    cancelBracketLeg(cloid: string, symbol: string): Promise<void>;
+    /** Coverage audit — THROWS when order state is unknown (null ≠ empty). */
+    auditBracketCoverage(symbol: string, positionSize: number): Promise<{
+        covered: boolean;
+        shortfall: {
+            stop: number;
+            target: number;
+        };
+        missing: ('stop' | 'target')[];
+    }>;
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+}
+export interface HlAttachResult {
+    ok: boolean;
+    latencyMs: number;
+    slCid?: string;
+    tpCid?: string;
+    error?: string;
+    attempts: number;
+}
+export interface HlCoordinatorOpts {
+    maxAttempts?: number;
+    retryBackoffMs?: (attempt: number) => number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function isTerminalBracketState(state: BracketState): boolean;
+export declare class HlBracketCoordinator extends EventEmitter {
+    private readonly executor;
+    private readonly ledger;
+    private readonly maxAttempts;
+    private readonly backoff;
+    private readonly now;
+    private readonly sleep;
+    /** Per-symbol in-flight guard so a WS fill + the createOrder return path
+     *  can't both run attachOnFill concurrently (double-submit). */
+    private readonly inFlight;
+    /** Cloids WE deliberately cancelled (resize/modify supersede, retry cleanup,
+     *  cancelBrackets). Their WS 'canceled' events are OUR OWN and must never
+     *  trip the stripped-protection canary — the T-8 testnet run proved the WS
+     *  event can arrive BEFORE the ledger's fresh-cid update lands, so a
+     *  generation check alone loses the race. Entries pruned after 5 min. */
+    private readonly ownCancels;
+    constructor(executor: HlBracketExecutor, ledger: BracketLedger, opts?: HlCoordinatorOpts);
+    getLedger(): BracketLedger;
+    /** Record a leg cancel WE initiated (see `ownCancels`). The adapter calls
+     *  this for every deliberate leg cancel, including the resize path's direct
+     *  api cancels, BEFORE the cancel request goes out. */
+    noteOwnLegCancel(cloid: string): void;
+    /** Same anti-clobber contract as BracketManager.registerEntry: a duplicate
+     *  fill signal against a non-terminal row is a warned NO-OP, never a fresh
+     *  bracketId that orphans the live legs' ledger identity. */
+    registerEntry(req: BracketRequest, bracketId: BracketId, entryCid: string): void;
+    /** Attach both legs (ONE batched signed action) with retries. Idempotent on
+     *  a non-pending row. On exhaustion: ledger 'failed' + attach_failed event —
+     *  the ADAPTER escalates to auto-flatten (it owns closePosition). */
+    attachOnFill(symbol: string, filledSize: number): Promise<HlAttachResult>;
+    /** ★ T-2: bring the legs to the CURRENT position size (scale-in / partial
+     *  fill growth). Submit-first-then-cancel inside the adapter. Updates the
+     *  ledger's qty + fresh cids on success. */
+    resizeToPosition(symbol: string, newPositionSize: number): Promise<{
+        resized: boolean;
+    }>;
+    /** Move the stop. HL ordering: submit the NEW leg first, then cancel the old
+     *  one — over-protection for a moment beats a naked window (see header). */
+    modifyStop(symbol: string, newStopPrice: number): Promise<void>;
+    modifyTarget(symbol: string, newTargetPrice: number): Promise<void>;
+    private modifyLeg;
+    /** Cancel both legs, mark cancelled. Risk-reducing; best-effort per leg. */
+    cancelBrackets(symbol: string, reason: string): Promise<void>;
+    /**
+     * The HL analog of the Binance ALGO_UPDATE handler — `orderUpdates` is
+     * authoritative for bracket-leg lifecycle. Returns the transition applied
+     * (for the adapter to emit drift/close-bypass signals on triggers).
+     */
+    handleOrderUpdate(update: HlOrderUpdateEvent): 'triggered_sl' | 'triggered_tp' | 'forced_close' | null;
+    /**
+     * ★ T-5 mandate: REST truth-check. Runs after every WS (re)connect AND on the
+     * periodic sweep. TRUSTED reads only — a null positions fetch skips the pass
+     * (never act on unknown). Self-heals: pending rows whose entry filled while
+     * we were blind get their legs attached; undersized legs get resized; flat
+     * positions get their rows closed out (T-1 already cancelled the legs).
+     * Returns symbols whose rows were closed out (close-bypass signals for the
+     * adapter's drift pipeline).
+     */
+    resyncAgainstExchange(reasonTag: string): Promise<{
+        closedSymbols: string[];
+    }>;
+    private emitEvent;
+}