perp-cli 0.12.17 → 0.14.0

package/dist/secret-env.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Environment variables that carry key material (SSOT Rule #3).
+ *
+ * Child processes (tmux background jobs, the OWS CLI) never receive these: they
+ * are stripped from the child's environment, and a background job resolves its
+ * credentials itself from the OWS vault / agent keystores / ~/.perp/.env.
+ */
+/** Every secret-bearing env var perp-cli (or the OWS CLI) reads. */
+export declare const SECRET_ENV_NAMES: readonly string[];
+/** True when an env var name is (or looks like) key material. */
+export declare function isSecretEnvName(name: string): boolean;
+/** Secret env var names to remove from a child: the fixed list plus any secret-looking name in `env`. */
+export declare function secretEnvNamesIn(env: NodeJS.ProcessEnv): string[];
+/** A copy of `env` without any secret-bearing variable. */
+export declare function scrubSecretEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/secret-env.js

@@ -0,0 +1,36 @@
+/**
+ * Environment variables that carry key material (SSOT Rule #3).
+ *
+ * Child processes (tmux background jobs, the OWS CLI) never receive these: they
+ * are stripped from the child's environment, and a background job resolves its
+ * credentials itself from the OWS vault / agent keystores / ~/.perp/.env.
+ */
+/** Every secret-bearing env var perp-cli (or the OWS CLI) reads. */
+export const SECRET_ENV_NAMES = [
+    "PRIVATE_KEY", "pk",
+    "PACIFICA_PRIVATE_KEY", "HL_PRIVATE_KEY", "HYPERLIQUID_PRIVATE_KEY",
+    "LIGHTER_PRIVATE_KEY", "LT_PRIVATE_KEY", "ASTER_PRIVATE_KEY", "LIGHTER_API_KEY",
+    "OWS_PASSPHRASE", "OWS_API_KEY", "OWS_PRIVATE_KEY", "OWS_MNEMONIC",
+    "LWS_PASSPHRASE", "LWS_PRIVATE_KEY", "LWS_MNEMONIC",
+];
+const SECRET_NAME_PATTERN = /PRIVATE_KEY|PASSPHRASE|SECRET|MNEMONIC|(^|_)API_KEY$/i;
+/** True when an env var name is (or looks like) key material. */
+export function isSecretEnvName(name) {
+    return SECRET_ENV_NAMES.includes(name) || SECRET_NAME_PATTERN.test(name);
+}
+/** Secret env var names to remove from a child: the fixed list plus any secret-looking name in `env`. */
+export function secretEnvNamesIn(env) {
+    const names = new Set(SECRET_ENV_NAMES);
+    for (const k of Object.keys(env))
+        if (isSecretEnvName(k))
+            names.add(k);
+    return [...names];
+}
+/** A copy of `env` without any secret-bearing variable. */
+export function scrubSecretEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (!isSecretEnvName(k))
+            out[k] = v;
+    return out;
+}

package/dist/settings.d.ts

