perp-cli 0.12.15 → 0.14.0

package/dist/commands/agent.d.ts

@@ -1,4 +1,168 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
+import { loadSettings, type OndoAgentMeta, type ArcusAgentMeta, type QfexAgentMeta } from "../settings.js";
+import "../exchanges/venues/index.js";
+import type { Network, VenueId } from "../exchanges/venue-types.js";
+import { type LighterVenueId } from "../exchanges/venues/lighter-family.js";
+import { OwsSolanaSigner } from "../signer/ows-solana.js";
+/**
+ * Subcommand `--passphrase <pp>`: still accepted (existing scripts) but deprecated like the root
+ * flag — hidden from help, and a stderr warning when it was given on the command line (it is
+ * visible in ps / shell history). Use with `.hook("preAction", warnDeprecatedPassphrase)`.
+ */
+export declare function deprecatedPassphraseOption(what?: string, flags?: string): Option;
+export declare const ARGV_PASSPHRASE_WARNING = "[warn] --passphrase on the command line is DEPRECATED and visible in ps / shell history. Use the OWS_PASSPHRASE env var or pipe it on stdin.\n";
+/** preAction hook paired with deprecatedPassphraseOption(): warns once per command run. */
+export declare function warnDeprecatedPassphrase(cmd: Command): void;
+export declare function isLighterFamilyVenue(v: VenueId): v is LighterVenueId;
+/** Validate an explicit Lighter-family API key slot: 4..254, minus venue-reserved indexes. */
+export declare function assertLighterSlot(venue: LighterVenueId, n: number): void;
+/** Read one line from a TTY without echo (raw mode). */
+export declare function promptHidden(question: string): Promise<string>;
+export interface VerifyResult {
+    registered: boolean;
+    count: number;
+    items: unknown[];
+    warnings?: string[];
+}
+/** Extract the agent list from a Pacifica /agent/list envelope; throws on an unrecognized shape. */
+export declare function parsePacAgentList(json: unknown): unknown[];
+/**
+ * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
+ * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
+ */
+export declare function confirmImportAccount(explicitAccountId: string | null, json: boolean): (binding: {
+    accountId: string;
+    isPrimaryAccount: boolean;
+    method: string;
+}) => Promise<boolean>;
+/** Agent-management operation gated per venue/network. */
+export type AgentOp = "approve" | "revoke" | "rotate";
+/**
+ * Why agent `op` cannot run for `venue` on `network`; null when it can. Every
+ * other venue resolves endpoints / signing chain from the selected network
+ * (venue definition) — never a mainnet fallback.
+ *
+ * Aster testnet: approve uses POST /fapi/v3/registerAndApproveAgent, documented
+ * for testnet (asterdex/api-docs V3 aster-finance-futures-api-testnet.md,
+ * 2026-05-12). Revoke / rotate need the master-signed DelAgent (AsterChain,
+ * Domain A) flow, which the testnet docs do not document.
+ */
+export declare function agentApproveUnsupportedReason(venue: VenueId, network: Network, op: AgentOp): string | null;
+/** Throws the uniform CAPABILITY_UNSUPPORTED error when agentApproveUnsupportedReason() is non-null. */
+export declare function assertAgentApproveSupported(venue: VenueId, network: Network, op: AgentOp): void;
+/** Default agent name per venue and network (the `--agent-name` default of `wallet agent approve`). */
+export declare function defaultAgentName(venue: VenueId, network: Network): string;
+export interface ApproveAgentParams {
+    venue: VenueId;
+    network: Network;
+    /** Master OWS wallet; null → settings.owsActiveWallet. Unused for Ondo. */
+    master: string | null;
+    /** null → defaultAgentName(venue). */
+    agentName: string | null;
+    /** 30d, 90d, 180d, 1y, or ISO-8601 datetime. */
+    expiresIn: string;
+    canPerp: boolean;
+    canSpot: boolean;
+    canWithdraw: boolean;
+    /**
+     * Replace an existing agent of the same name. Ondo / Arcus: re-register in place;
+     * Pacifica / Hyperliquid / Aster: the `wallet agent rotate` path (rotateVenueAgent).
+     */
+    rotate: boolean;
+    /** Resolved master passphrase. null → PASSPHRASE_REQUIRED for every venue except Ondo / Arcus. */
+    passphrase: string | null;
+    /** Lighter / Lighter RH slot; null → next free slot (free locally AND on-chain). */
+    apiKeyIndex: number | null;
+    /** Lighter / Lighter RH: allow an explicit apiKeyIndex whose slot already holds an on-chain key (`--force`). */
+    forceSlot: boolean;
+    /** Arcus subaccount: 0-9, or 255 for all. */
+    accountIndex: number;
+    /** Aster-only IP whitelist. (Builder approval: `perp wallet builder approve aster`.) */
+    aster: {
+        ipWhitelist?: string;
+    };
+    /** Ondo key id + secret; null → read from stdin (TTY prompt, or 2 piped lines). Never a flag. */
+    ondoKey: {
+        keyId: string;
+        secret: string;
+    } | null;
+}
+export type ApproveAgentOutcome = {
+    venue: "ondo";
+    meta: OndoAgentMeta;
+} | {
+    venue: "arcus";
+    meta: ArcusAgentMeta;
+} | {
+    venue: LighterVenueId;
+    agentName: string;
+    expiresAt: string;
+    result: LtApproveFlowResult;
+} | {
+    venue: "pacifica";
+    agentName: string;
+    expiresAt: string;
+    result: PacApproveFlowResult;
+} | {
+    venue: "hyperliquid";
+    agentName: string;
+    expiresAt: string;
+    result: HlApproveFlowResult;
+} | {
+    venue: "aster";
+    agentName: string;
+    expiresAt: string;
+    result: ApproveFlowResult;
+};
+/**
+ * Register one agent wallet / API key on `venue`. Throws on any failure (the
+ * caller decides whether to exit or continue with other venues). Holds the
+ * per-venue lock for the duration of the venue round-trip.
+ */
+export declare function approveVenueAgent(p: ApproveAgentParams): Promise<ApproveAgentOutcome>;
+/**
+ * Loud warning for a QFEX key that has — or may have (it cannot be checked without acting) — the
+ * "Deposit and withdraw" permission. Such a key can withdraw with the key alone, and imported keys
+ * are stored with an empty passphrase (file permissions only). Not a block: a funding key is needed
+ * for a QFEX withdrawal. Shown at import and in `wallet agent list`. null = no warning.
+ */
+export declare function qfexWithdrawKeyWarning(meta: Pick<QfexAgentMeta, "agentName" | "permissions">): string | null;
+/** Venues `wallet agent rotate` (and `approve --rotate`) can rotate. */
+type RotatableVenue = "aster" | "hyperliquid" | "pacifica" | LighterVenueId;
+type RotatedAgentOutcome = Exclude<ApproveAgentOutcome, {
+    venue: "ondo" | "arcus";
+}>;
+export interface RotateAgentParams {
+    exchange: RotatableVenue;
+    network: Network;
+    agentNameToRotate: string;
+    /** null → the old agent's master, then settings.owsActiveWallet. */
+    master: string | null;
+    /** Resolved lazily, after the record / master checks (null → PASSPHRASE_REQUIRED). */
+    passphrase: () => Promise<string | null>;
+    expiresIn: string;
+    /** Both undefined → inherit the old agent's trade permissions. */
+    canPerp: boolean | undefined;
+    canSpot: boolean | undefined;
+    /** Never inherited: true only when --can-withdraw was passed explicitly (Aster: needs ipWhitelist). */
+    canWithdraw: boolean | undefined;
+    /** Aster-only IP whitelist. */
+    ipWhitelist: string | undefined;
+}
+/**
+ * Rotate an agent: venue-confirmed revoke of the existing agent (when one is recorded), delete
+ * its dead OWS wallet and local record, then approve a fresh agent under the same name. The single
+ * path of `wallet agent rotate` and `wallet agent approve --rotate`.
+ */
+export declare function rotateVenueAgent(p: RotateAgentParams): Promise<RotatedAgentOutcome>;
+/** Live (read-only) registration check for `venue` — `wallet agent verify <venue>`. */
+export declare function verifyVenueAgent(venue: VenueId, network: Network, opts: {
+    master: string | null;
+    passphrase: string;
+}): Promise<VerifyResult>;
+/** Human-readable summary of a successful approve (no secrets — public ids/addresses only). */
+export declare function printApproveOutcome(outcome: ApproveAgentOutcome): void;
 /**
  * Register the per-DEX agent-wallet management subtree (`approve` /
  * `list` / `revoke` / `rotate` / `verify`) under the supplied parent
@@ -7,6 +171,34 @@ import { Command } from "commander";
  * relocates it to `wallet agent ...`.
  */
 export declare function registerWalletAgentCommands(walletCmd: Command, isJson: () => boolean): void;
