perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/pacifica-presigned.js

@@ -0,0 +1,141 @@
+/**
+ * Pacifica signed writes whose body the caller builds before signing (Print `/game/*`, vault
+ * `/lake/*`). Building the canonical message and the request body is pure, so `--dry-run`
+ * prints exactly what a live run would sign and send — only the signature is missing.
+ *
+ * Signing scheme (docs.pacifica.fi api-documentation/api/signing, reused from
+ * src/pacifica/signing.ts): message = compact JSON, keys sorted recursively, of
+ * `{ type, timestamp, expiry_window, data: <payload> }`; Ed25519 signature, base58. The body is
+ * `{ account, agent_wallet?, signature, timestamp, expiry_window, ...payload }` — the same shape
+ * as `buildSignedRequest` / `buildAgentSignedRequest`.
+ *
+ * Send outcome (money-safety rules):
+ *  - HTTP 4xx (except 409 / 429): the venue refused — ACTION_REJECTED, nothing happened;
+ *  - HTTP 409 "duplicate idempotency key": a request with this key already exists — ORDER_PENDING;
+ *  - HTTP 429: RATE_LIMITED, nothing happened;
+ *  - timeout / reset / 5xx / unreadable or ambiguous 2xx body: ORDER_PENDING — never resubmit.
+ */
+import bs58 from "bs58";
+import { prepareMessage } from "../pacifica/signing.js";
+import { DEFAULT_EXPIRY_WINDOW } from "../pacifica/constants.js";
+import { PerpError, extractErrorMessage, orderNotSent } from "../errors.js";
+/** Build the canonical message and unsigned body. Undefined payload values are refused (they would be dropped by JSON but not by the signer). */
+export function buildPresigned(p) {
+    for (const [k, v] of Object.entries(p.payload)) {
+        if (v === undefined)
+            throw new Error(`buildPresigned: payload field ${k} is undefined`);
+    }
+    const expiryWindow = p.expiryWindow ?? DEFAULT_EXPIRY_WINDOW;
+    const message = prepareMessage({ type: p.type, timestamp: p.timestamp, expiry_window: expiryWindow }, p.payload);
+    const body = {
+        account: p.identity.account,
+        ...(p.identity.agentWallet !== null ? { agent_wallet: p.identity.agentWallet } : {}),
+        timestamp: p.timestamp,
+        expiry_window: expiryWindow,
+        ...p.payload,
+    };
+    const key = p.payload.idempotency_key;
+    return { type: p.type, path: p.path, message, body, idempotencyKey: typeof key === "string" ? key : null };
+}
+/**
+ * The same request with a new timestamp (message + body re-derived; payload, identity, expiry
+ * window and idempotency key unchanged) — used after the pre-sign credit wait so the signature's
+ * expiry window starts when it is signed.
+ */
+export function restampPresigned(req, timestamp) {
+    const { account, agent_wallet, timestamp: _t, expiry_window, ...payload } = req.body;
+    return buildPresigned({
+        type: req.type, path: req.path, payload, timestamp, expiryWindow: expiry_window,
+        identity: { account: account, agentWallet: typeof agent_wallet === "string" ? agent_wallet : null },
+    });
+}
+/** Sign the canonical message; returns the full body (`signature` added). A signing failure is "not sent". */
+export async function signPresigned(req, signMessage) {
+    try {
+        const sig = await signMessage(new TextEncoder().encode(req.message));
+        const { account, agent_wallet, ...rest } = req.body;
+        return { account, ...(agent_wallet !== undefined ? { agent_wallet } : {}), signature: bs58.encode(sig), ...rest };
+    }
+    catch (e) {
+        throw orderNotSent("pacifica", req.type, e);
+    }
+}
+/**
+ * Send a signed body and return the response `data` object. `what` names the action in errors
+ * ("Print deposit"); `check` is the read command that settles an unknown outcome.
+ */
+export async function sendPresigned(client, req, signedBody, ctx) {
+    const details = { exchange: "pacifica", path: req.path, idempotencyKey: req.idempotencyKey, ...(ctx.before !== undefined ? { before: ctx.before } : {}) };
+    const pending = (why) => new PerpError("ORDER_PENDING", `Pacifica ${ctx.what}: outcome unknown — ${why}`, {
+        ...details,
+        remediation: pendingRemediation(ctx.what, ctx.check, req.idempotencyKey),
+    });
+    let raw;
+    try {
+        raw = await client.postPresigned(req.path, signedBody);
+    }
+    catch (e) {
+        if (e instanceof PerpError) {
+            if (e.structured.code === "ORDER_PENDING")
+                throw pending(e.message);
+            throw e; // definite (not sent / refused) — client already classified it
+        }
+        const m = /^POST \S+ failed \((\d{3})\): ([\s\S]*)$/.exec(extractErrorMessage(e));
+        if (m === null)
+            throw pending(extractErrorMessage(e));
+        const status = Number(m[1]);
+        const venueError = venueErrorOf(m[2]);
+        if (status === 409)
+            throw pending(`HTTP 409 duplicate idempotency key ${req.idempotencyKey ?? "(none)"} — a request with this key already reached the venue: ${venueError}`);
+        if (status === 429) {
+            throw new PerpError("RATE_LIMITED", `Pacifica ${ctx.what} rate-limited (HTTP 429, nothing was executed): ${venueError}`, { ...details, remediation: "Wait and retry" });
+        }
+        if (status >= 400 && status < 500) {
+            throw new PerpError("ACTION_REJECTED", `Pacifica ${ctx.what} refused (HTTP ${status}, nothing was executed): ${venueError}`, {
+                ...details, httpStatus: status, remediation: "Fix the parameter named in the venue message and retry",
+            });
+        }
+        throw pending(`HTTP ${status}: ${venueError}`);
+    }
+    if (raw === null || typeof raw !== "object")
+        throw pending(`unreadable response ${JSON.stringify(raw)?.slice(0, 160)}`);
+    const env = raw;
+    if (env.success === false) {
+        throw new PerpError("ACTION_REJECTED", `Pacifica ${ctx.what} refused (nothing was executed): ${String(env.error ?? "success: false")}`, {
+            ...details, venueCode: env.code ?? null, remediation: "Fix the parameter named in the venue message and retry",
+        });
+    }
+    const data = env.data;
+    if (env.success !== true || data === null || typeof data !== "object" || Array.isArray(data)) {
+        throw pending(`response without a data object: ${JSON.stringify(raw).slice(0, 200)}`);
+    }
+    return data;
+}
+/**
+ * ORDER_PENDING remediation. With an idempotency key, the ONLY safe retry is the same request with
+ * the same key (`--idempotency-key`): the venue answers a duplicate with HTTP 409 instead of
+ * executing it twice. How long Pacifica remembers a key is not documented (unverified).
+ */
+export function pendingRemediation(what, check, idempotencyKey) {
+    const base = `Do NOT resubmit with a new request — the ${what} may have been executed. Check first: ${check}.`;
+    return idempotencyKey === null
+        ? `${base} This action carries no idempotency key: run it again only once that check shows it did not take effect.`
+        : `${base} If you must retry, the only safe way is the same command with --idempotency-key ${idempotencyKey} (the venue refuses a duplicate key with HTTP 409; its dedupe window is unverified).`;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `--idempotency-key`: a full UUID string (API docs), lowercased; refused otherwise. */
+export function requireIdempotencyKey(raw) {
+    const k = raw.trim();
+    if (!UUID.test(k))
+        throw new PerpError("INVALID_PARAMS", `--idempotency-key must be a full UUID (got "${raw}")`, { remediation: "Pass the idempotencyKey reported by the earlier attempt" });
+    return k.toLowerCase();
+}
+function venueErrorOf(text) {
+    try {
+        const j = JSON.parse(text);
+        if (typeof j.error === "string" && j.error !== "")
+            return j.error;
+    }
+    catch { /* not JSON */ }
+    return text.slice(0, 300);
+}

package/dist/exchanges/pacifica-print.d.ts

@@ -0,0 +1,200 @@
+import type { PacificaClient } from "../pacifica/client.js";
+import { type PresignedIdentity, type PresignedRequest } from "./pacifica-presigned.js";
+/** docs print/placing-and-managing-orders: "Deposit — your locked margin, minimum $10". */
+export declare const PRINT_MIN_DEPOSIT_USDC = "10";
+/** docs: target "at least 0.5% away from the current mark price". */
+export declare const PRINT_MIN_TARGET_DISTANCE_PCT = "0.5";
+/** docs: "at most 10% on a 24-hour cycle, 20% on 7 days, or 40% on 30 days" (keyed by cycle days). */
+export declare const PRINT_MAX_TARGET_DISTANCE_PCT: Readonly<Record<number, string>>;
+/** API create-print-order: "total_segments … 1 to 1000". */
+export declare const PRINT_MAX_CYCLES = 1000;
+/**
+ * The docs formula (target ∓ (deposit + yield) × target / (leverage × deposit)) is where the margin
+ * is fully lost. A liquidation was observed earlier than that in one live case (mainnet 2026-10-16:
+ * a ZEC_24H short, strike 1150.95, 10×, deposit 922.93, premium 23.80, liquidated at the checkpoint
+ * with mark 1216.836 while the formula gives ≈ 1269.0). The venue's trigger is unpublished; its own
+ * figure comes only from the signed preview (preview_game_account), not called here.
+ */
+export declare const PRINT_LIQUIDATION_NOTE = "docsLiquidationPrice is the docs formula (margin fully lost) \u2014 an outer bound, not the trigger: a liquidation was observed earlier in one live case (2026-10-16); the venue's trigger is unpublished. After a fill the position follows ordinary perp liquidation (continuous mark price, main account).";
+export type PrintDirection = "long" | "short";
+export interface PrintGame {
+    schema: 1;
+    /** Product id sent as `game` (e.g. BTC_24H, BTC_7D, BTC_1M). */
+    game: string;
+    asset: string;
+    /** Cycle length in days (segment_kind fixed_days), null when the venue reports another kind. */
+    cycleDays: number | null;
+    maxLeverage: string | null;
+    /** Cap on the TOTAL open deposits of this product across all users (USDC) — not a per-order limit. */
+    productDepositCap: string | null;
+    /** Cap on open deposits of the whole Print pool (USDC). */
+    poolDepositCap: string | null;
+    capScope: string | null;
+    /** Vault ("lake") that pays the premiums. */
+    poolAddress: string | null;
+    minDeposit: string;
+    targetDistancePct: {
+        min: string;
+        max: string | null;
+    };
+}
+export type PrintStatus = "printing" | "cancelling" | "filled" | "liquidated" | "cancelled" | "completed" | "ended";
+export interface PrintPosition {
+    schema: 1;
+    /** Print order account address (`game_account`). */
+    address: string;
+    game: string;
+    asset: string | null;
+    direction: PrintDirection;
+    deposit: string;
+    strikePrice: string;
+    leverage: string;
+    entryMarkPrice: string | null;
+    /** Premiums credited so far (USDC). */
+    premiumPaid: string | null;
+    /** deposit × leverage. */
+    notional: string;
+    /** Size opened on a fill: notional ÷ strike. */
+    size: string | null;
+    /**
+     * docs formula (margin fully lost) with the premiums paid; null when ≤ 0 or unknown. NOT the
+     * venue's trigger: it liquidates earlier, at maintenance margin (PRINT_LIQUIDATION_NOTE).
+     */
+    docsLiquidationPrice: string | null;
+    /** deposit + premiums — the most that can be lost. */
+    maxLoss: string | null;
+    cycles: {
+        total: number | null;
+        started: number | null;
+    };
+    createdAt: number | null;
+    startedAt: number | null;
+    currentCycleEndAt: number | null;
+    scheduledEndAt: number | null;
+    endedAt: number | null;
+    endReason: string | null;
+    cancelRequested: boolean;
+    status: PrintStatus;
+}
+export interface PrintEvent {
+    schema: 1;
+    id: number;
+    printAddress: string;
+    depositor: string | null;
+    event: string;
+    amount: string | null;
+    strikePrice: string | null;
+    markPrice: string | null;
+    /** Position size of a position_opened event. */
+    size: string | null;
+    cycleStartedAt: number | null;
+    cycleEndedAt: number | null;
+    cycleNumber: number | null;
+    time: number;
+}
+export interface Page<T> {
+    items: T[];
+    hasMore: boolean | null;
+    nextCursor: string | null;
+}
+/** `data` of a `{success: true, data}` envelope; a refusal / other shape is EXCHANGE_ERROR. */
+export declare function envelopeData(env: Record<string, unknown>, path: string): unknown;
+/** GET /game/config `data` → products (`{configs: [...]}`; the app also accepts a bare array). */
+export declare function parsePrintGames(data: unknown): PrintGame[];
+/** docs margin-and-liquidation: target ∓ (deposit + yield) × target / (leverage × deposit). */
+export declare function printLiquidationPrice(direction: PrintDirection, strike: string, deposit: string, leverage: string, premium: string, tickSize?: string | null): string | null;
+/** One /game/accounts or /game/history_summary row. */
+export declare function parsePrintPosition(x: unknown): PrintPosition;
+/** GET /game/accounts `data` (`{game_accounts: [...]}`). */
+export declare function parsePrintAccounts(data: unknown): PrintPosition[];
+/** One /game/history event (created / premium / end_requested / filled / liquidated / …). */
+export declare function parsePrintEvent(x: unknown): PrintEvent;
+type Reader = Pick<PacificaClient, "getEnvelope">;
+export declare function fetchPrintGames(client: Reader): Promise<PrintGame[]>;
+export declare function fetchPrintPositions(client: Reader, account: string): Promise<PrintPosition[]>;
+export declare function fetchPrintHistory(client: Reader, account: string, page: {
+    limit: number | null;
+    cursor: string | null;
+}): Promise<Page<PrintPosition>>;
+export declare function fetchPrintEvents(client: Reader, printAddress: string, page: {
+    limit: number | null;
+    cursor: string | null;
+}): Promise<Page<PrintEvent>>;
+/** Mark price + tick size of the product's perp market (GET /prices, GET /info). */
+export declare function fetchPrintMarket(client: Pick<PacificaClient, "getPrices" | "getInfo">, asset: string): Promise<{
+    mark: string;
+    tickSize: string;
+}>;
+/** The product `game` (case-insensitive) from the live list; unknown → SYMBOL_NOT_FOUND naming what exists. */
+export declare function findPrintGame(games: PrintGame[], game: string): PrintGame;
+export interface PrintOrderInput {
+    game: string;
+    direction: PrintDirection;
+    /** USDC deposit (decimal string). */
+    deposit: string;
+    strikePrice: string;
+    leverage: string;
+    /** Number of cycles (total_segments) or null = roll until ended. */
+    cycles: number | null;
+}
+export interface PrintQuote {
+    schema: 1;
+    game: string;
+    asset: string;
+    cycleDays: number;
+    direction: PrintDirection;
+    deposit: string;
+    leverage: string;
+    strikePrice: string;
+    markPrice: string;
+    /** |mark − strike| ÷ mark × 100, 4 decimals. */
+    targetDistancePct: string;
+    allowedTargetDistancePct: {
+        min: string;
+        max: string;
+    };
+    notional: string;
+    /** Position size opened on a fill (asset units, 8 decimals). */
+    size: string;
+    /** docs formula before any premium (margin fully lost) — the venue liquidates EARLIER (PRINT_LIQUIDATION_NOTE). */
+    docsLiquidationPrice: string | null;
+    liquidationNote: string;
+    /** The deposit now; the deposit plus every premium credited later. Never more. */
+    maxLoss: string;
+    cycles: number | null;
+    /** cycles × cycleDays, null = until ended. */
+    maxDurationDays: number | null;
+    /** An end request takes effect at the end of the running cycle: up to this many days. */
+    cancelSettlesWithinDays: number;
+    /** The venue's premium quote is a signed request (preview_game_account) — not called on a read path. */
+    estimatedPremium: null;
+    notes: string[];
+}
+/** Plain non-negative decimal without leading zeros ("0.5", "10", "10.25"; not "010", "1e3", ".5"). */
+export declare const PLAIN_POSITIVE: RegExp;
+/** Strict USDC amount: plain positive decimal, no leading zeros, at most 6 fractional digits (USDC precision). */
+export declare function requireUsdcAmount(raw: string, what: string): string;
+/**
+ * Validate a Print order against the product and the live mark (docs limits) and compute the
+ * preview. Throws INVALID_PARAMS / INVALID_TICK / CAPABILITY_UNSUPPORTED; signs and sends nothing.
+ */
+export declare function quotePrintOrder(game: PrintGame, input: PrintOrderInput, market: {
+    mark: string;
+    tickSize: string;
+}): PrintQuote;
+/** POST /game/deposit body + canonical message (deposit_to_game). Field set per the API docs. */
+export declare function buildPrintDepositRequest(q: PrintQuote, identity: PresignedIdentity, opts: {
+    timestamp: number;
+    idempotencyKey: string;
+    expiryWindow?: number;
+}): PresignedRequest;
+/** POST /game/end body + canonical message (end_game, payload `{game_account}` as app.pacifica.fi sends it). */
+export declare function buildPrintEndRequest(printAddress: string, identity: PresignedIdentity, opts: {
+    timestamp: number;
+    expiryWindow?: number;
+}): PresignedRequest;
+/** An end request is accepted only for a running order of the account (not ended, not already ending). */
+export declare function requireEndable(positions: PrintPosition[], printAddress: string): PrintPosition;
+/** When a cycle that ends at `cycleEndAt` frees the funds, in days from `now` (null = unknown). */
+export declare function daysUntil(cycleEndAt: number | null, now: number): string | null;
+export {};