@@ -1,3 +1,5 @@
+import type { VenueId } from "./exchanges/venue-types.js";
+import { type BuilderSettings } from "./exchanges/builder-fee.js";
 export interface ExchangeFees {
     taker: number;
     maker: number;
@@ -74,34 +76,122 @@ export interface AgentMeta {
     owsPolicyId: string;
     expiresAt: string;
     approvedAt: string;
+    /**
+     * canWithdraw null = unknown: a key imported from the exchange website (its withdraw
+     * permission is set there and cannot be read back). Never treated as true (rotate does not
+     * inherit it; Aster withdraw requires === true).
+     */
     permissions: {
         canPerpTrade: boolean;
         canSpotTrade: boolean;
-        canWithdraw: boolean;
+        canWithdraw: boolean | null;
     };
     asterApprovalNonce: string;
     status?: "active" | "partial";
+    /**
+     * Network the agent was registered on. Every approve/rotate writes it.
+     * Records written before network tagging lack it — see agentNetworkOf()
+     * in agent-wallet/store.ts for how those are classified.
+     */
+    network?: "mainnet" | "testnet";
+    /**
+     * How the key got here: "approved" = this CLI signed the approval with a master wallet on this
+     * machine; "imported" = created on the exchange website and imported with
+     * `perp wallet agent import` (the master is known only by its public address and
+     * `masterWalletName` is ""). Records written before this field are "approved" — see
+     * agentSourceOf() in agent-wallet/store.ts.
+     */
+    source?: AgentSource;
+}
+/** See AgentMeta.source. */
+export type AgentSource = "approved" | "imported";
+/** Ondo Perps API key (HMAC). The secret lives only in ~/.perp/ondo-agents/<keyId>.json (SSOT Rule #3). */
+export interface OndoAgentMeta {
+    kind: "ondo";
+    agentName: string;
+    keyId: string;
+    keystorePath: string;
+    scopes: string[] | null;
+    /** Network the key was verified against at approve time; adapters refuse a mismatch. */
+    network: "mainnet" | "testnet";
+    approvedAt: string;
+    /** Ondo keys are always created in the Ondo Perps web app; absent on records written before this field. */
+    source?: AgentSource;
+}
+/** Arcus Ed25519 API key. The private key lives only in OWS wallet `agentWalletName` (SSOT Rule #3). */
+export interface ArcusAgentMeta {
+    kind: "arcus";
+    agentName: string;
+    agentWalletName: string;
+    /** 64-hex Ed25519 public key registered via createApiKey. */
+    apiKeyHex: string;
+    /** Subaccount index 0–9, or 255 for all subaccounts. */
+    accountIndex: number;
+    ownerAddress: `0x${string}`;
+    /** ISO timestamp; Arcus keys expire after at most 180 days. */
+    validUntil: string;
+    /** Network the key was registered on at approve time; adapters refuse a mismatch. */
+    network: "mainnet" | "testnet";
+    approvedAt: string;
+    /** See AgentMeta.source; absent = "approved" (records written before this field). */
+    source?: AgentSource;
+}
+/**
+ * QFEX API key (HMAC), created on the QFEX website (2FA) and imported. The secret lives only in
+ * ~/.perp/qfex-agents/<publicKey>.json (SSOT Rule #3).
+ */
+export interface QfexAgentMeta {
+    kind: "qfex";
+    agentName: string;
+    publicKey: string;
+    keystorePath: string;
+    /**
+     * The concrete account UUID this key trades (resolved and confirmed at import: the primary
+     * account's id, or the chosen subaccount). Never null — every request names it explicitly.
+     */
+    accountId: string;
+    /** Whether accountId is the user's primary account (deposits / withdrawals are primary-only). */
+    isPrimaryAccount: boolean;
+    /**
+     * What the import-time read checks showed. INFORMATIONAL ONLY: never used as a gate and never
+     * updated from a runtime denial (which may be KYC, terms, region or scope). null = not checked.
+     */
+    permissions: {
+        viewPositions: boolean | null;
+        viewBalance: boolean | null;
+        viewOrders: boolean | null;
+        executeOrders: boolean | null;
+        depositWithdraw: boolean | null;
+    };
+    /** Network the key was verified against at import; the adapter refuses a mismatch. */
+    network: "mainnet" | "testnet";
+    approvedAt: string;
+    source: "imported";
 }
+export type AnyAgentMeta = AgentMeta | OndoAgentMeta | ArcusAgentMeta | QfexAgentMeta;
 export interface AgentsByExchange {
     aster?: Record<string, AgentMeta>;
     hyperliquid?: Record<string, AgentMeta>;
     pacifica?: Record<string, AgentMeta>;
     lighter?: Record<string, AgentMeta>;
+    "lighter-rh"?: Record<string, AgentMeta>;
+    ondo?: Record<string, OndoAgentMeta>;
+    arcus?: Record<string, ArcusAgentMeta>;
+    qfex?: Record<string, QfexAgentMeta>;
 }
 export interface Settings {
     /** Default exchange when -e flag is omitted */
     defaultExchange: string;
     /** Active OWS wallet name (used when no --ows or --wallet flag) */
     owsActiveWallet: string;
-    /** Per-exchange referral / builder codes (always applied per SSOT Rule #3:
-     *  no opt-out — Pacifica builder code has always been mandatory; HL/LT
-     *  aligned 2026-05-01). */
+    /** HL / Lighter referral code: the default for the explicit, one-time
+     *  `wallet manage referral set` (never applied implicitly on adapter creation).
+     *  Referral = a one-time referrer binding only — per-order builder fees live in `builder`. */
     referralCodes: {
-        pacifica: string;
         hyperliquid: string;
         lighter: string;
     };
-    /** Track which exchanges have had referral codes applied (one-time) */
+    /** Which exchanges `wallet manage referral set` has applied a referral code on */
     referralApplied: {
         hyperliquid: boolean;
         lighter: boolean;
@@ -112,6 +202,79 @@ export interface Settings {
     alerts: AlertSettings;
     /** OWS-native agent wallets registered per exchange (Phase 2a: Aster only) */
     agents?: AgentsByExchange;
+    /**
+     * Per-venue slippage bound override (basis points) for market-type orders
+     * (design §13.2). Absent key = use `defaultSlippageBps`.
+     * Resolved only by resolveSlippage() (src/exchanges/slippage.ts).
+     */
+    slippageBps: {
+        [K in VenueId]?: number;
+    };
+    /**
+     * Slippage bound (bps) for every market-type order (entry, close, trigger) when
+     * neither --slippage-bps nor slippageBps[venue] is set. Shipped default 50 —
+     * a documented, user-visible configuration value (`perp settings show` marks it
+     * "(shipped default)", `perp settings set defaultSlippageBps <n>` changes it),
+     * not a hidden fallback: see docs/SSOT_RULES.md Rule #2 (shipped defaults).
+     */
+    defaultSlippageBps: number;
+    /**
+     * Per-venue builder fee (src/exchanges/builder-fee.ts). Absent venue = OFF; ships
+     * empty. A fee is attached only when the venue approval is also confirmed.
+     */
+    builder: BuilderSettings;
+    /** Bridge integrations. */
+    bridge: BridgeSettings;
+    /**
+     * Withdraw gate: qfex (API-key withdrawals; absent = refused) and hyperliquid (withdrawals /
+     * transfers to a non-owner address; absent = only the owner's own address). Ships empty. See WithdrawGate.
+     */
+    withdraw: WithdrawSettings;
+}
+/**
+ * Local limits a key-authorized withdrawal must pass before anything is sent. It guards against
+ * mistakes and misdirected automation; it is NOT a defence against key theft (a thief does not
+ * use this CLI) — that defence is a trading key WITHOUT the withdraw permission.
+ */
+export interface WithdrawGate {
+    /** Destination addresses (EVM, lowercase) withdrawals may go to. Changed only with an interactive confirmation. */
+    allowlist: string[];
+    /** Largest single withdrawal (USDC). */
+    maxPerTx: number;
+    /** Largest total withdrawn per UTC day (USDC), counted from this machine's withdraw log. */
+    maxPerDay: number;
+}
+/**
+ * Venues with a withdraw gate. qfex: API-key-authority withdrawals (every destination is gated).
+ * hyperliquid: master-signed withdraw3 / usdSend to any address other than the account owner
+ * (`funds withdraw hyperliquid --to`, `funds transfer`); the owner's own address needs no gate.
+ * Follow-up: ondo.
+ */
+export declare const WITHDRAW_GATE_VENUES: readonly ["qfex", "hyperliquid"];
+export type WithdrawGateVenue = typeof WITHDRAW_GATE_VENUES[number];
+export type WithdrawSettings = {
+    [K in WithdrawGateVenue]?: WithdrawGate;
+};
+/** Validate one settings.withdraw.<venue> entry (also used by `perp settings set`). Never clamps. */
+export declare function validateWithdrawGate(venue: string, raw: unknown, invalid: (problem: string) => Error): WithdrawGate;
+/** deBridge DLN affiliate parameters — appended to quotes / create-tx only when set (ships absent). */
+export interface DebridgeAffiliate {
+    /** deBridge referral code (attribution only, no fee); null = not sent. */
+    referralCode: string | null;
+    /** Affiliate fee percent charged on the bridged amount (e.g. 0.1 = 0.1%); null = no fee. Requires feeRecipient. */
+    feePercent: number | null;
+    /** Address receiving the affiliate fee; null = no fee. Requires feePercent. */
+    feeRecipient: string | null;
+}
+export interface BridgeSettings {
+    /** null = no affiliate / referral parameters are sent to deBridge. */
+    debridgeAffiliate: DebridgeAffiliate | null;
 }
+/** Shipped default slippage bound (bps); see Settings.defaultSlippageBps. */
+export declare const SHIPPED_DEFAULT_SLIPPAGE_BPS: number;
 export declare function loadSettings(): Settings;
+/** Validate bridge.debridgeAffiliate (also used by `perp settings set`). */
+export declare function validateDebridgeAffiliate(raw: unknown, invalid: (problem: string) => Error): DebridgeAffiliate;
+/** A slippage bound in bps: a finite number ≥ 1. Per-venue maxima are enforced by resolveSlippage(). */
+export declare function isValidSlippageBps(v: unknown): v is number;
 export declare function saveSettings(settings: Settings): void;

package/dist/settings.js

@@ -1,12 +1,59 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { isVenueId } from "./exchanges/venue-types.js";
+import { PerpError } from "./errors.js";
+import { parseBuilderSettings } from "./exchanges/builder-fee.js";
+import { existsSync, readFileSync, mkdirSync } from "fs";
+import { writeKeystoreAtomic } from "./agent-wallet/venue-keystore.js";
 import { resolve } from "path";
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
 const SETTINGS_FILE = resolve(PERP_DIR, "settings.json");
+/**
+ * Venues with a withdraw gate. qfex: API-key-authority withdrawals (every destination is gated).
+ * hyperliquid: master-signed withdraw3 / usdSend to any address other than the account owner
+ * (`funds withdraw hyperliquid --to`, `funds transfer`); the owner's own address needs no gate.
+ * Follow-up: ondo.
+ */
+export const WITHDRAW_GATE_VENUES = ["qfex", "hyperliquid"];
+const EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/** Validate one settings.withdraw.<venue> entry (also used by `perp settings set`). Never clamps. */
+export function validateWithdrawGate(venue, raw, invalid) {
+    if (!WITHDRAW_GATE_VENUES.includes(venue)) {
+        throw invalid(`withdraw: "${venue}" has no withdraw gate (venues: ${WITHDRAW_GATE_VENUES.join(", ")})`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw invalid(`withdraw.${venue} must be { allowlist: [<0x address>…], maxPerTx: <USDC>, maxPerDay: <USDC> }`);
+    }
+    const g = raw;
+    for (const k of Object.keys(g)) {
+        if (k !== "allowlist" && k !== "maxPerTx" && k !== "maxPerDay")
+            throw invalid(`withdraw.${venue}: unknown key "${k}" (expected allowlist, maxPerTx, maxPerDay)`);
+    }
+    if (!Array.isArray(g.allowlist) || g.allowlist.some(a => typeof a !== "string" || !EVM_ADDRESS_RE.test(a))) {
+        throw invalid(`withdraw.${venue}.allowlist must be a list of 0x-prefixed 20-byte EVM addresses (got ${JSON.stringify(g.allowlist)})`);
+    }
+    const positive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+    if (!positive(g.maxPerTx))
+        throw invalid(`withdraw.${venue}.maxPerTx must be a number of USDC > 0 (got ${JSON.stringify(g.maxPerTx)})`);
+    if (!positive(g.maxPerDay))
+        throw invalid(`withdraw.${venue}.maxPerDay must be a number of USDC > 0 (got ${JSON.stringify(g.maxPerDay)})`);
+    if (g.maxPerDay < g.maxPerTx)
+        throw invalid(`withdraw.${venue}.maxPerDay (${g.maxPerDay}) is below maxPerTx (${g.maxPerTx})`);
+    return { allowlist: [...new Set(g.allowlist.map(a => a.toLowerCase()))], maxPerTx: g.maxPerTx, maxPerDay: g.maxPerDay };
+}
+function parseWithdrawSettings(raw) {
+    const out = {};
+    if (raw === undefined || raw === null)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw invalidSettings("withdraw must be an object of { venue: { allowlist, maxPerTx, maxPerDay } }");
+    for (const [venue, entry] of Object.entries(raw)) {
+        out[venue] = validateWithdrawGate(venue, entry, invalidSettings);
+    }
+    return out;
+}
 const DEFAULTS = {
     defaultExchange: "",
     owsActiveWallet: "",
     referralCodes: {
-        pacifica: "",
         hyperliquid: "HYPERCASH",
         lighter: "718585MY",
     },
@@ -24,51 +71,185 @@ const DEFAULTS = {
         intervalSec: 300,
         cooldownMin: 60,
     },
+    slippageBps: {},
+    defaultSlippageBps: 50,
+    builder: {},
+    bridge: { debridgeAffiliate: null },
+    withdraw: {},
 };
+/** Shipped default slippage bound (bps); see Settings.defaultSlippageBps. */
+export const SHIPPED_DEFAULT_SLIPPAGE_BPS = DEFAULTS.defaultSlippageBps;
+function freshDefaults() {
+    return {
+        ...DEFAULTS,
+        referralCodes: { ...DEFAULTS.referralCodes },
+        referralApplied: { ...DEFAULTS.referralApplied },
+        fees: { ...DEFAULTS.fees },
+        alerts: { ...DEFAULTS.alerts, rules: [...DEFAULTS.alerts.rules] },
+        slippageBps: {},
+        builder: {},
+        bridge: { debridgeAffiliate: null },
+        withdraw: {},
+    };
+}
+function invalidSettings(problem) {
+    return new PerpError("INVALID_PARAMS", `Invalid ${SETTINGS_FILE}: ${problem}`, {
+        remediation: `Fix the offending value in ${SETTINGS_FILE} (or move the file aside to start from defaults — it also holds agent registrations), then retry.`,
+    });
+}
+/**
+ * One-time migration (2026-10-02): `referralCodes.pacifica` used to be a builder code
+ * attached to every Pacifica order (with an env / "PERPCLI" fallback). Builder fees are
+ * now opt-in per venue (`builder.pacifica`), so the old key is dropped from the file and
+ * never attached — the user is told once how to opt in explicitly.
+ */
+function migrateLegacyPacificaBuilderCode(stored) {
+    const rc = stored.referralCodes;
+    if (rc === null || typeof rc !== "object" || !("pacifica" in rc))
+        return;
+    const old = rc.pacifica;
+    delete rc.pacifica;
+    writeSettingsFile(stored);
+    if (typeof old === "string" && old !== "") {
+        process.stderr.write(`[notice] settings referralCodes.pacifica ("${old}") was a Pacifica builder code attached to every order. ` +
+            `Builder fees are now opt-in and it is no longer attached. To keep attaching it, set it explicitly: ` +
+            `perp settings set builder.pacifica ${old},<maxFeeBps>, ` +
+            `then approve it: perp wallet builder approve pacifica\n`);
+    }
+}
 export function loadSettings() {
+    // A missing file is not a failure: the user has not configured anything yet.
     if (!existsSync(SETTINGS_FILE))
-        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes }, fees: { ...DEFAULTS.fees }, alerts: { ...DEFAULTS.alerts } };
+        return freshDefaults();
+    let stored; // parsed JSON; validated field by field below
     try {
-        const stored = JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
-        // Merge stored fees with defaults (so new exchanges get defaults)
-        const fees = { ...DEFAULTS.fees };
-        if (stored.fees && typeof stored.fees === "object") {
-            for (const [ex, f] of Object.entries(stored.fees)) {
-                const fee = f;
-                if (fee && typeof fee.taker === "number" && typeof fee.maker === "number") {
-                    fees[ex] = { taker: fee.taker, maker: fee.maker };
-                }
+        stored = JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+    }
+    catch (e) {
+        throw invalidSettings(`not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+    }
+    if (stored === null || typeof stored !== "object" || Array.isArray(stored)) {
+        throw invalidSettings("top level must be a JSON object");
+    }
+    migrateLegacyPacificaBuilderCode(stored);
+    // Merge stored fees with defaults (so new exchanges get defaults)
+    const fees = { ...DEFAULTS.fees };
+    if (stored.fees !== undefined && stored.fees !== null) {
+        if (typeof stored.fees !== "object" || Array.isArray(stored.fees))
+            throw invalidSettings("fees must be an object of { venue: { taker, maker } }");
+        for (const [ex, f] of Object.entries(stored.fees)) {
+            // Rule #2: a malformed entry is an error, never silently replaced by the built-in fee.
+            const fee = f;
+            const ok = (v) => typeof v === "number" && Number.isFinite(v) && v > -1 && v < 1;
+            if (fee === null || typeof fee !== "object" || Array.isArray(fee) || !ok(fee.taker) || !ok(fee.maker)) {
+                throw invalidSettings(`fees.${ex} must be { taker: <fraction>, maker: <fraction> } (got ${JSON.stringify(f)})`);
             }
+            fees[ex] = { taker: fee.taker, maker: fee.maker };
         }
-        return {
-            defaultExchange: stored.defaultExchange ?? DEFAULTS.defaultExchange,
-            owsActiveWallet: stored.owsActiveWallet ?? DEFAULTS.owsActiveWallet,
-            referralCodes: {
-                pacifica: stored.referralCodes?.pacifica ?? DEFAULTS.referralCodes.pacifica,
-                hyperliquid: stored.referralCodes?.hyperliquid ?? DEFAULTS.referralCodes.hyperliquid,
-                lighter: stored.referralCodes?.lighter ?? DEFAULTS.referralCodes.lighter,
-            },
-            referralApplied: {
-                hyperliquid: stored.referralApplied?.hyperliquid ?? DEFAULTS.referralApplied.hyperliquid,
-                lighter: stored.referralApplied?.lighter ?? DEFAULTS.referralApplied.lighter,
-            },
-            alerts: {
-                discord: stored.alerts?.discord ?? DEFAULTS.alerts.discord,
-                telegram: stored.alerts?.telegram ?? DEFAULTS.alerts.telegram,
-                rules: Array.isArray(stored.alerts?.rules) ? stored.alerts.rules : DEFAULTS.alerts.rules,
-                intervalSec: stored.alerts?.intervalSec ?? DEFAULTS.alerts.intervalSec,
-                cooldownMin: stored.alerts?.cooldownMin ?? DEFAULTS.alerts.cooldownMin,
-            },
-            fees,
-            agents: stored.agents && typeof stored.agents === "object" ? stored.agents : undefined,
-        };
-    }
-    catch {
-        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes }, fees: { ...DEFAULTS.fees }, alerts: { ...DEFAULTS.alerts } };
     }
+    return {
+        defaultExchange: stored.defaultExchange ?? DEFAULTS.defaultExchange,
+        owsActiveWallet: stored.owsActiveWallet ?? DEFAULTS.owsActiveWallet,
+        referralCodes: {
+            hyperliquid: stored.referralCodes?.hyperliquid ?? DEFAULTS.referralCodes.hyperliquid,
+            lighter: stored.referralCodes?.lighter ?? DEFAULTS.referralCodes.lighter,
+        },
+        referralApplied: {
+            hyperliquid: stored.referralApplied?.hyperliquid ?? DEFAULTS.referralApplied.hyperliquid,
+            lighter: stored.referralApplied?.lighter ?? DEFAULTS.referralApplied.lighter,
+        },
+        alerts: {
+            discord: stored.alerts?.discord ?? DEFAULTS.alerts.discord,
+            telegram: stored.alerts?.telegram ?? DEFAULTS.alerts.telegram,
+            rules: Array.isArray(stored.alerts?.rules) ? stored.alerts.rules : DEFAULTS.alerts.rules,
+            intervalSec: stored.alerts?.intervalSec ?? DEFAULTS.alerts.intervalSec,
+            cooldownMin: stored.alerts?.cooldownMin ?? DEFAULTS.alerts.cooldownMin,
+        },
+        fees,
+        agents: stored.agents && typeof stored.agents === "object" ? stored.agents : undefined,
+        slippageBps: parseSlippageBps(stored.slippageBps),
+        defaultSlippageBps: parseDefaultSlippageBps(stored.defaultSlippageBps),
+        builder: parseBuilderSettings(stored.builder, invalidSettings),
+        bridge: { debridgeAffiliate: parseDebridgeAffiliate(stored.bridge) },
+        withdraw: parseWithdrawSettings(stored.withdraw),
+    };
+}
+function parseDebridgeAffiliate(rawBridge) {
+    if (rawBridge === undefined || rawBridge === null)
+        return null;
+    if (typeof rawBridge !== "object" || Array.isArray(rawBridge))
+        throw invalidSettings("bridge must be an object");
+    for (const k of Object.keys(rawBridge)) {
+        if (k !== "debridgeAffiliate")
+            throw invalidSettings(`bridge: unknown key "${k}" (expected debridgeAffiliate)`);
+    }
+    const raw = rawBridge.debridgeAffiliate;
+    if (raw === undefined || raw === null)
+        return null;
+    return validateDebridgeAffiliate(raw, invalidSettings);
+}
+/** Validate bridge.debridgeAffiliate (also used by `perp settings set`). */
+export function validateDebridgeAffiliate(raw, invalid) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw invalid("bridge.debridgeAffiliate must be { referralCode, feePercent, feeRecipient } (each may be null)");
+    }
+    const a = raw;
+    for (const k of Object.keys(a)) {
+        if (k !== "referralCode" && k !== "feePercent" && k !== "feeRecipient")
+            throw invalid(`bridge.debridgeAffiliate: unknown key "${k}"`);
+    }
+    const referralCode = a.referralCode ?? null;
+    const feePercent = a.feePercent ?? null;
+    const feeRecipient = a.feeRecipient ?? null;
+    if (referralCode !== null && (typeof referralCode !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(referralCode))) {
+        throw invalid(`bridge.debridgeAffiliate.referralCode must be 1-64 chars of A-Z a-z 0-9 _ - (got ${JSON.stringify(referralCode)})`);
+    }
+    if (feePercent !== null && (typeof feePercent !== "number" || !Number.isFinite(feePercent) || feePercent <= 0 || feePercent > 1)) {
+        throw invalid(`bridge.debridgeAffiliate.feePercent must be a percent in (0, 1] (got ${JSON.stringify(feePercent)})`);
+    }
+    if (feeRecipient !== null && (typeof feeRecipient !== "string" || feeRecipient.trim() === "")) {
+        throw invalid(`bridge.debridgeAffiliate.feeRecipient must be an address string (got ${JSON.stringify(feeRecipient)})`);
+    }
+    if ((feePercent === null) !== (feeRecipient === null)) {
+        throw invalid("bridge.debridgeAffiliate: feePercent and feeRecipient must be set together");
+    }
+    return { referralCode: referralCode, feePercent: feePercent, feeRecipient: feeRecipient };
+}
+/** A slippage bound in bps: a finite number ≥ 1. Per-venue maxima are enforced by resolveSlippage(). */
+export function isValidSlippageBps(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 1;
+}
+function parseDefaultSlippageBps(raw) {
+    if (raw === undefined)
+        return DEFAULTS.defaultSlippageBps;
+    if (!isValidSlippageBps(raw))
+        throw invalidSettings(`defaultSlippageBps must be a number of basis points ≥ 1 (got ${JSON.stringify(raw)})`);
+    return raw;
+}
+function parseSlippageBps(raw) {
+    const out = {};
+    if (raw === undefined || raw === null)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw invalidSettings("slippageBps must be an object of { venue: bps }");
+    for (const [k, v] of Object.entries(raw)) {
+        if (!isVenueId(k))
+            throw invalidSettings(`slippageBps: unknown venue "${k}"`);
+        if (!isValidSlippageBps(v))
+            throw invalidSettings(`slippageBps.${k} must be a number of basis points ≥ 1 (got ${JSON.stringify(v)})`);
+        out[k] = v;
+    }
+    return out;
 }
 export function saveSettings(settings) {
+    writeSettingsFile(settings);
+}
+/**
+ * The one writer of settings.json: tmp file (0600) + fsync + rename over the target, so a crash
+ * or full disk never leaves a truncated settings.json (which loadSettings would refuse).
+ */
+function writeSettingsFile(contents) {
     if (!existsSync(PERP_DIR))
         mkdirSync(PERP_DIR, { recursive: true, mode: 0o700 });
-    writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), { mode: 0o600 });
+    writeKeystoreAtomic(SETTINGS_FILE, JSON.stringify(contents, null, 2));
 }

package/dist/signer/ows-evm.d.ts

@@ -1,4 +1,5 @@
 import type { EvmSigner } from "./interface.js";
+import type { Transaction } from "ethers";
 /**
  * EVM signer backed by Open Wallet Standard.
  * Keys never leave the OWS encrypted vault.
@@ -14,6 +15,13 @@ export declare class OwsEvmSigner implements EvmSigner {
         name: string;
         type: string;
     }>>, value: Record<string, unknown>): Promise<string>;
+    /**
+     * Sign an unsigned EVM transaction (on-chain txs sent by the master wallet — Lighter RH
+     * deposit, design §13). The digest is computed HERE from the transaction (`unsignedHash`),
+     * so callers can never feed an arbitrary 32-byte hash to the master key. Returns the
+     * 65-byte 0x signature; the caller attaches it and checks the recovered sender.
+     */
+    signTransaction(tx: Transaction): Promise<string>;
     signMessage(message: string | Uint8Array): Promise<string>;
 }
 /**
@@ -30,3 +38,8 @@ export declare function canonicalizeOwsSignature(result: {
     signature: string;
     recoveryId?: number;
 }): string;
+/**
+ * The signing digest of an unsigned, chain-bound EVM transaction. Refuses an already-signed
+ * tx or one without a chainId (replayable across chains).
+ */
+export declare function unsignedTxDigest(tx: Transaction): string;

package/dist/signer/ows-evm.js

@@ -42,6 +42,17 @@ export class OwsEvmSigner {
         const result = ows.signTypedData(this._walletName, "ethereum", typedData, this._passphrase);
         return canonicalizeOwsSignature(result);
     }
+    /**
+     * Sign an unsigned EVM transaction (on-chain txs sent by the master wallet — Lighter RH
+     * deposit, design §13). The digest is computed HERE from the transaction (`unsignedHash`),
+     * so callers can never feed an arbitrary 32-byte hash to the master key. Returns the
+     * 65-byte 0x signature; the caller attaches it and checks the recovered sender.
+     */
+    async signTransaction(tx) {
+        const digest = unsignedTxDigest(tx);
+        const ows = loadOws();
+        return canonicalizeOwsSignature(ows.signHash(this._walletName, "ethereum", digest, this._passphrase));
+    }
     async signMessage(message) {
         const ows = loadOws();
         const msgStr = typeof message === "string"
@@ -84,3 +95,14 @@ function inferEip712DomainType(key) {
         default: return "string";
     }
 }
+/**
+ * The signing digest of an unsigned, chain-bound EVM transaction. Refuses an already-signed
+ * tx or one without a chainId (replayable across chains).
+ */
+export function unsignedTxDigest(tx) {
+    if (tx.signature !== null)
+        throw new Error("unsignedTxDigest: transaction is already signed");
+    if (tx.chainId === 0n)
+        throw new Error("unsignedTxDigest: transaction has no chainId (replay-unsafe)");
+    return tx.unsignedHash;
+}

package/dist/smart-order.d.ts

@@ -16,12 +16,19 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
+ * Order-outcome typing (design §12.3): every failure BEFORE the IOC is sent (orderbook read,
+ * empty book, unusable price), an explicit venue rejection embedded in the response, and an
+ * explicit IOC no-match (nothing filled, nothing rests) throw a definite ORDER_REJECTED
+ * (orderNotSent), so placePerpVerified does not quarantine a leg that never traded. Anything
+ * else the IOC call throws is rethrown unchanged (placePerpVerified measures it).
+ *
  * SSOT rule #2: silent fallback is forbidden. The opt-in `fallback: true` flag
  * is preserved for callers that explicitly want best-effort market substitution
  * after IOC reject, but the DEFAULT is `false` — failure must surface as a
  * thrown error, never a silent market sweep.
  */
 import type { ExchangeAdapter } from "./exchanges/index.js";
+import { type ResolvedSlippage } from "./exchanges/slippage.js";
 export interface SmartOrderOpts {
     /** Extra ticks of tolerance beyond best price. Default: 1 */
     tickTolerance?: number;
@@ -32,6 +39,8 @@ export interface SmartOrderOpts {
     fallback?: boolean;
     /** Reduce only flag for closing positions. Default: false */
     reduceOnly?: boolean;
+    /** Bound for the market fallback; omitted → resolveSlippage(venue, null). */
+    slippage?: ResolvedSlippage;
 }
 export interface SmartOrderResult {
     result: unknown;