perp-cli 0.9.8 → 0.12.0

package/dist/exchanges/lighter.js

@@ -1,4 +1,30 @@
 import { LocalEvmSigner } from "../signer/index.js";
+import { isExpired } from "../agent-wallet/expiry.js";
+import { PerpError } from "../errors.js";
+/** Lighter trigger orderType enum (matches WASM signer). */
+export const LIGHTER_ORDER_TYPE = {
+    STOP_LOSS: 2,
+    STOP_LOSS_LIMIT: 3,
+    TAKE_PROFIT: 4,
+    TAKE_PROFIT_LIMIT: 5,
+};
+/**
+ * Pick Lighter trigger orderType from side, trigger price, and current mark.
+ *
+ * STOP_LOSS protects against adverse moves; TAKE_PROFIT locks in favorable moves.
+ *   buy + trigger >= mark  → STOP_LOSS  (close short on rise / breakout entry)
+ *   buy + trigger <  mark  → TAKE_PROFIT (close short on fall)
+ *   sell + trigger <= mark → STOP_LOSS  (close long on fall)
+ *   sell + trigger >  mark → TAKE_PROFIT (close long on rise)
+ *
+ * Tied trigger==mark is classified as STOP_LOSS — the protective default.
+ */
+export function classifyTriggerOrderType(side, triggerPrice, markPrice, isMarket) {
+    const isStopLoss = side === "buy" ? triggerPrice >= markPrice : triggerPrice <= markPrice;
+    if (isStopLoss)
+        return isMarket ? LIGHTER_ORDER_TYPE.STOP_LOSS : LIGHTER_ORDER_TYPE.STOP_LOSS_LIMIT;
+    return isMarket ? LIGHTER_ORDER_TYPE.TAKE_PROFIT : LIGHTER_ORDER_TYPE.TAKE_PROFIT_LIMIT;
+}
 export class LighterAdapter {
     name = "lighter";
     chain = "ethereum";
@@ -21,6 +47,16 @@ export class LighterAdapter {
     _marketsCache = null;
     _marketsCacheTime = 0;
     static CACHE_TTL = 30_000;
+    // ── 3-tier signer state (Phase 2d) ──
+    /** Tier 1 metadata (Phase 2d). When set + not expired + !_useNoAgent, agent
+     *  apiKeyIndex/publicKey/accountIndex take priority over master/PK env. */
+    _agentMeta;
+    /** Tier 1 secp256k1 hex private key (40 bytes) for the agent slot. Lighter
+     *  has no OWS curve binding for raw L2 keys; this is held in-memory only when
+     *  passed by the caller (e.g. immediately after `setupApiKey()` or via env). */
+    _agentApiKey;
+    /** --no-agent bypass flag. */
+    _useNoAgent = false;
     /**
      * @param evmKey    EVM private key (0x-prefixed, 32 bytes) — for deposits & key registration
      * @param testnet   Use testnet (chain ID 300) instead of mainnet (chain ID 304)
@@ -28,9 +64,12 @@ export class LighterAdapter {
      */
     constructor(evmKey, testnet = false, opts) {
         this._evmKey = evmKey;
-        this._apiKey = opts?.apiKey || process.env.LIGHTER_API_KEY || "";
-        this._accountIndexInit = opts?.accountIndex ?? parseInt(process.env.LIGHTER_ACCOUNT_INDEX || "-1");
-        this._apiKeyIndex = parseInt(process.env.LIGHTER_API_KEY_INDEX || "4");
+        // SSOT Rule #3: L2 API key is no longer read from env. Caller must inject
+        // via opts.apiKey (Tier 1 agent path uses setAgentSigner; auto-setup at
+        // init() runs ChangePubKey when apiKey is empty AND we have an EVM key).
+        this._apiKey = opts?.apiKey ?? "";
+        this._accountIndexInit = opts?.accountIndex ?? -1;
+        this._apiKeyIndex = opts?.apiKeyIndex ?? 4;
         this._address = "";
         this._testnet = testnet;
         this._readOnly = !this._apiKey;
@@ -64,19 +103,120 @@ export class LighterAdapter {
     /** Inject an external EVM signer. Call before init() to skip LocalEvmSigner creation. */
     setSigner(signer) {
         this._evmSigner = signer;
+        this._address = signer.getAddress();
+        // Reset any caller-supplied accountIndex hint: when the agent flow injects
+        // an OWS signer that differs from the constructor-time master, force a
+        // fresh /api/v1/account lookup keyed on the injected signer. Without this
+        // reset, a stale account index would route ChangePubKey to the wrong
+        // account (Lighter rejects the L1 sig with code=21504 "fail to l1 signature").
+        this._accountIndexInit = -1;
+        this._accountIndex = -1;
+    }
+    /**
+     * Tier 1: inject a Lighter agent's slot+L2 key (Phase 2d).
+     *
+     * Caller supplies the AgentMeta (settings.agents.lighter[name]) plus the
+     * 40-byte L2 private key (hex). Adapter swaps `_apiKey`/`_apiKeyIndex` to
+     * the agent's slot/key so all subsequent `signCreateOrder`/`signCancelOrder`
+     * etc. flow through the agent identity.
+     *
+     * NOTE: when the agent path is active, `_address` (master EVM) is left
+     * unchanged because Lighter REST queries (account, balance, positions) use
+     * `account_index` not address. The L1 EVM identity is irrelevant for the
+     * hot-path; only the L2 secp256k1 key is consulted.
+     */
+    setAgentSigner(meta, agentApiKey) {
+        this._agentMeta = meta;
+        this._agentApiKey = agentApiKey;
+        // Reset any prior accountIndex hint: the agent may belong to a different
+        // Lighter account than the master signer, so any stale value must not
+        // override the AgentMeta-derived accountIndex applied in init().
+        this._accountIndexInit = -1;
+        this._accountIndex = -1;
+        // Active slot+key swap happens lazily in `_resolveSigner()`/init flows.
+    }
+    /** Bypass Tier 1 (agent) — used for `--no-agent` flag. */
+    setNoAgent(noAgent) {
+        this._useNoAgent = noAgent;
+    }
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier() {
+        try {
+            return this._resolveSigner().tier;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve the active signer tier across three tiers (Phase 2d).
+     *
+     * Tier 1 (agent): active when AgentMeta + agent L2 key set, not expired,
+     *   and `--no-agent` NOT set. The actual swap of `_apiKeyIndex`/`_apiKey`
+     *   happens in `init()` (or via `_activateAgentTier()` post-init).
+     * Tier 2 (master): active when an OWS master EVM signer was injected via
+     *   `setSigner()`. Used for the L1 ChangePubKey path (auto-setup at slot 4).
+     * Tier 3 (pk): active when constructor was supplied an evmKey. Same role
+     *   as Tier 2 — signs L1 ChangePubKey for auto-setup.
+     *
+     * Lighter is unique among the 4 DEXs in that the actual order-signing is
+     * always done by the L2 secp256k1 key (`_apiKey`), regardless of tier. The
+     * tiers differ in WHICH L2 key is loaded: Tier 1 uses the agent's slot/key
+     * from AgentMeta; Tier 2/3 use whatever the env/auto-setup produced.
+     */
+    _resolveSigner() {
+        if (!this._useNoAgent && this._agentMeta && this._agentApiKey) {
+            if (isExpired(this._agentMeta)) {
+                // Skip Tier 1 only if Tier 2/3 available; otherwise throw AGENT_EXPIRED
+                if (!this._evmSigner && !this._evmKey) {
+                    throw new PerpError("AGENT_EXPIRED", "Agent wallet has expired", {
+                        remediation: "perp wallet agent approve lighter --rotate",
+                    });
+                }
+                // fall through
+            }
+            else {
+                return { tier: "agent" };
+            }
+        }
+        if (this._evmSigner)
+            return { tier: "master" };
+        if (this._evmKey)
+            return { tier: "pk" };
+        throw new PerpError("NO_SIGNER_AVAILABLE", "No signing path configured for Lighter", {
+            remediation: "Run one of: (a) perp wallet agent approve lighter --master <wallet>; (b) perp wallet generate && perp -e lighter --ows <wallet>; (c) export LIGHTER_PRIVATE_KEY=0x...",
+        });
     }
     async init() {
+        // Phase 2d: when an agent is registered (Tier 1), swap _apiKey/_apiKeyIndex
+        // to the agent's slot/key BEFORE any of the existing init logic runs. This
+        // ensures the WASM client below is created with the agent's credentials.
+        // The agent L2 key is loaded from the encrypted keystore by the caller and
+        // injected via setAgentSigner() — never read from env (SSOT Rule #3).
+        if (!this._useNoAgent && this._agentMeta && this._agentApiKey && !isExpired(this._agentMeta)) {
+            this._apiKey = this._agentApiKey;
+            if (typeof this._agentMeta.apiKeyIndex === "number") {
+                this._apiKeyIndex = this._agentMeta.apiKeyIndex;
+            }
+            if (typeof this._agentMeta.accountIndex === "number") {
+                this._accountIndex = this._agentMeta.accountIndex;
+                this._accountIndexInit = this._agentMeta.accountIndex;
+            }
+        }
         // Initialize EVM signer if not externally injected (skip if no key — read-only mode)
         if (!this._evmSigner && this._evmKey) {
             this._evmSigner = await LocalEvmSigner.create(this._evmKey);
             this._address = this._evmSigner.getAddress();
         }
+        else if (this._evmSigner && !this._address) {
+            this._address = this._evmSigner.getAddress();
+        }
         // Fetch account index from REST API (skip if no address — read-only mode)
         if (!this._address) {
             await this._refreshMarketMap();
             return;
         }
-        // If accountIndex is already known (from env/opts), skip API lookup entirely
+        // If accountIndex is already known (from env/opts/agent meta), skip API lookup entirely
         if (this._accountIndexInit >= 0) {
             this._accountIndex = this._accountIndexInit;
         }
@@ -114,19 +254,18 @@ export class LighterAdapter {
                 // setupApiKey already configured the static WASM client — reuse it
                 this._signer = LighterAdapter._wasmClient;
                 signerReady = true;
-                // Save to .env for future use
+                // SSOT Rule #3: persist L2 key to encrypted keystore so subsequent
+                // process invocations can reload it without re-running ChangePubKey.
                 try {
-                    const { setEnvVar } = await import("../commands/init.js");
-                    setEnvVar("LIGHTER_API_KEY", apiKey);
-                    setEnvVar("LIGHTER_ACCOUNT_INDEX", String(this._accountIndex));
-                    setEnvVar("LIGHTER_API_KEY_INDEX", String(autoKeyIndex));
+                    const { saveLighterKey } = await import("../agent-wallet/lighter-keystore.js");
+                    saveLighterKey(this._accountIndex, autoKeyIndex, apiKey, "");
                 }
-                catch { /* non-critical — env save may fail in some contexts */ }
+                catch { /* non-critical — keystore save may fail in some contexts */ }
             }
             catch (e) {
                 // Auto-setup failed — log the error and continue in read-only mode
                 const msg = e instanceof Error ? e.message : String(e);
-                console.error(`[lighter] API key auto-setup failed: ${msg}. Trading will be read-only. Run 'perp -e lighter manage setup-api-key' to retry.`);
+                console.error(`[lighter] API key auto-setup failed: ${msg}. Trading will be read-only. Run 'perp wallet agent approve lighter' to register an agent.`);
             }
         }
         // Initialize signer for trading if we have an API key (reuse singleton WASM client)
@@ -136,7 +275,7 @@ export class LighterAdapter {
             if (cleanKey.startsWith("0x"))
                 cleanKey = cleanKey.slice(2);
             if (cleanKey.length > 0 && !/^[0-9a-fA-F]+$/.test(cleanKey)) {
-                console.error(`[lighter] API key contains invalid chars (expected hex). Check LIGHTER_API_KEY in ~/.perp/.env or run 'perp -e lighter manage setup-api-key' to regenerate.`);
+                console.error(`[lighter] API key contains invalid chars (expected hex). Run 'perp wallet agent approve lighter' to register an agent.`);
                 this._apiKey = "";
             }
             else if (cleanKey.length === 0) {
@@ -144,7 +283,7 @@ export class LighterAdapter {
             }
             else if (this._accountIndex < 0) {
                 // Account lookup failed or returned no accounts — cannot initialize WASM signer
-                console.error(`[lighter] Account index not available (got ${this._accountIndex}). Trading will be read-only. Ensure the wallet has a Lighter account or set LIGHTER_ACCOUNT_INDEX.`);
+                console.error(`[lighter] Account index not available (got ${this._accountIndex}). Trading will be read-only. Ensure the wallet has a Lighter account, or run 'perp wallet agent approve lighter' to register an agent.`);
                 this._apiKey = "";
             }
             else {
@@ -280,9 +419,10 @@ export class LighterAdapter {
                 const maxLev = imf > 0 ? Math.floor(10000 / imf) : 50;
                 const fr = fundingRates.get(d.symbol);
                 const dec = this._marketDecimals.get(d.symbol.toUpperCase());
+                const fundingMark = fr && Number(fr.markPrice) > 0 ? fr.markPrice : null;
                 markets.push({
                     symbol: d.symbol,
-                    markPrice: fr?.markPrice ?? String(d.last_trade_price ?? 0),
+                    markPrice: fundingMark ?? String(d.last_trade_price ?? 0),
                     indexPrice: String(d.last_trade_price ?? 0),
                     fundingRate: fr?.rate ?? null,
                     volume24h: String(d.daily_quote_token_volume ?? 0),
@@ -616,28 +756,29 @@ export class LighterAdapter {
         const marketIndex = this.getMarketIndex(symbol);
         const { baseAmount } = this.toTicks(symbol, parseFloat(size), 0);
         const { priceTicks: triggerTicks } = this.toTicks(symbol, 0, parseFloat(triggerPrice));
-        // If limitPrice given → stop-limit (type 0, GTT), else stop-market (type 1, IOC)
+        const triggerNum = parseFloat(triggerPrice);
+        const markPrice = await this.getMarkPrice(symbol);
         const isMarket = !opts?.limitPrice;
         let priceTicks;
         if (isMarket) {
-            const markPrice = await this.getMarkPrice(symbol);
             const slippagePrice = side === "buy" ? markPrice * 2 : markPrice * 0.5;
             priceTicks = this.toTicks(symbol, 0, slippagePrice).priceTicks;
         }
         else {
             priceTicks = this.toTicks(symbol, 0, parseFloat(opts.limitPrice)).priceTicks;
         }
+        const orderType = classifyTriggerOrderType(side, triggerNum, markPrice, isMarket);
         const signed = await this.signOrder({
             marketIndex,
             clientOrderIndex: this.nextClientOrderIndex(),
             baseAmount,
             price: Math.max(priceTicks, 1),
             isAsk: side === "sell" ? 1 : 0,
-            orderType: isMarket ? 1 : 0,
+            orderType,
             timeInForce: isMarket ? 0 : 1, // IOC for market, GTT for limit
             reduceOnly: opts?.reduceOnly ? 1 : 0,
             triggerPrice: triggerTicks,
-            orderExpiry: isMarket ? 0 : -1,
+            orderExpiry: -1, // matches Lighter SDK DEFAULT_28_DAY_ORDER_EXPIRY for trigger orders
             nonce,
         });
         return this.sendTx(signed);
@@ -961,8 +1102,11 @@ export class LighterAdapter {
                 is_external_deposit: "true",
             }),
         });
-        if (!res.ok)
-            throw new Error(`createIntentAddress failed: ${await res.text()}`);
+        if (!res.ok) {
+            const text = await res.text();
+            const clean = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+            throw new Error(`createIntentAddress failed: ${clean}`);
+        }
         return res.json();
     }
     /**
@@ -989,7 +1133,15 @@ export class LighterAdapter {
             account_index: String(this._accountIndex),
             api_key_index: String(this._apiKeyIndex),
         });
-        return res.nonce ?? res.next_nonce ?? 0;
+        const nonce = res.nonce ?? res.next_nonce;
+        // SSOT rule #2: refuse to silently default to nonce 0. A stale or
+        // missing nonce will cause Lighter to reject the tx with cryptic errors
+        // and the user has no way to diagnose the upstream failure.
+        if (nonce === undefined || !Number.isFinite(nonce) || nonce < 0) {
+            throw new Error(`Lighter /nextNonce returned no valid nonce for account_index=${this._accountIndex} ` +
+                `api_key_index=${this._apiKeyIndex}; raw response=${JSON.stringify(res)}`);
+        }
+        return nonce;
     }
     async signOrder(params) {
         try {
@@ -1017,11 +1169,18 @@ export class LighterAdapter {
             throw new Error(`Signer error: ${signed.error}`);
         if (!signed.txInfo)
             throw new Error("Signer returned empty txInfo");
+        // SSOT rule #2: refuse to silently default txType to 0 — different tx
+        // types (createOrder=14, cancelOrder=15, updateLeverage=20, etc.) need
+        // different routing on Lighter's side, and a 0 either rejects with a
+        // generic error or silently misroutes.
+        if (signed.txType === undefined || !Number.isFinite(signed.txType)) {
+            throw new Error(`Lighter signer returned no txType (received ${signed.txType}); refusing to send with default 0.`);
+        }
         const res = await fetch(`${this._baseUrl}/api/v1/sendTx`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
-                tx_type: String(signed.txType ?? 0),
+                tx_type: String(signed.txType),
                 tx_info: signed.txInfo,
             }),
         });
@@ -1035,8 +1194,11 @@ export class LighterAdapter {
         for (const [k, v] of Object.entries(params))
             url.searchParams.set(k, v);
         const res = await fetch(url.toString());
-        if (!res.ok)
-            throw new Error(`GET ${path} failed (${res.status}): ${await res.text()}`);
+        if (!res.ok) {
+            const text = await res.text();
+            const clean = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+            throw new Error(`GET ${path} failed (${res.status}): ${clean}`);
+        }
         return res.json();
     }
     /** Generate a unique client order index (uint48). */
@@ -1046,8 +1208,7 @@ export class LighterAdapter {
     }
     ensureSigner() {
         if (this._readOnly || this._accountIndex < 0 || !this._signer) {
-            throw new Error("This command requires a Lighter API key. Run `perp -e lighter manage setup-api-key` first, " +
-                "then set LIGHTER_API_KEY in your .env");
+            throw new Error("This command requires a Lighter API key. Run `perp wallet agent approve lighter` to register an agent.");
         }
     }
     static _wasmClient = null;
@@ -1098,16 +1259,22 @@ export class LighterAdapter {
             throw new Error("No EVM private key configured. Run: perp setup");
         }
         if (this._accountIndex < 0) {
-            throw new Error("Account index not available. Call init() first or set LIGHTER_ACCOUNT_INDEX.");
+            throw new Error("Account index not available. Call init() first.");
         }
         // 1. Generate key pair
         const { privateKey, publicKey } = await LighterAdapter.generateApiKey();
         // 2. Get nonce from API
+        // SSOT rule #2: refuse to silently default to nonce 0 — see getNextNonce.
         const nonceRes = await this.restGet("/nextNonce", {
             account_index: String(this._accountIndex),
             api_key_index: String(apiKeyIndex),
         });
-        const nonce = nonceRes.nonce ?? nonceRes.next_nonce ?? 0;
+        const nonce = nonceRes.nonce ?? nonceRes.next_nonce;
+        if (nonce === undefined || !Number.isFinite(nonce) || nonce < 0) {
+            throw new Error(`Lighter /nextNonce returned no valid nonce for ChangePubKey ` +
+                `(account_index=${this._accountIndex} api_key_index=${apiKeyIndex}); ` +
+                `raw response=${JSON.stringify(nonceRes)}`);
+        }
         // 3. Create signer client with new key and sign ChangePubKey
         const client = await LighterAdapter.getWasmClient();
         await client.createClient({
@@ -1135,11 +1302,15 @@ export class LighterAdapter {
         const txInfo = JSON.parse(signed.txInfo);
         txInfo.L1Sig = l1Sig;
         // 6. Submit to Lighter API
+        // SSOT rule #2: refuse to silently default txType to 0 — see sendTx.
+        if (signed.txType === undefined || !Number.isFinite(signed.txType)) {
+            throw new Error(`Lighter signChangePubKey returned no txType (received ${signed.txType}); refusing to send with default 0.`);
+        }
         const sendRes = await fetch(`${this._baseUrl}/api/v1/sendTx`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
-                tx_type: String(signed.txType ?? 0),
+                tx_type: String(signed.txType),
                 tx_info: JSON.stringify(txInfo),
             }),
         });
@@ -1160,7 +1331,14 @@ export class LighterAdapter {
                         account_index: String(this._accountIndex),
                         api_key_index: String(apiKeyIndex),
                     });
-                    const freshNonce = (freshNonceRes.nonce ?? freshNonceRes.next_nonce ?? nonce) + attempt;
+                    const freshNonceCandidate = freshNonceRes.nonce ?? freshNonceRes.next_nonce;
+                    if (freshNonceCandidate === undefined || !Number.isFinite(freshNonceCandidate) || freshNonceCandidate < 0) {
+                        // SSOT rule #2: refuse to silently fall back to the original nonce.
+                        // Skip the retry attempt and surface the upstream nonce-fetch failure.
+                        lastError = `fresh /nextNonce returned no valid nonce (raw=${JSON.stringify(freshNonceRes)})`;
+                        continue;
+                    }
+                    const freshNonce = freshNonceCandidate + attempt;
                     const retrySigned = await client.signChangePubKey({
                         pubkey: publicKey, nonce: freshNonce, apiKeyIndex, accountIndex: this._accountIndex,
                     });
@@ -1168,13 +1346,17 @@ export class LighterAdapter {
                         lastError = retrySigned.error ?? "incomplete response";
                         continue;
                     }
+                    if (retrySigned.txType === undefined || !Number.isFinite(retrySigned.txType)) {
+                        lastError = `signChangePubKey retry returned no txType (received ${retrySigned.txType})`;
+                        continue;
+                    }
                     const retryTxInfo = JSON.parse(retrySigned.txInfo);
                     retryTxInfo.L1Sig = await this._evmSigner.signMessage(retrySigned.messageToSign);
                     const retryRes = await fetch(`${this._baseUrl}/api/v1/sendTx`, {
                         method: "POST",
                         headers: { "Content-Type": "application/x-www-form-urlencoded" },
                         body: new URLSearchParams({
-                            tx_type: String(retrySigned.txType ?? 0),
+                            tx_type: String(retrySigned.txType),
                             tx_info: JSON.stringify(retryTxInfo),
                         }),
                     });

package/dist/exchanges/pacifica-typed-data.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pacifica agent-wallet signing builders (Phase 2c).
+ *
+ * Pacifica auth model — off-chain signed messages over Solana Ed25519.
+ * Reference: https://pacifica.gitbook.io/docs/api-documentation/api/signing.md
+ *
+ * Canonical JSON rules (from Pacifica signing spec + production reference
+ * `src/pacifica/signing.ts:prepareMessage()`):
+ *   1. Recursively sort all object keys alphabetically.
+ *   2. Compact JSON (`JSON.stringify(value)` — no whitespace).
+ *   3. Outer wrapper has the shape `{ <header fields>, "data": <payload> }`
+ *      where header is `{ type, timestamp, expiry_window }`. The `data` key
+ *      is sorted lexicographically alongside the header fields.
+ *
+ * The agent bind/unbind action types are documented in HypurrQuant_FE
+ * `PacificaPerpAdapter.ts` (production reference for HypurrQuant_FE; see
+ * project memory `hypurrquant_fe_reference.md`). We mirror their `bind_agent_wallet`
+ * and `unbind_agent_wallet` operation types here.
+ *
+ * Pure functions — no side effects, no fs/fetch/env reads.
+ */
+/** Default expiry window for signed Pacifica REST requests (ms). */
+export declare const DEFAULT_EXPIRY_WINDOW = 5000;
+export interface BindAgentMessageParams {
+    /** Master Solana base58 public key. */
+    account: string;
+    /** Agent Solana base58 public key. */
+    agentWallet: string;
+    /** Optional ms-epoch timestamp; defaults to `Date.now()`. */
+    timestamp?: number;
+    /** Optional expiry window (ms); defaults to DEFAULT_EXPIRY_WINDOW. */
+    expiryWindow?: number;
+}
+export interface UnbindAgentMessageParams {
+    /** Master Solana base58 public key. */
+    account: string;
+    /**
+     * Agent Solana base58 public key to unbind. Pass an empty string to
+     * unbind all agent wallets per Pacifica convention.
+     */
+    agentWallet: string;
+    timestamp?: number;
+    expiryWindow?: number;
+}
+export interface BuiltMessage {
+    /** Canonical JSON string ready for Ed25519 signing. */
+    canonicalJson: string;
+    /** Header captured for use in the REST envelope. */
+    header: {
+        type: string;
+        timestamp: number;
+        expiry_window: number;
+    };
+    /** Original payload object (caller supplies in REST envelope alongside signature). */
+    payload: Record<string, unknown>;
+}
+/**
+ * Build the canonical JSON for `bind_agent_wallet`.
+ *
+ * Wire shape (after sorting):
+ *   {"data":{"agent_wallet":"<base58>"},"expiry_window":5000,"timestamp":...,"type":"bind_agent_wallet"}
+ *
+ * The `account` field is supplied separately in the REST envelope; only the
+ * `agent_wallet` payload field is included inside the signed `data` block.
+ * This mirrors `buildSignedRequest()` in `src/pacifica/signing.ts`, which is
+ * the production reference for non-agent signed Pacifica requests.
+ */
+export declare function buildBindAgentMessage(params: BindAgentMessageParams): BuiltMessage;
+/**
+ * Build the canonical JSON for `unbind_agent_wallet`.
+ *
+ * Pacifica convention: empty `agent_wallet` string unbinds all agents; a
+ * specific base58 address unbinds just that agent.
+ */
+export declare function buildUnbindAgentMessage(params: UnbindAgentMessageParams): BuiltMessage;

package/dist/exchanges/pacifica-typed-data.js

@@ -0,0 +1,74 @@
+/**
+ * Pacifica agent-wallet signing builders (Phase 2c).
+ *
+ * Pacifica auth model — off-chain signed messages over Solana Ed25519.
+ * Reference: https://pacifica.gitbook.io/docs/api-documentation/api/signing.md
+ *
+ * Canonical JSON rules (from Pacifica signing spec + production reference
+ * `src/pacifica/signing.ts:prepareMessage()`):
+ *   1. Recursively sort all object keys alphabetically.
+ *   2. Compact JSON (`JSON.stringify(value)` — no whitespace).
+ *   3. Outer wrapper has the shape `{ <header fields>, "data": <payload> }`
+ *      where header is `{ type, timestamp, expiry_window }`. The `data` key
+ *      is sorted lexicographically alongside the header fields.
+ *
+ * The agent bind/unbind action types are documented in HypurrQuant_FE
+ * `PacificaPerpAdapter.ts` (production reference for HypurrQuant_FE; see
+ * project memory `hypurrquant_fe_reference.md`). We mirror their `bind_agent_wallet`
+ * and `unbind_agent_wallet` operation types here.
+ *
+ * Pure functions — no side effects, no fs/fetch/env reads.
+ */
+import { sortJsonKeys } from "../pacifica/signing.js";
+/** Default expiry window for signed Pacifica REST requests (ms). */
+export const DEFAULT_EXPIRY_WINDOW = 5_000;
+// ── Builders ─────────────────────────────────────────────────────────────
+/**
+ * Build the canonical JSON for `bind_agent_wallet`.
+ *
+ * Wire shape (after sorting):
+ *   {"data":{"agent_wallet":"<base58>"},"expiry_window":5000,"timestamp":...,"type":"bind_agent_wallet"}
+ *
+ * The `account` field is supplied separately in the REST envelope; only the
+ * `agent_wallet` payload field is included inside the signed `data` block.
+ * This mirrors `buildSignedRequest()` in `src/pacifica/signing.ts`, which is
+ * the production reference for non-agent signed Pacifica requests.
+ */
+export function buildBindAgentMessage(params) {
+    const timestamp = params.timestamp ?? Date.now();
+    const expiryWindow = params.expiryWindow ?? DEFAULT_EXPIRY_WINDOW;
+    const type = "bind_agent_wallet";
+    const payload = {
+        agent_wallet: params.agentWallet,
+    };
+    const header = { type, timestamp, expiry_window: expiryWindow };
+    const wrapped = { ...header, data: payload };
+    const sorted = sortJsonKeys(wrapped);
+    return {
+        canonicalJson: JSON.stringify(sorted),
+        header,
+        payload,
+    };
+}
+/**
+ * Build the canonical JSON for `unbind_agent_wallet`.
+ *
+ * Pacifica convention: empty `agent_wallet` string unbinds all agents; a
+ * specific base58 address unbinds just that agent.
+ */
+export function buildUnbindAgentMessage(params) {
+    const timestamp = params.timestamp ?? Date.now();
+    const expiryWindow = params.expiryWindow ?? DEFAULT_EXPIRY_WINDOW;
+    const type = "unbind_agent_wallet";
+    const payload = {
+        agent_wallet: params.agentWallet,
+    };
+    const header = { type, timestamp, expiry_window: expiryWindow };
+    const wrapped = { ...header, data: payload };
+    const sorted = sortJsonKeys(wrapped);
+    return {
+        canonicalJson: JSON.stringify(sorted),
+        header,
+        payload,
+    };
+}

package/dist/exchanges/pacifica.d.ts

@@ -2,22 +2,50 @@ import { Keypair } from "@solana/web3.js";
 import { PacificaClient, type Network } from "../pacifica/index.js";
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { SolanaSigner } from "../signer/index.js";
+import type { AgentMeta } from "../settings.js";
 export declare class PacificaAdapter implements ExchangeAdapter {
     readonly name = "pacifica";
     readonly chain = "solana";
     readonly aliases: readonly ["pac"];
     private client;
+    /** Tier 3: PK direct (constructor-supplied keypair). */
     private _solanaSigner;
+    /** Tier 2: OWS master signer (set via setSigner). */
+    private _masterSigner?;
+    /** Tier 1: agent OWS signer (Phase 2c). */
+    private _agentSigner?;
+    /** Tier 1 metadata. */
+    private _agentMeta?;
+    /** --no-agent bypass flag. */
+    private _useNoAgent;
+    /** True when adapter was constructed without a real PK (read-only). */
     private _hasRealKey;
+    /** Public Solana base58 of the active signer (`_resolveSigner().address`). */
     private account;
+    /** Bound `signMessage` for the active signer (Phase 2c routes through `_resolveSigner`). */
     private signMessage;
     private _marketsCache;
     private _marketsCacheTime;
     private static readonly CACHE_TTL;
     constructor(keypair: Keypair, network?: Network, builderCode?: string, hasRealKey?: boolean);
     private ensureSigner;
-    /** Inject an external Solana signer. */
+    /**
+     * Inject an external Solana signer (Tier 2 — OWS master).
+     * Backward-compatible: existing callers (e.g. `perp -e pacifica --ows ...`
+     * in `_initWithOws`) continue to work; the master signer is what
+     * `_resolveSigner()` falls back to when no agent is registered.
+     */
     setSigner(signer: SolanaSigner): void;
+    /** Tier 1: inject agent OWS Solana signer (Phase 2c). */
+    setAgentSigner(meta: AgentMeta, signer: SolanaSigner): void;
+    /** Bypass Tier 1 (agent) — used for `--no-agent` flag. */
+    setNoAgent(noAgent: boolean): void;
+    /** True only when ALL THREE tiers are unconfigured. */
+    get isReadOnly(): boolean;
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier(): "agent" | "master" | "pk" | null;
+    /** Resolve the active signer across three tiers. Mirrors AsterAdapter._resolveSigner. */
+    private _resolveSigner;
     /** Access the underlying Keypair (only available with LocalSolanaSigner). */
     get keypair(): Keypair;
     private _getPrices;