perp-cli 0.12.17 → 0.14.0

package/dist/bridge-signers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Master-wallet signers for the USDC bridge (`funds bridge send / exchange`, `funds rebalance
+ * execute --auto-bridge`).
+ *
+ * The master is either an OWS vault wallet (the supported secret store, SSOT Rule #3) or a raw
+ * private key (--private-key / wallets.json / legacy env). Addresses are read without decrypting
+ * anything (OWS: the vault's public account list; raw key: derived locally). Signing goes through
+ * the existing signers: OwsEvmSigner / OwsSolanaSigner for vault wallets (digest derived inside the
+ * signer), a local SigningKey / Keypair for raw keys.
+ */
+import { type Transaction } from "ethers";
+import { type Keypair, type VersionedTransaction } from "@solana/web3.js";
+import type { CliCredentialOpts } from "./config.js";
+import type { VenueId } from "./exchanges/venue-types.js";
+import type { SolanaSigner } from "./signer/interface.js";
+type TypedDataTypes = Record<string, Array<{
+    name: string;
+    type: string;
+}>>;
+/** EVM signer the bridge engine uses. OwsEvmSigner satisfies it; raw keys use pkEvmSigner. */
+export interface BridgeEvmSigner {
+    getAddress(): string;
+    /** Signs an unsigned, chain-bound tx (digest derived inside); returns the 65-byte 0x signature. */
+    signTransaction(tx: Transaction): Promise<string>;
+    signTypedData(domain: Record<string, unknown>, types: TypedDataTypes, value: Record<string, unknown>): Promise<string>;
+}
+/** Signs with a raw EVM private key (legacy raw-key masters). */
+export declare function pkEvmSigner(privateKey: string): BridgeEvmSigner;
+/** Signs with a raw Solana secret key (base58 or JSON byte array). */
+export declare function pkSolanaSigner(secret: string): Promise<SolanaSigner>;
+export declare function isBridgeEvmSigner(x: unknown): x is BridgeEvmSigner;
+export declare function isSolanaSigner(x: unknown): x is SolanaSigner;
+/**
+ * EIP-712 signature from the bridge signer, checked locally: the recovered address must be the
+ * signer's own address before anything is submitted.
+ */
+export declare function signTypedDataChecked(signer: BridgeEvmSigner, domain: Record<string, unknown>, types: TypedDataTypes, value: Record<string, unknown>, what: string): Promise<string>;
+/**
+ * Add the master's signature to a v0 Solana transaction (plus any locally generated keypairs,
+ * e.g. a CCTP event-data account). OWS never exposes a keypair, so the serialized transaction is
+ * signed inside the vault and the signature attached. The signature is verified locally before
+ * the caller sends anything.
+ */
+export declare function signVersionedSolanaTx(signer: SolanaSigner, tx: VersionedTransaction, extra?: Keypair[]): Promise<void>;
+/** The venue whose master key signs on a bridge chain (Solana → Pacifica's, EVM → the given EVM venue). */
+export declare function bridgeVenueForChain(chain: string, evmVenue?: VenueId): VenueId;
+/**
+ * The master wallet's own PUBLIC address on a bridge chain. Nothing is decrypted: OWS reads the
+ * vault's public account list, a raw key is derived locally.
+ */
+export declare function bridgeAddress(chain: string, venue: VenueId, opts: CliCredentialOpts): Promise<string>;
+/** The master wallet's signer on a bridge chain (OWS vault signer, or a raw-key signer). */
+export declare function loadBridgeSigner(chain: string, venue: VenueId, opts: CliCredentialOpts): Promise<BridgeEvmSigner | SolanaSigner>;
+export {};

package/dist/bridge-signers.js

@@ -0,0 +1,161 @@
+/**
+ * Master-wallet signers for the USDC bridge (`funds bridge send / exchange`, `funds rebalance
+ * execute --auto-bridge`).
+ *
+ * The master is either an OWS vault wallet (the supported secret store, SSOT Rule #3) or a raw
+ * private key (--private-key / wallets.json / legacy env). Addresses are read without decrypting
+ * anything (OWS: the vault's public account list; raw key: derived locally). Signing goes through
+ * the existing signers: OwsEvmSigner / OwsSolanaSigner for vault wallets (digest derived inside the
+ * signer), a local SigningKey / Keypair for raw keys.
+ */
+import { SigningKey, computeAddress, verifyTypedData } from "ethers";
+import { PublicKey } from "@solana/web3.js";
+import { PerpError } from "./errors.js";
+import { LocalSolanaSigner } from "./signer/solana-local.js";
+import { unsignedTxDigest } from "./signer/ows-evm.js";
+/** Signs with a raw EVM private key (legacy raw-key masters). */
+export function pkEvmSigner(privateKey) {
+    const key = new SigningKey(privateKey);
+    const address = computeAddress(key);
+    return {
+        getAddress: () => address,
+        signTransaction: async (tx) => key.sign(unsignedTxDigest(tx)).serialized,
+        signTypedData: async (domain, types, value) => {
+            const { TypedDataEncoder } = await import("ethers");
+            return key.sign(TypedDataEncoder.hash(domain, types, value)).serialized;
+        },
+    };
+}
+/** Signs with a raw Solana secret key (base58 or JSON byte array). */
+export async function pkSolanaSigner(secret) {
+    const { parseSolanaKeypair } = await import("./config.js");
+    return new LocalSolanaSigner(parseSolanaKeypair(secret));
+}
+export function isBridgeEvmSigner(x) {
+    const o = x;
+    return typeof o === "object" && o !== null && typeof o.getAddress === "function"
+        && typeof o.signTransaction === "function" && typeof o.signTypedData === "function";
+}
+export function isSolanaSigner(x) {
+    const o = x;
+    return typeof o === "object" && o !== null && typeof o.getPublicKeyBase58 === "function";
+}
+/**
+ * EIP-712 signature from the bridge signer, checked locally: the recovered address must be the
+ * signer's own address before anything is submitted.
+ */
+export async function signTypedDataChecked(signer, domain, types, value, what) {
+    const sig = await signer.signTypedData(domain, types, value);
+    const recovered = verifyTypedData(domain, types, value, sig);
+    if (recovered.toLowerCase() !== signer.getAddress().toLowerCase()) {
+        throw new PerpError("SIGNATURE_FAILED", `${what}: signature recovered ${recovered}, expected ${signer.getAddress()} — nothing was sent`, {
+            remediation: "Check the selected master wallet (perp wallet list); nothing was submitted",
+        });
+    }
+    return sig;
+}
+/**
+ * Add the master's signature to a v0 Solana transaction (plus any locally generated keypairs,
+ * e.g. a CCTP event-data account). OWS never exposes a keypair, so the serialized transaction is
+ * signed inside the vault and the signature attached. The signature is verified locally before
+ * the caller sends anything.
+ */
+export async function signVersionedSolanaTx(signer, tx, extra = []) {
+    if (extra.length > 0)
+        tx.sign(extra);
+    const pubkey = new PublicKey(signer.getPublicKeyBase58());
+    const message = tx.message.serialize();
+    let sig;
+    if (signer instanceof LocalSolanaSigner) {
+        sig = await signer.signMessage(message);
+    }
+    else if (typeof signer.signTransactionBytes === "function") {
+        sig = signer.signTransactionBytes(tx.serialize());
+    }
+    else {
+        throw new PerpError("NO_SIGNER_AVAILABLE", "This Solana signer cannot sign transactions", {
+            remediation: "Use an OWS vault wallet (perp wallet use <name>) or a local Solana key",
+        });
+    }
+    const nacl = (await import("tweetnacl")).default;
+    if (sig.length !== 64 || !nacl.sign.detached.verify(message, sig, pubkey.toBytes())) {
+        throw new PerpError("SIGNATURE_FAILED", `Solana transaction signature from ${pubkey.toBase58()} did not verify — nothing was sent`, {
+            remediation: "Check the selected master wallet; the transaction was not submitted",
+        });
+    }
+    tx.addSignature(pubkey, sig);
+}
+/** The venue whose master key signs on a bridge chain (Solana → Pacifica's, EVM → the given EVM venue). */
+export function bridgeVenueForChain(chain, evmVenue = "hyperliquid") {
+    return chain === "solana" ? "pacifica" : evmVenue;
+}
+async function resolveBridgeMaster(venue, opts) {
+    const { resolveOwsMaster, loadPrivateKey, isOwsKey } = await import("./config.js");
+    const ows = await resolveOwsMaster(venue, opts);
+    if (ows !== null)
+        return { kind: "ows", ...ows };
+    // Not an OWS wallet: a raw-key master (throws NO_SIGNER_AVAILABLE when none is configured).
+    const key = await loadPrivateKey(venue, opts.privateKey ?? undefined, opts.wallet ?? undefined);
+    if (isOwsKey(key)) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", `The ${venue} master resolved to an OWS wallet reference that the vault does not serve`, {
+            remediation: "Select the master wallet explicitly: --ows <name> (or perp wallet use <name>)",
+        });
+    }
+    return { kind: "pk", key };
+}
+function owsAccountMissing(wallet, vm, e) {
+    return new PerpError("NO_SIGNER_AVAILABLE", `OWS wallet "${wallet}" has no ${vm} account usable for bridging (${e instanceof Error ? e.message : String(e)})`, {
+        remediation: `Use an OWS wallet with an ${vm} account (perp wallet list), or pass --ows <name>`,
+    });
+}
+/**
+ * The master wallet's own PUBLIC address on a bridge chain. Nothing is decrypted: OWS reads the
+ * vault's public account list, a raw key is derived locally.
+ */
+export async function bridgeAddress(chain, venue, opts) {
+    const master = await resolveBridgeMaster(venue, opts);
+    if (master.kind === "ows") {
+        if (chain === "solana") {
+            const { OwsSolanaSigner } = await import("./signer/ows-solana.js");
+            try {
+                return OwsSolanaSigner.create(master.wallet, master.passphrase).getPublicKeyBase58();
+            }
+            catch (e) {
+                throw owsAccountMissing(master.wallet, "Solana", e);
+            }
+        }
+        const { OwsEvmSigner } = await import("./signer/ows-evm.js");
+        try {
+            return OwsEvmSigner.create(master.wallet, master.passphrase).getAddress();
+        }
+        catch (e) {
+            throw owsAccountMissing(master.wallet, "EVM", e);
+        }
+    }
+    if (chain === "solana")
+        return (await pkSolanaSigner(master.key)).getPublicKeyBase58();
+    return computeAddress(new SigningKey(master.key));
+}
+/** The master wallet's signer on a bridge chain (OWS vault signer, or a raw-key signer). */
+export async function loadBridgeSigner(chain, venue, opts) {
+    const master = await resolveBridgeMaster(venue, opts);
+    if (master.kind === "ows") {
+        if (chain === "solana") {
+            const { OwsSolanaSigner } = await import("./signer/ows-solana.js");
+            try {
+                return OwsSolanaSigner.create(master.wallet, master.passphrase);
+            }
+            catch (e) {
+                throw owsAccountMissing(master.wallet, "Solana", e);
+            }
+        }
+        const { OwsEvmSigner } = await import("./signer/ows-evm.js");
+        try {
+            return OwsEvmSigner.create(master.wallet, master.passphrase);
+        }
+        catch (e) {
+            throw owsAccountMissing(master.wallet, "EVM", e);
+        }
+    }
+    return chain === "solana" ? pkSolanaSigner(master.key) : pkEvmSigner(master.key);
+}

