perp-cli 0.12.6 → 0.12.8

package/dist/commands/account.js

@@ -9,7 +9,27 @@ function pac(adapter) {
 }
 export function registerAccountCommands(program, getAdapter, isJson, getAdapterForExchange) {
     const account = program.command("account").description("Account commands");
-    // ── Single exchange balance fetch (used by both single + multi mode) ──
+    // ── balance alias → redirect to portfolio (renamed in v0.12) ──
+    // Users who type `perp account balance` get a structured pointer instead of
+    // "unknown command". Per Rule #2 we don't silently retarget — we tell the
+    // user what to run and exit non-zero so scripts can detect the rename.
+    account
+        .command("balance")
+        .description("[renamed] Use 'perp portfolio' (exchange-aggregated) or 'perp portfolio -e <ex>'")
+        .action(async () => {
+        const msg = "'account balance' was renamed in v0.12 — use 'portfolio' instead.";
+        const remediation = "perp portfolio                      # all exchanges\nperp portfolio -e <exchange>        # single exchange detail";
+        if (isJson()) {
+            const { jsonError } = await import("../utils.js");
+            const { printJson } = await import("../utils.js");
+            printJson(jsonError("INVALID_PARAMS", msg, { details: { remediation } }));
+            process.exit(1);
+        }
+        const chalk = (await import("chalk")).default;
+        console.error(chalk.yellow(`\n  ${msg}`));
+        console.error(chalk.gray(`  Run: ${remediation}\n`));
+        process.exit(1);
+    });
     // ── HIP-3 dex helper: fetch data from all deployed dexes in parallel ──
     async function fetchHip3Data(hlAdapter, fetcher) {
         const dexes = await hlAdapter.listDeployedDexes();

package/dist/commands/agent.d.ts

@@ -7,3 +7,37 @@ import { Command } from "commander";
  * relocates it to `wallet agent ...`.
  */
 export declare function registerWalletAgentCommands(walletCmd: Command, isJson: () => boolean): void;
+/** Public abstraction modes (CLI surface) → HL on-wire string. */
+declare const HL_ABSTRACTION_TO_WIRE: {
+    readonly unified: "unifiedAccount";
+    readonly standard: "disabled";
+    readonly portfolio: "portfolioMargin";
+};
+export type HlAbstractionMode = keyof typeof HL_ABSTRACTION_TO_WIRE;
+interface HlSetAbstractionFlowOpts {
+    masterName: string;
+    passphrase: string;
+    mode: HlAbstractionMode;
+    isTestnet: boolean;
+}
+interface HlSetAbstractionFlowResult {
+    mode: HlAbstractionMode;
+    abstraction: string;
+    hyperliquidChain: "Mainnet" | "Testnet";
+    nonce: number;
+    userEvmAddress: `0x${string}`;
+    response: Record<string, unknown>;
+}
+/**
+ * Send a Hyperliquid `userSetAbstraction` action.
+ *
+ * Reuses the same EIP-712 user-signed domain (`HyperliquidSignTransaction`,
+ * chainId 42161) and `OwsEvmSigner.signTypedData` plumbing as
+ * `runHlApproveFlow`; the only differences are the type struct
+ * (`UserSetAbstraction` vs `ApproveAgent`) and the action payload.
+ *
+ * Throws `PerpError` with structured remediation on signature/network/venue
+ * failure (Rule #2: no fallback, no silent retry).
+ */
+export declare function runHlSetAbstractionFlow(opts: HlSetAbstractionFlowOpts): Promise<HlSetAbstractionFlowResult>;
+export {};

package/dist/commands/agent.js

@@ -1703,6 +1703,96 @@ async function revokeHlAgent(masterSigner) {
     });
     // Revoke is best-effort — don't throw on HTTP errors
 }
