perp-cli 0.12.15 → 0.14.0

package/dist/arb/file-lock.js

@@ -0,0 +1,74 @@
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from "fs";
+import { resolve } from "path";
+import { PerpError } from "../errors.js";
+/** How long to wait for another process's lock, and when a lock left by a dead process is stale. */
+export const FILE_LOCK_WAIT_MS = 5_000;
+export const FILE_LOCK_STALE_MS = 30_000;
+/** Locks this process holds (path → depth): a nested load-modify-save in the same process never self-deadlocks. */
+const held = new Map();
+/**
+ * Run `fn` holding the advisory lock file `<path>.lock` (O_EXCL create) — for a load → modify →
+ * save of a state file shared by several perp processes (bots, daemons, CLI), so one process
+ * never overwrites another's concurrent write. A lock older than FILE_LOCK_STALE_MS (its holder
+ * died) is removed; a live one not released within FILE_LOCK_WAIT_MS → LOCK_HELD (nothing is
+ * written on top of an unknown concurrent write).
+ */
+export function withFileLock(path, what, fn) {
+    const lock = `${path}.lock`;
+    const depth = held.get(lock) ?? 0;
+    if (depth > 0) {
+        held.set(lock, depth + 1);
+        try {
+            return fn();
+        }
+        finally {
+            held.set(lock, depth);
+        }
+    }
+    const dir = resolve(path, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + FILE_LOCK_WAIT_MS;
+    const sleeper = new Int32Array(new SharedArrayBuffer(4));
+    for (;;) {
+        try {
+            closeSync(openSync(lock, "wx", 0o600));
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            let stale = false;
+            try {
+                stale = Date.now() - statSync(lock).mtimeMs > FILE_LOCK_STALE_MS;
+            }
+            catch {
+                continue; // released between the open and the stat: try again
+            }
+            if (stale) {
+                try {
+                    unlinkSync(lock);
+                }
+                catch { /* another process removed it */ }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new PerpError("LOCK_HELD", `${what} is locked by another perp process (${lock})`, {
+                    remediation: `Retry shortly; if no other perp process is running, delete ${lock}`,
+                });
+            }
+            Atomics.wait(sleeper, 0, 0, 10);
+        }
+    }
+    held.set(lock, 1);
+    try {
+        return fn();
+    }
+    finally {
+        held.delete(lock);
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* already gone */ }
+    }
+}

package/dist/arb/index.d.ts

@@ -1,7 +1,7 @@
-export { computeMatchedSize, computeSpotPerpMatchedSize, reconcileArbFills } from "./sizing.js";
+export { computeMatchedSize, computeSpotPerpMatchedSize } from "./sizing.js";
 export { SETTLEMENT_SCHEDULES, getLastSettlement, getMinutesSinceSettlement, aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk, formatNotifyMessage, sendNotification, notifyIfEnabled, } from "./utils.js";
 export type { SettleStrategy, BasisRisk, ArbNotifyEvent } from "./utils.js";
-export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, getPositions, createInitialState, } from "./state.js";
+export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, removePositionEntry, updatePositionEntry, positionKey, getPositions, createInitialState, } from "./state.js";
 export type { ArbPositionState, ArbDaemonState } from "./state.js";
 export { computeEnhancedStats } from "./history-stats.js";
 export type { ArbTradeForStats, ExchangePairPerf, TimeOfDayPerf, EnhancedHistoryStats } from "./history-stats.js";

package/dist/arb/index.js

@@ -1,5 +1,5 @@
 // arb/ barrel — public API
-export { computeMatchedSize, computeSpotPerpMatchedSize, reconcileArbFills } from "./sizing.js";
+export { computeMatchedSize, computeSpotPerpMatchedSize } from "./sizing.js";
 export { SETTLEMENT_SCHEDULES, getLastSettlement, getMinutesSinceSettlement, aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk, formatNotifyMessage, sendNotification, notifyIfEnabled, } from "./utils.js";