+export interface ApproveFlowResult {
+    agentAddress: `0x${string}`;
+    agentName: string;
+    expiresAt: string;
+    owsApiKeyId: string;
+    policyId: string;
+    asterApprovalNonce: string;
+    userEvmAddress: `0x${string}`;
+}
+/** Aster: an API wallet with withdraw permission must carry an IP whitelist (pre-flight, nothing signed). */
+export declare function assertAsterWithdrawIpWhitelist(canWithdraw: boolean, ipWhitelist: string | undefined): void;
+/**
+ * Normalize the `--ip-whitelist` flag (comma- or space-separated) to the
+ * space-delimited form registerAndApproveAgent signs; "" when absent.
+ */
+export declare function asterSpaceIpWhitelist(raw: string | undefined): string;
+/**
+ * Parse an expires-in string to a Date.
+ * Accepts: "30d", "90d", "180d", "1y", or any ISO-8601 datetime string.
+ * Throws if malformed.
+ */
+export declare function parseExpiresIn(value: string): Date;
+export interface HlApproveFlowResult {
+    agentAddress: `0x${string}`;
+    agentName: string;
+    expiresAt: string;
+    userEvmAddress: `0x${string}`;
+}
 /** Public abstraction modes (CLI surface) → HL on-wire string. */
 declare const HL_ABSTRACTION_TO_WIRE: {
     readonly unified: "unifiedAccount";
@@ -32,7 +224,7 @@ interface HlSetAbstractionFlowResult {
  * Send a Hyperliquid `userSetAbstraction` action.
  *
  * Reuses the same EIP-712 user-signed domain (`HyperliquidSignTransaction`,
- * chainId 42161) and `OwsEvmSigner.signTypedData` plumbing as
+ * per-network signatureChainId) and `OwsEvmSigner.signTypedData` plumbing as
  * `runHlApproveFlow`; the only differences are the type struct
  * (`UserSetAbstraction` vs `ApproveAgent`) and the action payload.
  *
@@ -40,4 +232,42 @@ interface HlSetAbstractionFlowResult {
  * failure (Rule #2: no fallback, no silent retry).
  */
 export declare function runHlSetAbstractionFlow(opts: HlSetAbstractionFlowOpts): Promise<HlSetAbstractionFlowResult>;
+export interface PacApproveFlowResult {
+    agentSolanaAddress: string;
+    userSolanaAddress: string;
+    agentName: string;
+    expiresAt: string;
+}
+/**
+ * Revoke a Pacifica agent wallet.
+ *
+ * Endpoint + operation type follow the official Pacifica SDK
+ * (`rest/api_agent_keys_detailed.py`): `revoke_agent_wallet` → POST
+ * /agent/revoke. A missing agent address is refused (it must never widen into
+ * `revoke_all_agent_wallets`, which would also kill agents this CLI does not own).
+ *
+ * Rule #2: this THROWS on a rejected revoke. It previously POSTed an
+ * `unbind_agent_wallet` type to /agent/bind — neither of which Pacifica
+ * exposes — and discarded the response entirely, so a refused revoke was
+ * reported to the user as success while the agent key stayed authorized to
+ * trade. Callers that genuinely want best-effort must catch explicitly.
+ */
+export declare function revokePacAgent(masterSigner: OwsSolanaSigner, agentSolanaAddress: string | null, network: Network): Promise<void>;
+export interface LtApproveFlowResult {
+    apiKeyIndex: number;
+    publicKey: string;
+    accountIndex: number;
+    agentName: string;
+    expiresAt: string;
+    userEvmAddress: `0x${string}`;
+}
+/**
+ * Pick the first free Lighter slot in [5, 254].
+ *
+ * A slot is used when any local agent record (any network — conservative) holds it,
+ * when the venue reserves it, or when the account's on-chain key list shows a key on
+ * it (`onChainOccupied`) — an auto pick must never overwrite a key some other client
+ * (web app, another machine) is using.
+ */
+export declare function pickNextFreeLtSlot(settings: ReturnType<typeof loadSettings>, venue: LighterVenueId, onChainOccupied: ReadonlySet<number>): number;
 export {};