perp-cli 0.12.17 → 0.14.1

package/dist/exchanges/hl-signing.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Hyperliquid signing — L1 actions (phantom agent, agent- or master-signable) and
+ * user-signed actions (HyperliquidSignTransaction EIP-712, master only). Mirrors
+ * hyperliquid-python-sdk `utils/signing.py` (action_hash, sign_l1_action,
+ * sign_user_signed_action and the *_SIGN_TYPES tables).
+ *
+ * Note: src/commands/agent.ts (approveAgent / userSetAbstraction) and
+ * src/commands/builder.ts (approveBuilderFee) still carry their own copies of the
+ * user-signed domain; they produce the same payload as signHlUserSignedAction.
+ */
+import type { EvmSigner } from "../signer/index.js";
+import type { Network } from "./venue.js";
+export interface HlSignature {
+    r: string;
+    s: string;
+    v: number;
+}
+type Eip712Field = {
+    name: string;
+    type: string;
+};
+/**
+ * keccak(msgpack(action) ‖ nonce u64be ‖ vault flag [‖ vault 20B] [‖ 0x00 ‖ expiresAfter u64be])
+ * — python SDK `action_hash`.
+ */
+export declare function hlL1ActionHash(action: Record<string, unknown>, nonce: number, vaultAddress: string | null, expiresAfter: number | null): Promise<string>;
+/** Sign an L1 action (phantom agent, domain "Exchange"/1337) — python `sign_l1_action`. */
+export declare function signHlL1Action(signer: EvmSigner, action: Record<string, unknown>, nonce: number, isMainnet: boolean, vaultAddress?: string | null, expiresAfter?: number | null): Promise<HlSignature>;
+/**
+ * User-signed action types (python SDK *_SIGN_TYPES). `hyperliquidChain` is always
+ * the first field; the remaining fields are copied from the action into the message.
+ */
+export declare const HL_USER_SIGNED_TYPES: {
+    readonly withdraw3: {
+        readonly primaryType: "HyperliquidTransaction:Withdraw";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "destination";
+            readonly type: "string";
+        }, {
+            readonly name: "amount";
+            readonly type: "string";
+        }, {
+            readonly name: "time";
+            readonly type: "uint64";
+        }];
+    };
+    readonly usdSend: {
+        readonly primaryType: "HyperliquidTransaction:UsdSend";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "destination";
+            readonly type: "string";
+        }, {
+            readonly name: "amount";
+            readonly type: "string";
+        }, {
+            readonly name: "time";
+            readonly type: "uint64";
+        }];
+    };
+    readonly approveBuilderFee: {
+        readonly primaryType: "HyperliquidTransaction:ApproveBuilderFee";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "maxFeeRate";
+            readonly type: "string";
+        }, {
+            readonly name: "builder";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint64";
+        }];
+    };
+    readonly tokenDelegate: {
+        readonly primaryType: "HyperliquidTransaction:TokenDelegate";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "validator";
+            readonly type: "address";
+        }, {
+            readonly name: "wei";
+            readonly type: "uint64";
+        }, {
+            readonly name: "isUndelegate";
+            readonly type: "bool";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint64";
+        }];
+    };
+    readonly sendToEvmWithData: {
+        readonly primaryType: "HyperliquidTransaction:SendToEvmWithData";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "token";
+            readonly type: "string";
+        }, {
+            readonly name: "amount";
+            readonly type: "string";
+        }, {
+            readonly name: "sourceDex";
+            readonly type: "string";
+        }, {
+            readonly name: "destinationRecipient";
+            readonly type: "string";
+        }, {
+            readonly name: "addressEncoding";
+            readonly type: "string";
+        }, {
+            readonly name: "destinationChainId";
+            readonly type: "uint32";
+        }, {
+            readonly name: "gasLimit";
+            readonly type: "uint64";
+        }, {
+            readonly name: "data";
+            readonly type: "bytes";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint64";
+        }];
+    };
+    readonly usdClassTransfer: {
+        readonly primaryType: "HyperliquidTransaction:UsdClassTransfer";
+        readonly fields: readonly [{
+            readonly name: "hyperliquidChain";
+            readonly type: "string";
+        }, {
+            readonly name: "amount";
+            readonly type: "string";
+        }, {
+            readonly name: "toPerp";
+            readonly type: "bool";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint64";
+        }];
+    };
+};
+export type HlUserSignedType = keyof typeof HL_USER_SIGNED_TYPES;
+/** The action field that carries the nonce (withdraw3/usdSend use `time`). */
+export declare function hlUserSignedNonceField(type: HlUserSignedType): "time" | "nonce";
+/** Action object for a user-signed type: type + signatureChainId + hyperliquidChain + fields. */
+export declare function buildHlUserSignedAction(type: HlUserSignedType, network: Network, fields: Record<string, unknown>): Record<string, unknown>;
+/** EIP-712 domain/types/message for a user-signed action (python `user_signed_payload`). */
+export declare function hlUserSignedTypedData(action: Record<string, unknown>): {
+    domain: Record<string, unknown>;
+    types: Record<string, Eip712Field[]>;
+    message: Record<string, unknown>;
+};
+/** Sign a user-signed action with the MASTER signer (python `sign_user_signed_action`). */
+export declare function signHlUserSignedAction(signer: EvmSigner, action: Record<string, unknown>): Promise<HlSignature>;
+export {};

