@raintree-technology/perps 0.1.0

package/dist/lib/db/index.js

@@ -0,0 +1,272 @@
+import Database from "better-sqlite3";
+import { copyFileSync, existsSync } from "node:fs";
+import { HL_DIR, DB_PATH, LEGACY_DB_PATH } from "../paths.js";
+import { ensurePrivateDir, hardenPrivateFile } from "../fs-security.js";
+let db = null;
+/**
+ * Get or create the database connection
+ */
+export function getDb() {
+    if (db) {
+        return db;
+    }
+    // Ensure runtime storage is private to the local user.
+    ensurePrivateDir(HL_DIR);
+    // One-time migration for pre-rename databases (~/.hl/hl.db -> ~/.perp/perp.db).
+    if (!existsSync(DB_PATH) && existsSync(LEGACY_DB_PATH)) {
+        copyFileSync(LEGACY_DB_PATH, DB_PATH);
+        hardenPrivateFile(DB_PATH);
+    }
+    db = new Database(DB_PATH);
+    hardenPrivateFile(DB_PATH);
+    // Enable foreign keys
+    db.pragma("foreign_keys = ON");
+    // Run migrations
+    runMigrations(db);
+    return db;
+}
+/**
+ * Close the database connection
+ */
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+/**
+ * Run database migrations
+ */
+function runMigrations(db) {
+    // Create migrations table if it doesn't exist
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS migrations (
+      id INTEGER PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      applied_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+    )
+  `);
+    const migrations = [
+        {
+            name: "001_create_accounts",
+            sql: `
+        CREATE TABLE IF NOT EXISTS accounts (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          alias TEXT NOT NULL,
+          user_address TEXT NOT NULL,
+          type TEXT NOT NULL CHECK (type IN ('readonly', 'api_wallet')),
+          source TEXT NOT NULL DEFAULT 'cli_import',
+          api_wallet_private_key TEXT,
+          api_wallet_public_key TEXT,
+          is_default INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+          updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+        );
+
+        -- Index for quick default account lookup
+        CREATE INDEX IF NOT EXISTS idx_accounts_is_default ON accounts(is_default);
+
+        -- Index for user address lookups
+        CREATE INDEX IF NOT EXISTS idx_accounts_user_address ON accounts(user_address);
+      `,
+        },
+        {
+            name: "002_add_exchange_column",
+            sql: `
+        -- Add exchange column with default 'hyperliquid' for existing accounts
+        ALTER TABLE accounts ADD COLUMN exchange TEXT NOT NULL DEFAULT 'hyperliquid';
+        
+        -- Make alias unique per exchange (not globally)
+        CREATE INDEX IF NOT EXISTS idx_accounts_exchange ON accounts(exchange);
+        CREATE INDEX IF NOT EXISTS idx_accounts_alias_exchange ON accounts(alias, exchange);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_alias_exchange_unique ON accounts(alias, exchange);
+      `,
+        },
+        {
+            name: "003_create_funding_history",
+            sql: `
+        -- Funding rate history for arbitrage analysis
+        CREATE TABLE IF NOT EXISTS funding_history (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          exchange TEXT NOT NULL,
+          market TEXT NOT NULL,
+          rate REAL NOT NULL,           -- Hourly rate as decimal (e.g., 0.0001 = 0.01%)
+          annualized REAL NOT NULL,     -- Annualized rate
+          next_funding INTEGER,         -- Next funding timestamp
+          recorded_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+        );
+        
+        CREATE INDEX IF NOT EXISTS idx_funding_exchange_market ON funding_history(exchange, market);
+        CREATE INDEX IF NOT EXISTS idx_funding_recorded_at ON funding_history(recorded_at);
+        CREATE INDEX IF NOT EXISTS idx_funding_market_time ON funding_history(market, recorded_at);
+      `,
+        },
+        {
+            name: "004_rebuild_accounts_alias_scope",
+            sql: `
+        PRAGMA foreign_keys = OFF;
+
+        CREATE TABLE accounts_new (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          alias TEXT NOT NULL,
+          exchange TEXT NOT NULL,
+          user_address TEXT NOT NULL,
+          type TEXT NOT NULL CHECK (type IN ('readonly', 'api_wallet')),
+          source TEXT NOT NULL DEFAULT 'cli_import',
+          api_wallet_private_key TEXT,
+          api_wallet_public_key TEXT,
+          is_default INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+          updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+          UNIQUE(alias, exchange)
+        );
+
+        INSERT INTO accounts_new (
+          id,
+          alias,
+          exchange,
+          user_address,
+          type,
+          source,
+          api_wallet_private_key,
+          api_wallet_public_key,
+          is_default,
+          created_at,
+          updated_at
+        )
+        SELECT
+          id,
+          alias,
+          exchange,
+          user_address,
+          type,
+          source,
+          api_wallet_private_key,
+          api_wallet_public_key,
+          is_default,
+          created_at,
+          updated_at
+        FROM accounts;
+
+        DROP TABLE accounts;
+        ALTER TABLE accounts_new RENAME TO accounts;
+
+        CREATE INDEX IF NOT EXISTS idx_accounts_is_default ON accounts(is_default);
+        CREATE INDEX IF NOT EXISTS idx_accounts_user_address ON accounts(user_address);
+        CREATE INDEX IF NOT EXISTS idx_accounts_exchange ON accounts(exchange);
+        CREATE INDEX IF NOT EXISTS idx_accounts_alias_exchange ON accounts(alias, exchange);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_alias_exchange_unique ON accounts(alias, exchange);
+
+        PRAGMA foreign_keys = ON;
+      `,
+        },
+        {
+            name: "005_create_execution_journal",
+            sql: `
+        CREATE TABLE IF NOT EXISTS execution_journal (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          idempotency_key TEXT NOT NULL UNIQUE,
+          request_hash TEXT NOT NULL,
+          command TEXT NOT NULL,
+          exchange TEXT NOT NULL,
+          testnet INTEGER NOT NULL DEFAULT 0,
+          market TEXT,
+          side TEXT,
+          order_type TEXT,
+          status TEXT NOT NULL CHECK (status IN ('pending', 'succeeded', 'failed')),
+          request_json TEXT NOT NULL,
+          result_json TEXT,
+          error_message TEXT,
+          created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+          updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+          completed_at INTEGER
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_execution_journal_status ON execution_journal(status);
+        CREATE INDEX IF NOT EXISTS idx_execution_journal_exchange_created ON execution_journal(exchange, created_at);
+        CREATE INDEX IF NOT EXISTS idx_execution_journal_created ON execution_journal(created_at);
+      `,
+        },
+        {
+            name: "006_create_risk_rules",
+            sql: `
+        CREATE TABLE IF NOT EXISTS risk_rules (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          name TEXT NOT NULL UNIQUE,
+          type TEXT NOT NULL CHECK(type IN ('max_position_size', 'max_total_exposure', 'max_leverage', 'max_drawdown', 'min_confidence', 'cooldown_after_loss', 'rate_limit')),
+          scope TEXT NOT NULL CHECK(scope IN ('global', 'exchange', 'market', 'strategy')),
+          scope_value TEXT,
+          value REAL NOT NULL,
+          enabled INTEGER NOT NULL DEFAULT 1,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+        CREATE INDEX IF NOT EXISTS idx_risk_rules_scope ON risk_rules(scope, scope_value);
+        CREATE INDEX IF NOT EXISTS idx_risk_rules_enabled ON risk_rules(enabled);
+      `,
+        },
+        {
+            name: "007_create_risk_evaluation_log",
+            sql: `
+        CREATE TABLE IF NOT EXISTS risk_evaluation_log (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          trace_id TEXT,
+          exchange TEXT NOT NULL,
+          market TEXT,
+          side TEXT,
+          requested_size_usd REAL NOT NULL,
+          equity REAL NOT NULL,
+          exposure_usd REAL NOT NULL,
+          confidence REAL,
+          allowed INTEGER NOT NULL,
+          adjusted_size_usd REAL,
+          drawdown_pct REAL,
+          rules_evaluated TEXT,
+          rules_fired TEXT,
+          reason TEXT,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+        CREATE INDEX IF NOT EXISTS idx_risk_eval_trace ON risk_evaluation_log(trace_id);
+        CREATE INDEX IF NOT EXISTS idx_risk_eval_time ON risk_evaluation_log(created_at);
+        CREATE INDEX IF NOT EXISTS idx_risk_eval_allowed ON risk_evaluation_log(allowed);
+      `,
+        },
+        {
+            name: "008_add_trace_id_to_journal",
+            sql: `ALTER TABLE execution_journal ADD COLUMN trace_id TEXT;
+        CREATE INDEX IF NOT EXISTS idx_journal_trace ON execution_journal(trace_id);`,
+        },
+        {
+            name: "009_create_trade_signals",
+            sql: `
+        CREATE TABLE IF NOT EXISTS trade_signals (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          trace_id TEXT,
+          exchange TEXT NOT NULL,
+          market TEXT,
+          strategy TEXT,
+          signal TEXT NOT NULL CHECK(signal IN ('up', 'down')),
+          reason TEXT,
+          pnl_usd REAL,
+          metadata TEXT,
+          created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+        );
+        CREATE INDEX IF NOT EXISTS idx_signals_trace ON trade_signals(trace_id);
+        CREATE INDEX IF NOT EXISTS idx_signals_exchange ON trade_signals(exchange);
+        CREATE INDEX IF NOT EXISTS idx_signals_signal ON trade_signals(signal);
+        CREATE INDEX IF NOT EXISTS idx_signals_time ON trade_signals(created_at);
+      `,
+        },
+    ];
+    const appliedMigrations = db
+        .prepare("SELECT name FROM migrations")
+        .all();
+    const appliedNames = new Set(appliedMigrations.map((m) => m.name));
+    for (const migration of migrations) {
+        if (!appliedNames.has(migration.name)) {
+            db.exec(migration.sql);
+            db.prepare("INSERT INTO migrations (name) VALUES (?)").run(migration.name);
+        }
+    }
+}
+export * from "./accounts.js";
+export * from "./funding-history.js";

package/dist/lib/events/bus.d.ts

@@ -0,0 +1,10 @@
+import type { EventMap } from "./types.js";
+export type { EventMap };
+declare class TypedEventBus {
+    private emitter;
+    on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    off<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    once<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+}
+export declare const eventBus: TypedEventBus;

package/dist/lib/events/bus.js

@@ -0,0 +1,17 @@
+import { EventEmitter } from "node:events";
+class TypedEventBus {
+    emitter = new EventEmitter();
+    on(event, handler) {
+        this.emitter.on(event, handler);
+    }
+    off(event, handler) {
+        this.emitter.off(event, handler);
+    }
+    once(event, handler) {
+        this.emitter.once(event, handler);
+    }
+    emit(event, data) {
+        this.emitter.emit(event, data);
+    }
+}
+export const eventBus = new TypedEventBus();

package/dist/lib/events/types.d.ts

@@ -0,0 +1,51 @@
+export interface EventMap {
+    "risk.circuit_breaker.tripped": {
+        exchange: string;
+        drawdownPct: number;
+        peakEquity: number;
+        currentEquity: number;
+        timestamp: number;
+    };
+    "risk.evaluation.denied": {
+        exchange: string;
+        market: string;
+        reason: string;
+        traceId?: string;
+        timestamp: number;
+    };
+    "order.filled": {
+        exchange: string;
+        market: string;
+        orderId: string;
+        side: string;
+        size: number;
+        price: number;
+        timestamp: number;
+    };
+    "position.opened": {
+        exchange: string;
+        market: string;
+        side: string;
+        size: number;
+        entryPrice: number;
+        timestamp: number;
+    };
+    "position.closed": {
+        exchange: string;
+        market: string;
+        side: string;
+        size: number;
+        entryPrice: number;
+        exitPrice: number;
+        pnl: number;
+        timestamp: number;
+    };
+    "operator.halt": {
+        reason: string;
+        source: "manual" | "drawdown" | "error";
+        timestamp: number;
+    };
+    "operator.resume": {
+        timestamp: number;
+    };
+}

package/dist/lib/events/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/exchange.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Exchange Factory and Context
+ * Provides adapter instances based on configuration
+ */
+import { type PerpDEXAdapter } from "../adapters/index.js";
+/**
+ * Set the current exchange context
+ */
+export declare function setExchange(exchangeId: string): void;
+/**
+ * Get the current exchange ID
+ */
+export declare function getExchangeId(): string;
+/**
+ * Get the current exchange adapter
+ * Creates a new instance if needed
+ */
+export declare function getExchangeAdapter(): PerpDEXAdapter;
+/**
+ * Get a specific exchange adapter by ID
+ */
+export declare function getExchangeAdapterById(exchangeId: string): PerpDEXAdapter;
+/**
+ * List all available exchanges
+ */
+export declare function getAvailableExchanges(): string[];
+/**
+ * Check if an exchange is supported
+ */
+export declare function isExchangeSupported(exchangeId: string): boolean;

package/dist/lib/exchange.js

@@ -0,0 +1,84 @@
+/**
+ * Exchange Factory and Context
+ * Provides adapter instances based on configuration
+ */
+import { getAdapter, listAdapters } from "../adapters/index.js";
+import { getSetting } from "./settings.js";
+// Current exchange context (set by CLI)
+let currentExchange = null;
+let currentAdapter = null;
+/**
+ * Get the default exchange from settings
+ */
+function getDefaultExchange() {
+    const available = listAdapters();
+    const fallback = "hyperliquid";
+    try {
+        const configured = getSetting("defaultExchange") || fallback;
+        if (available.includes(configured)) {
+            return configured;
+        }
+        return available.includes(fallback) ? fallback : available[0] ?? fallback;
+    }
+    catch {
+        return available.includes(fallback) ? fallback : available[0] ?? fallback;
+    }
+}
+/**
+ * Set the current exchange context
+ */
+export function setExchange(exchangeId) {
+    const id = exchangeId.toLowerCase();
+    if (!listAdapters().includes(id)) {
+        const available = listAdapters().join(", ");
+        throw new Error(`Unknown exchange: ${exchangeId}. Available: ${available}`);
+    }
+    currentExchange = id;
+    currentAdapter = null; // Reset adapter so it gets recreated
+}
+/**
+ * Get the current exchange ID
+ */
+export function getExchangeId() {
+    if (!currentExchange) {
+        currentExchange = getDefaultExchange();
+    }
+    return currentExchange;
+}
+/**
+ * Get the current exchange adapter
+ * Creates a new instance if needed
+ */
+export function getExchangeAdapter() {
+    const exchangeId = getExchangeId();
+    if (!currentAdapter) {
+        currentAdapter = getAdapter(exchangeId);
+        if (!currentAdapter) {
+            throw new Error(`Failed to create adapter for: ${exchangeId}`);
+        }
+    }
+    return currentAdapter;
+}
+/**
+ * Get a specific exchange adapter by ID
+ */
+export function getExchangeAdapterById(exchangeId) {
+    const adapter = getAdapter(exchangeId.toLowerCase());
+    if (!adapter) {
+        const available = listAdapters().join(", ");
+        throw new Error(`Unknown exchange: ${exchangeId}. Available: ${available}`);
+    }
+    return adapter;
+}
+/**
+ * List all available exchanges
+ */
+export function getAvailableExchanges() {
+    return listAdapters();
+}
+/**
+ * Check if an exchange is supported
+ */
+export function isExchangeSupported(exchangeId) {
+    return listAdapters().includes(exchangeId.toLowerCase());
+}

package/dist/lib/execution/journal.d.ts

@@ -0,0 +1,25 @@
+export declare const AUTO_IDEMPOTENCY_WINDOW_MS = 30000;
+export interface ExecutionJournalMetadata {
+    command: string;
+    exchange: string;
+    testnet: boolean;
+    market?: string;
+    side?: string;
+    orderType?: string;
+}
+export interface ExecutionJournalOptions<T> {
+    idempotencyKey?: string;
+    traceId?: string;
+    metadata: ExecutionJournalMetadata;
+    request: unknown;
+    execute: () => Promise<T>;
+}
+export interface ExecutionJournalResult<T> {
+    result: T;
+    idempotencyKey: string;
+    autoGeneratedKey: boolean;
+    replayed: boolean;
+    journalId: number;
+    traceId?: string;
+}
+export declare function runWithExecutionJournal<T>(options: ExecutionJournalOptions<T>): Promise<ExecutionJournalResult<T>>;

package/dist/lib/execution/journal.js

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { getDb } from "../db/index.js";
+import { stableStringify } from "../stable-stringify.js";
+export const AUTO_IDEMPOTENCY_WINDOW_MS = 30_000;
+function hashRequest(request) {
+    const canonical = stableStringify(request);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+function normalizeExplicitKey(input) {
+    if (!input) {
+        return null;
+    }
+    const key = input.trim();
+    if (!key) {
+        return null;
+    }
+    if (key.length > 128) {
+        throw new Error("Idempotency key must be 128 characters or fewer");
+    }
+    if (!/^[A-Za-z0-9:._/-]+$/.test(key)) {
+        throw new Error("Idempotency key contains invalid characters");
+    }
+    return key;
+}
+function resolveIdempotencyKey(explicitKey, requestHash, nowMs) {
+    const normalized = normalizeExplicitKey(explicitKey);
+    if (normalized) {
+        return { key: normalized, autoGenerated: false };
+    }
+    const bucket = Math.floor(nowMs / AUTO_IDEMPOTENCY_WINDOW_MS);
+    return {
+        key: `auto:${requestHash.slice(0, 24)}:${bucket}`,
+        autoGenerated: true,
+    };
+}
+function getByKey(idempotencyKey) {
+    const db = getDb();
+    const row = db
+        .prepare("SELECT * FROM execution_journal WHERE idempotency_key = ?")
+        .get(idempotencyKey);
+    return row ?? null;
+}
+function parseStoredResult(row) {
+    if (!row.result_json) {
+        throw new Error(`Execution journal entry ${row.id} is missing result payload`);
+    }
+    return JSON.parse(row.result_json);
+}
+function handleExistingRow(row, requestHash, resolved) {
+    if (row.request_hash !== requestHash) {
+        throw new Error(`Idempotency key "${resolved.key}" was already used for a different request`);
+    }
+    if (row.status === "succeeded") {
+        return {
+            result: parseStoredResult(row),
+            idempotencyKey: row.idempotency_key,
+            autoGeneratedKey: resolved.autoGenerated,
+            replayed: true,
+            journalId: row.id,
+        };
+    }
+    if (row.status === "pending") {
+        throw new Error(`Execution with idempotency key "${resolved.key}" is still pending. ` +
+            "Refusing retry to avoid duplicate orders.");
+    }
+    throw new Error(`Execution with idempotency key "${resolved.key}" already failed` +
+        (row.error_message ? `: ${row.error_message}` : ". Use a new key to retry."));
+}
+function insertPending(idempotencyKey, requestHash, requestJson, metadata, nowMs, traceId) {
+    const db = getDb();
+    const result = db.prepare(`
+    INSERT INTO execution_journal (
+      idempotency_key,
+      request_hash,
+      command,
+      exchange,
+      testnet,
+      market,
+      side,
+      order_type,
+      status,
+      request_json,
+      created_at,
+      updated_at,
+      trace_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, ?)
+  `).run(idempotencyKey, requestHash, metadata.command, metadata.exchange, metadata.testnet ? 1 : 0, metadata.market ?? null, metadata.side ?? null, metadata.orderType ?? null, requestJson, nowMs, nowMs, traceId ?? null);
+    return Number(result.lastInsertRowid);
+}
+function markSucceeded(idempotencyKey, result, nowMs) {
+    const db = getDb();
+    const resultJson = JSON.stringify(result ?? null);
+    db.prepare(`
+    UPDATE execution_journal
+    SET
+      status = 'succeeded',
+      result_json = ?,
+      error_message = NULL,
+      updated_at = ?,
+      completed_at = ?
+    WHERE idempotency_key = ?
+  `).run(resultJson, nowMs, nowMs, idempotencyKey);
+}
+function markFailed(idempotencyKey, err, nowMs) {
+    const db = getDb();
+    const errorMessage = err instanceof Error
+        ? `${err.name}: ${err.message}`
+        : String(err);
+    db.prepare(`
+    UPDATE execution_journal
+    SET
+      status = 'failed',
+      error_message = ?,
+      updated_at = ?,
+      completed_at = ?
+    WHERE idempotency_key = ?
+  `).run(errorMessage, nowMs, nowMs, idempotencyKey);
+}
+export async function runWithExecutionJournal(options) {
+    const now = Date.now();
+    const requestHash = hashRequest(options.request);
+    const requestJson = stableStringify(options.request);
+    const resolved = resolveIdempotencyKey(options.idempotencyKey, requestHash, now);
+    const existing = getByKey(resolved.key);
+    if (existing) {
+        return handleExistingRow(existing, requestHash, resolved);
+    }
+    let journalId;
+    try {
+        journalId = insertPending(resolved.key, requestHash, requestJson, options.metadata, now, options.traceId);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("UNIQUE constraint failed: execution_journal.idempotency_key")) {
+            const raceExisting = getByKey(resolved.key);
+            if (raceExisting) {
+                return handleExistingRow(raceExisting, requestHash, resolved);
+            }
+        }
+        throw err;
+    }
+    try {
+        const result = await options.execute();
+        markSucceeded(resolved.key, result, Date.now());
+        return {
+            result,
+            idempotencyKey: resolved.key,
+            autoGeneratedKey: resolved.autoGenerated,
+            replayed: false,
+            journalId,
+            traceId: options.traceId,
+        };
+    }
+    catch (err) {
+        markFailed(resolved.key, err, Date.now());
+        throw err;
+    }
+}

package/dist/lib/execution/safety.d.ts

@@ -0,0 +1,34 @@
+import type { Order, OrderParams, PerpDEXAdapter } from "../../adapters/interface.js";
+import type { ExecutionSafetyConfig } from "../config.js";
+export interface SafetyExecutionOptions {
+    closeThenFlip?: boolean;
+    spreadAwarePricing?: boolean;
+    spreadOffset?: number;
+    attachTpSl?: boolean;
+    tpSlConfig?: Pick<ExecutionSafetyConfig, "stopLossPct" | "takeProfitPct">;
+}
+export interface SafetyExecutionResult {
+    order: Order;
+    closedOppositePosition: boolean;
+    tpSlOrderIds: string[];
+    pricing?: {
+        source: "orderbook" | "ticker";
+        referencePrice: number;
+        spread?: number;
+    };
+}
+interface SpreadAwarePrice {
+    source: "orderbook" | "ticker";
+    referencePrice: number;
+    spread?: number;
+}
+export declare function executeOrderWithSafety(adapter: PerpDEXAdapter, params: OrderParams, options?: SafetyExecutionOptions): Promise<SafetyExecutionResult>;
+export declare function closeThenFlipIfNeeded(adapter: PerpDEXAdapter, market: string, desiredSide: "long" | "short"): Promise<boolean>;
+export declare function attachTpSlForPosition(adapter: PerpDEXAdapter, position: {
+    market: string;
+    side: "long" | "short";
+    size: string;
+    entryPrice: number;
+}, config: Pick<ExecutionSafetyConfig, "stopLossPct" | "takeProfitPct">): Promise<string[]>;
+export declare function resolveSpreadAwarePrice(adapter: PerpDEXAdapter, market: string, side: "long" | "short", spreadOffset?: number): Promise<SpreadAwarePrice>;
+export {};