-export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, getPositions, createInitialState, } from "./state.js";
+export { setStateFilePath, resetStateFilePath, loadArbState, saveArbState, addPosition, removePosition, updatePosition, removePositionEntry, updatePositionEntry, positionKey, getPositions, createInitialState, } from "./state.js";
 export { computeEnhancedStats } from "./history-stats.js";

package/dist/arb/pending-entry.d.ts

@@ -0,0 +1,32 @@
+import type { Network } from "../exchanges/venue-types.js";
+/**
+ * Pending-entry records of the arb daemons (`arb auto`, `arb auto --hip3`) — PER NETWORK, next to
+ * the arb state (`arb-state.json` → `arb-state.pending.json`, testnet → `arb-state.testnet.pending.json`).
+ *
+ * A record is written BEFORE the first leg of a pair entry and removed once the pair is in the
+ * arb state / in memory, or rolled back / quarantined. A record that is still there when a daemon
+ * of the same source starts means the previous process died (crash, kill) between two legs: what
+ * is open is unknown → the symbol is quarantined (never re-entered, never "flat").
+ */
+export interface PendingEntry {
+    /** Daemon that wrote it: "arb-auto" | "arb-dex-auto". */
+    source: string;
+    symbol: string;
+    longExchange: string;
+    shortExchange: string;
+    /** Requested base size per leg. */
+    size: string;
+    startedAt: string;
+    pid: number;
+}
+export declare function pendingEntryFilePath(network: Network): string;
+/** Record an entry about to send its first leg. Throws when it cannot be persisted (the caller must not trade). */
+export declare function writePendingEntry(network: Network, e: Omit<PendingEntry, "startedAt" | "pid">): void;
+/** The entry's outcome is recorded (state / memory / rollback / quarantine): drop its pending record. */
+export declare function clearPendingEntry(network: Network, source: string, symbol: string): void;
+/**
+ * Pending records of `source` left by a process that is no longer running (crashed / killed
+ * mid-entry). Read-only: the caller quarantines each one, then clears it (clearPendingEntry).
+ * Records of a live process (another daemon still entering) are not returned.
+ */
+export declare function orphanedPendingEntries(network: Network, source: string): PendingEntry[];

package/dist/arb/pending-entry.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { PerpError } from "../errors.js";
+import { withFileLock } from "./file-lock.js";
+import { arbStateFilePath } from "./state.js";
+export function pendingEntryFilePath(network) {
+    const state = arbStateFilePath(network);
+    return state.endsWith(".json") ? `${state.slice(0, -5)}.pending.json` : `${state}.pending`;
+}
+function keyOf(source, symbol) {
+    return `${source}:${symbol.toUpperCase()}`;
+}
+/** A missing file = no pending entry; an unreadable / malformed one throws (never "none pending"). */
+function load(path) {
+    if (!existsSync(path))
+        return { version: 1, entries: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        throw new PerpError("INVALID_PARAMS", `Arb pending-entry file is unreadable: ${path} (${e instanceof Error ? e.message : String(e)})`, {
+            remediation: `Check the symbols it names on the venues (perp arb status), then fix or remove ${path}`,
+        });
+    }
+    const f = parsed;
+    if (f === null || f.version !== 1 || typeof f.entries !== "object" || f.entries === null) {
+        throw new PerpError("INVALID_PARAMS", `Arb pending-entry file has an unexpected shape: ${path}`, {
+            remediation: `Check the symbols it names on the venues (perp arb status), then fix or remove ${path}`,
+        });
+    }
+    return f;
+}
+function save(path, f) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(f, null, 2), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+function modify(network, fn) {
+    const path = pendingEntryFilePath(network);
+    return withFileLock(path, `Arb pending-entry file (${network})`, () => {
+        const f = load(path);
+        const out = fn(f);
+        save(path, f);
+        return out;
+    });
+}
+/** Record an entry about to send its first leg. Throws when it cannot be persisted (the caller must not trade). */
+export function writePendingEntry(network, e) {
+    modify(network, (f) => {
+        f.entries[keyOf(e.source, e.symbol)] = { ...e, startedAt: new Date().toISOString(), pid: process.pid };
+    });
+}
+/** The entry's outcome is recorded (state / memory / rollback / quarantine): drop its pending record. */
+export function clearPendingEntry(network, source, symbol) {
+    modify(network, (f) => { delete f.entries[keyOf(source, symbol)]; });
+}
+function alive(pid) {
+    if (pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: the process exists (another user) — treat as alive.
+        return e.code === "EPERM";
+    }
+}
+/**
+ * Pending records of `source` left by a process that is no longer running (crashed / killed
+ * mid-entry). Read-only: the caller quarantines each one, then clears it (clearPendingEntry).
+ * Records of a live process (another daemon still entering) are not returned.
+ */
+export function orphanedPendingEntries(network, source) {
+    const f = load(pendingEntryFilePath(network));
+    return Object.values(f.entries).filter(e => e.source === source && !alive(e.pid));
+}