+// ── HL userSetAbstraction (account-mode write) helper ────────────────────────
+/** EIP-712 types for HyperliquidTransaction:UserSetAbstraction */
+const HL_USER_SET_ABSTRACTION_TYPES = {
+    "HyperliquidTransaction:UserSetAbstraction": [
+        { name: "hyperliquidChain", type: "string" },
+        { name: "abstraction", type: "string" },
+        { name: "nonce", type: "uint64" },
+    ],
+};
+/** Public abstraction modes (CLI surface) → HL on-wire string. */
+const HL_ABSTRACTION_TO_WIRE = {
+    unified: "unifiedAccount",
+    standard: "disabled",
+    portfolio: "portfolioMargin",
+};
+/**
+ * Send a Hyperliquid `userSetAbstraction` action.
+ *
+ * Reuses the same EIP-712 user-signed domain (`HyperliquidSignTransaction`,
+ * chainId 42161) and `OwsEvmSigner.signTypedData` plumbing as
+ * `runHlApproveFlow`; the only differences are the type struct
+ * (`UserSetAbstraction` vs `ApproveAgent`) and the action payload.
+ *
+ * Throws `PerpError` with structured remediation on signature/network/venue
+ * failure (Rule #2: no fallback, no silent retry).
+ */
+export async function runHlSetAbstractionFlow(opts) {
+    const { masterName, passphrase, mode, isTestnet } = opts;
+    const { ethers } = await import("ethers");
+    const masterSigner = OwsEvmSigner.create(masterName, passphrase);
+    const userEvmAddress = masterSigner.getAddress();
+    const hyperliquidChain = (isTestnet ? "Testnet" : "Mainnet");
+    const sigChainIdHex = "0xa4b1"; // 42161 hex
+    const abstraction = HL_ABSTRACTION_TO_WIRE[mode];
+    const nonce = Date.now();
+    const action = {
+        type: "userSetAbstraction",
+        hyperliquidChain,
+        signatureChainId: sigChainIdHex,
+        user: userEvmAddress,
+        abstraction,
+        nonce,
+    };
+    const message = {
+        hyperliquidChain,
+        abstraction,
+        nonce,
+    };
+    let sigRaw;
+    try {
+        sigRaw = await masterSigner.signTypedData(HL_USER_SIGNED_DOMAIN, HL_USER_SET_ABSTRACTION_TYPES, message);
+    }
+    catch (sigErr) {
+        throw new PerpError("SIGNATURE_FAILED", `HL userSetAbstraction signing failed: ${sigErr instanceof Error ? sigErr.message : String(sigErr)}`, {
+            remediation: "Confirm OWS master is unlocked and passphrase is correct.",
+        });
+    }
+    const parsed = ethers.Signature.from(sigRaw);
+    const signature = { r: parsed.r, s: parsed.s, v: parsed.v };
+    const baseUrl = isTestnet ? "https://api.hyperliquid-testnet.xyz" : "https://api.hyperliquid.xyz";
+    const payload = { action, nonce, signature, vaultAddress: null };
+    const res = await fetch(`${baseUrl}/exchange`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    const text = await res.text();
+    let resp;
+    try {
+        resp = JSON.parse(text);
+    }
+    catch {
+        throw new PerpError("EXCHANGE_ERROR", `HL exchange API parse error (${res.status}): ${text.slice(0, 200)}`, {
+            remediation: "Check Hyperliquid API status. Retry: perp wallet manage account-mode <mode>",
+        });
+    }
+    if (resp?.status === "err") {
+        throw new PerpError("EXCHANGE_ERROR", `HL userSetAbstraction failed: ${typeof resp.response === "string" ? resp.response : JSON.stringify(resp)}`, {
+            remediation: "Verify master EVM wallet is the account owner. Retry: perp wallet manage account-mode <mode>",
+        });
+    }
+    return {
+        mode,
+        abstraction,
+        hyperliquidChain,
+        nonce,
+        userEvmAddress,
+        response: resp,
+    };
+}
 /**
  * Core Pacifica approve flow.
  * Caller MUST hold the "pacifica" lock before calling this function.

package/dist/commands/manage.js

@@ -1,8 +1,13 @@
 import { printJson, jsonOk, jsonError } from "../utils.js";
 import chalk from "chalk";
 import { hasPacificaSdk } from "../exchanges/capabilities.js";
+import { PerpError } from "../errors.js";
+import { loadSettings } from "../settings.js";
+import { resolvePassphrase } from "../agent-wallet/passphrase.js";
+import { runHlSetAbstractionFlow } from "./agent.js";
+import { HyperliquidAdapter } from "../exchanges/hyperliquid.js";
 export function registerWalletManageCommands(parent, getAdapter, isJson, getPacificaAdapter) {
-    const manage = parent.command("manage").description("Exchange account settings (margin, subaccount, API keys, builder) — Pacifica + Lighter");
+    const manage = parent.command("manage").description("Exchange account settings (margin, subaccount, API keys, builder, account-mode) — Pacifica + Lighter + Hyperliquid");
     // Ensure adapter is initialized before accessing PacificaAdapter
     async function pac() {
         const adapter = await getAdapter();
@@ -236,4 +241,154 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
     // 3-tier signer routing, expiry tracking, free-slot picking, and AgentMeta
     // persistence. The auto-setup path in LighterAdapter.init() remains as the
     // env-key fallback for users who haven't run the unified command yet.
+    // ── Hyperliquid account abstraction mode ────────────────────────────────
+    // Read side: HyperliquidAdapter._getAbstractionMode() (added v0.12.7).
+    // Write side: HL `userSetAbstraction` action — master EVM EIP-712 signature.
+    // Reuses the same `OwsEvmSigner.signTypedData` path as `wallet agent approve
+    // hyperliquid` (see runHlApproveFlow). No agent signer involved: this is a
+    // master-only action that toggles the user's account-level mode.
+    manage
+        .command("account-mode [mode]")
+        .description("Hyperliquid account abstraction mode. Modes: unified | standard | portfolio. No arg = show current.")
+        .option("--master <name>", "Master OWS wallet name (defaults to settings.owsActiveWallet)")
+        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
+        .option("--json", "Machine-readable output")
+        .action(async (mode, opts, command) => {
+        const useJson = opts.json ?? isJson();
+        // C5 fix: parent --passphrase shadows subcommand flag in Commander v13.
+        // Merge parent + subcommand opts so --passphrase works on either side.
+        const mergedOpts = command.optsWithGlobals();
+        const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
+        const network = mergedOpts.network ?? "mainnet";
+        const isTestnet = network === "testnet";
+        // ── Show branch (no positional arg) ─────────────────────────────────
+        if (!mode) {
+            try {
+                const adapter = new HyperliquidAdapter(undefined, isTestnet);
+                // Resolve the address. _getAbstractionMode requires an address; if
+                // the user hasn't configured one, surface a clear error instead of
+                // an opaque "address not set" exception.
+                const masterName = opts.master ?? loadSettings().owsActiveWallet;
+                if (!masterName) {
+                    throw new PerpError("INVALID_PARAMS", "Master wallet name required to read account-mode. Use --master <name> or set owsActiveWallet.", {
+                        remediation: "Run: perp wallet generate <name> or perp wallet use <name>, then retry.",
+                    });
+                }
+                // Resolve the EVM address from the OWS wallet without unlocking it
+                // (read-only path needs no signature).
+                const { loadOws } = await import("../signer/ows-loader.js");
+                const ows = loadOws();
+                const wallet = ows.getWallet(masterName);
+                const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
+                if (!evmAccount) {
+                    throw new PerpError("INVALID_PARAMS", `OWS wallet "${masterName}" has no EVM account.`, {
+                        remediation: "Generate an EVM-capable wallet: perp wallet generate <name>",
+                    });
+                }
+                adapter.setAddress(evmAccount.address);
+                const current = await adapter._getAbstractionMode();
+                if (useJson) {
+                    return printJson(jsonOk({ mode: current, master: masterName, address: evmAccount.address, network: isTestnet ? "testnet" : "mainnet" }));
+                }
+                console.log(chalk.cyan.bold("\n  Hyperliquid Account Mode\n"));
+                console.log(`  Master:   ${chalk.white(masterName)}`);
+                console.log(`  Address:  ${chalk.gray(evmAccount.address)}`);
+                console.log(`  Network:  ${chalk.gray(isTestnet ? "testnet" : "mainnet")}`);
+                console.log(`  Mode:     ${chalk.green(current)}\n`);
+                return;
+            }
+            catch (err) {
+                if (useJson) {
+                    const e = err instanceof PerpError
+                        ? err.structured
+                        : { code: "UNKNOWN", message: err instanceof Error ? err.message : String(err) };
+                    console.error(JSON.stringify(jsonError(e.code, e.message)));
+                    process.exit(1);
+                }
+                console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+                process.exit(1);
+            }
+        }
+        // ── Set branch ─────────────────────────────────────────────────────
+        const modeLower = mode.toLowerCase();
+        if (modeLower !== "unified" && modeLower !== "standard" && modeLower !== "portfolio") {
+            const e = new PerpError("INVALID_PARAMS", `Mode must be one of: unified, standard, portfolio (got "${mode}")`, {
+                remediation: "Example: perp wallet manage account-mode standard --master main",
+            });
+            if (useJson) {
+                console.error(JSON.stringify(jsonError(e.structured.code, e.structured.message)));
+                process.exit(1);
+            }
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+        const newMode = modeLower;
+        try {
+            const masterName = opts.master ?? loadSettings().owsActiveWallet;
+            if (!masterName) {
+                throw new PerpError("INVALID_PARAMS", "Master wallet name is required. Use --master or set owsActiveWallet in settings.", {
+                    remediation: "Run: perp wallet generate <name> or perp wallet use <name>, then retry.",
+                });
+            }
+            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
+            if (passphrase === null) {
+                throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
+                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
+                });
+            }
+            // Capture previous mode (best-effort — info-only, do NOT block on read).
+            let prevMode = null;
+            try {
+                const readAdapter = new HyperliquidAdapter(undefined, isTestnet);
+                const { loadOws } = await import("../signer/ows-loader.js");
+                const ows = loadOws();
+                const wallet = ows.getWallet(masterName);
+                const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
+                if (evmAccount) {
+                    readAdapter.setAddress(evmAccount.address);
+                    prevMode = await readAdapter._getAbstractionMode();
+                }
+            }
+            catch {
+                // Best-effort previous-mode capture. SSOT Rule #2 forbids fallback
+                // for the primary action, but reading the prior mode is purely
+                // informational metadata — its absence does NOT mask the write.
+                prevMode = null;
+            }
+            const result = await runHlSetAbstractionFlow({
+                masterName,
+                passphrase: passphrase ?? "",
+                mode: newMode,
+                isTestnet,
+            });
+            if (useJson) {
+                return printJson(jsonOk({
+                    mode: result.mode,
+                    prevMode,
+                    abstraction: result.abstraction,
+                    hyperliquidChain: result.hyperliquidChain,
+                    nonce: result.nonce,
+                    user: result.userEvmAddress,
+                    response: result.response,
+                }));
+            }
+            console.log(chalk.green.bold("\n  Hyperliquid account mode updated.\n"));
+            console.log(`  User:      ${chalk.gray(result.userEvmAddress)}`);
+            console.log(`  Network:   ${chalk.gray(result.hyperliquidChain)}`);
+            if (prevMode)
+                console.log(`  Previous:  ${chalk.gray(prevMode)}`);
+            console.log(`  New mode:  ${chalk.cyan(result.mode)} ${chalk.gray(`(${result.abstraction})`)}\n`);
+        }
+        catch (err) {
+            if (useJson) {
+                const e = err instanceof PerpError
+                    ? err.structured
+                    : { code: "UNKNOWN", message: err instanceof Error ? err.message : String(err) };
+                console.error(JSON.stringify(jsonError(e.code, e.message)));
+                process.exit(1);
+            }
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    });
 }

package/dist/exchanges/hyperliquid.d.ts

@@ -33,6 +33,12 @@ 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;
+    /**
+     * Set the user EVM address without attaching a signer. Used by read-only
+     * paths (e.g. `wallet manage account-mode` show branch) that need to query
+     * `/info` endpoints scoped to a master wallet but never sign.
+     */
+    setAddress(address: string): void;
     /** Tier 1: inject agent OWS wallet signer. */
     setAgentSigner(meta: AgentMeta, signer: EvmSigner): void;
     /** Bypass Tier 1 (agent) — use for --no-agent flag. */
@@ -64,6 +70,25 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     private ensureAddress;
     /** Read-through cached clearinghouseState — returns cached data if fresh */
     private _getClearinghouseState;
+    /**
+     * Read the user's account abstraction mode from HL.
+     *
+     * Returns the canonical mode used to branch collateral accounting:
+     *   - "unified"   → spot clearinghouseState is the truth source (USDC total
+     *                   is unified across spot + perp). app.hyperliquid.xyz default.
+     *   - "standard"  → perp clearinghouseState is the truth source. Required
+     *                   mode for builder fee accrual.
+     *   - "portfolio" → multi-asset cross-collateral; for now treated like
+     *                   unified (spot truth). Refine when portfolio margin GA.
+     *
+     * Per SSOT Rule #2: an unrecognized venue response throws — no silent
+     * default. HIP-3 dex accounts (`this._dex` set) bypass the lookup since
+     * cross margin scopes per-DEX in standard semantics.
+     *
+     * Endpoint: `POST /info {"type":"userAbstraction","user":"0x..."}` →
+     * returns one of `"unifiedAccount" | "disabled" | "portfolioMargin"`.
+     */
+    _getAbstractionMode(): Promise<"unified" | "standard" | "portfolio">;
     /** Cached spot clearinghouse state — shared between getBalance() and HyperliquidSpotAdapter */
     _getSpotClearinghouseState(): Promise<Record<string, unknown>>;
     getBalance(): Promise<ExchangeBalance>;

package/dist/exchanges/hyperliquid.js

@@ -61,6 +61,14 @@ export class HyperliquidAdapter {
         this._evmSigner = signer;
         this._address = signer.getAddress();
     }
+    /**
+     * Set the user EVM address without attaching a signer. Used by read-only
+     * paths (e.g. `wallet manage account-mode` show branch) that need to query
+     * `/info` endpoints scoped to a master wallet but never sign.
+     */
+    setAddress(address) {
+        this._address = address;
+    }
     /** Tier 1: inject agent OWS wallet signer. */
     setAgentSigner(meta, signer) {
         this._agentMeta = meta;
@@ -344,6 +352,40 @@ export class HyperliquidAdapter {
             return state;
         });
     }
