perp-cli 0.14.2 → 0.15.0

package/dist/commands/pacifica-earn.js

@@ -0,0 +1,468 @@
+/**
+ * `perp print …` (Pacifica Print) and `perp vault …` (Pacifica vaults / "lakes").
+ *
+ * Pacifica-only products: the commands always talk to Pacifica (an explicit `-e <other venue>` is
+ * refused). Reads are unauthenticated GETs and never sign; `--account <address>` reads any
+ * account without loading a key or building the adapter.
+ *
+ * Signer policy (perp-cli rule, stricter than the venue, which accepts `agent_wallet` on all four):
+ *  - `vault deposit` (deposit_to_lake) is MASTER-ONLY, like `funds withdraw pacifica`: a leaked agent
+ *    key must not be able to move the whole balance into a vault an attacker manages;
+ *  - `vault withdraw` (pays only into the own account), `print deposit` and `print cancel` are
+ *    signed by the active signer (agent when approved, else master).
+ * Every write supports `--dry-run` (exact canonical message + body, never signs, never sends). An
+ * unknown send outcome is ORDER_PENDING: never resubmitted except with the same --idempotency-key.
+ */
+import { randomUUID } from "node:crypto";
+import chalk from "chalk";
+import { isDryRun, networkOf, supportsDryRun } from "../cli-flags.js";
+import { PerpError } from "../errors.js";
+import { PacificaAdapter } from "../exchanges/pacifica.js";
+import { resolveVenueId } from "../exchanges/venue.js";
+import { PacificaClient } from "../pacifica/client.js";
+import { logExecution } from "../execution-log.js";
+import { jsonOk, makeTable, printJson } from "../utils.js";
+import { mulDecimal } from "../exchanges/precision.js";
+import { cmpDecimal, isPlainDecimal, trimDecimal } from "../exchanges/pacifica-decimal.js";
+import { fundsFailStatus } from "./funds.js";
+import { requireIdempotencyKey, restampPresigned, sendPresigned, signPresigned } from "../exchanges/pacifica-presigned.js";
+import { buildPrintDepositRequest, buildPrintEndRequest, daysUntil, fetchPrintEvents, fetchPrintGames, fetchPrintHistory, fetchPrintMarket, fetchPrintPositions, findPrintGame, quotePrintOrder, requireEndable, } from "../exchanges/pacifica-print.js";
+import { buildVaultDepositRequest, buildVaultWithdrawRequest, DEPOSIT_WHITELIST_API_STATUS, fetchDepositWhitelist, fetchVaults, findVault, heldShares, planVaultDeposit, planVaultWithdraw, withdrawWindowAt, } from "../exchanges/pacifica-vaults.js";
+const ts = (ms) => (ms === null ? "—" : new Date(ms).toISOString().replace("T", " ").slice(0, 16) + " UTC");
+export function registerPacificaEarnCommands(program, getAdapterForExchange, isJson) {
+    /** Pacifica-only: an explicit -e naming another venue is refused (never silently ignored). */
+    function assertPacifica() {
+        if (program.getOptionValueSource("exchange") !== "cli")
+            return;
+        const raw = program.opts().exchange;
+        if (raw !== undefined && resolveVenueId(raw) !== "pacifica") {
+            throw new PerpError("INVALID_PARAMS", `Print and vaults are Pacifica products; -e ${raw} has neither`, { remediation: "Run with -e pacifica (or omit -e)" });
+        }
+    }
+    const publicClient = () => new PacificaClient({ network: networkOf(program) });
+    async function pacificaAdapter() {
+        const a = await getAdapterForExchange("pacifica");
+        if (!(a instanceof PacificaAdapter))
+            throw new Error("pacifica venue did not produce a PacificaAdapter");
+        return a;
+    }
+    /** Account to read: --account, else the configured wallet's (master) address. Signs nothing. */
+    async function readAccount(opt) {
+        if (opt !== undefined)
+            return requireAddress(opt);
+        const a = await pacificaAdapter();
+        if (a.isReadOnly) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "No Pacifica wallet configured to read", { remediation: "Pass --account <solana address>, or configure a Pacifica wallet (perp setup)" });
+        }
+        return a.publicKey;
+    }
+    /** Identity for a write. --account only plans (dry-run, no key loaded); a live write signs as the configured wallet. */
+    async function signing(accountOpt, dryRun) {
+        if (accountOpt !== undefined) {
+            if (!dryRun) {
+                throw new PerpError("INVALID_PARAMS", "--account only plans with --dry-run; a live write signs as the configured Pacifica wallet", { remediation: "Drop --account (or add --dry-run)" });
+            }
+            return { identity: { account: requireAddress(accountOpt), agentWallet: null }, tier: null, sign: null, client: publicClient() };
+        }
+        const a = await pacificaAdapter();
+        const id = a.signingIdentity();
+        return { identity: { account: id.account, agentWallet: id.agentWallet }, tier: id.tier, sign: id.signMessage, client: a.sdk };
+    }
+    /**
+     * Master-only identity (vault deposit): the master Solana signer, never the agent — even when an
+     * agent is approved. No master on this machine → NO_SIGNER_AVAILABLE. Mirrors PacificaAdapter.withdraw.
+     */
+    async function masterSigning(accountOpt, dryRun) {
+        if (accountOpt !== undefined) {
+            const plan = await signing(accountOpt, dryRun);
+            return { ...plan, tier: null };
+        }
+        const a = await pacificaAdapter();
+        const refuse = () => new PerpError("NO_SIGNER_AVAILABLE", "A Pacifica vault deposit must be signed by the account's master wallet (an agent key cannot fund a vault), and it is not loaded", {
+            exchange: "pacifica",
+            remediation: "Run with the master wallet: perp -e pacifica --ows <wallet> vault deposit … (or deposit on the Pacifica website)",
+        });
+        let master;
+        try {
+            master = a.masterSolanaSigner();
+        }
+        catch {
+            throw refuse();
+        }
+        if (master.getPublicKeyBase58() !== a.publicKey)
+            throw refuse();
+        return { identity: { account: a.publicKey, agentWallet: null }, tier: "master", sign: (m) => master.signMessage(m), client: a.sdk };
+    }
+    /** Dry-run: the exact request a live run would sign and send (no signature). */
+    function printDryRun(plan, req, tier, extra = {}) {
+        const request = { path: `POST /api/v1${req.path}`, type: req.type, signer: tier ?? "not loaded (--account plan)", signedMessage: req.message, body: { ...req.body, signature: null } };
+        if (isJson())
+            return printJson(jsonOk({ dryRun: true, sent: false, ...extra, plan, request }));
+        if (extra.apiStatus === "unofficial")
+            console.log(chalk.yellow(`  ! ${req.path} is UNOFFICIAL (not in the Pacifica API docs; shape captured from app.pacifica.fi)`));
+        console.log(chalk.yellow(`\n  [dry-run] ${req.type} — nothing signed, nothing sent`));
+        console.log(`  POST /api/v1${req.path}   signer: ${request.signer}`);
+        console.log(chalk.gray("  message to sign:"));
+        console.log(`  ${req.message}`);
+        console.log(chalk.gray("  body (signature added at send):"));
+        console.log(`  ${JSON.stringify(request.body)}\n`);
+    }
+    /** Sign + send; log every outcome incl. a signing failure (unknown outcome → "unverified", ORDER_PENDING). */
+    async function send(s, req, o) {
+        if (s.sign === null)
+            throw new Error("send without a signer");
+        const base = { type: o.logType, exchange: "pacifica", symbol: o.symbol, side: req.type, size: o.size, dryRun: false, meta: { ...o.meta, signer: s.tier, idempotencyKey: req.idempotencyKey, before: o.before } };
+        try {
+            // Credit wait BEFORE signing (a post-sign wait would eat the 5 s expiry_window). The body's
+            // timestamp is re-stamped after the wait so the signature window starts now.
+            await s.client.awaitPresignedCapacity(req.type);
+            req = restampPresigned(req, Date.now());
+            const body = await signPresigned(req, s.sign);
+            const data = await sendPresigned(s.client, req, body, { what: o.what, check: o.check, before: o.before });
+            logExecution({ ...base, status: "success", meta: { ...base.meta, response: data } });
+            return data;
+        }
+        catch (err) {
+            logExecution({ ...base, status: fundsFailStatus(err), error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+    }
+    const keyOf = (raw) => (raw === undefined ? randomUUID() : requireIdempotencyKey(raw));
+    // ═══════════════════════════ PRINT ═══════════════════════════
+    const print = program.command("print").description("Pacifica Print — strike orders that earn a premium every cycle while they wait (reads, quote, deposit/cancel with --dry-run)");
+    print.command("games").alias("products")
+        .description("Print products: market, cycle, max leverage, deposit caps, allowed target range")
+        .action(async () => {
+        assertPacifica();
+        const games = await fetchPrintGames(publicClient());
+        if (isJson())
+            return printJson(jsonOk(games));
+        console.log(chalk.white.bold("\n  Pacifica Print products"));
+        console.log(makeTable(["game", "asset", "cycle", "max lev", "target from mark", "product cap (total)", "pool cap (total)"], games.map((g) => [g.game, g.asset, g.cycleDays === null ? "?" : `${g.cycleDays}d`, g.maxLeverage === null ? "?" : `${g.maxLeverage}x`,
+            g.targetDistancePct.max === null ? "?" : `${g.targetDistancePct.min}%–${g.targetDistancePct.max}%`, g.productDepositCap ?? "—", g.poolDepositCap ?? "—"])));
+        console.log(chalk.gray(`  Min deposit ${games[0]?.minDeposit ?? "10"} USDC · while resting, fill/liquidation only at each cycle's checkpoint · after a fill: ordinary perp position · cancel settles at the cycle's end\n`));
+    });
+    const orderArgs = (c) => c
+        .argument("<game>", "Print product, e.g. BTC_24H, BTC_7D, BTC_1M (perp print games)")
+        .argument("<direction>", "long (target below mark) | short (target above mark)")
+        .argument("<deposit>", "USDC deposit (locked margin), min 10")
+        .requiredOption("--strike <price>", "Target price (on the market tick)")
+        .requiredOption("--leverage <n>", "Whole-number leverage, 1 … the product max")
+        .option("--cycles <n>", "Cycles to run, 1 … 1000 (default: roll until cancelled)");
+    async function quoteFrom(gameArg, dirArg, deposit, o) {
+        const direction = parseDirection(dirArg);
+        const cycles = o.cycles === undefined ? null : parseWhole(o.cycles, "--cycles");
+        const c = publicClient();
+        const game = findPrintGame(await fetchPrintGames(c), gameArg);
+        const market = await fetchPrintMarket(c, game.asset);
+        return quotePrintOrder(game, { game: game.game, direction, deposit, strikePrice: o.strike, leverage: o.leverage, cycles }, market);
+    }
+    orderArgs(print.command("quote"))
+        .description("Validate a Print order and preview size, liquidation price, max loss and lock period (read-only; the premium itself is quoted only by the venue)")
+        .action(async (gameArg, dirArg, deposit, o) => {
+        assertPacifica();
+        const q = await quoteFrom(gameArg, dirArg, deposit, o);
+        if (isJson())
+            return printJson(jsonOk(q));
+        printQuote(q);
+    });
+    print.command("positions")
+        .description("Current Print orders of the account (printing / cancelling / just settled)")
+        .option("--account <address>", "Read this account instead of the configured wallet")
+        .action(async (o) => {
+        assertPacifica();
+        const account = await readAccount(o.account);
+        const rows = await fetchPrintPositions(publicClient(), account);
+        if (isJson())
+            return printJson(jsonOk({ account, positions: rows }));
+        printPositions(account, rows);
+    });
+    print.command("history")
+        .description("Every Print order of the account, newest first (paginated)")
+        .option("--account <address>", "Read this account instead of the configured wallet")
+        .option("--limit <n>", "Rows per page")
+        .option("--cursor <cursor>", "next_cursor of the previous page")
+        .action(async (o) => {
+        assertPacifica();
+        const account = await readAccount(o.account);
+        const page = await fetchPrintHistory(publicClient(), account, { limit: o.limit === undefined ? null : parseWhole(o.limit, "--limit"), cursor: o.cursor ?? null });
+        if (isJson())
+            return printJson(jsonOk({ account, positions: page.items, hasMore: page.hasMore, nextCursor: page.nextCursor }));
+        printPositions(account, page.items);
+        if (page.hasMore === true)
+            console.log(chalk.gray(`  More: --cursor ${page.nextCursor ?? "?"}\n`));
+    });
+    print.command("events <printAddress>")
+        .description("Event log of one Print order: created, premium, end_requested, filled, liquidated, …")
+        .option("--limit <n>", "Rows per page")
+        .option("--cursor <cursor>", "next_cursor of the previous page")
+        .action(async (addr, o) => {
+        assertPacifica();
+        const page = await fetchPrintEvents(publicClient(), requireAddress(addr), { limit: o.limit === undefined ? null : parseWhole(o.limit, "--limit"), cursor: o.cursor ?? null });
+        if (isJson())
+            return printJson(jsonOk({ printAddress: addr, events: page.items, hasMore: page.hasMore, nextCursor: page.nextCursor }));
+        console.log("\n" + makeTable(["time", "event", "amount", "strike", "mark", "cycle"], page.items.map((e) => [ts(e.time), e.event, e.amount ?? "—", e.strikePrice ?? "—", e.markPrice ?? "—", e.cycleStartedAt === null ? "—" : `${ts(e.cycleStartedAt)} → ${ts(e.cycleEndedAt)}`])) + "\n");
+    });
+    supportsDryRun(orderArgs(print.command("deposit").alias("open")))
+        .description("Place a Print order (POST /game/deposit, deposit_to_game) — locks the deposit until it fills or a cancel settles at a cycle's end; supports --dry-run")
+        .option("--account <address>", "With --dry-run: plan for this account without loading a key")
+        .option("--idempotency-key <uuid>", "Re-send an earlier attempt with ITS key (only safe retry after ORDER_PENDING; default: a fresh key)")
+        .action(async (gameArg, dirArg, deposit, o, cmd) => {
+        assertPacifica();
+        const dryRun = isDryRun(cmd);
+        const idempotencyKey = keyOf(o.idempotencyKey);
+        const q = await quoteFrom(gameArg, dirArg, deposit, o);
+        const s = await signing(o.account, dryRun);
+        const ordersBefore = (await fetchPrintPositions(publicClient(), s.identity.account)).length;
+        const available = availableOf(await publicClient().getAccount(s.identity.account), s.identity.account);
+        if (cmpDecimal(available, q.deposit) < 0) {
+            throw new PerpError("INSUFFICIENT_BALANCE", `Print deposit ${q.deposit} USDC exceeds available_to_withdraw ${available}`, { exchange: "pacifica", remediation: "Deposit less, or free margin first (perp -e pacifica portfolio)" });
+        }
+        const req = buildPrintDepositRequest(q, s.identity, { timestamp: Date.now(), idempotencyKey });
+        if (!isJson())
+            printQuote(q);
+        if (dryRun)
+            return printDryRun(q, req, s.tier);
+        const data = await send(s, req, {
+            what: `Print deposit ${q.deposit} USDC ${q.game} ${q.direction} @ ${q.strikePrice}`,
+            check: `perp -e pacifica print positions — look for a new ${q.game} ${q.direction} order with strikePrice ${q.strikePrice} and deposit ${q.deposit} (${ordersBefore} current order(s) before this request)`,
+            logType: "print_deposit", symbol: q.game, size: q.deposit, before: { printOrders: ordersBefore },
+            meta: { game: q.game, direction: q.direction, strike: q.strikePrice, leverage: q.leverage, cycles: q.cycles },
+        });
+        const printAddress = typeof data.game_account_address === "string" ? data.game_account_address : null;
+        if (isJson())
+            return printJson(jsonOk({ placed: true, printAddress, quote: q, idempotencyKey: req.idempotencyKey, response: data }));
+        console.log(chalk.green(`\n  Print order placed: ${printAddress ?? "(no address in response)"}`));
+        console.log(chalk.gray("  Track it: perp -e pacifica print positions\n"));
+    });
+    supportsDryRun(print.command("cancel <printAddress>").alias("end"))
+        .description("[UNOFFICIAL endpoint] End a running Print order (POST /game/end, end_game — not in the API docs; shape captured from app.pacifica.fi). It still runs to the end of the current cycle, then fills or returns the deposit + premiums. Live run needs --unverified-endpoint; supports --dry-run")
+        .option("--account <address>", "With --dry-run: plan for this account without loading a key")
+        .option("--unverified-endpoint", "Acknowledge that /game/end is undocumented (required for a live run)")
+        .action(async (addr, o, cmd) => {
+        assertPacifica();
+        const dryRun = isDryRun(cmd);
+        if (!dryRun && o.unverifiedEndpoint !== true) {
+            throw new PerpError("INVALID_PARAMS", "print cancel uses POST /game/end (end_game), which is not in the Pacifica API docs (apiStatus: unofficial)", {
+                exchange: "pacifica", apiStatus: "unofficial",
+                remediation: "Check it first with --dry-run, then re-run with --unverified-endpoint — or end the order on app.pacifica.fi",
+            });
+        }
+        const s = await signing(o.account, dryRun);
+        const p = requireEndable(await fetchPrintPositions(publicClient(), s.identity.account), requireAddress(addr));
+        const req = buildPrintEndRequest(p.address, s.identity, { timestamp: Date.now() });
+        const plan = { printAddress: p.address, game: p.game, settlesAt: p.currentCycleEndAt, settlesInDays: daysUntil(p.currentCycleEndAt, Date.now()), lockedNow: p.maxLoss };
+        if (!isJson())
+            console.log(chalk.cyan(`\n  End ${p.address} (${p.game}): it keeps running until ${ts(p.currentCycleEndAt)}, then fills or returns ${p.maxLoss ?? p.deposit} USDC`));
+        if (dryRun)
+            return printDryRun(plan, req, s.tier, { apiStatus: "unofficial" });
+        const data = await send(s, req, {
+            what: `Print end ${p.address}`,
+            check: `perp -e pacifica print positions — order ${p.address} shows status "cancelling" if the end was accepted (it was "${p.status}" before)`,
+            logType: "print_end", symbol: p.game, size: p.deposit, before: { status: p.status }, meta: { printAddress: p.address, game: p.game, apiStatus: "unofficial" },
+        });
+        const at = typeof data.scheduled_end_at_ms === "number" ? data.scheduled_end_at_ms : null;
+        if (isJson())
+            return printJson(jsonOk({ endRequested: true, apiStatus: "unofficial", printAddress: p.address, scheduledEndAt: at, response: data }));
+        console.log(chalk.green(`\n  End requested for ${p.address} — settles at ${ts(at)} (the order runs until then).\n`));
+    });
+    // ═══════════════════════════ VAULT ═══════════════════════════
+    const vault = program.command("vault").alias("lake").description("Pacifica vaults (API: lakes) — list, info, positions, deposit/withdraw with --dry-run");
+    vault.command("list")
+        .description("Vaults by TVL with NAV per share, fees, lock-up and withdrawal window")
+        .option("--account <address>", "Include this account's LP shares")
+        .option("--limit <n>", "Rows shown (human output; --json returns all)", "25")
+        .action(async (o) => {
+        assertPacifica();
+        const vaults = sortByTvl(await fetchVaults(publicClient(), o.account === undefined ? null : requireAddress(o.account)));
+        if (isJson())
+            return printJson(jsonOk(vaults));
+        const n = parseWhole(o.limit, "--limit");
+        console.log("\n" + makeTable(["vault", "address", "TVL", "NAV/LP share", "fee", "lock-up", "withdraw window"], vaults.slice(0, n).map((v) => [v.nickname ?? "—", v.address, v.tvl, v.navPerLpShare ?? "1 (empty)", v.config.managerProfitShare ?? "—",
+            v.config.depositMinDurationMs === null ? "—" : `${(v.config.depositMinDurationMs / 3_600_000).toFixed(1)}h`, windowLabel(v)])));
+        console.log(chalk.gray(`  ${Math.min(n, vaults.length)} of ${vaults.length} vaults · APY is not published by Pacifica\n`));
+    });
+    vault.command("info <vault>")
+        .description("One vault (address or nickname): balances, NAV, config, live account equity, positions, withdrawal window now")
+        .action(async (ref) => {
+        assertPacifica();
+        const c = publicClient();
+        const v = findVault(await fetchVaults(c, null), ref);
+        const [acct, positions, whitelist] = await Promise.all([c.getAccount(v.address), c.getPositions(v.address), whitelistOrNull(c, v.address)]);
+        const out = {
+            ...v,
+            live: { accountEquity: acct.account_equity ?? null, availableToWithdraw: acct.available_to_withdraw ?? null, positions: positions.map((p) => ({ symbol: p.symbol, side: p.side, amount: p.amount, entryPrice: p.entry_price })) },
+            depositWhitelist: { apiStatus: DEPOSIT_WHITELIST_API_STATUS, addresses: whitelist },
+            withdrawWindow: withdrawWindowAt(v.config, Date.now()),
+        };
+        if (isJson())
+            return printJson(jsonOk(out));
+        console.log(chalk.white.bold(`\n  ${v.nickname ?? v.address}`));
+        for (const [k, val] of Object.entries({
+            address: v.address, manager: v.manager ?? "none (fresh vault)", creator: v.creator ?? "—", TVL: v.tvl, "NAV / LP share": v.navPerLpShare ?? "1 (LP class empty)",
+            "NAV / manager share": v.navPerManagerShare ?? "—", "high-water mark": v.highWatermark ?? "—", "live equity": out.live.accountEquity ?? "—",
+            "vault free balance": out.live.availableToWithdraw ?? "—", "performance fee": v.config.managerProfitShare ?? "none", "deposit cap": v.config.depositCap ?? "none",
+            "lock-up after deposit": v.config.depositMinDurationMs === null ? "none" : `${(v.config.depositMinDurationMs / 3_600_000).toFixed(2)} h (reset by every deposit)`,
+            "withdrawal window": `${windowLabel(v)}${out.withdrawWindow.restricted ? ` — now ${out.withdrawWindow.open ? "OPEN until" : "closed, opens"} ${ts(out.withdrawWindow.nextChangeAt)}` : ""}`,
+            "deposit whitelist": `${whitelist === null ? "unknown" : whitelist.length === 0 ? "none (anyone)" : `${whitelist.length} address(es)`} (unofficial endpoint; the venue decides)`, APY: "not published",
+        }))
+            console.log(`  ${k.padEnd(22)} ${val}`);
+        if (out.live.positions.length > 0)
+            console.log("\n" + makeTable(["symbol", "side", "amount", "entry"], out.live.positions.map((p) => [p.symbol, p.side, p.amount, p.entryPrice])));
+        console.log("");
+    });
+    vault.command("positions")
+        .description("Vaults where the account holds shares (LP shares, or the manager's own)")
+        .option("--account <address>", "Read this account instead of the configured wallet")
+        .action(async (o) => {
+        assertPacifica();
+        const account = await readAccount(o.account);
+        const rows = (await fetchVaults(publicClient(), account)).map((v) => ({ v, h: heldShares(v, account) }))
+            .filter(({ h }) => h.shares !== null && Number(h.shares) > 0)
+            .map(({ v, h }) => ({ schema: 1, vault: v.address, nickname: v.nickname, role: h.role, shares: h.shares, navPerShare: h.nav, value: h.nav === null ? null : mul(h.shares, h.nav), withdrawWindow: withdrawWindowAt(v.config, Date.now()), lockMs: v.config.depositMinDurationMs }));
+        if (isJson())
+            return printJson(jsonOk({ account, positions: rows }));
+        if (rows.length === 0) {
+            console.log(chalk.gray(`\n  ${account} holds no vault shares.\n`));
+            return;
+        }
+        console.log("\n" + makeTable(["vault", "role", "shares", "NAV/share", "value ≈ USDC", "withdraw now"], rows.map((r) => [r.nickname ?? r.vault, r.role, r.shares, r.navPerShare ?? "—", r.value ?? "—", r.withdrawWindow.open ? "window open" : `closed → ${ts(r.withdrawWindow.nextChangeAt)}`])) + "\n");
+    });
+    supportsDryRun(vault.command("deposit <vault> <amount>"))
+        .description("Deposit USDC from the trading balance into a vault (POST /lake/deposit, deposit_to_lake) for shares at NAV; supports --dry-run")
+        .option("--account <address>", "With --dry-run: plan for this account without loading a key")
+        .option("--idempotency-key <uuid>", "Re-send an earlier attempt with ITS key (only safe retry after ORDER_PENDING; default: a fresh key)")
+        .action(async (ref, amount, o, cmd) => {
+        assertPacifica();
+        const dryRun = isDryRun(cmd);
+        const idempotencyKey = keyOf(o.idempotencyKey);
+        const c = publicClient();
+        const s = await masterSigning(o.account, dryRun);
+        const v = findVault(await fetchVaults(c, s.identity.account), ref);
+        const [info, whitelist] = await Promise.all([c.getAccount(s.identity.account), whitelistOrNull(c, v.address)]);
+        const plan = planVaultDeposit(v, s.identity.account, amount, { availableToWithdraw: availableOf(info, s.identity.account), whitelist });
+        const sharesBefore = heldShares(v, s.identity.account).shares ?? "0";
+        const req = buildVaultDepositRequest(v.address, plan.amount, s.identity, { timestamp: Date.now(), idempotencyKey });
+        if (!isJson())
+            printWarnings(`Depositing ${plan.amount} USDC into vault ${v.address} "${v.nickname ?? ""}" (manager ${v.manager ?? "none"}) — ≈ ${plan.estimatedShares ?? "?"} shares; signer: master`, plan.warnings);
+        if (dryRun)
+            return printDryRun(plan, req, s.tier === null ? null : "master");
+        const data = await send(s, req, {
+            what: `vault deposit ${plan.amount} USDC into ${v.address}`,
+            check: `perp -e pacifica vault positions — shares in vault ${v.address} (${sharesBefore} before this request)`,
+            logType: "vault_deposit", symbol: "USDC", size: plan.amount, before: { shares: sharesBefore }, meta: { vault: v.address, manager: v.manager },
+        });
+        const minted = typeof data.shares_minted === "string" ? data.shares_minted : null;
+        if (isJson())
+            return printJson(jsonOk({ deposited: true, vault: v.address, amount: plan.amount, sharesMinted: minted, idempotencyKey: req.idempotencyKey, response: data }));
+        console.log(chalk.green(`\n  Deposited ${plan.amount} USDC — shares minted: ${minted ?? "(not in response)"}\n`));
+    });
+    supportsDryRun(vault.command("withdraw <vault> [shares]"))
+        .description("Redeem vault shares back into YOUR OWN trading balance (POST /lake/withdraw, withdraw_from_lake; no destination exists); supports --dry-run")
+        .option("--all", "Redeem every share the account holds")
+        .option("--account <address>", "With --dry-run: plan for this account without loading a key")
+        .option("--idempotency-key <uuid>", "Re-send an earlier attempt with ITS key (only safe retry after ORDER_PENDING; default: a fresh key)")
+        .action(async (ref, shares, o, cmd) => {
+        assertPacifica();
+        if ((shares === undefined) === (o.all !== true)) {
+            throw new PerpError("INVALID_PARAMS", "vault withdraw: give exactly one of <shares> or --all", { remediation: "e.g. perp -e pacifica vault withdraw <vault> 50 | --all" });
+        }
+        const dryRun = isDryRun(cmd);
+        const idempotencyKey = keyOf(o.idempotencyKey);
+        const c = publicClient();
+        const s = await signing(o.account, dryRun);
+        const v = findVault(await fetchVaults(c, s.identity.account), ref);
+        const lake = await c.getAccount(v.address);
+        const plan = planVaultWithdraw(v, s.identity.account, o.all === true ? "all" : shares, { nowMs: Date.now(), vaultAvailableToWithdraw: isPlainDecimal(lake.available_to_withdraw) ? lake.available_to_withdraw : null });
+        const req = buildVaultWithdrawRequest(v.address, plan.shares, s.identity, { timestamp: Date.now(), idempotencyKey });
+        if (req.body.account !== s.identity.account)
+            throw new Error("vault withdraw body account mismatch");
+        if (!isJson())
+            printWarnings(`Redeeming ${plan.shares} shares (≈ ${plan.estimatedAmount ?? "?"} USDC) from vault ${v.address} "${v.nickname ?? ""}" (manager ${v.manager ?? "none"}) to ${plan.destination}`, plan.warnings);
+        if (dryRun)
+            return printDryRun(plan, req, s.tier);
+        const data = await send(s, req, {
+            what: `vault withdraw ${plan.shares} shares from ${v.address}`,
+            check: `perp -e pacifica vault positions — shares in vault ${v.address} (${plan.heldShares} before this request)`,
+            logType: "vault_withdraw", symbol: "USDC", size: plan.shares, before: { shares: plan.heldShares }, meta: { vault: v.address, estimatedAmount: plan.estimatedAmount },
+        });
+        const amt = typeof data.amount_withdrawn === "string" ? data.amount_withdrawn : null;
+        if (isJson())
+            return printJson(jsonOk({ withdrawn: true, vault: v.address, shares: plan.shares, amountWithdrawn: amt, destination: plan.destination, idempotencyKey: req.idempotencyKey, response: data }));
+        console.log(chalk.green(`\n  Redeemed ${plan.shares} shares → ${amt ?? "(amount not in response)"} USDC credited to ${plan.destination}\n`));
+    });
+}
+// ── helpers ──────────────────────────────────────────────────────────────
+/** Unofficial whitelist read: null when unreadable (advisory only — the venue's refusal is final). */
+async function whitelistOrNull(c, vault) {
+    try {
+        return await fetchDepositWhitelist(c, vault);
+    }
+    catch {
+        return null;
+    }
+}
+function requireAddress(s) {
+    const a = s.trim();
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(a)) {
+        throw new PerpError("INVALID_PARAMS", `Not a Solana (base58) address: "${s}"`, { remediation: "Pass a base58 Solana address" });
+    }
+    return a;
+}
+function parseDirection(s) {
+    const d = s.trim().toLowerCase();
+    if (d === "long" || d === "short")
+        return d;
+    throw new PerpError("INVALID_PARAMS", `direction must be long or short (got "${s}")`, { remediation: "long = target below mark, short = target above mark" });
+}
+function parseWhole(s, what) {
+    if (!/^[1-9]\d*$/.test(s.trim()))
+        throw new PerpError("INVALID_PARAMS", `${what} must be a positive whole number (got "${s}")`);
+    return Number(s.trim());
+}
+function mul(a, b) {
+    return trimDecimal(mulDecimal(a, b));
+}
+/** available_to_withdraw of GET /account; unreadable → EXCHANGE_ERROR (never treated as 0). */
+function availableOf(info, account) {
+    const v = info.available_to_withdraw;
+    if (!isPlainDecimal(v))
+        throw new PerpError("EXCHANGE_ERROR", `Pacifica /account for ${account} has no readable available_to_withdraw`, { exchange: "pacifica" });
+    return v;
+}
+function sortByTvl(v) {
+    return [...v].sort((a, b) => Number(b.tvl) - Number(a.tvl));
+}
+function windowLabel(v) {
+    const { withdrawWindowS: w, withdrawDurationS: d } = v.config;
+    return w === null || d === null ? "always" : `${(d / 3600).toFixed(1)}h every ${(w / 3600).toFixed(1)}h`;
+}
+function printWarnings(title, warnings) {
+    console.log(chalk.cyan(`\n  ${title}`));
+    for (const w of warnings)
+        console.log(chalk.yellow(`  ! ${w}`));
+}
+function printQuote(q) {
+    console.log(chalk.white.bold(`\n  Print ${q.direction.toUpperCase()} ${q.game} — preview`));
+    for (const [k, v] of Object.entries({
+        "deposit (locked)": `${q.deposit} USDC`,
+        leverage: `${q.leverage}x  → notional ${q.notional} USDC`,
+        "target / mark": `${q.strikePrice} / ${q.markPrice}  (${q.targetDistancePct}% away; allowed ${q.allowedTargetDistancePct.min}%–${q.allowedTargetDistancePct.max}%)`,
+        "size on fill": `${q.size} ${q.asset} at exactly ${q.strikePrice}`,
+        "liquidation": `${q.docsLiquidationPrice ?? "unknown (docs formula gives ≤ 0)"} — docs-formula outer bound only; observed earlier in one live case, venue trigger unpublished`,
+        "after a fill": "ordinary position in your main account: continuous mark-price liquidation, nets with an existing position, may be cross-margined (perp -e pacifica account positions)",
+        "MAX LOSS": `${q.maxLoss} USDC deposit + every premium credited — never more`,
+        cycles: q.cycles === null ? `rolls every ${q.cycleDays}d until cancelled` : `${q.cycles} × ${q.cycleDays}d (up to ${q.maxDurationDays} days)`,
+        "cancel settles": `at the end of the running cycle (up to ${q.cancelSettlesWithinDays}d)`,
+        premium: "set by the venue each cycle (not quoted here)",
+    }))
+        console.log(`  ${k.padEnd(18)} ${v}`);
+    console.log("");
+}
+function printPositions(account, rows) {
+    if (rows.length === 0) {
+        console.log(chalk.gray(`\n  No Print orders for ${account}.\n`));
+        return;
+    }
+    console.log("\n" + makeTable(["address", "game", "dir", "deposit", "lev", "strike", "premium", "liq (docs, outer)", "status", "cycle ends"], rows.map((p) => [p.address, p.game, p.direction, p.deposit, `${p.leverage}x`, p.strikePrice, p.premiumPaid ?? "—", p.docsLiquidationPrice ?? "—", p.status, ts(p.currentCycleEndAt ?? p.scheduledEndAt)])) + "\n");
+}

package/dist/commands/pacifica-orders.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pacifica-specific order types exposed through `perp -e pacifica trade …`.
+ *
+ * Of Pacifica's strategy order types (docs trading-on-pacifica/order-types/strategies) only Atomic
+ * has an API path: it is a batch of ordinary market orders (POST /orders/batch). Chase, OCO,
+ * Trailing Stop, Swarm, Trigger Swarm and Conditional Market / Limit have no documented API / SDK
+ * path (as of 2026-10-19): no REST endpoint, no signing operation type (api/signing/operation-types),
+ * no batch action type and no order-type code; the official python-sdk and Pacifica MCP server
+ * expose none. Nearest perp-cli equivalents: `trade twap` (≈ Swarm: a split market execution) and
+ * `trade tpsl` (≈ OCO bracket exit: position take-profit + stop-loss).
+ */
+import type { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerPacificaOrderCommands(trade: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, isDryRun: () => boolean): void;

package/dist/commands/pacifica-orders.js

@@ -0,0 +1,142 @@
+/**
+ * Pacifica-specific order types exposed through `perp -e pacifica trade …`.
+ *
+ * Of Pacifica's strategy order types (docs trading-on-pacifica/order-types/strategies) only Atomic
+ * has an API path: it is a batch of ordinary market orders (POST /orders/batch). Chase, OCO,
+ * Trailing Stop, Swarm, Trigger Swarm and Conditional Market / Limit have no documented API / SDK
+ * path (as of 2026-10-19): no REST endpoint, no signing operation type (api/signing/operation-types),
+ * no batch action type and no order-type code; the official python-sdk and Pacifica MCP server
+ * expose none. Nearest perp-cli equivalents: `trade twap` (≈ Swarm: a split market execution) and
+ * `trade tpsl` (≈ OCO bracket exit: position take-profit + stop-loss).
+ */
+import chalk from "chalk";
+import { supportsDryRun } from "../cli-flags.js";
+import { PerpError, extractErrorMessage, parsePositiveDecimal } from "../errors.js";
+import { atomicBasketRiskCheck, atomicDryRunPlan, atomicIncompleteError, atomicLegClientOrderId, atomicLegPayload, atomicMarketsOf, executeAtomic, parseAtomicLegs, requireAtomicReduceOnly, sizeAtomicLegs, } from "../exchanges/pacifica-atomic.js";
+import { resolveSlippage } from "../exchanges/slippage.js";
+import { parseSlippageBpsFlag } from "./trade.js";
+import { reduceOnlyGateOf, unsupported } from "../exchanges/trading-v2.js";
+import { getVenue } from "../exchanges/venue.js";
+import { quarantineEntryFor, quarantineSymbol } from "../bot/quarantine.js";
+import { enforceOrderRisk } from "../trade-validator.js";
+import { assessRisk, loadRiskLimits } from "../risk.js";
+import { logExecution } from "../execution-log.js";
+import { invalidateCache } from "../cache.js";
+import { printJson, jsonOk } from "../utils.js";
+export function registerPacificaOrderCommands(trade, getAdapter, isJson, isDryRun) {
+    supportsDryRun(trade.command("atomic"))
+        .description("Pacifica only: weighted basket of market orders across markets, sent in ONE batch request. Each leg fills or fails on its own (not all-or-nothing). "
+        + "An unconfirmed leg → ORDER_PENDING and its symbol is quarantined; a batch failure other than HTTP 400 / 429 (timeout, 5xx, unreadable answer) quarantines EVERY leg. "
+        + "Pacifica Chase / OCO / Trailing / Swarm have no documented API (as of 2026-10-19) — nearest here: trade twap (≈ Swarm), trade tpsl (≈ OCO)")
+        .requiredOption("--usd <total>", "Total basket notional in USD, split across the legs by weight at each mark price")
+        .option("--long <legs...>", "Buy legs: SYMBOL[:WEIGHT] (up to 5; no weight = 1)")
+        .option("--short <legs...>", "Sell legs: SYMBOL[:WEIGHT] (up to 5; no weight = 1)")
+        .option("--reduce-only", "Every leg reduce-only: --long legs must close shorts, --short legs must close longs")
+        .option("--slippage-bps <n>", "Per-leg slippage bound in bps (default: settings slippageBps.pacifica → defaultSlippageBps)")
+        .option("--force", "Bypass local risk-limit checks (maxPosition / total exposure) for every leg")
+        .action(async (opts) => {
+        const adapter = await getAdapter();
+        if (adapter.name !== "pacifica") {
+            const def = getVenue(adapter.name);
+            throw unsupported(def.displayName, "atomicOrder", "Atomic is a Pacifica basket order (POST /orders/batch of market orders)", "Run it on Pacifica (perp -e pacifica trade atomic …), or use perp trade multi for a cross-venue multi-leg order");
+        }
+        const pac = adapter;
+        const specs = parseAtomicLegs(opts.long ?? [], opts.short ?? []);
+        const usd = parsePositiveDecimal(opts.usd, "--usd");
+        const slippage = resolveSlippage("pacifica", parseSlippageBpsFlag(opts.slippageBps));
+        const reduceOnly = opts.reduceOnly === true;
+        const [info, prices] = await Promise.all([pac.sdk.getInfo(), pac.sdk.getPrices()]);
+        const legs = sizeAtomicLegs(specs, usd, atomicMarketsOf(specs, info, prices), slippage.bps);
+        // Pre-send gates (read only), before the dry-run return so a dry run reports the same refusal.
+        if (reduceOnly) {
+            const gate = reduceOnlyGateOf(adapter);
+            if (gate !== null)
+                throw gate;
+            invalidateCache("acct");
+            requireAtomicReduceOnly(legs, await adapter.getPositions());
+        }
+        else {
+            for (const l of legs) {
+                const q = quarantineEntryFor(l.symbol, (m) => { if (!isJson())
+                    console.error(m); });
+                if (q !== null) {
+                    throw new PerpError("RISK_VIOLATION", `${l.symbol} is quarantined by ${q.strategy}: ${q.reason}`, {
+                        exchange: "pacifica",
+                        remediation: `${q.remediation} — only reduce-only orders are accepted until a human clears it (perp strategy quarantine-clear ${l.symbol})`,
+                    });
+                }
+                await enforceOrderRisk(adapter, { symbol: l.symbol, size: Number(l.size), price: Number(l.mark), force: opts.force });
+            }
+            // The basket as one order: total notional vs total exposure, new markets vs max positions.
+            if (opts.force !== true) {
+                const [balance, positions] = await Promise.all([adapter.getBalance(), adapter.getPositions()]);
+                const assessment = assessRisk([{ exchange: adapter.name, balance }], positions.map(position => ({ exchange: adapter.name, position })), loadRiskLimits());
+                atomicBasketRiskCheck(assessment, legs, positions);
+            }
+        }
+        const builder = await pac.builderDecision();
+        const builderCode = builder.applied === null ? null : builder.applied.identity;
+        const payloads = legs.map(l => atomicLegPayload(l, { reduceOnly, slippageBps: slippage.bps, clientOrderId: atomicLegClientOrderId(), builderCode }));
+        const legView = legs.map((l, i) => ({
+            symbol: l.symbol, side: l.side, weight: l.weight, share: Number(l.share.toFixed(6)), mark: l.mark, lotSize: l.lotSize,
+            size: l.size, notionalUsd: Number(l.notionalUsd.toFixed(2)), clientOrderId: payloads[i].client_order_id,
+        }));
+        const summary = { exchange: "pacifica", totalUsd: usd, reduceOnly, slippageBps: slippage.bps, legs: legView, builderFee: builder.applied, ...(builder.note !== null ? { builderNote: builder.note } : {}) };
+        if (isDryRun()) {
+            const tier = pac.activeSignerTier;
+            const plan = atomicDryRunPlan(payloads, {
+                account: pac.isReadOnly ? "<no signer configured: a live run needs a Pacifica key>" : pac.publicKey,
+                agentWallet: tier === "agent" ? "<agent wallet public key>" : null,
+                timestamp: Date.now(),
+            });
+            for (const l of legs) {
+                logExecution({ type: "multi_leg", exchange: "pacifica", symbol: l.symbol, side: l.side, size: l.size, status: "simulated", dryRun: true, meta: { atomic: true, reduceOnly } });
+            }
+            if (isJson())
+                return printJson(jsonOk({ dryRun: true, sent: false, action: "atomic_order", ...summary, request: plan }));
+            console.log(chalk.yellow("\n  [DRY RUN] Would send a Pacifica Atomic basket (nothing signed or sent):"));
+            for (const l of legView)
+                console.log(chalk.gray(`    ${l.side.toUpperCase().padEnd(4)} ${l.size} ${l.symbol} ≈ $${l.notionalUsd} (weight ${l.weight}, mark ${l.mark})`));
+            console.log(chalk.gray(`    reduce-only: ${reduceOnly} · slippage: ${slippage.bps} bps per leg · builder: ${builder.applied === null ? "none" : builder.applied.identity}`));
+            console.log(chalk.gray(`    ${plan.endpoint}\n${JSON.stringify(plan.body, null, 2).split("\n").map(s => `    ${s}`).join("\n")}`));
+            console.log(chalk.gray(`    signed messages (create_market_order, one per leg):\n${plan.signedMessages.map(s => `    ${s}`).join("\n")}\n`));
+            return;
+        }
+        let outcomes;
+        let venueRaw;
+        try {
+            ({ outcomes, venueRaw } = await executeAtomic(pac, legs, payloads));
+        }
+        catch (e) {
+            for (const l of legs) {
+                logExecution({ type: "multi_leg", exchange: "pacifica", symbol: l.symbol, side: l.side, size: l.size, status: e instanceof PerpError && e.structured.code === "ORDER_PENDING" ? "unverified" : "failed", dryRun: false, error: extractErrorMessage(e), meta: { atomic: true, reduceOnly } });
+                if (!reduceOnly && e instanceof PerpError && e.structured.code === "ORDER_PENDING")
+                    quarantineAtomicLeg(l.symbol, extractErrorMessage(e), isJson);
+            }
+            throw e;
+        }
+        for (const o of outcomes) {
+            logExecution({
+                type: "multi_leg", exchange: "pacifica", symbol: o.symbol, side: o.side, size: o.size,
+                status: o.status === "unknown" ? "unverified" : o.status === "filled" || o.status === "partiallyFilled" ? "success" : "failed",
+                dryRun: false, ...(o.detail !== null && o.status !== "filled" ? { error: o.detail } : {}),
+                meta: { atomic: true, reduceOnly, orderId: o.orderId, clientOrderId: o.clientOrderId, filledSize: o.filledSize },
+            });
+            if (o.status === "unknown" && !reduceOnly)
+                quarantineAtomicLeg(o.symbol, o.detail ?? "outcome unknown", isJson);
+        }
+        const incomplete = atomicIncompleteError(outcomes);
+        if (incomplete !== null)
+            throw incomplete;
+        if (isJson())
+            return printJson(jsonOk({ ...summary, outcomes, venueRaw }));
+        console.log(chalk.green(`\n  Atomic basket filled on Pacifica ($${usd}):`));
+        for (const o of outcomes)
+            console.log(`  ${chalk.green("FILLED")}  ${o.side.toUpperCase().padEnd(4)} ${o.filledSize ?? o.size} ${o.symbol}  order ${o.orderId ?? "-"}`);
+        console.log();
+    });
+}
+function quarantineAtomicLeg(symbol, reason, isJson) {
+    quarantineSymbol("trade-atomic", symbol, `atomic leg on ${symbol}: outcome unknown (${reason})`, `Check the position and fills: perp -e pacifica account positions / trade fills ${symbol}`, (m) => { if (!isJson())
+        console.error(m); });
+}