package/dist/cache.d.ts

@@ -19,6 +19,9 @@ export declare function withCache<T>(key: string, ttlMs: number, fetcher: () =>
  */
 export declare function fetchAndCache<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T>;
 /**
- * Invalidate cache entries matching a prefix (e.g., "acct" after a trade).
+ * Monotonic counter bumped on every account-cache invalidation. Adapters that keep
+ * in-process account / position / order snapshots (Aster) store the epoch with the
+ * snapshot and treat a mismatch as stale, so `invalidateCache("acct")` also reaches them.
  */
+export declare function accountCacheEpoch(): number;
 export declare function invalidateCache(keyPrefix?: string): void;

package/dist/cache.js

@@ -77,7 +77,18 @@ export async function fetchAndCache(key, ttlMs, fetcher) {
 /**
  * Invalidate cache entries matching a prefix (e.g., "acct" after a trade).
  */
+let _accountEpoch = 0;
+/**
+ * Monotonic counter bumped on every account-cache invalidation. Adapters that keep
+ * in-process account / position / order snapshots (Aster) store the epoch with the
+ * snapshot and treat a mismatch as stale, so `invalidateCache("acct")` also reaches them.
+ */
+export function accountCacheEpoch() {
+    return _accountEpoch;
+}
 export function invalidateCache(keyPrefix) {
+    if (keyPrefix === undefined || keyPrefix === "acct" || "acct".startsWith(keyPrefix))
+        _accountEpoch++;
     try {
         const prefix = keyPrefix ? safeKey(keyPrefix) : "";
         const files = readdirSync(CACHE_DIR);

package/dist/cli-flags.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Root-level CLI flags shared by every command (single source).
+ *
+ * `--dry-run` and `-n/--network` are defined ONLY on the root program. Commander
+ * (v13, non-positional options) lets the root consume a root option wherever it
+ * appears in argv — so a subcommand that re-declares `--dry-run` never sees it
+ * (the root swallows it) and silently runs live. Commands therefore never declare
+ * these options themselves; they read them with `isDryRun(cmd)` / `networkOf(cmd)`.
+ *
+ * Dry-run is default-deny: `installDryRunGuard(root)` rejects `--dry-run` with
+ * INVALID_PARAMS on every command that has not been explicitly marked with
+ * `supportsDryRun(cmd)`. A write command added later without dry-run handling
+ * therefore refuses `--dry-run` instead of executing live.
+ */
+import { Command, Option } from "commander";
+import type { Network } from "./exchanges/venue-types.js";
+export declare const NETWORKS: readonly ["mainnet", "testnet"];
+/** `-n, --network` option for the root program (validated: a typo is a usage error, never mainnet). */
+export declare function networkOption(): Option;
+/**
+ * The root-only safety flags (`-n/--network`, `--dry-run`) — declared ONCE on the root program
+ * (cli-program.ts) and by tests that mount a command subtree on a bare root.
+ */
+export declare function addRootSafetyOptions(root: Command): Command;
+/** True when the root `--dry-run` flag is set (wherever it appeared in argv). */
+export declare function isDryRun(cmd: Command): boolean;
+/** The validated `-n` network. Throws INVALID_PARAMS for anything but mainnet/testnet (no coercion). */
+export declare function networkOf(cmd: Command): Network;
+export declare function parseNetwork(value: unknown): Network;
+/**
+ * Mark a command as honoring `--dry-run`: it must return a plan — `sent: false` — before
+ * SIGNING or SENDING anything. Contract (review L3): reading account state (balance /
+ * positions / open orders, needed to size closes and run the local risk check) may resolve
+ * the configured credentials — that can decrypt a key or prompt for the passphrase — but a
+ * dry-run never signs, never sends, and never writes venue state. Commands that can plan
+ * from public data alone (funds deposit/withdraw plans, `funds bridge send` with --sender
+ * and --recipient) load no key. Returns the command for chaining.
+ */
+export declare function supportsDryRun<T extends Command>(cmd: T): T;
+export declare function honorsDryRun(cmd: Command): boolean;
+export declare function commandPath(cmd: Command): string;
+/** Throws INVALID_PARAMS when `--dry-run` is set on a command that does not honor it. */
+export declare function assertDryRunSupported(actionCommand: Command): void;
+/**
+ * Root preAction hook: validates `-n` and enforces default-deny dry-run before any
+ * command action runs (so nothing is loaded or signed for a rejected invocation).
+ */
+export declare function installDryRunGuard(root: Command): void;
+/** Every command in the tree (depth-first), excluding the root. */
+export declare function allCommands(root: Command): Command[];

package/dist/cli-flags.js

@@ -0,0 +1,104 @@
+/**
+ * Root-level CLI flags shared by every command (single source).
+ *
+ * `--dry-run` and `-n/--network` are defined ONLY on the root program. Commander
+ * (v13, non-positional options) lets the root consume a root option wherever it
+ * appears in argv — so a subcommand that re-declares `--dry-run` never sees it
+ * (the root swallows it) and silently runs live. Commands therefore never declare
+ * these options themselves; they read them with `isDryRun(cmd)` / `networkOf(cmd)`.
+ *
+ * Dry-run is default-deny: `installDryRunGuard(root)` rejects `--dry-run` with
+ * INVALID_PARAMS on every command that has not been explicitly marked with
+ * `supportsDryRun(cmd)`. A write command added later without dry-run handling
+ * therefore refuses `--dry-run` instead of executing live.
+ */
+import { Option } from "commander";
+import { PerpError } from "./errors.js";
+export const NETWORKS = ["mainnet", "testnet"];
+/** `-n, --network` option for the root program (validated: a typo is a usage error, never mainnet). */
+export function networkOption() {
+    return new Option("-n, --network <network>", "Network: mainnet or testnet").choices(NETWORKS).default("mainnet");
+}
+/**
+ * The root-only safety flags (`-n/--network`, `--dry-run`) — declared ONCE on the root program
+ * (cli-program.ts) and by tests that mount a command subtree on a bare root.
+ */
+export function addRootSafetyOptions(root) {
+    return root
+        .addOption(networkOption())
+        .option("--dry-run", "Simulate without sending anything (only commands that support it; others reject --dry-run)");
+}
+function rootOf(cmd) {
+    let c = cmd;
+    while (c.parent)
+        c = c.parent;
+    return c;
+}
+/** True when the root `--dry-run` flag is set (wherever it appeared in argv). */
+export function isDryRun(cmd) {
+    return rootOf(cmd).opts().dryRun === true;
+}
+/** The validated `-n` network. Throws INVALID_PARAMS for anything but mainnet/testnet (no coercion). */
+export function networkOf(cmd) {
+    return parseNetwork(rootOf(cmd).opts().network);
+}
+export function parseNetwork(value) {
+    if (value === "mainnet" || value === "testnet")
+        return value;
+    throw new PerpError("INVALID_PARAMS", `Invalid network "${String(value)}" — expected one of: ${NETWORKS.join(", ")}`, {
+        remediation: "Pass -n mainnet or -n testnet (lowercase)",
+    });
+}
+const DRY_RUN_AWARE = new WeakSet();
+/**
+ * Mark a command as honoring `--dry-run`: it must return a plan — `sent: false` — before
+ * SIGNING or SENDING anything. Contract (review L3): reading account state (balance /
+ * positions / open orders, needed to size closes and run the local risk check) may resolve
+ * the configured credentials — that can decrypt a key or prompt for the passphrase — but a
+ * dry-run never signs, never sends, and never writes venue state. Commands that can plan
+ * from public data alone (funds deposit/withdraw plans, `funds bridge send` with --sender
+ * and --recipient) load no key. Returns the command for chaining.
+ */
+export function supportsDryRun(cmd) {
+    DRY_RUN_AWARE.add(cmd);
+    return cmd;
+}
+export function honorsDryRun(cmd) {
+    return DRY_RUN_AWARE.has(cmd);
+}
+export function commandPath(cmd) {
+    const parts = [];
+    for (let c = cmd; c && c.parent; c = c.parent)
+        parts.unshift(c.name());
+    return parts.join(" ");
+}
+/** Throws INVALID_PARAMS when `--dry-run` is set on a command that does not honor it. */
+export function assertDryRunSupported(actionCommand) {
+    if (!isDryRun(actionCommand) || honorsDryRun(actionCommand))
+        return;
+    throw new PerpError("INVALID_PARAMS", `'perp ${commandPath(actionCommand)}' does not support --dry-run (it would run live)`, {
+        remediation: "Remove --dry-run. Commands that can simulate say 'supports --dry-run' in --help",
+    });
+}
+/**
+ * Root preAction hook: validates `-n` and enforces default-deny dry-run before any
+ * command action runs (so nothing is loaded or signed for a rejected invocation).
+ */
+export function installDryRunGuard(root) {
+    root.hook("preAction", (_thisCommand, actionCommand) => {
+        networkOf(actionCommand);
+        assertDryRunSupported(actionCommand);
+    });
+}
+/** Every command in the tree (depth-first), excluding the root. */
+export function allCommands(root) {
+    const out = [];
+    const walk = (c) => {
+        for (const sub of c.commands) {
+            out.push(sub);
+            walk(sub);
+        }
+    };
+    walk(root);
+    return out;
+}

package/dist/cli-program.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The perp CLI Commander tree (root options + every command group), built without
+ * parsing argv — `src/index.ts` parses it; tests parse full argv through the same tree.
+ */
+import { Command } from "commander";
+import type { ExchangeAdapter } from "./exchanges/interface.js";
+import "./exchanges/venues/index.js";
+import { PerpError } from "./errors.js";
+export interface CliProgram {
+    program: Command;
+    getAdapterForExchange: (rawExchange: string) => Promise<ExchangeAdapter>;
+    isJson: () => boolean;
+}
+export declare function assertNoArgvSecrets(root: Command): void;
+/**
+ * `-n` used to be the record count of `history` / `account` subcommands (now `--limit`); it is the
+ * root network flag. A numeric `-n` / `--network` value on those commands is a migration error
+ * (INVALID_PARAMS "use --limit <n>") instead of the bare "invalid network" usage error. null = no such use.
+ */
+export declare function numericNetworkFlagError(argv: readonly string[]): PerpError | null;
+/** `perp --json` with no subcommand: the landing / usage document (static — no wallet or venue reads). */
+export declare function landingData(program: Command, version: string): {
+    name: string;
+    version: string;
+    usage: string;
+    help: string;
+    commands: {
+        name: string;
+        description: string;
+    }[];
+};
+export declare function buildProgram(opts: {
+    defaultExchange: string;
+    version: string;
+}): CliProgram;