@raintree-technology/perps 0.1.0

package/dist/lib/schema.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+const hexAddress = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{40}$/, "must be a 0x-prefixed 40-byte hex address");
+const hexPrivateKey = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{64}$/, "must be a 0x-prefixed 32-byte hex private key");
+const aptosAddress = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{1,64}$/, "must be a 0x-prefixed Aptos address");
+const starknetFieldElement = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{1,64}$/, "must be a 0x-prefixed Starknet field element");
+function isLoopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+function allowSecureProtocol(value, secureProtocol, localInsecureProtocol) {
+    const parsed = new URL(value);
+    if (parsed.protocol === secureProtocol) {
+        return true;
+    }
+    return parsed.protocol === localInsecureProtocol && isLoopbackHost(parsed.hostname);
+}
+const secureHttpUrl = z
+    .string()
+    .url()
+    .refine((value) => allowSecureProtocol(value, "https:", "http:"), {
+    message: "must use https:// (http:// allowed only for localhost)",
+});
+const secureWsUrl = z
+    .string()
+    .url()
+    .refine((value) => allowSecureProtocol(value, "wss:", "ws:"), {
+    message: "must use wss:// (ws:// allowed only for localhost)",
+});
+const EXCHANGE_URL_HOST_ALLOWLIST = {
+    DECIBEL_REST_URL: ["api.testnet.aptoslabs.com", "api.mainnet.aptoslabs.com"],
+    DECIBEL_WS_URL: ["api.testnet.aptoslabs.com", "api.mainnet.aptoslabs.com"],
+    DECIBEL_FULLNODE_URL: ["api.testnet.aptoslabs.com", "api.mainnet.aptoslabs.com"],
+    AEVO_REST_URL: ["api-testnet.aevo.xyz", "api.aevo.xyz"],
+    ORDERLY_REST_URL: ["testnet-api.orderly.org", "api-evm.orderly.org"],
+    PARADEX_REST_URL: ["api.testnet.paradex.trade", "api.prod.paradex.trade"],
+};
+function isTrustedExchangeHost(key, value) {
+    const hostname = new URL(value).hostname.toLowerCase();
+    if (isLoopbackHost(hostname)) {
+        return true;
+    }
+    const trustedHosts = EXCHANGE_URL_HOST_ALLOWLIST[key];
+    return trustedHosts.includes(hostname);
+}
+export const envSchema = z
+    .object({
+    // Hyperliquid credentials
+    HYPERLIQUID_PRIVATE_KEY: hexPrivateKey.optional(),
+    HYPERLIQUID_WALLET_ADDRESS: hexAddress.optional(),
+    HYPERLIQUID_NETWORK: z.enum(["testnet", "mainnet"]).optional(),
+    // Decibel credentials/settings
+    DECIBEL_API_WALLET_PRIVATE_KEY: hexPrivateKey.optional(),
+    DECIBEL_API_WALLET_ADDRESS: aptosAddress.optional(),
+    DECIBEL_API_BEARER_TOKEN: z.string().min(1).optional(),
+    DECIBEL_SUBACCOUNT_ADDRESS: aptosAddress.optional(),
+    DECIBEL_PACKAGE_ADDRESS: aptosAddress.optional(),
+    DECIBEL_REST_URL: secureHttpUrl.optional(),
+    DECIBEL_WS_URL: secureWsUrl.optional(),
+    DECIBEL_FULLNODE_URL: secureHttpUrl.optional(),
+    DECIBEL_NETWORK: z.enum(["testnet", "mainnet"]).optional(),
+    // Aevo credentials
+    AEVO_API_KEY: z.string().min(1).optional(),
+    AEVO_API_SECRET: z.string().min(1).optional(),
+    AEVO_SIGNING_KEY: hexPrivateKey.optional(),
+    AEVO_ACCOUNT_PRIVATE_KEY: hexPrivateKey.optional(),
+    AEVO_REST_URL: secureHttpUrl.optional(),
+    AEVO_NETWORK: z.enum(["testnet", "mainnet"]).optional(),
+    // Orderly credentials
+    ORDERLY_BROKER_ID: z.string().min(1).optional(),
+    ORDERLY_CHAIN_ID: z.string().min(1).optional(),
+    ORDERLY_ACCOUNT_ID: z.string().min(1).optional(),
+    ORDERLY_KEY: z.string().min(1).optional(),
+    ORDERLY_SECRET: z.string().min(1).optional(),
+    ORDERLY_TRADING_KEY: z.string().min(1).optional(),
+    ORDERLY_TRADING_SECRET: z.string().min(1).optional(),
+    ORDERLY_REST_URL: secureHttpUrl.optional(),
+    ORDERLY_NETWORK: z.enum(["testnet", "mainnet"]).optional(),
+    // Paradex credentials
+    PARADEX_API_BEARER_TOKEN: z.string().min(1).optional(),
+    PARADEX_ACCOUNT_ADDRESS: starknetFieldElement.optional(),
+    PARADEX_PRIVATE_KEY: starknetFieldElement.optional(),
+    PARADEX_ETHEREUM_ACCOUNT: hexAddress.optional(),
+    PARADEX_CHAIN_ID: z.string().min(1).optional(),
+    PARADEX_REST_URL: secureHttpUrl.optional(),
+    PARADEX_NETWORK: z.enum(["testnet", "mainnet"]).optional(),
+    // Risk policy
+    RISK_MAX_POSITION_SIZE_USD: z.coerce.number().positive().optional().default(1_000),
+    RISK_MAX_TOTAL_EXPOSURE_USD: z.coerce.number().positive().optional().default(3_000),
+    RISK_MAX_LEVERAGE: z.coerce.number().positive().optional().default(3),
+    RISK_MIN_SIGNAL_CONFIDENCE: z.coerce.number().min(0).max(1).optional().default(0.3),
+    RISK_MAX_DRAWDOWN_PCT: z.coerce.number().positive().max(100).optional().default(10),
+    RISK_DEFAULT_LEVERAGE: z.coerce.number().positive().optional().default(3),
+    // Execution safety
+    EXECUTION_STOP_LOSS_PCT: z.coerce.number().positive().optional().default(2),
+    EXECUTION_TAKE_PROFIT_PCT: z.coerce.number().positive().optional().default(4),
+    EXECUTION_SPREAD_OFFSET_PCT: z.coerce.number().min(0).max(100).optional().default(30),
+    // Operator heartbeat
+    OPERATOR_HEARTBEAT_INTERVAL_MS: z.coerce.number().int().positive().optional().default(60_000),
+    // Endpoint safety
+    PERPS_ALLOW_UNTRUSTED_ENDPOINTS: z.enum(["0", "1", "true", "false"]).optional(),
+    PERPS_BLOCKED_EXCHANGES: z.string().optional(),
+    PERPS_BLOCKED_MARKETS: z.string().optional(),
+    PERPS_BLOCKED_MARKET_PATTERNS: z.string().optional(),
+    PERPS_REPUTATION_BLOCKLIST_FILE: z.string().min(1).optional(),
+})
+    .superRefine((env, ctx) => {
+    if (env.DECIBEL_API_WALLET_PRIVATE_KEY && !env.DECIBEL_API_WALLET_ADDRESS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["DECIBEL_API_WALLET_ADDRESS"],
+            message: "required when DECIBEL_API_WALLET_PRIVATE_KEY is set",
+        });
+    }
+    if (env.DECIBEL_API_BEARER_TOKEN && !env.DECIBEL_API_WALLET_ADDRESS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["DECIBEL_API_WALLET_ADDRESS"],
+            message: "required when DECIBEL_API_BEARER_TOKEN is set",
+        });
+    }
+    const aevoCredentialValues = [env.AEVO_API_KEY, env.AEVO_API_SECRET];
+    const aevoCredentialCount = aevoCredentialValues.filter(Boolean).length;
+    if (aevoCredentialCount === 1) {
+        if (!env.AEVO_API_KEY) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["AEVO_API_KEY"],
+                message: "required when AEVO_API_SECRET is set",
+            });
+        }
+        if (!env.AEVO_API_SECRET) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["AEVO_API_SECRET"],
+                message: "required when AEVO_API_KEY is set",
+            });
+        }
+    }
+    const orderlyCoreValues = [env.ORDERLY_ACCOUNT_ID, env.ORDERLY_KEY, env.ORDERLY_SECRET];
+    const orderlyCoreCount = orderlyCoreValues.filter(Boolean).length;
+    if (orderlyCoreCount > 0 && orderlyCoreCount < orderlyCoreValues.length) {
+        if (!env.ORDERLY_ACCOUNT_ID) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["ORDERLY_ACCOUNT_ID"],
+                message: "required with ORDERLY_KEY and ORDERLY_SECRET",
+            });
+        }
+        if (!env.ORDERLY_KEY) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["ORDERLY_KEY"],
+                message: "required with ORDERLY_ACCOUNT_ID and ORDERLY_SECRET",
+            });
+        }
+        if (!env.ORDERLY_SECRET) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["ORDERLY_SECRET"],
+                message: "required with ORDERLY_ACCOUNT_ID and ORDERLY_KEY",
+            });
+        }
+    }
+    const allowUntrustedEndpoints = env.PERPS_ALLOW_UNTRUSTED_ENDPOINTS === "1" ||
+        env.PERPS_ALLOW_UNTRUSTED_ENDPOINTS === "true";
+    if (!allowUntrustedEndpoints) {
+        for (const key of Object.keys(EXCHANGE_URL_HOST_ALLOWLIST)) {
+            const value = env[key];
+            if (!value) {
+                continue;
+            }
+            if (!isTrustedExchangeHost(key, value)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [key],
+                    message: "host is not in the trusted exchange list (set PERPS_ALLOW_UNTRUSTED_ENDPOINTS=1 to override intentionally)",
+                });
+            }
+        }
+    }
+});
+export function parseEnv(env) {
+    const result = envSchema.safeParse(env);
+    if (!result.success) {
+        const lines = result.error.issues.map((issue) => {
+            const key = issue.path.length > 0 ? issue.path.join(".") : "env";
+            return `${key}: ${issue.message}`;
+        });
+        throw new Error(`Invalid environment configuration:\n${lines.join("\n")}`);
+    }
+    return result.data;
+}