package/dist/arb/sizing.d.ts

@@ -1,4 +1,3 @@
-import type { ExchangeAdapter } from "../exchanges/index.js";
 /**
  * Calculate the exact same size for both legs of an arb position,
  * respecting both exchanges' minimum order and size precision constraints.
@@ -9,6 +8,12 @@ export declare function computeMatchedSize(sizeUsd: number, price: number, longE
     longSizeDecimals?: number;
     shortSizeDecimals?: number;
     lotSize?: number;
+    /**
+     * The pair's minimum order value in USD from the venues' published market info (the larger of
+     * the two legs; 0 = neither venue publishes one). When given it is the ONLY minimum applied —
+     * the per-venue table below is for callers that have no market info at hand.
+     */
+    minNotional?: number;
 }): {
     size: string;
     notional: number;
@@ -21,15 +26,3 @@ export declare function computeSpotPerpMatchedSize(sizeUsd: number, price: numbe
     size: string;
     notional: number;
 } | null;
-/**
- * After both legs are submitted, verify actual fills match.
- * If there's a size mismatch, place a correction order on the larger side.
- *
- * @returns the corrected size, or null if already matched
- */
-export declare function reconcileArbFills(longAdapter: ExchangeAdapter, shortAdapter: ExchangeAdapter, symbol: string, log?: (msg: string) => void): Promise<{
-    matched: boolean;
-    longSize: number;
-    shortSize: number;
-    correction?: string;
-}>;

package/dist/arb/sizing.js

@@ -24,7 +24,9 @@ export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange,
         return null;
     // Verify notional meets minimum for both exchanges
     const notional = roundedSize * price;
-    const minNotional = Math.max(getMinNotional(longExchange), getMinNotional(shortExchange));
+    const minNotional = opts?.minNotional !== undefined
+        ? opts.minNotional
+        : Math.max(getMinNotional(longExchange), getMinNotional(shortExchange));
     if (notional < minNotional) {
         // Try rounding UP instead
         let roundedUp;
@@ -36,11 +38,14 @@ export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange,
             roundedUp = Math.ceil(rawSize * factor) / factor;
         }
         const notionalUp = roundedUp * price;
-        // Only round up if the increase is small (< 20% over requested)
-        if (notionalUp <= sizeUsd * 1.2) {
+        // Round up only if it both (a) clears the venue minimum and (b) does not
+        // overshoot the requested size by more than 20%. Pre-fix this checked only
+        // (b), so a ceil that still fell short of minNotional was returned and then
+        // rejected by the venue — SSOT Rule #2: fail honestly with null instead.
+        if (notionalUp >= minNotional && notionalUp <= sizeUsd * 1.2) {
             return { size: formatSize(roundedUp, szDecimals, opts?.lotSize), notional: notionalUp };
         }
-        return null; // Can't meet minimum
+        return null; // Can't meet minimum within tolerance
     }
     return { size: formatSize(roundedSize, szDecimals, opts?.lotSize), notional };
 }
