@reefclaw/connect 0.1.11 → 0.1.12

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

@@ -1,116 +0,0 @@
-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/assets/plugin/venues/hyperliquid/hl-balance.js

@@ -1,145 +0,0 @@
-// 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/assets/plugin/venues/hyperliquid/hl-bracket-coordinator.d.ts

@@ -1,123 +0,0 @@
-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;
-}