perp-cli 0.12.17 → 0.14.0

package/dist/commands/funds-onchain.js

@@ -0,0 +1,286 @@
+/**
+ * `funds deposit aster|ondo`, `funds withdraw aster`, `funds address-book add ondo` — fund movements
+ * whose on-chain leg is signed by the OWS master wallet (src/evm-master-tx.ts).
+ *
+ * Every command: `--dry-run` prints the plan and returns before any key, adapter or network is
+ * touched; the live path runs all read-only checks before the first signature; an outcome that
+ * cannot be read after a send is ORDER_PENDING (logged "unverified"), never "failed".
+ */
+import chalk from "chalk";
+import { supportsDryRun } from "../cli-flags.js";
+import { cliCredentialOptsFrom } from "../config.js";
+import { PerpError, parsePositiveDecimal } from "../errors.js";
+import { logExecution } from "../execution-log.js";
+import { unsupported } from "../exchanges/trading-v2.js";
+import { getVenue, networkConfig } from "../exchanges/venue.js";
+import { ASTER_FUNDS_CHAINS } from "../exchanges/venues/aster.js";
+import { ONDO_DEPOSIT_CHAINS } from "../exchanges/venues/ondo.js";
+import { jsonOk, printJson } from "../utils.js";
+const realSleep = (ms) => new Promise(r => setTimeout(r, ms));
+export function registerOnchainFundsCommands(ctx) {
+    const { program, funds, deposit, withdraw, isJson, isDryRun, getNetwork, getAdapterForExchange, printFundsPlan, failStatus } = ctx;
+    const creds = () => cliCredentialOptsFrom(program.opts());
+    /** Execution-log + rethrow for a failed live fund movement (unknown outcome → "unverified"). */
+    const logFailure = (venue, asset, side, amount, err, meta) => {
+        const txHash = err instanceof PerpError ? err.structured.details?.txHash : undefined;
+        logExecution({
+            type: "bridge", exchange: venue, symbol: asset, side, size: amount, status: failStatus(err), dryRun: false,
+            error: err instanceof Error ? err.message : String(err),
+            meta: { action: side, ...meta, ...(typeof txHash === "string" ? { txHash } : {}) },
+        });
+    };
+    // ═══ Aster deposit — vault contract on BNB Chain / Arbitrum ═══
+    supportsDryRun(deposit.command("aster <amount>"))
+        .description("Deposit USDT / USDC into Aster perps through the vault contract on BNB Chain or Arbitrum (approve + deposit; mainnet only; supports --dry-run)")
+        // --chain, not --network: the root -n/--network (mainnet | testnet) would swallow a subcommand --network.
+        .option("--chain <chain>", "Source chain: bsc | arbitrum", "bsc")
+        .option("--asset <asset>", "Deposit asset: USDT | USDC", "USDT")
+        .action(async (amount, opts) => {
+        const net = getNetwork();
+        const { requireAsterFundsNetwork, asterFundsChain, asterFundsAsset, planAsterDeposit, executeAsterDeposit, awaitAsterDepositCredit, ASTER_DEPOSIT_CREDIT_TIMEOUT_MS, ASTER_DEPOSIT_CREDIT_POLL_MS } = await import("../exchanges/aster-funds.js");
+        requireAsterFundsNetwork(net, "deposit");
+        const chain = asterFundsChain(opts.chain);
+        const asset = asterFundsAsset(opts.asset);
+        parsePositiveDecimal(amount, "amount");
+        const pins = ASTER_FUNDS_CHAINS[chain];
+        if (isDryRun()) {
+            return printFundsPlan({
+                action: "deposit", venue: "aster", network: net, asset, amount, chain: pins.label, chainId: pins.chainId,
+                vault: pins.vault, token: pins.tokens[asset], broker: "1 (perp account)", signer: "OWS master wallet",
+                steps: `approve(vault, exact amount) when the allowance is short → vault.depositFor(${asset}, forAddress = the master wallet, amount, broker 1) → Deposit event check → venue credit poll`,
+                checks: "eth_chainId, on-chain decimals(), supportToken, paused(), token balance, native gas, allowance, deposit simulation",
+            });
+        }
+        const { loadMasterEvmSigner } = await import("../evm-master-tx.js");
+        const signer = await loadMasterEvmSigner("aster", creds(), "Aster deposit");
+        const depositor = signer.getAddress();
+        // The venue credit is confirmed through the API wallet — required before anything is sent.
+        const { AsterAdapter } = await import("../exchanges/aster.js");
+        const adapter = await getAdapterForExchange("aster");
+        if (!(adapter instanceof AsterAdapter))
+            throw new Error("aster venue did not produce an AsterAdapter");
+        if (adapter.activeSignerTier !== "agent") {
+            throw new PerpError("AGENT_NOT_REGISTERED", "Aster deposit confirms the venue credit through an API wallet, and none is usable on this computer", {
+                exchange: "aster", remediation: "Approve one first (this works before the first deposit): perp wallet agent approve aster — then retry the deposit",
+            });
+        }
+        if (adapter.userAddress.toLowerCase() !== depositor.toLowerCase()) {
+            throw new PerpError("INVALID_PARAMS", `The master wallet ${depositor} is not the owner of the Aster API wallet's account (${adapter.userAddress}) — the vault credits the sender`, {
+                exchange: "aster", remediation: "Select the wallet that owns the Aster account (--ows <wallet>)",
+            });
+        }
+        const plan = await planAsterDeposit({ network: net, chain, asset, amount, depositor });
+        const view = {
+            venue: "aster", network: net, asset, amount, depositor, chain: plan.chainLabel, chainId: plan.chainId,
+            vault: plan.vault, token: plan.token, decimals: plan.decimals, broker: plan.broker.toString(), needsApprove: plan.needsApprove,
+        };
+        if (!isJson()) {
+            console.log(chalk.cyan(`\n  Depositing ${amount} ${asset} into Aster perps on ${plan.chainLabel}...\n`));
+            console.log(`  From:  ${depositor}`);
+            console.log(`  Vault: ${plan.vault}`);
+            if (plan.needsApprove)
+                console.log(chalk.gray(`  Approving ${amount} ${asset} for the vault...`));
+        }
+        try {
+            const res = await executeAsterDeposit(plan, tx => signer.signTransaction(tx));
+            if (!isJson())
+                console.log(chalk.gray(`  Deposit tx ${res.depositTxHash} confirmed (Deposit event verified). Waiting for the venue credit...`));
+            const credit = await awaitAsterDepositCredit(() => adapter.depositWithdrawHistory(), res.depositTxHash, {
+                timeoutMs: ASTER_DEPOSIT_CREDIT_TIMEOUT_MS, pollMs: ASTER_DEPOSIT_CREDIT_POLL_MS, sleep: realSleep, now: () => Date.now(),
+            });
+            logExecution({
+                type: "bridge", exchange: "aster", symbol: asset, side: "deposit", size: amount, status: "success", dryRun: false,
+                meta: { action: "deposit", method: "vault", chain, txHash: res.depositTxHash, approveTxHash: res.approveTxHash },
+            });
+            if (isJson())
+                return printJson(jsonOk({ ...view, ...res, method: "vault", credit: { state: credit.state, amount: credit.amount, accountType: credit.accountType } }));
+            console.log(chalk.green(`\n  Deposit credited by Aster.`));
+            console.log(`  Amount:  ${amount} ${asset}`);
+            if (res.approveTxHash !== null)
+                console.log(`  Approve: ${res.approveTxHash}`);
+            console.log(`  TX Hash: ${res.depositTxHash}\n`);
+        }
+        catch (err) {
+            logFailure("aster", asset, "deposit", amount, err, { method: "vault", chain });
+            throw err;
+        }
+    });
+    // ═══ Aster withdraw — POST /fapi/v3/aster/user-withdraw ═══
+    {
+        const def = getVenue("aster");
+        const assets = def.capabilities?.withdrawAssets;
+        if (assets === null || assets === undefined || assets.length === 0)
+            throw new Error("aster declares no withdrawAssets but has a withdraw command");
+        supportsDryRun(withdraw.command("aster <amount>"))
+            .description(`Withdraw ${assets.join(" or ")} from Aster perps to your own address on BNB Chain or Arbitrum (mainnet only; needs an API wallet approved with --can-withdraw --ip-whitelist; supports --dry-run)`)
+            .option("--chain <chain>", "Destination chain: bsc | arbitrum", "bsc")
+            .option("--asset <asset>", `Asset to withdraw: ${assets.join(" | ")}`, assets[0])
+            .option("--to <address>", "Destination EVM address (must be the account's own address — the default)")
+            .action(async (amount, opts) => {
+            const asset = opts.asset.toUpperCase();
+            if (!assets.includes(asset)) {
+                throw new PerpError("INVALID_PARAMS", `Aster withdraws ${assets.join(" / ")} only (got "${opts.asset}")`, { remediation: `Use --asset ${assets.join(" or --asset ")}` });
+            }
+            const net = getNetwork();
+            const { requireAsterFundsNetwork, asterFundsChain } = await import("../exchanges/aster-funds.js");
+            requireAsterFundsNetwork(net, "withdraw");
+            const chain = asterFundsChain(opts.chain);
+            const pins = ASTER_FUNDS_CHAINS[chain];
+            if (!/^\d+(\.\d+)?$/.test(amount) || !(Number(amount) > 0)) {
+                throw new PerpError("INVALID_PARAMS", `Withdraw amount must be a positive decimal (got "${amount}")`);
+            }
+            if (isDryRun()) {
+                return printFundsPlan({
+                    action: "withdraw", venue: "aster", network: net, asset, amount, chain: pins.label, chainId: pins.chainId,
+                    destination: opts.to !== undefined ? opts.to : "the account's own address",
+                    fee: "read from POST /fapi/v3/aster/user-withdraw-info at send time (amount must exceed it; it is taken from the amount)",
+                    signatures: "master wallet EIP-712 \"Aster\" withdraw message + API wallet (canWithdraw, IP whitelist) request signature",
+                    note: "POST /fapi/v3/aster/user-withdraw; Aster only pays the account's own address",
+                });
+            }
+            await ctx.requireMaster("aster", "Aster withdraw");
+            const { AsterAdapter } = await import("../exchanges/aster.js");
+            const adapter = await getAdapterForExchange("aster");
+            if (!(adapter instanceof AsterAdapter))
+                throw new Error("aster venue did not produce an AsterAdapter");
+            const owner = adapter.userAddress;
+            if (opts.to !== undefined && opts.to.toLowerCase() !== owner.toLowerCase()) {
+                throw new PerpError("INVALID_PARAMS", `Aster only withdraws to the account's own address ${owner}`, { remediation: `Omit --to (defaults to ${owner})` });
+            }
+            if (!isJson()) {
+                console.log(chalk.cyan(`\n  Withdrawing ${amount} ${asset} from Aster...\n`));
+                console.log(`  Destination: ${owner} (${pins.label})`);
+            }
+            try {
+                const result = await adapter.withdraw(amount, owner, { chain, asset });
+                logExecution({
+                    type: "bridge", exchange: "aster", symbol: asset, side: "withdraw", size: amount, status: "success", dryRun: false,
+                    meta: { action: "withdraw", destination: owner, chain, withdrawId: result.withdrawId, fee: result.fee },
+                });
+                if (isJson())
+                    return printJson(jsonOk(result));
+                console.log(chalk.green(`\n  Withdrawal accepted by Aster.`));
+                console.log(`  Amount: ${amount} ${asset} (fee ${result.fee} ${asset} taken from it)`);
+                console.log(`  Withdraw id: ${result.withdrawId}`);
+                console.log(chalk.gray(`\n  Track it in the Aster app (Assets → History) until it arrives on ${pins.label}.\n`));
+            }
+            catch (err) {
+                logFailure("aster", asset, "withdraw", amount, err, { destination: owner, chain });
+                throw err;
+            }
+        });
+    }
+    // ═══ Ondo deposit — USDC transfer to the account's funding address ═══
+    supportsDryRun(deposit.command("ondo <amount>"))
+        .description("Deposit USDC into Ondo Perps: ERC-20 transfer to the account's funding address on Arbitrum or Ethereum (mainnet only; --probe sends a small amount first; supports --dry-run)")
+        .option("--chain <chain>", "Source chain: arbitrum | ethereum", "arbitrum")
+        .option("--probe <amount>", "Send this amount first, wait until Ondo credits it, then send the rest")
+        .action(async (amount, opts) => {
+        const net = getNetwork();
+        const f = await import("../exchanges/ondo/funds.js");
+        f.requireOndoDepositNetwork(net);
+        const chain = f.ondoDepositChain(opts.chain);
+        parsePositiveDecimal(amount, "amount");
+        const probe = opts.probe === undefined ? null : parsePositiveDecimal(opts.probe, "--probe");
+        const pins = ONDO_DEPOSIT_CHAINS[chain];
+        if (isDryRun()) {
+            return printFundsPlan({
+                action: "deposit", venue: "ondo", network: net, asset: "USDC", amount, chain: pins.label, chainId: pins.chainId, token: pins.usdc,
+                probe: probe === null ? "none (single transfer)" : probe, signer: "OWS master wallet",
+                destination: `first listed USDC ${chain} funding address of this account (POST /v1/wallet/deposit_address/list; provisioned only when none exists)`,
+                steps: probe === null
+                    ? "USDC transfer → wait for the credit (GET /v1/wallet/deposits)"
+                    : `USDC transfer of ${probe} (probe) → wait for the credit → USDC transfer of the remainder → wait for the credit (the remainder is NOT sent while the probe is uncredited)`,
+                checks: "eth_chainId, on-chain decimals(), USDC balance, ETH gas, funding address belongs to this account",
+            });
+        }
+        const { loadMasterEvmSigner } = await import("../evm-master-tx.js");
+        const signer = await loadMasterEvmSigner("ondo", creds(), "Ondo deposit");
+        const { OndoAdapter } = await import("../exchanges/ondo/adapter.js");
+        const adapter = await getAdapterForExchange("ondo");
+        if (!(adapter instanceof OndoAdapter))
+            throw new Error("ondo venue did not produce an OndoAdapter");
+        const client = adapter.restClient;
+        const funding = await f.resolveOndoDepositAddress(client, chain);
+        const plan = await f.planOndoDeposit({ network: net, chain, amount, probe, depositor: signer.getAddress(), funding });
+        const view = {
+            venue: "ondo", network: net, asset: "USDC", amount, probe, depositor: plan.depositor, chain: plan.chainLabel, chainId: plan.chainId,
+            token: plan.token, depositAddress: plan.depositAddress, accountId: plan.accountId, addressProvisioned: funding.provisioned,
+        };
+        if (!isJson()) {
+            console.log(chalk.cyan(`\n  Depositing ${amount} USDC into Ondo Perps from ${plan.chainLabel}...\n`));
+            console.log(`  From: ${plan.depositor}`);
+            console.log(`  To:   ${plan.depositAddress} (funding address of account ${plan.accountId}${funding.provisioned ? ", newly provisioned" : ""})`);
+            if (probe !== null)
+                console.log(chalk.gray(`  Probe: ${probe} USDC first; the rest follows once it is credited.`));
+        }
+        try {
+            const res = await f.executeOndoDeposit(plan, tx => signer.signTransaction(tx), () => client.get("/v1/wallet/deposits", null), {
+                timeoutMs: f.ONDO_DEPOSIT_CREDIT_TIMEOUT_MS, pollMs: f.ONDO_DEPOSIT_CREDIT_POLL_MS, sleep: realSleep, now: () => Date.now(),
+            });
+            logExecution({
+                type: "bridge", exchange: "ondo", symbol: "USDC", side: "deposit", size: amount, status: "success", dryRun: false,
+                meta: { action: "deposit", method: "transfer", chain, depositAddress: plan.depositAddress, txHashes: res.transfers.map(t => t.txHash) },
+            });
+            if (isJson())
+                return printJson(jsonOk({ ...view, ...res, method: "transfer", credited: true }));
+            console.log(chalk.green(`\n  Deposit credited by Ondo Perps.`));
+            for (const t of res.transfers)
+                console.log(`  ${t.step === "probe" ? "Probe  " : "Deposit"} ${t.amount} USDC: ${t.txHash}`);
+            console.log();
+        }
+        catch (err) {
+            logFailure("ondo", "USDC", "deposit", amount, err, { method: "transfer", chain, depositAddress: plan.depositAddress });
+            throw err;
+        }
+    });
+    // ═══ Address book (Ondo withdrawal destinations) ═══
+    const addressBook = funds.command("address-book").description("Withdrawal address book (Ondo Perps only withdraws to listed addresses)");
+    supportsDryRun(addressBook.command("add <venue> <address>"))
+        .description("Add the master wallet's own address to the Ondo Perps withdrawal address book (SIWE challenge signed by the OWS master wallet; supports --dry-run)")
+        .option("--label <text>", "Label of the address book entry")
+        .action(async (venue, address, opts) => {
+        const def = getVenue(venue);
+        if (def.id !== "ondo") {
+            throw unsupported(def.displayName, "address-book", "only Ondo Perps has a withdrawal address book", "perp funds address-book add ondo <address>");
+        }
+        const net = getNetwork();
+        if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+            throw new PerpError("INVALID_PARAMS", `"${address}" is not an EVM address`);
+        const plan = {
+            venue: "ondo", network: net, address, label: opts.label === undefined ? null : opts.label,
+            steps: "POST /v1/auth/erc-4361/address_book/get_challenge → personal_sign with the OWS master wallet → POST …/complete_challenge",
+        };
+        if (isDryRun()) {
+            if (isJson())
+                return printJson(jsonOk({ dryRun: true, sent: false, action: "address-book add", ...plan }));
+            console.log(chalk.yellow(`\n  [dry-run] Would add ${address} to the Ondo Perps address book (${net})`));
+            console.log(`  steps: ${plan.steps}`);
+            console.log(chalk.gray("  Nothing was signed or sent.\n"));
+            return;
+        }
+        const { loadMasterEvmSigner } = await import("../evm-master-tx.js");
+        const signer = await loadMasterEvmSigner("ondo", creds(), "Adding an Ondo address book entry");
+        if (signer.getAddress().toLowerCase() !== address.toLowerCase()) {
+            throw new PerpError("INVALID_PARAMS", `The CLI only adds the master wallet's own address (${signer.getAddress()}) to the Ondo address book; ${address} is a different address`, {
+                remediation: "Add other addresses in the Ondo Perps web app (Withdraw → address book)",
+            });
+        }
+        const { OndoAdapter } = await import("../exchanges/ondo/adapter.js");
+        const adapter = await getAdapterForExchange("ondo");
+        if (!(adapter instanceof OndoAdapter))
+            throw new Error("ondo venue did not produce an OndoAdapter");
+        const { addOndoAddressBookEntry } = await import("../exchanges/ondo/funds.js");
+        const res = await addOndoAddressBookEntry(adapter.restClient, {
+            wallet: signer.getAddress(), restUrl: networkConfig(def, net).restUrl, label: plan.label, signMessage: m => signer.signMessage(m),
+        });
+        if (isJson())
+            return printJson(jsonOk({ venue: "ondo", network: net, ...res }));
+        if (res.alreadyListed)
+            console.log(chalk.green(`\n  ${res.address} is already on the Ondo Perps address book.\n`));
+        else if (res.listed)
+            console.log(chalk.green(`\n  Added ${res.address} to the Ondo Perps address book.\n`));
+        else
+            console.log(chalk.yellow(`\n  Ondo accepted the challenge, but ${res.address} is not listed yet (a cooldown may apply). Check the Ondo Perps app before withdrawing.\n`));
+    });
+}

