perp-cli 0.12.17 → 0.14.1

package/dist/pacifica/client.js

@@ -1,14 +1,49 @@
-import { BUILDER_CODE, getNetworkConfig } from "./constants.js";
-import { buildSignedRequest } from "./signing.js";
+import { getNetworkConfig } from "./constants.js";
+import { buildSignedRequest, buildAgentSignedRequest } from "./signing.js";
+import { PerpError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
+import { invalidateCache } from "../cache.js";
+/** Per-request timeout of a POST (fetch + body read). */
+export const PACIFICA_POST_TIMEOUT_MS = 15_000;
+/**
+ * Account-setting writes whose HTTP 4xx is the venue's explicit refusal (nothing changed).
+ * docs.pacifica.fi (api-documentation/api/rest-api):
+ *   account/update-leverage:      "Status 400: Invalid request parameters" — {"error": "Invalid leverage", "code": 400}
+ *   orders/create-position-tp-sl: "Status 400: Bad request" — {"error": "Position not found", "code": 400}
+ * Both pages list only "Status 500: Internal server error" besides.
+ */
+const DEFINITE_4XX_PATHS = new Set(["/positions/tpsl", "/account/leverage"]);
+/** POST endpoints that only read (signed listings): a failure there is an ordinary read error. */
+const READ_POST_PATHS = new Set(["/account/subaccount/list", "/agent/list", "/account/api_keys"]);
 export class PacificaClient {
     baseUrl;
     apiKey;
-    builderCode;
+    /**
+     * Agent-wallet pubkey for the current request signer, set by the adapter when an
+     * agent wallet (not the master) is signing. When present, signed bodies carry the
+     * `agent_wallet` field (with account = master) so Pacifica verifies the signature
+     * against the agent key. Undefined for master/PK signers.
+     */
+    requestAgentWallet;
+    /** Attach (or clear) the agent wallet used for subsequent signed requests. */
+    setRequestAgentWallet(agentWallet) {
+        this.requestAgentWallet = agentWallet;
+    }
+    /** Build a signed POST body, attaching agent_wallet when an agent is the active signer. */
+    async signedBody(operationType, payload, account, signMessage) {
+        try {
+            return await (this.requestAgentWallet
+                ? buildAgentSignedRequest(operationType, payload, account, this.requestAgentWallet, signMessage)
+                : buildSignedRequest(operationType, payload, account, signMessage));
+        }
+        catch (e) {
+            // Signing failed before any request was sent: definitely not placed (never ORDER_PENDING).
+            throw orderNotSent("pacifica", operationType, e);
+        }
+    }
     constructor(config = {}) {
         this.baseUrl =
             config.baseUrl || getNetworkConfig(config.network).restUrl;
         this.apiKey = config.apiKey;
-        this.builderCode = config.builderCode || BUILDER_CODE;
     }
     headers() {
         const h = { "Content-Type": "application/json" };
@@ -36,23 +71,77 @@ export class PacificaClient {
         }
         return json;
     }
+    /**
+     * Signed POST. Every path except the listing reads (READ_POST_PATHS) is an account write: once
+     * the request is on the wire a connection reset / timeout / 5xx / unreadable body leaves the
+     * outcome unknown → ORDER_PENDING (sendFailure), never a retryable network error. No connection
+     * at all → not sent. A 4xx is the venue's refusal and keeps the plain `POST <path> failed
+     * (<status>): <body>` error the adapters map (422 business codes) — except on
+     * DEFINITE_4XX_PATHS, where it is a definite ACTION_REJECTED (429 stays the plain error →
+     * RATE_LIMITED). A fetch timeout (PACIFICA_POST_TIMEOUT_MS) on a write is ORDER_PENDING too;
+   * on a listing read a timeout is TIMEOUT and any other transport failure EXCHANGE_UNREACHABLE.
+     */
     async post(path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: "POST",
-            headers: this.headers(),
-            body: JSON.stringify(body),
-        });
-        if (!res.ok) {
-            const text = await res.text();
-            throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+        const write = !READ_POST_PATHS.has(path);
+        const what = `POST ${path}`;
+        const remediation = `Do NOT resubmit — the request may have been executed. Check open orders, positions and balances first: perp -e pacifica account orders / portfolio`;
+        try {
+            let res;
+            let text;
+            try {
+                res = await fetch(`${this.baseUrl}${path}`, {
+                    method: "POST",
+                    headers: this.headers(),
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(PACIFICA_POST_TIMEOUT_MS),
+                });
+                text = await res.text();
+            }
+            catch (e) {
+                if (write)
+                    throw sendFailure("pacifica", what, e, remediation);
+                // Signed listing read: nothing can have been executed — an ordinary retryable read failure.
+                const timedOut = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+                throw new PerpError(timedOut ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `Pacifica ${what} ${timedOut ? `timed out after ${PACIFICA_POST_TIMEOUT_MS} ms` : `failed: ${extractErrorMessage(e)}`} (read-only listing; nothing was changed)`, {
+                    exchange: "pacifica",
+                    remediation: "Retry; if it keeps failing check the network and Pacifica's status",
+                });
+            }
+            if (write && res.status >= 500) {
+                throw orderOutcomeUnknown("pacifica", what, new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`), remediation);
+            }
+            if (!res.ok) {
+                if (DEFINITE_4XX_PATHS.has(path) && res.status >= 400 && res.status < 500 && res.status !== 429) {
+                    throw new PerpError("ACTION_REJECTED", `Pacifica ${what} refused (HTTP ${res.status}, nothing was changed): ${text.slice(0, 300)}`, {
+                        exchange: "pacifica",
+                        httpStatus: res.status,
+                        remediation: "The venue rejected the request — fix the parameters named in the message and retry",
+                    });
+                }
+                throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (e) {
+                if (!write)
+                    throw e;
+                throw orderOutcomeUnknown("pacifica", what, new Error(`unreadable response (HTTP ${res.status}): ${text.slice(0, 200)}`), remediation);
+            }
         }
-        return res.json();
-    }
-    addBuilderCode(payload) {
-        if (this.builderCode) {
-            return { ...payload, builder_code: this.builderCode };
+        finally {
+            // Every POST is an account write (order / cancel / TP/SL / leverage / transfer): drop the
+            // shared acct: disk cache so no later read serves the pre-write positions / orders.
+            invalidateCache("acct");
         }
-        return payload;
+    }
+    /**
+     * `builder_code` is attached only when the caller passes one — the adapter decides
+     * (settings builder.pacifica + confirmed approval, src/exchanges/builder-fee.ts).
+     * null = no builder code (the default, and always for spot: err 108).
+     */
+    withBuilderCode(payload, builderCode) {
+        return builderCode === null ? payload : { ...payload, builder_code: builderCode };
     }
     // ==================== PUBLIC ENDPOINTS ====================
     async getInfo() {
@@ -158,135 +247,150 @@ export class PacificaClient {
         return this.get("/orders/twap", { account });
     }
     // ==================== AUTHENTICATED POST ENDPOINTS ====================
-    async createMarketOrder(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_market_order", payload, account, signMessage);
+    async createMarketOrder(params, account, signMessage, builderCode) {
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_market_order", payload, account, signMessage);
         return this.post("/orders/create_market", body);
     }
-    async createLimitOrder(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_order", payload, account, signMessage);
+    async createLimitOrder(params, account, signMessage, builderCode) {
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_order", payload, account, signMessage);
         return this.post("/orders/create", body);
     }
-    async createStopOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("create_stop_order", params, account, signMessage);
+    async createStopOrder(params, account, signMessage, builderCode) {
+        // builder_code applies to every order-creation endpoint, stop orders included (builder-program docs).
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("create_stop_order", payload, account, signMessage);
         return this.post("/orders/stop/create", body);
     }
     async editOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("edit_order", params, account, signMessage);
+        const body = await this.signedBody("edit_order", params, account, signMessage);
         return this.post("/orders/edit", body);
     }
     async cancelOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_order", params, account, signMessage);
         return this.post("/orders/cancel", body);
     }
     async cancelAllOrders(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_all_orders", params, account, signMessage);
+        const body = await this.signedBody("cancel_all_orders", params, account, signMessage);
         return this.post("/orders/cancel_all", body);
     }
     async cancelStopOrder(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_stop_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_stop_order", params, account, signMessage);
         return this.post("/orders/stop/cancel", body);
     }
+    /** create_twap_order documents no builder_code, so a TWAP never carries one (builder-fee.ts). */
     async createTWAP(params, account, signMessage) {
-        const payload = this.addBuilderCode({ ...params });
-        const body = await buildSignedRequest("create_twap_order", payload, account, signMessage);
+        const body = await this.signedBody("create_twap_order", { ...params }, account, signMessage);
         return this.post("/orders/twap/create", body);
     }
     async cancelTWAP(params, account, signMessage) {
-        const body = await buildSignedRequest("cancel_twap_order", params, account, signMessage);
+        const body = await this.signedBody("cancel_twap_order", params, account, signMessage);
         return this.post("/orders/twap/cancel", body);
     }
-    async setTPSL(params, account, signMessage) {
-        const body = await buildSignedRequest("set_position_tpsl", params, account, signMessage);
+    async setTPSL(params, account, signMessage, builderCode) {
+        // Position TP/SL creates orders and therefore takes builder_code too (POST /positions/tpsl).
+        const payload = this.withBuilderCode({ ...params }, builderCode);
+        const body = await this.signedBody("set_position_tpsl", payload, account, signMessage);
         return this.post("/positions/tpsl", body);
     }
     async updateLeverage(params, account, signMessage) {
-        const body = await buildSignedRequest("update_leverage", params, account, signMessage);
+        const body = await this.signedBody("update_leverage", params, account, signMessage);
         return this.post("/account/leverage", body);
     }
     async updateMarginMode(params, account, signMessage) {
-        const body = await buildSignedRequest("update_margin_mode", params, account, signMessage);
+        const body = await this.signedBody("update_margin_mode", params, account, signMessage);
         return this.post("/account/margin", body);
     }
     async withdraw(params, account, signMessage) {
-        const body = await buildSignedRequest("withdraw", params, account, signMessage);
+        const body = await this.signedBody("withdraw", params, account, signMessage);
         return this.post("/account/withdraw", body);
     }
     // ==================== SUBACCOUNT ====================
-    async createSubaccount(subaccountName, account, signMessage) {
-        // Step 1: Initiate
-        const initiateBody = await buildSignedRequest("subaccount_initiate", { subaccount_name: subaccountName }, account, signMessage);
-        await this.post("/account/subaccount/create", initiateBody);
-        // Step 2: Confirm
-        const confirmBody = await buildSignedRequest("subaccount_confirm", { subaccount_name: subaccountName }, account, signMessage);
-        return this.post("/account/subaccount/create", confirmBody);
-    }
+    // POST /account/subaccount/create is not implemented. Docs (rest-api/subaccounts/create-subaccount):
+    // "Both the main account and subaccount must sign to establish the relationship." — the body is
+    // {main_account, subaccount, main_signature, sub_signature, timestamp, expiry_window}; the
+    // subaccount keypair signs {account: <main>} ("subaccount_initiate") and the main account signs
+    // {signature: <sub_signature>} ("subaccount_confirm") (python-sdk rest/create_subaccount.py).
+    // perp-cli has no second (subaccount) keypair source, so `manage sub create` is gated.
     async listSubaccounts(account, signMessage) {
-        const body = await buildSignedRequest("list_subaccounts", {}, account, signMessage);
+        const body = await this.signedBody("list_subaccounts", {}, account, signMessage);
         return this.post("/account/subaccount/list", body);
     }
     async transferFunds(params, account, signMessage) {
-        const body = await buildSignedRequest("transfer_funds", params, account, signMessage);
+        const body = await this.signedBody("transfer_funds", params, account, signMessage);
         return this.post("/account/subaccount/transfer", body);
     }
     // ==================== AGENT WALLET ====================
     async bindAgentWallet(agentWallet, account, signMessage) {
-        const body = await buildSignedRequest("bind_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
+        const body = await this.signedBody("bind_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
         return this.post("/agent/bind", body);
     }
     async listAgentWallets(account, signMessage) {
-        const body = await buildSignedRequest("list_agent_wallets", {}, account, signMessage);
+        const body = await this.signedBody("list_agent_wallets", {}, account, signMessage);
         return this.post("/agent/list", body);
     }
     async revokeAgentWallet(agentWallet, account, signMessage) {
-        const body = await buildSignedRequest("revoke_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
+        const body = await this.signedBody("revoke_agent_wallet", { agent_wallet: agentWallet }, account, signMessage);
         return this.post("/agent/revoke", body);
     }
     async revokeAllAgentWallets(account, signMessage) {
-        const body = await buildSignedRequest("revoke_all_agent_wallets", {}, account, signMessage);
+        const body = await this.signedBody("revoke_all_agent_wallets", {}, account, signMessage);
         return this.post("/agent/revoke_all", body);
     }
     // ==================== API KEYS ====================
-    async createApiKey(name, maxFeeRate, account, signMessage) {
-        const body = await buildSignedRequest("create_api_key", { name, max_fee_rate: maxFeeRate }, account, signMessage);
+    /**
+     * API Config Key (rate-limit key). Docs (api/rate-limits/api-config-keys): the request body is
+     * account / signature / timestamp / expiry_window only; python-sdk rest/api_config_keys.py signs
+     * type "create_api_key" with `signature_payload = {}`.
+     */
+    async createApiKey(account, signMessage) {
+        const body = await this.signedBody("create_api_key", {}, account, signMessage);
         return this.post("/account/api_keys/create", body);
     }
     async listApiKeys(account, signMessage) {
-        const body = await buildSignedRequest("list_api_keys", {}, account, signMessage);
+        const body = await this.signedBody("list_api_keys", {}, account, signMessage);
         return this.post("/account/api_keys", body);
     }
     async revokeApiKey(apiKey, account, signMessage) {
-        const body = await buildSignedRequest("revoke_api_key", { api_key: apiKey }, account, signMessage);
+        const body = await this.signedBody("revoke_api_key", { api_key: apiKey }, account, signMessage);
         return this.post("/account/api_keys/revoke", body);
     }
     // ==================== LAKE ====================
     async createLake(params, account, signMessage) {
-        const body = await buildSignedRequest("create_lake", params, account, signMessage);
+        // Optional fields are omitted, not sent as null (the signed payload must equal the body).
+        const payload = {};
+        if (params.manager !== null)
+            payload.manager = params.manager;
+        if (params.nickname !== null)
+            payload.nickname = params.nickname;
+        if (params.initial_deposit !== null)
+            payload.initial_deposit = params.initial_deposit;
+        const body = await this.signedBody("create_lake", payload, account, signMessage);
         return this.post("/lake/create", body);
     }
     async depositToLake(params, account, signMessage) {
-        const body = await buildSignedRequest("deposit_to_lake", params, account, signMessage);
+        const body = await this.signedBody("deposit_to_lake", params, account, signMessage);
         return this.post("/lake/deposit", body);
     }
     async withdrawFromLake(params, account, signMessage) {
-        const body = await buildSignedRequest("withdraw_from_lake", params, account, signMessage);
+        const body = await this.signedBody("withdraw_from_lake", params, account, signMessage);
         return this.post("/lake/withdraw", body);
     }
     // ==================== BUILDER CODE ====================
     async approveBuilderCode(params, account, signMessage) {
-        const body = await buildSignedRequest("approve_builder_code", params, account, signMessage);
+        const body = await this.signedBody("approve_builder_code", params, account, signMessage);
         return this.post("/account/builder_codes/approve", body);
     }
     async revokeBuilderCode(params, account, signMessage) {
-        const body = await buildSignedRequest("revoke_builder_code", params, account, signMessage);
+        const body = await this.signedBody("revoke_builder_code", params, account, signMessage);
         return this.post("/account/builder_codes/revoke", body);
     }
     async getBuilderApprovals(account) {
         return this.get("/account/builder_codes/approvals", { account });
     }
     async updateBuilderFeeRate(params, account, signMessage) {
-        const body = await buildSignedRequest("update_builder_code_fee_rate", params, account, signMessage);
+        const body = await this.signedBody("update_builder_code_fee_rate", params, account, signMessage);
         return this.post("/builder/update_fee_rate", body);
     }
     async getBuilderOverview(account) {
@@ -300,7 +404,7 @@ export class PacificaClient {
     }
     // ==================== REFERRAL ====================
     async claimReferralCode(params, account, signMessage) {
-        const body = await buildSignedRequest("claim_referral_code", params, account, signMessage);
+        const body = await this.signedBody("claim_referral_code", params, account, signMessage);
         return this.post("/referral/user/code/claim", body);
     }
     // ==================== BATCH ====================

package/dist/pacifica/constants.d.ts

@@ -12,7 +12,6 @@ export declare const TESTNET_PACIFICA_VAULT = "5SDFdHZGTZbyRYu54CgmRkCGnPHC5pYaN
 export declare const TESTNET_USDC_MINT = "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM";
 export declare const DEFAULT_EXPIRY_WINDOW = 5000;
 export declare const USDC_DECIMALS = 6;
-export declare const BUILDER_CODE = "PERPCLI";
 export type Network = "mainnet" | "testnet";
 export declare function getNetworkConfig(network?: Network): {
     restUrl: string;

package/dist/pacifica/constants.js

@@ -19,11 +19,6 @@ export const TESTNET_USDC_MINT = "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM";
 export const DEFAULT_EXPIRY_WINDOW = 5000; // 5 seconds
 // USDC decimals
 export const USDC_DECIMALS = 6;
-// Builder code — 0% fee, used for Pacifica hackathon tracking
-// The actual 3-way fallback (env → settings.referralCodes.pacifica → "PERPCLI") is
-// resolved in index.ts before constructing PacificaAdapter. This constant is only
-// a last-resort default for direct PacificaClient usage without a builderCode arg.
-export const BUILDER_CODE = "PERPCLI";
 export function getNetworkConfig(network = "mainnet") {
     if (network === "testnet") {
         return {

package/dist/pacifica/deposit.d.ts

@@ -4,11 +4,38 @@ import { type Network } from "./constants.js";
  * Build a Pacifica deposit instruction.
  *
  * @param userPubkey - User's wallet public key
- * @param amount - Amount in USDC (e.g., 100 for $100)
+ * @param amount - Amount in USDC as a plain decimal string with at most 6 decimals (e.g. "100", "99.5");
+ *                 scaled exactly (no float math). Anything else → INVALID_PARAMS.
  * @param network - mainnet or testnet
  */
-export declare function buildDepositInstruction(userPubkey: PublicKey, amount: number, network?: Network): Promise<TransactionInstruction>;
+export declare function buildDepositInstruction(userPubkey: PublicKey, amount: string, network?: Network): Promise<TransactionInstruction>;
 /**
  * Build and send a deposit transaction.
  */
-export declare function deposit(connection: Connection, userPubkey: PublicKey, amount: number, signTransaction: (tx: Transaction) => Promise<Transaction>, network?: Network): Promise<TransactionSignature>;
+export declare function deposit(connection: Connection, userPubkey: PublicKey, amount: string, signTransaction: (tx: Transaction) => Promise<Transaction>, network?: Network): Promise<TransactionSignature>;
+/** Highest relayer fee (USDC) the CLI signs for a relayed deposit. Above it the transaction is refused. */
+export declare const PACIFICA_RELAY_FEE_CAP_USDC = 1;
+/**
+ * Verify a RELAYER-BUILT transaction before the master Solana key signs it. The relayer is an
+ * untrusted HTTP service (PERP_RELAYER_URL): whatever it returns is signed only when it is
+ * exactly
+ *  - ONE pinned Pacifica deposit instruction — the program id, every account (user, user USDC
+ *    ATA, central state, vault, mint, …, in order, same signer / writable flags) and the data
+ *    `buildDepositInstruction` would produce for `declared.netAmount`;
+ *  - any number of ComputeBudget instructions (they move no funds);
+ *  - at most ONE relayer fee transfer: an SPL Token Transfer / TransferChecked of exactly
+ *    `declared.fee` USDC from the user's USDC account, authority = user, to the token account the
+ *    build response declared (`feeRecipient`), with fee ≤ PACIFICA_RELAY_FEE_CAP_USDC;
+ * and fee + netAmount equals the amount the user asked to deposit, and the fee payer is not the
+ * user (the relayer sponsors gas). Anything else → POLICY_DENIED, nothing is signed.
+ */
+export declare function assertRelayedDepositTransaction(tx: Transaction, ctx: {
+    user: PublicKey;
+    requestedAmount: string;
+    network: Network;
+    declared: {
+        fee: number;
+        netAmount: number;
+        feeRecipient: string | null;
+    };
+}): Promise<void>;

package/dist/pacifica/deposit.js

@@ -1,5 +1,6 @@
 import { PublicKey, TransactionInstruction, Transaction, } from "@solana/web3.js";
 import { getNetworkConfig, USDC_DECIMALS } from "./constants.js";
+import { PerpError } from "../errors.js";
 const TOKEN_PROGRAM = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
 const ASSOCIATED_TOKEN_PROGRAM = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
 const SYSTEM_PROGRAM = new PublicKey("11111111111111111111111111111111");
@@ -30,7 +31,8 @@ function getEventAuthority(programId) {
  * Build a Pacifica deposit instruction.
  *
  * @param userPubkey - User's wallet public key
- * @param amount - Amount in USDC (e.g., 100 for $100)
+ * @param amount - Amount in USDC as a plain decimal string with at most 6 decimals (e.g. "100", "99.5");
+ *                 scaled exactly (no float math). Anything else → INVALID_PARAMS.
  * @param network - mainnet or testnet
  */
 export async function buildDepositInstruction(userPubkey, amount, network = "mainnet") {
@@ -43,7 +45,12 @@ export async function buildDepositInstruction(userPubkey, amount, network = "mai
     const eventAuthority = getEventAuthority(programId);
     // Build instruction data: discriminator + amount (u64 LE)
     const discriminator = await getDepositDiscriminator();
-    const amountLamports = BigInt(Math.round(amount * 10 ** USDC_DECIMALS));
+    const amountLamports = usdcUnits(amount);
+    if (amountLamports === null || amountLamports <= 0n) {
+        throw new PerpError("INVALID_PARAMS", `Pacifica deposit amount "${amount}" is not a positive USDC amount with at most ${USDC_DECIMALS} decimals; nothing was built`, {
+            exchange: "pacifica", remediation: `Pass a plain decimal with at most ${USDC_DECIMALS} decimals, e.g. 100 or 99.5`,
+        });
+    }
     const amountBytes = new Uint8Array(8);
     const view = new DataView(amountBytes.buffer);
     view.setBigUint64(0, amountLamports, true); // little-endian
@@ -76,3 +83,113 @@ export async function deposit(connection, userPubkey, amount, signTransaction, n
     const signed = await signTransaction(tx);
     return connection.sendRawTransaction(signed.serialize());
 }
+const COMPUTE_BUDGET_PROGRAM = new PublicKey("ComputeBudget111111111111111111111111111111");
+/** Highest relayer fee (USDC) the CLI signs for a relayed deposit. Above it the transaction is refused. */
+export const PACIFICA_RELAY_FEE_CAP_USDC = 1;
+/** Decimal USDC string → integer base units (6 decimals), exact; null when not a plain decimal with ≤ 6 decimals. */
+function usdcUnits(amount) {
+    const m = /^(\d+)(?:\.(\d{1,6}))?$/.exec(amount.trim());
+    if (m === null)
+        return null;
+    return BigInt(m[1]) * 10n ** BigInt(USDC_DECIMALS) + BigInt((m[2] ?? "").padEnd(USDC_DECIMALS, "0"));
+}
+function readU64LE(data, offset) {
+    if (data.length < offset + 8)
+        return null;
+    return new DataView(data.buffer, data.byteOffset + offset, 8).getBigUint64(0, true);
+}
+/**
+ * Verify a RELAYER-BUILT transaction before the master Solana key signs it. The relayer is an
+ * untrusted HTTP service (PERP_RELAYER_URL): whatever it returns is signed only when it is
+ * exactly
+ *  - ONE pinned Pacifica deposit instruction — the program id, every account (user, user USDC
+ *    ATA, central state, vault, mint, …, in order, same signer / writable flags) and the data
+ *    `buildDepositInstruction` would produce for `declared.netAmount`;
+ *  - any number of ComputeBudget instructions (they move no funds);
+ *  - at most ONE relayer fee transfer: an SPL Token Transfer / TransferChecked of exactly
+ *    `declared.fee` USDC from the user's USDC account, authority = user, to the token account the
+ *    build response declared (`feeRecipient`), with fee ≤ PACIFICA_RELAY_FEE_CAP_USDC;
+ * and fee + netAmount equals the amount the user asked to deposit, and the fee payer is not the
+ * user (the relayer sponsors gas). Anything else → POLICY_DENIED, nothing is signed.
+ */
+export async function assertRelayedDepositTransaction(tx, ctx) {
+    const refuse = (why) => new PerpError("POLICY_DENIED", `Refusing to sign the relayer-built Pacifica deposit: ${why}. Nothing was signed`, {
+        exchange: "pacifica", remediation: "Drop --relay for a direct deposit (you pay gas, ~0.005 SOL)",
+    });
+    const { user, declared } = ctx;
+    const requested = usdcUnits(ctx.requestedAmount);
+    if (requested === null || requested <= 0n)
+        throw refuse(`the requested amount "${ctx.requestedAmount}" is not a USDC amount with at most ${USDC_DECIMALS} decimals`);
+    if (!Number.isFinite(declared.fee) || !Number.isFinite(declared.netAmount) || declared.fee < 0 || declared.netAmount <= 0) {
+        throw refuse(`the build response declares fee ${declared.fee} / netAmount ${declared.netAmount}`);
+    }
+    const feeUnits = BigInt(Math.round(declared.fee * 10 ** USDC_DECIMALS));
+    const netUnits = BigInt(Math.round(declared.netAmount * 10 ** USDC_DECIMALS));
+    if (feeUnits + netUnits !== requested)
+        throw refuse(`declared fee ${declared.fee} + netAmount ${declared.netAmount} is not the requested ${ctx.requestedAmount} USDC`);
+    if (declared.fee > PACIFICA_RELAY_FEE_CAP_USDC)
+        throw refuse(`the relayer fee ${declared.fee} USDC is above the cap of ${PACIFICA_RELAY_FEE_CAP_USDC} USDC`);
+    if (tx.feePayer === undefined || tx.feePayer === null || tx.feePayer.equals(user))
+        throw refuse("the fee payer is not the relayer (a sponsored deposit never makes the user pay gas)");
+    const config = getNetworkConfig(ctx.network);
+    const usdcMint = new PublicKey(config.usdcMint);
+    const userAta = getATA(user, usdcMint);
+    const netDecimal = `${netUnits / 10n ** BigInt(USDC_DECIMALS)}.${(netUnits % 10n ** BigInt(USDC_DECIMALS)).toString().padStart(USDC_DECIMALS, "0")}`;
+    const expected = await buildDepositInstruction(user, netDecimal, ctx.network);
+    let deposits = 0;
+    let feeTransfers = 0;
+    for (const [i, ix] of tx.instructions.entries()) {
+        const at = `instruction ${i} (${ix.programId.toBase58()})`;
+        if (ix.programId.equals(COMPUTE_BUDGET_PROGRAM)) {
+            if (ix.keys.length !== 0)
+                throw refuse(`${at}: a compute-budget instruction with accounts`);
+            continue;
+        }
+        if (ix.programId.equals(expected.programId)) {
+            const sameKeys = ix.keys.length === expected.keys.length && ix.keys.every((k, j) => k.pubkey.equals(expected.keys[j].pubkey) && k.isSigner === expected.keys[j].isSigner && k.isWritable === expected.keys[j].isWritable);
+            if (!sameKeys)
+                throw refuse(`${at}: the deposit accounts are not the pinned user / vault / mint accounts`);
+            if (!Buffer.from(ix.data).equals(Buffer.from(expected.data)))
+                throw refuse(`${at}: the deposit data is not "deposit ${declared.netAmount} USDC"`);
+            deposits++;
+            continue;
+        }
+        if (ix.programId.equals(TOKEN_PROGRAM)) {
+            // SPL Token Transfer (3): [source, destination, authority]; TransferChecked (12): [source, mint, destination, authority].
+            const tag = ix.data[0];
+            const checked = tag === 12;
+            if (tag !== 3 && !checked)
+                throw refuse(`${at}: an SPL token instruction that is not a transfer`);
+            if (ix.data.length !== (checked ? 10 : 9) || ix.keys.length !== (checked ? 4 : 3))
+                throw refuse(`${at}: a malformed token transfer`);
+            const [source, dest, authority] = checked ? [ix.keys[0], ix.keys[2], ix.keys[3]] : [ix.keys[0], ix.keys[1], ix.keys[2]];
+            if (checked && (!ix.keys[1].pubkey.equals(usdcMint) || ix.data[9] !== USDC_DECIMALS))
+                throw refuse(`${at}: the fee transfer is not in the deposit token`);
+            if (!source.pubkey.equals(userAta) || !authority.pubkey.equals(user))
+                throw refuse(`${at}: the token transfer is not from the user's own USDC account`);
+            if (declared.feeRecipient === null)
+                throw refuse(`${at}: a fee transfer the build response did not declare (no feeRecipient)`);
+            let recipient;
+            try {
+                recipient = new PublicKey(declared.feeRecipient);
+            }
+            catch {
+                throw refuse(`the declared feeRecipient "${declared.feeRecipient}" is not a Solana address`);
+            }
+            if (!dest.pubkey.equals(recipient))
+                throw refuse(`${at}: the fee transfer goes to ${dest.pubkey.toBase58()}, not the declared ${recipient.toBase58()}`);
+            if (readU64LE(ix.data, 1) !== feeUnits)
+                throw refuse(`${at}: the fee transfer amount is not the declared ${declared.fee} USDC`);
+            if (++feeTransfers > 1)
+                throw refuse("more than one fee transfer");
+            continue;
+        }
+        throw refuse(`${at} is not a Pacifica deposit, a compute-budget instruction or the declared fee transfer`);
+    }
+    if (deposits !== 1)
+        throw refuse(`it contains ${deposits} Pacifica deposit instructions (exactly one expected)`);
+    if (feeUnits > 0n && feeTransfers !== 1)
+        throw refuse(`the declared fee ${declared.fee} USDC is not transferred by the transaction`);
+    if (feeUnits === 0n && feeTransfers !== 0)
+        throw refuse("a fee transfer although the declared fee is 0");
+}

package/dist/pacifica/faucet.d.ts

@@ -0,0 +1,29 @@
+import { Connection, PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { SolanaSigner } from "../signer/index.js";
+export declare const PACIFICA_DEVNET_RPC = "https://api.devnet.solana.com";
+export declare const MINT_TEST_USDC_COMPUTE_UNITS = 400000;
+/** sha256("global:mint_test_usdc")[:8]. */
+export declare function mintTestUsdcDiscriminator(): Buffer;
+/** Plain positive decimal with ≤ 6 decimals → base units (u64). */
+export declare function testUsdcBaseUnits(amount: string): bigint;
+export interface MintTestUsdcPlan {
+    user: string;
+    userAccountPda: string;
+    userAta: string;
+    mint: string;
+    centralState: string;
+    programId: string;
+    amount: string;
+    baseUnits: string;
+}
+/** Accounts + amount the faucet instruction uses (pure; used for --dry-run). */
+export declare function mintTestUsdcPlan(user: PublicKey, amount: string): MintTestUsdcPlan;
+export declare function buildMintTestUsdcInstruction(plan: MintTestUsdcPlan): TransactionInstruction;
+/**
+ * Build, sign, SIMULATE, then send + confirm the faucet transaction. A simulation
+ * error throws EXCHANGE_ERROR (with the program logs) and nothing is sent.
+ */
+export declare function mintTestUsdc(connection: Connection, signer: SolanaSigner, amount: string): Promise<{
+    signature: string;
+    plan: MintTestUsdcPlan;
+}>;