package/dist/lib/secrets.d.ts

@@ -0,0 +1,3 @@
+export declare function isEncryptedSecret(value: string): boolean;
+export declare function encryptSecret(plaintext: string): string;
+export declare function decryptSecret(ciphertext: string): string;

package/dist/lib/secrets.js

@@ -0,0 +1,62 @@
+import { createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { MASTER_KEY_PATH } from "./paths.js";
+import { ensurePrivateDir, hardenPrivateFile, PRIVATE_FILE_MODE } from "./fs-security.js";
+const ENCRYPTION_PREFIX = "enc:v1:";
+const KEY_SIZE_BYTES = 32;
+const IV_SIZE_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+let cachedKey = null;
+function parseStoredKey(raw) {
+    const decoded = Buffer.from(raw.trim(), "base64");
+    if (decoded.length !== KEY_SIZE_BYTES) {
+        throw new Error("Invalid secret key length");
+    }
+    return decoded;
+}
+function getOrCreateMasterKey() {
+    if (cachedKey) {
+        return cachedKey;
+    }
+    if (existsSync(MASTER_KEY_PATH)) {
+        hardenPrivateFile(MASTER_KEY_PATH);
+        const raw = readFileSync(MASTER_KEY_PATH, "utf-8");
+        cachedKey = parseStoredKey(raw);
+        return cachedKey;
+    }
+    ensurePrivateDir(dirname(MASTER_KEY_PATH));
+    const key = randomBytes(KEY_SIZE_BYTES);
+    writeFileSync(MASTER_KEY_PATH, key.toString("base64"), { mode: PRIVATE_FILE_MODE });
+    hardenPrivateFile(MASTER_KEY_PATH);
+    cachedKey = key;
+    return key;
+}
+export function isEncryptedSecret(value) {
+    return value.startsWith(ENCRYPTION_PREFIX);
+}
+export function encryptSecret(plaintext) {
+    const key = getOrCreateMasterKey();
+    const iv = randomBytes(IV_SIZE_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf-8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const payload = Buffer.concat([iv, authTag, encrypted]).toString("base64");
+    return `${ENCRYPTION_PREFIX}${payload}`;
+}
+export function decryptSecret(ciphertext) {
+    if (!isEncryptedSecret(ciphertext)) {
+        return ciphertext;
+    }
+    const payload = Buffer.from(ciphertext.slice(ENCRYPTION_PREFIX.length), "base64");
+    if (payload.length <= IV_SIZE_BYTES + AUTH_TAG_BYTES) {
+        throw new Error("Stored secret payload is invalid");
+    }
+    const iv = payload.subarray(0, IV_SIZE_BYTES);
+    const authTag = payload.subarray(IV_SIZE_BYTES, IV_SIZE_BYTES + AUTH_TAG_BYTES);
+    const encrypted = payload.subarray(IV_SIZE_BYTES + AUTH_TAG_BYTES);
+    const key = getOrCreateMasterKey();
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf-8");
+}

package/dist/lib/settings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Global settings management
+ * Stores user preferences in SQLite
+ */
+export interface Settings {
+    defaultExchange: string;
+    testnetByDefault: boolean;
+}
+/**
+ * Get a setting value
+ */
+export declare function getSetting<K extends keyof Settings>(key: K): Settings[K];
+/**
+ * Set a setting value
+ */
+export declare function setSetting<K extends keyof Settings>(key: K, value: Settings[K]): void;
+/**
+ * Get all settings
+ */
+export declare function getAllSettings(): Settings;
+/**
+ * Reset all settings to defaults
+ */
+export declare function resetSettings(): void;

package/dist/lib/settings.js

@@ -0,0 +1,86 @@
+/**
+ * Global settings management
+ * Stores user preferences in SQLite
+ */
+import { getDb } from "./db/index.js";
+const DEFAULT_SETTINGS = {
+    defaultExchange: "hyperliquid",
+    testnetByDefault: false,
+};
+/**
+ * Ensure settings table exists
+ */
+function ensureSettingsTable() {
+    const db = getDb();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+    )
+  `);
+}
+/**
+ * Get a setting value
+ */
+export function getSetting(key) {
+    ensureSettingsTable();
+    const db = getDb();
+    const row = db.prepare("SELECT value FROM settings WHERE key = ?").get(key);
+    if (!row) {
+        return DEFAULT_SETTINGS[key];
+    }
+    // Parse based on expected type
+    const defaultValue = DEFAULT_SETTINGS[key];
+    if (typeof defaultValue === "boolean") {
+        return (row.value === "true");
+    }
+    return row.value;
+}
+/**
+ * Set a setting value
+ */
+export function setSetting(key, value) {
+    ensureSettingsTable();
+    const db = getDb();
+    const stringValue = String(value);
+    db.prepare(`
+    INSERT INTO settings (key, value, updated_at)
+    VALUES (?, ?, strftime('%s', 'now'))
+    ON CONFLICT(key) DO UPDATE SET
+      value = excluded.value,
+      updated_at = excluded.updated_at
+  `).run(key, stringValue);
+}
+/**
+ * Get all settings
+ */
+export function getAllSettings() {
+    ensureSettingsTable();
+    const db = getDb();
+    const rows = db.prepare("SELECT key, value FROM settings").all();
+    const settings = { ...DEFAULT_SETTINGS };
+    for (const row of rows) {
+        if (row.key in settings) {
+            const key = row.key;
+            const defaultValue = DEFAULT_SETTINGS[key];
+            if (typeof defaultValue === "boolean") {
+                ;
+                settings[key] = row.value === "true";
+            }
+            else {
+                ;
+                settings[key] = row.value;
+            }
+        }
+    }
+    return settings;
+}
+/**
+ * Reset all settings to defaults
+ */
+export function resetSettings() {
+    ensureSettingsTable();
+    const db = getDb();
+    db.prepare("DELETE FROM settings").run();
+}

package/dist/lib/signals.d.ts

@@ -0,0 +1,73 @@
+export type SignalValue = "up" | "down";
+export interface TradeSignal {
+    id: number;
+    traceId: string | null;
+    exchange: string;
+    market: string | null;
+    strategy: string | null;
+    signal: SignalValue;
+    reason: string | null;
+    pnlUsd: number | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: number;
+}
+export interface AddSignalInput {
+    traceId?: string;
+    exchange: string;
+    market?: string;
+    strategy?: string;
+    signal: SignalValue;
+    reason?: string;
+    pnlUsd?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SignalQuery {
+    exchange?: string;
+    market?: string;
+    strategy?: string;
+    signal?: SignalValue;
+    minutes?: number;
+    limit?: number;
+}
+export interface SignalSummary {
+    total: number;
+    up: number;
+    down: number;
+    winRate: number;
+    totalPnlUsd: number;
+    avgPnlUsd: number;
+    byStrategy: Array<{
+        strategy: string;
+        total: number;
+        up: number;
+        down: number;
+        winRate: number;
+        totalPnlUsd: number;
+    }>;
+    byMarket: Array<{
+        market: string;
+        total: number;
+        up: number;
+        down: number;
+        winRate: number;
+        totalPnlUsd: number;
+    }>;
+}
+/**
+ * Add a trade signal to the database.
+ * Returns the inserted row id.
+ */
+export declare function addSignal(input: AddSignalInput): number;
+/**
+ * Query trade signals with optional filters.
+ * Returns signals ordered by created_at DESC.
+ */
+export declare function querySignals(query?: SignalQuery): TradeSignal[];
+/**
+ * Get aggregated signal summary statistics.
+ */
+export declare function getSignalSummary(options?: {
+    minutes?: number;
+    exchange?: string;
+    strategy?: string;
+}): SignalSummary;

package/dist/lib/signals.js

@@ -0,0 +1,136 @@
+import { getDb } from "./db/index.js";
+function rowToSignal(row) {
+    return {
+        id: row.id,
+        traceId: row.trace_id,
+        exchange: row.exchange,
+        market: row.market,
+        strategy: row.strategy,
+        signal: row.signal,
+        reason: row.reason,
+        pnlUsd: row.pnl_usd,
+        metadata: row.metadata ? JSON.parse(row.metadata) : null,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Add a trade signal to the database.
+ * Returns the inserted row id.
+ */
+export function addSignal(input) {
+    const db = getDb();
+    const result = db
+        .prepare(`INSERT INTO trade_signals (trace_id, exchange, market, strategy, signal, reason, pnl_usd, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.traceId ?? null, input.exchange, input.market ?? null, input.strategy ?? null, input.signal, input.reason ?? null, input.pnlUsd ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Query trade signals with optional filters.
+ * Returns signals ordered by created_at DESC.
+ */
+export function querySignals(query) {
+    const db = getDb();
+    const conditions = [];
+    const params = [];
+    if (query?.exchange) {
+        conditions.push("exchange = ?");
+        params.push(query.exchange);
+    }
+    if (query?.market) {
+        conditions.push("market = ?");
+        params.push(query.market);
+    }
+    if (query?.strategy) {
+        conditions.push("strategy = ?");
+        params.push(query.strategy);
+    }
+    if (query?.signal) {
+        conditions.push("signal = ?");
+        params.push(query.signal);
+    }
+    if (query?.minutes) {
+        const cutoff = Date.now() - query.minutes * 60 * 1000;
+        conditions.push("created_at > ?");
+        params.push(cutoff);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = query?.limit ?? 100;
+    const rows = db
+        .prepare(`SELECT * FROM trade_signals ${where} ORDER BY created_at DESC LIMIT ?`)
+        .all(...params, limit);
+    return rows.map(rowToSignal);
+}
+/**
+ * Get aggregated signal summary statistics.
+ */
+export function getSignalSummary(options) {
+    const db = getDb();
+    const minutes = options?.minutes ?? 1440;
+    const cutoff = Date.now() - minutes * 60 * 1000;
+    const overallConditions = ["created_at > ?"];
+    const overallParams = [cutoff];
+    if (options?.exchange) {
+        overallConditions.push("exchange = ?");
+        overallParams.push(options.exchange);
+    }
+    if (options?.strategy) {
+        overallConditions.push("strategy = ?");
+        overallParams.push(options.strategy);
+    }
+    const where = overallConditions.join(" AND ");
+    // Overall stats
+    const overall = db
+        .prepare(`SELECT COUNT(*) as total,
+              COALESCE(SUM(CASE WHEN signal = 'up' THEN 1 ELSE 0 END), 0) as up,
+              COALESCE(SUM(CASE WHEN signal = 'down' THEN 1 ELSE 0 END), 0) as down,
+              COALESCE(SUM(pnl_usd), 0) as total_pnl,
+              COALESCE(AVG(pnl_usd), 0) as avg_pnl
+       FROM trade_signals
+       WHERE ${where}`)
+        .get(...overallParams);
+    // By strategy
+    const byStrategyRows = db
+        .prepare(`SELECT strategy, COUNT(*) as total,
+              SUM(CASE WHEN signal = 'up' THEN 1 ELSE 0 END) as up,
+              SUM(CASE WHEN signal = 'down' THEN 1 ELSE 0 END) as down,
+              COALESCE(SUM(pnl_usd), 0) as total_pnl
+       FROM trade_signals
+       WHERE strategy IS NOT NULL AND ${where}
+       GROUP BY strategy`)
+        .all(...overallParams);
+    // By market
+    const byMarketRows = db
+        .prepare(`SELECT market, COUNT(*) as total,
+              SUM(CASE WHEN signal = 'up' THEN 1 ELSE 0 END) as up,
+              SUM(CASE WHEN signal = 'down' THEN 1 ELSE 0 END) as down,
+              COALESCE(SUM(pnl_usd), 0) as total_pnl
+       FROM trade_signals
+       WHERE market IS NOT NULL AND ${where}
+       GROUP BY market`)
+        .all(...overallParams);
+    return {
+        total: overall.total,
+        up: overall.up,
+        down: overall.down,
+        winRate: overall.total > 0 ? overall.up / overall.total : 0,
+        totalPnlUsd: overall.total_pnl,
+        avgPnlUsd: overall.avg_pnl,
+        byStrategy: byStrategyRows.map((r) => ({
+            strategy: r.strategy,
+            total: r.total,
+            up: r.up,
+            down: r.down,
+            winRate: r.total > 0 ? r.up / r.total : 0,
+            totalPnlUsd: r.total_pnl,
+        })),
+        byMarket: byMarketRows.map((r) => ({
+            market: r.market,
+            total: r.total,
+            up: r.up,
+            down: r.down,
+            winRate: r.total > 0 ? r.up / r.total : 0,
+            totalPnlUsd: r.total_pnl,
+        })),
+    };
+}

package/dist/lib/stable-stringify.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deterministic JSON serialization with sorted keys.
+ * Used by both the execution journal (idempotency hashing) and
+ * the agent signature module — must remain identical in both contexts.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/lib/stable-stringify.js

@@ -0,0 +1,17 @@
+/**
+ * Deterministic JSON serialization with sorted keys.
+ * Used by both the execution journal (idempotency hashing) and
+ * the agent signature module — must remain identical in both contexts.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        const primitive = JSON.stringify(value);
+        return primitive === undefined ? "null" : primitive;
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+}

package/dist/lib/state-context.d.ts

@@ -0,0 +1,44 @@
+import type { PerpDEXAdapter, Order } from "../adapters/interface.js";
+import type { Config } from "./config.js";
+export interface PositionContext {
+    market: string;
+    side: "long" | "short";
+    size: number;
+    entryPrice: number;
+    markPrice: number;
+    notionalUsd: number;
+    unrealizedPnl: number;
+    realizedPnl: number;
+    leverage: number;
+    liquidationPrice: number | null;
+    marginType: string;
+}
+export interface StateContext {
+    exchange: string;
+    timestamp: number;
+    equity: number;
+    availableBalance: number;
+    marginUsed: number;
+    marginAvailable: number;
+    totalExposureUsd: number;
+    netUnrealizedPnl: number;
+    netRealizedPnl: number;
+    leverageUsed: number;
+    positionCount: number;
+    positions: PositionContext[];
+    openOrderCount: number;
+    openOrders: Order[];
+    halted: boolean;
+    haltReason: string;
+    drawdownFromPeakPct: number;
+    peakEquity: number;
+    riskLimits: {
+        maxPositionSizeUsd: number;
+        maxTotalExposureUsd: number;
+        maxLeverage: number;
+        minSignalConfidence: number;
+        maxDrawdownPct: number;
+    };
+    errors: string[];
+}
+export declare function buildStateContext(adapter: PerpDEXAdapter, exchangeId: string, config?: Config): Promise<StateContext>;