@@ -94,56 +99,12 @@ export function computeSpotPerpMatchedSize(sizeUsd, price, spotExchange, perpExc
     if (notional < minNotional) {
         const roundedUp = Math.ceil(rawSize * factor) / factor;
         const notionalUp = roundedUp * price;
-        if (notionalUp <= sizeUsd * 1.2) {
+        // Same minNotional re-check as computeMatchedSize (SSOT Rule #2): a ceil
+        // that is still under the venue minimum must fail, not be returned.
+        if (notionalUp >= minNotional && notionalUp <= sizeUsd * 1.2) {
             return { size: roundedUp.toFixed(szDecimals), notional: notionalUp };
         }
         return null;
     }
     return { size: roundedSize.toFixed(szDecimals), notional };
 }
-/**
- * After both legs are submitted, verify actual fills match.
- * If there's a size mismatch, place a correction order on the larger side.
- *
- * @returns the corrected size, or null if already matched
- */
-export async function reconcileArbFills(longAdapter, shortAdapter, symbol, log) {
-    const [longPositions, shortPositions] = await Promise.all([
-        longAdapter.getPositions(),
-        shortAdapter.getPositions(),
-    ]);
-    const longPos = longPositions.find(p => p.symbol.replace("-PERP", "").toUpperCase() === symbol.toUpperCase() && p.side === "long");
-    const shortPos = shortPositions.find(p => p.symbol.replace("-PERP", "").toUpperCase() === symbol.toUpperCase() && p.side === "short");
-    const longSize = longPos ? Math.abs(Number(longPos.size)) : 0;
-    const shortSize = shortPos ? Math.abs(Number(shortPos.size)) : 0;
-    if (longSize === 0 && shortSize === 0) {
-        return { matched: true, longSize: 0, shortSize: 0 };
-    }
-    const diff = Math.abs(longSize - shortSize);
-    const maxSize = Math.max(longSize, shortSize);
-    const diffPct = maxSize > 0 ? (diff / maxSize) * 100 : 0;
-    // Allow 1% tolerance (rounding differences)
-    if (diffPct <= 1) {
-        return { matched: true, longSize, shortSize };
-    }
-    log?.(`[ARB] Size mismatch: long ${longSize} vs short ${shortSize} (diff: ${diff.toFixed(4)}, ${diffPct.toFixed(1)}%)`);
-    // Correct the larger side by reducing it
-    const correctionSize = diff.toFixed(6);
-    try {
-        if (longSize > shortSize) {
-            log?.(`[ARB] Correcting: sell ${correctionSize} ${symbol} on ${longAdapter.name} to match`);
-            await longAdapter.marketOrder(symbol, "sell", correctionSize);
-        }
-        else {
-            log?.(`[ARB] Correcting: buy ${correctionSize} ${symbol} on ${shortAdapter.name} to match`);
-            await shortAdapter.marketOrder(symbol, "buy", correctionSize);
-        }
-        log?.(`[ARB] Sizes reconciled`);
-        return { matched: true, longSize: Math.min(longSize, shortSize), shortSize: Math.min(longSize, shortSize), correction: correctionSize };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log?.(`[ARB] Correction failed: ${msg}`);
-        return { matched: false, longSize, shortSize };
-    }
-}

package/dist/arb/state.d.ts

@@ -1,5 +1,8 @@
+import type { Network } from "../exchanges/venue-types.js";
 export declare function setStateFilePath(path: string): void;
 export declare function resetStateFilePath(): void;
+/** Absolute state-file path for `network` (mainnet = the pre-network path). */
+export declare function arbStateFilePath(network: Network): string;
 export interface ArbPositionState {
     id: string;
     symbol: string;
@@ -9,8 +12,9 @@ export interface ArbPositionState {
     shortSize: number;
     entryTime: string;
     entrySpread: number;
-    entryLongPrice: number;
-    entryShortPrice: number;
+    /** null = no verified fill price was reported for the leg (a strategy-bot entry; never a guess). */
+    entryLongPrice: number | null;
+    entryShortPrice: number | null;
     accumulatedFunding: number;
     lastCheckTime: string;
     /** "perp-perp" (default) or "spot-perp" */
@@ -22,6 +26,8 @@ export interface ArbPositionState {
 }
 export interface ArbDaemonState {
     version: 1;
+    /** Network the positions live on. Absent only in files written before per-network state (= mainnet). */
+    network?: Network;
     lastStartTime: string;
     lastScanTime: string;
     lastSuccessfulScanTime: string;
@@ -37,21 +43,48 @@ export interface ArbDaemonState {
         notifyUrl?: string;
     };
 }
-/** Load daemon state from disk. Falls back to .tmp if main file is corrupted. */
-export declare function loadArbState(): ArbDaemonState | null;
+/** Load the daemon state for `network`. Falls back to .tmp if main file is corrupted. */
+export declare function loadArbState(network: Network, opts?: {
+    readOnly: boolean;
+}): ArbDaemonState | null;
 /**
  * Save daemon state to disk using atomic write pattern.
  * Writes to .tmp first, then renames to main file.
  * If crash occurs mid-write, .tmp is partial but main file is intact.
  */
-export declare function saveArbState(state: ArbDaemonState): void;
-/** Add a position to the persisted state. Auto-initializes state if missing. */
-export declare function addPosition(pos: ArbPositionState): void;
-/** Remove a position by symbol from the persisted state. */
-export declare function removePosition(symbol: string): void;
+export declare function saveArbState(network: Network, state: ArbDaemonState): void;
+/** Identity of a state entry: symbol + long venue + short venue + mode (absent mode = perp-perp). */
+export declare function positionKey(p: Pick<ArbPositionState, "symbol" | "longExchange" | "shortExchange" | "mode">): string;
+/**
+ * Put `pos` into `positions`: an entry with the same key is replaced (a re-record of the same
+ * pair); an entry of the same symbol on OTHER venues / another mode is never overwritten —
+ * RISK_VIOLATION (the state tracks one pair per symbol; overwriting would drop a live pair).
+ */
+export declare function upsertPosition(positions: ArbPositionState[], pos: ArbPositionState): ArbPositionState[];
+/** Add a position to the persisted state for `network`. Auto-initializes state if missing. Throws RISK_VIOLATION for a conflicting entry (upsertPosition). */
+export declare function addPosition(network: Network, pos: ArbPositionState): void;
+/** Remove a position by symbol from the persisted state for `network` (one entry per symbol: upsertPosition). */
+export declare function removePosition(network: Network, symbol: string): void;
+/** Remove exactly the entry with `entry`'s key (symbol + venues + mode); another pair of the symbol is left alone. */
+export declare function removePositionEntry(network: Network, entry: Pick<ArbPositionState, "symbol" | "longExchange" | "shortExchange" | "mode">): void;
 /** Update a position by symbol with partial updates. */
-export declare function updatePosition(symbol: string, updates: Partial<ArbPositionState>): void;
-/** Get all persisted positions. */
-export declare function getPositions(): ArbPositionState[];
+export declare function updatePosition(network: Network, symbol: string, updates: Partial<ArbPositionState>): void;
+/** Update exactly the entry with `entry`'s key (symbol + venues + mode). */
+export declare function updatePositionEntry(network: Network, entry: Pick<ArbPositionState, "symbol" | "longExchange" | "shortExchange" | "mode">, updates: Partial<ArbPositionState>): void;
+/** Get all persisted positions for `network`. */
+export declare function getPositions(network: Network): ArbPositionState[];
 /** Create a default empty daemon state with the given config. */
 export declare function createInitialState(config: ArbDaemonState["config"]): ArbDaemonState;
+/** State access for the `arb auto` daemon (see createDaemonStateStore). */
+export interface DaemonStateStore {
+    load(): ArbDaemonState | null;
+    save(next: ArbDaemonState): void;
+    add(pos: ArbPositionState): void;
+    remove(symbol: string): void;
+}
+/**
+ * Live: the per-network state file. Dry-run (review N3): an in-memory copy seeded READ-ONLY
+ * from the real state — nothing is ever written to disk, so a simulated entry is never picked
+ * up by a live run and a simulated close never drops a real position from tracking.
+ */
+export declare function createDaemonStateStore(network: Network, dryRun: boolean, config: ArbDaemonState["config"]): DaemonStateStore;