+    /**
+     * Read the user's account abstraction mode from HL.
+     *
+     * Returns the canonical mode used to branch collateral accounting:
+     *   - "unified"   → spot clearinghouseState is the truth source (USDC total
+     *                   is unified across spot + perp). app.hyperliquid.xyz default.
+     *   - "standard"  → perp clearinghouseState is the truth source. Required
+     *                   mode for builder fee accrual.
+     *   - "portfolio" → multi-asset cross-collateral; for now treated like
+     *                   unified (spot truth). Refine when portfolio margin GA.
+     *
+     * Per SSOT Rule #2: an unrecognized venue response throws — no silent
+     * default. HIP-3 dex accounts (`this._dex` set) bypass the lookup since
+     * cross margin scopes per-DEX in standard semantics.
+     *
+     * Endpoint: `POST /info {"type":"userAbstraction","user":"0x..."}` →
+     * returns one of `"unifiedAccount" | "disabled" | "portfolioMargin"`.
+     */
+    async _getAbstractionMode() {
+        if (this._dex)
+            return "standard";
+        this.ensureAddress();
+        const { withCache, TTL_ACCOUNT } = await import("../cache.js");
+        return withCache(`acct:hl:abstraction:${this._address}`, TTL_ACCOUNT, async () => {
+            const raw = (await this._infoPost({ type: "userAbstraction", user: this._address }));
+            if (raw === "unifiedAccount")
+                return "unified";
+            if (raw === "portfolioMargin")
+                return "portfolio";
+            if (raw === "disabled")
+                return "standard";
+            throw new PerpError("INVALID_PARAMS", `UNKNOWN_ACCOUNT_MODE: HL returned unrecognized userAbstraction mode: ${JSON.stringify(raw)}`, { remediation: "Check app.hyperliquid.xyz Settings → Account Mode" });
+        });
+    }
     /** Cached spot clearinghouse state — shared between getBalance() and HyperliquidSpotAdapter */
     async _getSpotClearinghouseState() {
         this.ensureAddress();
@@ -367,26 +409,24 @@ export class HyperliquidAdapter {
         }
         let equity;
         let available;
-        if (!this._dex) {
-            // Unified account: spot USDC total IS the true equity (includes perp margin as "hold").
-            // perp accountValue is a subset — adding both double-counts.
-            try {
-                const spotState = await this._getSpotClearinghouseState();
-                const balances = (spotState?.balances ?? []);
-                const usdc = balances.find((b) => String(b.coin).startsWith("USDC"));
-                const spotTotal = usdc?.total !== undefined ? Number(usdc.total) : NaN;
-                const spotHold = Number(usdc?.hold ?? 0);
-                equity = !isNaN(spotTotal) ? spotTotal : Number(margin.accountValue ?? cross.accountValue ?? 0);
-                available = !isNaN(spotTotal) ? spotTotal - spotHold : Number(s?.withdrawable ?? 0);
-            }
-            catch {
-                // Spot API failed — fall back to perp-only values
-                equity = Number(margin.accountValue ?? cross.accountValue ?? 0);
-                available = Number(s?.withdrawable ?? 0);
-            }
+        // Branch by user's account abstraction mode (Rule #2: no silent fallback).
+        // - "unified" / "portfolio": spot USDC total = true equity; perp margin
+        //   is held against the same USDC pool, so adding both double-counts.
+        // - "standard": separate perp/spot accounting; perp clearinghouse is the
+        //   only collateral source. Required mode for builder fee accrual.
+        // HIP-3 dex accounts (this._dex) always use standard semantics.
+        const mode = await this._getAbstractionMode();
+        if (mode === "unified" || mode === "portfolio") {
+            const spotState = await this._getSpotClearinghouseState();
+            const balances = (spotState?.balances ?? []);
+            const usdc = balances.find((b) => String(b.coin).startsWith("USDC"));
+            const spotTotal = Number(usdc?.total ?? 0);
+            const spotHold = Number(usdc?.hold ?? 0);
+            equity = spotTotal;
+            available = spotTotal - spotHold;
         }
         else {
-            // Dex account: perp clearinghouse is the only source
+            // mode === "standard"
             equity = Number(margin.accountValue ?? cross.accountValue ?? 0);
             available = Number(s?.withdrawable ?? 0);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.12.6"
+  version: "0.12.8"
 ---
 
 # perp-cli Agent Guide
@@ -41,7 +41,7 @@ Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid
 ## Install
 
 ```bash
-perp --version 2>/dev/null  # check if exists (must be >= 0.12.6)
+perp --version 2>/dev/null  # check if exists (must be >= 0.12.8)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
 ```