package/dist/exchanges/hl-signing.js

@@ -0,0 +1,158 @@
+/**
+ * Hyperliquid signing — L1 actions (phantom agent, agent- or master-signable) and
+ * user-signed actions (HyperliquidSignTransaction EIP-712, master only). Mirrors
+ * hyperliquid-python-sdk `utils/signing.py` (action_hash, sign_l1_action,
+ * sign_user_signed_action and the *_SIGN_TYPES tables).
+ *
+ * Note: src/commands/agent.ts (approveAgent / userSetAbstraction) and
+ * src/commands/builder.ts (approveBuilderFee) still carry their own copies of the
+ * user-signed domain; they produce the same payload as signHlUserSignedAction.
+ */
+import { HL_USER_SIGNED } from "./venues/hyperliquid.js";
+import { PerpError } from "../errors.js";
+/**
+ * keccak(msgpack(action) ‖ nonce u64be ‖ vault flag [‖ vault 20B] [‖ 0x00 ‖ expiresAfter u64be])
+ * — python SDK `action_hash`.
+ */
+export async function hlL1ActionHash(action, nonce, vaultAddress, expiresAfter) {
+    const { encode } = await import("@msgpack/msgpack");
+    const { keccak256, getBytes } = await import("ethers");
+    const packed = encode(action);
+    const vault = vaultAddress === null ? new Uint8Array(0) : getBytes(vaultAddress);
+    const len = packed.length + 8 + 1 + vault.length + (expiresAfter === null ? 0 : 9);
+    const data = new Uint8Array(len);
+    const view = new DataView(data.buffer);
+    data.set(packed);
+    let off = packed.length;
+    view.setBigUint64(off, BigInt(nonce), false);
+    off += 8;
+    data[off] = vaultAddress === null ? 0 : 1;
+    off += 1;
+    data.set(vault, off);
+    off += vault.length;
+    if (expiresAfter !== null) {
+        data[off] = 0;
+        off += 1;
+        view.setBigUint64(off, BigInt(expiresAfter), false);
+    }
+    return keccak256(data);
+}
+/** Sign an L1 action (phantom agent, domain "Exchange"/1337) — python `sign_l1_action`. */
+export async function signHlL1Action(signer, action, nonce, isMainnet, vaultAddress = null, expiresAfter = null) {
+    const { ethers } = await import("ethers");
+    const connectionId = await hlL1ActionHash(action, nonce, vaultAddress, expiresAfter);
+    const sig = await signer.signTypedData({ name: "Exchange", version: "1", chainId: 1337, verifyingContract: "0x0000000000000000000000000000000000000000" }, { Agent: [{ name: "source", type: "string" }, { name: "connectionId", type: "bytes32" }] }, { source: isMainnet ? "a" : "b", connectionId });
+    const p = ethers.Signature.from(sig);
+    return { r: p.r, s: p.s, v: p.v };
+}
+/**
+ * User-signed action types (python SDK *_SIGN_TYPES). `hyperliquidChain` is always
+ * the first field; the remaining fields are copied from the action into the message.
+ */
+export const HL_USER_SIGNED_TYPES = {
+    withdraw3: {
+        primaryType: "HyperliquidTransaction:Withdraw",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "time", type: "uint64" },
+        ],
+    },
+    usdSend: {
+        primaryType: "HyperliquidTransaction:UsdSend",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "time", type: "uint64" },
+        ],
+    },
+    approveBuilderFee: {
+        primaryType: "HyperliquidTransaction:ApproveBuilderFee",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "maxFeeRate", type: "string" },
+            { name: "builder", type: "address" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    tokenDelegate: {
+        primaryType: "HyperliquidTransaction:TokenDelegate",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "validator", type: "address" },
+            { name: "wei", type: "uint64" },
+            { name: "isUndelegate", type: "bool" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    // CCTP withdrawal (native USDC): HyperCore → HyperEVM burn → CCTP mint on the destination chain.
+    // Field order per the Circle guide "Withdraw USDC from HyperCore to EVM chains"
+    // (developers.circle.com/cctp/howtos/withdraw-usdc-from-hypercore-to-evm) and the HL exchange endpoint docs.
+    sendToEvmWithData: {
+        primaryType: "HyperliquidTransaction:SendToEvmWithData",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "token", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "sourceDex", type: "string" },
+            { name: "destinationRecipient", type: "string" },
+            { name: "addressEncoding", type: "string" },
+            { name: "destinationChainId", type: "uint32" },
+            { name: "gasLimit", type: "uint64" },
+            { name: "data", type: "bytes" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    usdClassTransfer: {
+        primaryType: "HyperliquidTransaction:UsdClassTransfer",
+        fields: [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "toPerp", type: "bool" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+};
+/** The action field that carries the nonce (withdraw3/usdSend use `time`). */
+export function hlUserSignedNonceField(type) {
+    return type === "withdraw3" || type === "usdSend" ? "time" : "nonce";
+}
+/** Action object for a user-signed type: type + signatureChainId + hyperliquidChain + fields. */
+export function buildHlUserSignedAction(type, network, fields) {
+    const { hyperliquidChain, signatureChainIdHex } = HL_USER_SIGNED[network];
+    return { type, signatureChainId: signatureChainIdHex, hyperliquidChain, ...fields };
+}
+/** EIP-712 domain/types/message for a user-signed action (python `user_signed_payload`). */
+export function hlUserSignedTypedData(action) {
+    const type = action.type;
+    const spec = HL_USER_SIGNED_TYPES[type];
+    if (spec === undefined) {
+        throw new PerpError("INVALID_PARAMS", `Not a Hyperliquid user-signed action type: ${String(action.type)}`, { exchange: "hyperliquid" });
+    }
+    const message = {};
+    for (const f of spec.fields) {
+        if (action[f.name] === undefined) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid ${type}: missing field ${f.name}`, { exchange: "hyperliquid" });
+        }
+        message[f.name] = action[f.name];
+    }
+    return {
+        domain: {
+            name: "HyperliquidSignTransaction",
+            version: "1",
+            chainId: parseInt(String(action.signatureChainId), 16),
+            verifyingContract: "0x0000000000000000000000000000000000000000",
+        },
+        types: { [spec.primaryType]: spec.fields.map(f => ({ ...f })) },
+        message,
+    };
+}
+/** Sign a user-signed action with the MASTER signer (python `sign_user_signed_action`). */
+export async function signHlUserSignedAction(signer, action) {
+    const { ethers } = await import("ethers");
+    const { domain, types, message } = hlUserSignedTypedData(action);
+    const p = ethers.Signature.from(await signer.signTypedData(domain, types, message));
+    return { r: p.r, s: p.s, v: p.v };
+}

package/dist/exchanges/hyperliquid-outcome.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Hyperliquid Outcome Adapter (HIP-4).
+ *
+ * Composes with HyperliquidAdapter for signing. Asset id encoding:
+ *   100,000,000 + (10 * outcome + side)
+ *
+ * Coin name conventions:
+ *   - l2Book/candle/allMids: `#<encoding>` (e.g., `#10`)
+ *   - spotClearinghouseState balance: `+<encoding>` (e.g., `+10`)
+ *
+ * Outcome trades draw collateral from the spot balance of the outcome's own quote token —
+ * `outcomeMeta.outcomes[].quoteToken` (live 2026-10-12: "USDC" on every listed outcome; a USDH-only
+ * balance was refused by the venue "Insufficient spot balance asset=100014881"). Min order value:
+ * 10 quote tokens (docs error-responses MinTradeSpotNtl "Order must have minimum value of 10 {quote_token}.").
+ */
+import type { OutcomeAdapter, OutcomeMarketInfo, OutcomeOrderbook, OutcomePosition, OutcomeView, OutcomeViewUnderlying } from "./outcome-interface.js";
+import type { HyperliquidAdapter } from "./hyperliquid.js";
+export declare class HyperliquidOutcomeAdapter implements OutcomeAdapter {
+    readonly name = "hyperliquid";
+    private _hl;
+    private _outcomeMeta;
+    private _initialized;
+    constructor(hlAdapter: HyperliquidAdapter);
+    init(): Promise<void>;
+    static encoding(outcome: number, side: number): number;
+    static assetId(outcome: number, side: number): number;
+    static mintCoin(outcome: number, side: number): string;
+    static balanceCoin(outcome: number, side: number): string;
+    /**
+     * Decode a balance coin name like `+10` back to (outcome, side).
+     * Returns null if the name does not match the outcome scheme.
+     */
+    static decodeBalanceCoin(coin: string): {
+        outcome: number;
+        side: number;
+    } | null;
+    static parseDescription(description: string): {
+        class?: string;
+        underlying?: string;
+        expiryMs?: number;
+        targetPrice?: number;
+        period?: string;
+    };
+    /**
+     * Compute the underlying mark-price view (gap / inTheMoney) for an outcome
+     * from a parsed description and the live allMids map.
+     *
+     * Pure helper — extracted from getView so the settlement-status logic is
+     * directly unit-testable.
+     *
+     * - HL `allMids` keys perps by bare symbol (e.g. "BTC"). HIP-3 perps use
+     *   "@dexIdx:SYMBOL" but those aren't referenced in HIP-4 outcomes yet.
+     * - For `class:priceBinary` the convention is Yes = "underlying >= target".
+     *   When `class` is missing or non-binary, `inTheMoney` stays null rather
+     *   than guessing (Rule #2 — no silent classification fallback).
+     * - Returns null when there is no underlying field to look up.
+     */
+    static _computeUnderlying(parsed: {
+        class?: string;
+        underlying?: string;
+        targetPrice?: number;
+    }, allMids: Record<string, string>): OutcomeViewUnderlying | null;
+    /**
+     * Sum of `impliedProb` across sides — for fair binary markets the sum
+     * should converge to ~1.0. Deviation hints at arbitrage or stale mids.
+     *
+     * Returns undefined when any side is missing impliedProb OR when any
+     * impliedProb is non-finite (NaN, Infinity). This means "we don't have a
+     * trustworthy view of the symmetry right now" rather than emitting NaN
+     * downstream (Rule #2 — no silent garbage propagation).
+     */
+    static _computeMidSum(sides: Array<{
+        impliedProb?: number;
+    }>): number | undefined;
+    /**
+     * Compute the time-status pair (`serverTime`, `msToExpiry`) for a view.
+     * Pure helper — takes `nowMs` as an argument so callers can inject a
+     * deterministic clock under test.
+     *
+     * `msToExpiry` is the raw signed delta `expiryMs - nowMs`:
+     *   positive  = unexpired
+     *   zero      = at expiry
+     *   negative  = already settled (caller decides UX)
+     *   undefined = unknown expiry
+     *
+     * Does NOT clamp negatives or treat them as "expired" — that
+     * classification is the caller's job (Rule #2 — no silent classification
+     * fallback in a low-level helper).
+     */
+    static _computeTimeStatus(expiryMs: number | undefined, nowMs: number): {
+        serverTime: number;
+        msToExpiry?: number;
+    };
+    /**
+     * Pure arithmetic gate for the (outcome, side) pair.
+     *
+     * Rejects NaN / non-integer / negative values immediately so the
+     * encoding formula `10 * outcome + side` never produces a garbage
+     * asset id silently. Does NOT consult outcomeMeta — that lookup is in
+     * the instance-level `_validateOutcomeSide` which composes this
+     * helper with the live registry check.
+     *
+     * Boundary: outcome=9_999_999, side=9 → encoding=99_999_999 = MAX_ENCODING (valid).
+     *           outcome=10_000_000, side=0 → encoding=100_000_000 > MAX_ENCODING (rejected).
+     */
+    static _assertOutcomeRange(outcome: number, side: number): void;
+    /**
+     * Trim a raw orderbook to `depth` levels and surface best bid/ask.
+     *
+     * Throws (rather than silently coercing) when:
+     *  - `book.bids` or `book.asks` is missing/non-array (venue payload
+     *    malformed — Rule #2: don't fabricate an empty book)
+     *  - `depth` is not a non-negative integer (NaN, negative, Infinity,
+     *    fractional are all caller bugs that previously silently produced
+     *    `slice(0, NaN) === []` or `slice(0, -1)` = "all but last")
+     */
+    static _trimBook(book: {
+        bids: [string, string][];
+        asks: [string, string][];
+    } | {
+        bids: unknown;
+        asks: unknown;
+    } | null | undefined, depth: number): {
+        bids: [string, string][];
+        asks: [string, string][];
+        bestBid?: string;
+        bestAsk?: string;
+    };
+    /** Parse "20260504-0600" → ms-epoch (UTC). Returns undefined for malformed. */
+    private static _parseExpiry;
+    private _loadOutcomeMeta;
+    getMarkets(): Promise<OutcomeMarketInfo[]>;
+    getPositions(): Promise<OutcomePosition[]>;
+    /**
+     * Assemble a combined view of one outcome: all sides' books in parallel,
+     * the underlying mark price (HL perp mid for `description.underlying`),
+     * gap vs targetPrice, time-to-expiry, and per-side implied probability.
+     *
+     * Outcome markets have a symmetric (Yes / No) structure where the prices
+     * sum to ~$1; this view exposes both sides in a single round-trip and
+     * also surfaces the directional context for binary markets — what BTC
+     * mark price would settle the contract right now.
+     */
+    getView(outcome: number, depth?: number): Promise<OutcomeView>;
+    getOrderbook(outcome: number, side: number): Promise<OutcomeOrderbook>;
+    placeOrder(opts: {
+        outcome: number;
+        side: number;
+        isBuy: boolean;
+        price: string;
+        size: string;
+        tif?: "Gtc" | "Ioc" | "Alo";
+    }): Promise<unknown>;
+    cancelOrder(outcome: number, side: number, oid: number): Promise<unknown>;
+    /**
+     * Throw if the venue rejected the order embedded inside a top-level
+     * `status:"ok"` response (HL pattern). Returns silently for resting/filled.
+     */
+    static _assertOrderStatusOk(result: unknown): void;
+    static _assertCancelStatusOk(result: unknown): void;
+    getOpenOrders(): Promise<unknown[]>;
+    /**
+     * The outcome's quote token from outcomeMeta (`quoteToken`, e.g. "USDC"). Unknown outcome →
+     * SYMBOL_NOT_FOUND; missing / non-string quoteToken → EXCHANGE_ERROR (never an assumed token).
+     */
+    quoteTokenOf(outcome: number): string;
+    /**
+     * The outcome / side behind an outcome coin ("#14881" = outcome 1488, side 1) with its names from
+     * outcomeMeta; null when the coin is not an outcome coin or the outcome is not listed.
+     */
+    describeCoin(coin: string): {
+        outcome: number;
+        side: number;
+        name: string;
+        sideName: string;
+    } | null;
+    /**
+     * Price of held outcome balance coins (`+<encoding>`, spotClearinghouseState) in the outcome's quote
+     * token: the side's mid `allMids["#<encoding>"]` (docs info-endpoint "Retrieve mids for all coins";
+     * live 2026-10-13 mainnet allMids "#14880": "0.100405", "#14881": "0.899595"). HIP-4 docs: a side
+     * token settles to `settleFraction` (Yes) / `1 - settleFraction` (No) quote tokens and the Yes/No
+     * books are merged (buy Yes at p = sell No at 1 - p), so the mid is the token's value in its quote.
+     * `quoteToken` null = the outcome / side is not in outcomeMeta (outcomeMeta is re-read once when a
+     * coin's outcome is missing — outcomes are deployed after init) or has no quoteToken; `mid` null = no
+     * positive mid. Coins that are not `+<digits>` are not returned. A malformed allMids → EXCHANGE_ERROR.
+     */
+    getBalanceCoinPrices(coins: readonly string[]): Promise<Array<{
+        coin: string;
+        quoteToken: string | null;
+        mid: string | null;
+    }>>;
+    private _lookupSideName;
+    private _validateOutcomeSide;
+    /**
+     * Resolve the master EVM address for spot-clearinghouse queries.
+     * `HyperliquidAdapter._address` is populated only when a master/PK signer
+     * is configured. Agent-only setups (no master pk in OWS) leave it empty
+     * even though the agent meta knows the user's EVM address. Fall through
+     * to the agent registry rather than treating empty as zero balance —
+     * Rule #2: no silent fallback.
+     */
+    private _resolveUserAddress;
+    /**
+     * Available spot balance of `coin` (total − hold, spotClearinghouseState). A coin the account does
+     * not hold is not listed → 0 held. No balances list, or an unreadable total / hold → EXCHANGE_ERROR.
+     */
+    private _getSpotAvailable;
+    private _invalidateAccountCache;
+    private _trimZeros;
+    private _infoPost;
+}