package/dist/commands/funds.d.ts

@@ -1,4 +1,29 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
 import type { Network } from "../pacifica/index.js";
+import { PerpError } from "../errors.js";
+import "../exchanges/venues/index.js";
+/**
+ * Execution-log status of a failed funds action: an unknown outcome (ORDER_PENDING — the request
+ * was sent and may have executed) is logged "unverified", never "failed".
+ */
+export declare function fundsFailStatus(err: unknown): "failed" | "unverified";
+/** A broadcast deposit whose confirmation could not be read: unknown outcome, carrying the signature. */
+export declare function depositOutcomeUnknown(signature: string, e: unknown): PerpError;
+/**
+ * Local withdraw-gate verdict for a Hyperliquid destination that is not (known to be) the account
+ * owner: settings.withdraw.hyperliquid allowlist + maxPerTx / maxPerDay (the QFEX gate mechanism,
+ * src/withdraw-gate.ts). "passes" or "would refuse: …"; never throws a POLICY_DENIED (dry runs).
+ */
+export declare function hyperliquidGateVerdict(network: string, amount: string, destination: string, nowMs: number): string;
+/**
+ * Enforce settings.withdraw.hyperliquid for a master-signed withdraw3 / usdSend to `destination`
+ * and record the attempt in the withdraw ledger BEFORE it is sent. Returns the ledger id (forget it
+ * only on a definite refusal), or null when the destination is the owner (no gate, no ledger).
+ */
+export declare function hyperliquidGateEnforce(network: string, amount: string, destination: string, owner: string | null, nowMs: number): string | null;
+/** Label for a chain id. An unmapped id is a programming error (covered by a unit test over every venue). */
+export declare function chainLabel(chain: string): string;
+/** "-e lighter: USDC → Ethereum; -e lighter-rh: USDG → Robinhood Chain" — from the venue definitions. */
+export declare function lighterFamilyWithdrawSummary(): string;
 export declare function registerFundsCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getNetwork: () => Network, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>): void;