perp-cli 0.11.0 → 0.12.0

package/dist/exchanges/hyperliquid.d.ts

@@ -1,6 +1,7 @@
 import { Hyperliquid } from "hyperliquid";
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { EvmSigner } from "../signer/index.js";
+import type { AgentMeta } from "../settings.js";
 export declare class HyperliquidAdapter implements ExchangeAdapter {
     readonly name = "hyperliquid";
     readonly chain = "evm";
@@ -11,6 +12,9 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     private _privateKey;
     private _testnet;
     private _evmSigner?;
+    private _agentSigner?;
+    private _agentMeta?;
+    private _useNoAgent;
     private _assetMap;
     private _assetMapReverse;
     private _szDecimalsMap;
@@ -29,6 +33,16 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     get isTestnet(): boolean;
     /** Inject an external EVM signer. Call before init() to skip LocalEvmSigner creation. */
     setSigner(signer: EvmSigner): void;
+    /** Tier 1: inject agent OWS wallet signer. */
+    setAgentSigner(meta: AgentMeta, signer: EvmSigner): void;
+    /** Bypass Tier 1 (agent) — use for --no-agent flag. */
+    setNoAgent(noAgent: boolean): void;
+    /** True only when ALL THREE tiers are unconfigured. */
+    get isReadOnly(): boolean;
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier(): "agent" | "master" | "pk" | null;
+    /** Resolve the active signer across three tiers. */
+    private _resolveSigner;
     init(): Promise<void>;
     /** Load asset index map — supports native and HIP-3 dex. */
     private _loadAssetMap;

package/dist/exchanges/hyperliquid.js

@@ -1,5 +1,6 @@
 import { Hyperliquid } from "hyperliquid";
 import { LocalEvmSigner } from "../signer/index.js";
+import { PerpError } from "../errors.js";
 export class HyperliquidAdapter {
     name = "hyperliquid";
     chain = "evm";
@@ -9,7 +10,10 @@ export class HyperliquidAdapter {
     _address;
     _privateKey;
     _testnet;
-    _evmSigner;
+    _evmSigner; // Tier 2: OWS master
+    _agentSigner; // Tier 1: agent OWS wallet
+    _agentMeta; // Tier 1 metadata
+    _useNoAgent = false; // --no-agent bypass flag
     _assetMap = new Map();
     _assetMapReverse = new Map();
     _szDecimalsMap = new Map(); // symbol → szDecimals
@@ -57,6 +61,64 @@ export class HyperliquidAdapter {
         this._evmSigner = signer;
         this._address = signer.getAddress();
     }
+    /** Tier 1: inject agent OWS wallet signer. */
+    setAgentSigner(meta, signer) {
+        this._agentMeta = meta;
+        this._agentSigner = signer;
+    }
+    /** Bypass Tier 1 (agent) — use for --no-agent flag. */
+    setNoAgent(noAgent) {
+        this._useNoAgent = noAgent;
+    }
+    /** True only when ALL THREE tiers are unconfigured. */
+    get isReadOnly() {
+        return !this._agentSigner && !this._evmSigner && !this._privateKey;
+    }
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier() {
+        try {
+            return this._resolveSigner().tier;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Resolve the active signer across three tiers. */
+    _resolveSigner() {
+        // Tier 1: agent (when registered, not expired, --no-agent NOT set)
+        if (!this._useNoAgent && this._agentSigner && this._agentMeta) {
+            const expiresAt = new Date(this._agentMeta.expiresAt).getTime();
+            const expired = expiresAt < Date.now();
+            if (expired) {
+                // Skip Tier 1 only if Tier 2/3 available; otherwise throw AGENT_EXPIRED
+                if (!this._evmSigner && !this._privateKey) {
+                    throw new PerpError("AGENT_EXPIRED", "Agent wallet has expired", {
+                        remediation: "perp wallet agent approve hyperliquid --rotate",
+                    });
+                }
+                // fall through to Tier 2/3
+            }
+            else {
+                return { tier: "agent", signer: this._agentSigner };
+            }
+        }
+        // Tier 2: OWS master (_evmSigner set via setSigner)
+        if (this._evmSigner) {
+            return { tier: "master", signer: this._evmSigner };
+        }
+        // Tier 3: PK direct (_privateKey → _evmSigner created in init())
+        // After init(), PK is reflected in _evmSigner. But if init() hasn't run
+        // yet, _privateKey is non-empty. Either way this path is reachable only
+        // if _evmSigner is set, so Tier 2 catches it. This guard is for the edge
+        // case where init() failed but _privateKey is set — throw a clear error.
+        if (this._privateKey) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "Hyperliquid adapter has a private key but init() has not been called", { remediation: "Call adapter.init() before using mutating methods" });
+        }
+        // No signer at any tier
+        throw new PerpError("NO_SIGNER_AVAILABLE", "No signing path configured for Hyperliquid", {
+            remediation: "Run one of: (a) perp wallet agent approve hyperliquid --master <wallet>; (b) perp wallet generate && perp -e hyperliquid --ows <wallet>; (c) export PRIVATE_KEY=0x...",
+        });
+    }
     async init() {
         // Suppress "WebSocket connected" noise from hyperliquid SDK
         const origLog = console.log;
@@ -483,9 +545,8 @@ export class HyperliquidAdapter {
      * Bypasses the SDK entirely — works for order, batchModify, twapOrder, etc.
      */
     ensureSigner() {
-        if (!this._evmSigner) {
-            throw new Error("No private key configured. Run: perp setup");
-        }
+        // Resolves across all tiers; throws PerpError if none available
+        this._resolveSigner();
     }
     /**
      * Normalize trailing zeros from price ('p') and size ('s') string fields
@@ -522,7 +583,7 @@ export class HyperliquidAdapter {
         return result;
     }
     async _signAndSendAction(action) {
-        this.ensureSigner();
+        const { signer } = this._resolveSigner();
         const { encode } = await import("@msgpack/msgpack");
         const { ethers, keccak256 } = await import("ethers");
         const isMainnet = !this._testnet;
@@ -561,7 +622,7 @@ export class HyperliquidAdapter {
             source: isMainnet ? "a" : "b",
             connectionId: hash,
         };
-        const sig = await this._evmSigner.signTypedData(phantomDomain, agentTypes, phantomAgent);
+        const sig = await signer.signTypedData(phantomDomain, agentTypes, phantomAgent);
         const parsed = ethers.Signature.from(sig);
         const payload = {
             action,
@@ -639,21 +700,15 @@ export class HyperliquidAdapter {
     }
     async cancelOrder(symbol, orderId) {
         this.ensureSigner();
-        if (this._dex) {
-            // HIP-3 dex: use raw cancel action with global asset index
-            const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
-            const result = await this._signAndSendAction({
-                type: "cancel",
-                cancels: [{ a: assetIndex, o: parseInt(orderId) }],
-            });
-            await this._invalidateAccountCache();
-            return result;
-        }
-        // HL SDK expects coin in "ETH-PERP" format (internal symbol convention)
-        const resolved = this.resolveSymbol(symbol);
-        const result = await this.sdk.exchange.cancelOrder({
-            coin: resolved,
-            o: parseInt(orderId),
+        // HL SDK declares exchange.cancelOrder in types but the runtime ExchangeAPI
+        // instance (when constructed with our wallet/agent injection path) does not
+        // expose it as a callable method. Use raw cancel action via _signAndSendAction
+        // instead — same approach as the HIP-3 dex branch — which works uniformly for
+        // standard perps and HIP-3 dexes.
+        const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        const result = await this._signAndSendAction({
+            type: "cancel",
+            cancels: [{ a: assetIndex, o: parseInt(orderId) }],
         });
         await this._invalidateAccountCache();
         return result;
@@ -667,21 +722,16 @@ export class HyperliquidAdapter {
                 return norm(o.symbol) === norm(symbol);
             })
             : orders;
+        // Use _signAndSendAction uniformly for both standard perps and HIP-3 dexes.
+        // SDK exchange.cancelOrder has the same runtime unavailability as single
+        // cancelOrder (see comment there); raw cancel action works for both paths.
         const results = [];
         for (const o of toCancel) {
-            if (this._dex) {
-                const assetIndex = await this.getAssetIndex(o.symbol);
-                results.push(await this._signAndSendAction({
-                    type: "cancel",
-                    cancels: [{ a: assetIndex, o: parseInt(o.orderId) }],
-                }));
-            }
-            else {
-                results.push(await this.sdk.exchange.cancelOrder({
-                    coin: o.symbol,
-                    o: parseInt(o.orderId),
-                }));
-            }
+            const assetIndex = await this.getAssetIndex(o.symbol);
+            results.push(await this._signAndSendAction({
+                type: "cancel",
+                cancels: [{ a: assetIndex, o: parseInt(o.orderId) }],
+            }));
         }
         return results;
     }

package/dist/exchanges/lighter-spot.js

@@ -458,7 +458,7 @@ export class LighterSpotAdapter {
     // ── Private helpers ──
     async _placeOrder(opts) {
         if (this._lt.isReadOnly) {
-            throw new Error("Spot trading requires a Lighter API key. Run `perp -e lighter manage setup-api-key` first.");
+            throw new Error("Spot trading requires a Lighter API key. Run `perp wallet agent approve lighter` to register an agent.");
         }
         const nonce = await this._getNextNonce();
         const signer = this._lt.signer;
@@ -501,19 +501,30 @@ export class LighterSpotAdapter {
             account_index: String(this._lt.accountIndex),
             api_key_index: String(apiKeyIndex),
         });
-        return res.nonce ?? res.next_nonce ?? 0;
+        const nonce = res.nonce ?? res.next_nonce;
+        // SSOT rule #2: refuse to silently default to nonce 0. A stale or missing
+        // nonce will cause Lighter to reject the tx with cryptic errors and the
+        // user has no way to diagnose the upstream failure.
+        if (nonce === undefined || !Number.isFinite(nonce) || nonce < 0) {
+            throw new Error(`Lighter /nextNonce returned no valid nonce for account_index=${this._lt.accountIndex} ` +
+                `api_key_index=${apiKeyIndex}; raw response=${JSON.stringify(res)}`);
+        }
+        return nonce;
     }
     async _sendTx(signed) {
         if (signed.error)
             throw new Error(`Signer error: ${signed.error}`);
         if (!signed.txInfo)
             throw new Error("Signer returned empty txInfo");
+        if (signed.txType === undefined || !Number.isFinite(signed.txType)) {
+            throw new Error(`Lighter signer returned no txType (received ${signed.txType}); refusing to send with default 0.`);
+        }
         const baseUrl = this._lt._baseUrl;
         const res = await fetch(`${baseUrl}/api/v1/sendTx`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
-                tx_type: String(signed.txType ?? 0),
+                tx_type: String(signed.txType),
                 tx_info: signed.txInfo,
             }),
         });

package/dist/exchanges/lighter.d.ts

@@ -1,6 +1,27 @@
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { EvmSigner } from "../signer/index.js";
+import type { AgentMeta } from "../settings.js";
 import type { WasmSignerClient as WasmSignerClientType } from "lighter-ts-sdk";
+/** Lighter trigger orderType enum (matches WASM signer). */
+export declare const LIGHTER_ORDER_TYPE: {
+    readonly STOP_LOSS: 2;
+    readonly STOP_LOSS_LIMIT: 3;
+    readonly TAKE_PROFIT: 4;
+    readonly TAKE_PROFIT_LIMIT: 5;
+};
+export type LighterTriggerOrderType = typeof LIGHTER_ORDER_TYPE.STOP_LOSS | typeof LIGHTER_ORDER_TYPE.STOP_LOSS_LIMIT | typeof LIGHTER_ORDER_TYPE.TAKE_PROFIT | typeof LIGHTER_ORDER_TYPE.TAKE_PROFIT_LIMIT;
+/**
+ * Pick Lighter trigger orderType from side, trigger price, and current mark.
+ *
+ * STOP_LOSS protects against adverse moves; TAKE_PROFIT locks in favorable moves.
+ *   buy + trigger >= mark  → STOP_LOSS  (close short on rise / breakout entry)
+ *   buy + trigger <  mark  → TAKE_PROFIT (close short on fall)
+ *   sell + trigger <= mark → STOP_LOSS  (close long on fall)
+ *   sell + trigger >  mark → TAKE_PROFIT (close long on rise)
+ *
+ * Tied trigger==mark is classified as STOP_LOSS — the protective default.
+ */
+export declare function classifyTriggerOrderType(side: "buy" | "sell", triggerPrice: number, markPrice: number, isMarket: boolean): LighterTriggerOrderType;
 export declare class LighterAdapter implements ExchangeAdapter {
     readonly name = "lighter";
     readonly chain = "ethereum";
@@ -23,6 +44,15 @@ export declare class LighterAdapter implements ExchangeAdapter {
     private _marketsCache;
     private _marketsCacheTime;
     private static readonly CACHE_TTL;
+    /** Tier 1 metadata (Phase 2d). When set + not expired + !_useNoAgent, agent
+     *  apiKeyIndex/publicKey/accountIndex take priority over master/PK env. */
+    private _agentMeta?;
+    /** Tier 1 secp256k1 hex private key (40 bytes) for the agent slot. Lighter
+     *  has no OWS curve binding for raw L2 keys; this is held in-memory only when
+     *  passed by the caller (e.g. immediately after `setupApiKey()` or via env). */
+    private _agentApiKey?;
+    /** --no-agent bypass flag. */
+    private _useNoAgent;
     /**
      * @param evmKey    EVM private key (0x-prefixed, 32 bytes) — for deposits & key registration
      * @param testnet   Use testnet (chain ID 300) instead of mainnet (chain ID 304)
@@ -31,6 +61,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
     constructor(evmKey: string, testnet?: boolean, opts?: {
         apiKey?: string;
         accountIndex?: number;
+        apiKeyIndex?: number;
     });
     get signer(): {
         createAuthToken(deadline: number): Promise<{
@@ -43,6 +74,41 @@ export declare class LighterAdapter implements ExchangeAdapter {
     get isReadOnly(): boolean;
     /** Inject an external EVM signer. Call before init() to skip LocalEvmSigner creation. */
     setSigner(signer: EvmSigner): void;
+    /**
+     * Tier 1: inject a Lighter agent's slot+L2 key (Phase 2d).
+     *
+     * Caller supplies the AgentMeta (settings.agents.lighter[name]) plus the
+     * 40-byte L2 private key (hex). Adapter swaps `_apiKey`/`_apiKeyIndex` to
+     * the agent's slot/key so all subsequent `signCreateOrder`/`signCancelOrder`
+     * etc. flow through the agent identity.
+     *
+     * NOTE: when the agent path is active, `_address` (master EVM) is left
+     * unchanged because Lighter REST queries (account, balance, positions) use
+     * `account_index` not address. The L1 EVM identity is irrelevant for the
+     * hot-path; only the L2 secp256k1 key is consulted.
+     */
+    setAgentSigner(meta: AgentMeta, agentApiKey: string): void;
+    /** Bypass Tier 1 (agent) — used for `--no-agent` flag. */
+    setNoAgent(noAgent: boolean): void;
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier(): "agent" | "master" | "pk" | null;
+    /**
+     * Resolve the active signer tier across three tiers (Phase 2d).
+     *
+     * Tier 1 (agent): active when AgentMeta + agent L2 key set, not expired,
+     *   and `--no-agent` NOT set. The actual swap of `_apiKeyIndex`/`_apiKey`
+     *   happens in `init()` (or via `_activateAgentTier()` post-init).
+     * Tier 2 (master): active when an OWS master EVM signer was injected via
+     *   `setSigner()`. Used for the L1 ChangePubKey path (auto-setup at slot 4).
+     * Tier 3 (pk): active when constructor was supplied an evmKey. Same role
+     *   as Tier 2 — signs L1 ChangePubKey for auto-setup.
+     *
+     * Lighter is unique among the 4 DEXs in that the actual order-signing is
+     * always done by the L2 secp256k1 key (`_apiKey`), regardless of tier. The
+     * tiers differ in WHICH L2 key is loaded: Tier 1 uses the agent's slot/key
+     * from AgentMeta; Tier 2/3 use whatever the env/auto-setup produced.
+     */
+    private _resolveSigner;
     init(): Promise<void>;
     /** Populate marketMap + decimals from /orderBooks API (safe to call multiple times) */
     private _refreshMarketMap;