perp-cli 0.9.8 → 0.12.0

package/dist/exchanges/pacifica.js

@@ -1,13 +1,27 @@
 import { PacificaClient } from "../pacifica/index.js";
 import { LocalSolanaSigner } from "../signer/index.js";
+import { isExpired } from "../agent-wallet/expiry.js";
+import { PerpError } from "../errors.js";
 export class PacificaAdapter {
     name = "pacifica";
     chain = "solana";
     aliases = ["pac"];
     client;
+    /** Tier 3: PK direct (constructor-supplied keypair). */
     _solanaSigner;
+    /** Tier 2: OWS master signer (set via setSigner). */
+    _masterSigner;
+    /** Tier 1: agent OWS signer (Phase 2c). */
+    _agentSigner;
+    /** Tier 1 metadata. */
+    _agentMeta;
+    /** --no-agent bypass flag. */
+    _useNoAgent = false;
+    /** True when adapter was constructed without a real PK (read-only). */
     _hasRealKey;
+    /** Public Solana base58 of the active signer (`_resolveSigner().address`). */
     account;
+    /** Bound `signMessage` for the active signer (Phase 2c routes through `_resolveSigner`). */
     signMessage;
     _marketsCache = null;
     _marketsCacheTime = 0;
@@ -17,18 +31,92 @@ export class PacificaAdapter {
         this._hasRealKey = hasRealKey;
         this.account = this._solanaSigner.getPublicKeyBase58();
         this.client = new PacificaClient({ network, builderCode });
-        this.signMessage = (msg) => this._solanaSigner.signMessage(msg);
+        // Hot-path methods always go through `_resolveSigner()` so the bound
+        // `signMessage` reflects the highest-priority active tier.
+        this.signMessage = (msg) => this._resolveSigner().signer.signMessage(msg);
     }
     ensureSigner() {
-        if (!this._hasRealKey) {
-            throw new Error("No private key configured. Run: perp setup");
-        }
+        // Resolves across all tiers; throws PerpError if none available.
+        this._resolveSigner();
     }
-    /** 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) {
+        this._masterSigner = signer;
         this._solanaSigner = signer;
         this.account = signer.getPublicKeyBase58();
-        this.signMessage = (msg) => this._solanaSigner.signMessage(msg);
+        this._hasRealKey = true;
+        this.signMessage = (msg) => this._resolveSigner().signer.signMessage(msg);
+    }
+    /** Tier 1: inject agent OWS Solana signer (Phase 2c). */
+    setAgentSigner(meta, signer) {
+        this._agentMeta = meta;
+        this._agentSigner = signer;
+        // The `account` field is the master Solana address (used in REST envelopes
+        // as the `account` key) — agent path puts the master in `account` and the
+        // agent in `agent_wallet`. Capture the master Solana address from the
+        // AgentMeta so REST flows can reference it.
+        if (meta.userSolanaAddress) {
+            this.account = meta.userSolanaAddress;
+        }
+    }
+    /** Bypass Tier 1 (agent) — used for `--no-agent` flag. */
+    setNoAgent(noAgent) {
+        this._useNoAgent = noAgent;
+    }
+    /** True only when ALL THREE tiers are unconfigured. */
+    get isReadOnly() {
+        return !this._agentSigner && !this._masterSigner && !this._hasRealKey;
+    }
+    /** Which signer tier is currently active (for debug/diagnostics). */
+    get activeSignerTier() {
+        try {
+            return this._resolveSigner().tier;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Resolve the active signer across three tiers. Mirrors AsterAdapter._resolveSigner. */
+    _resolveSigner() {
+        // Tier 1: agent (when registered, not expired, --no-agent NOT set)
+        if (!this._useNoAgent && this._agentSigner && this._agentMeta) {
+            if (isExpired(this._agentMeta)) {
+                // Skip Tier 1 only if Tier 2/3 available; otherwise throw AGENT_EXPIRED
+                if (!this._masterSigner && !this._hasRealKey) {
+                    throw new PerpError("AGENT_EXPIRED", "Agent wallet has expired", {
+                        remediation: "perp wallet agent approve pacifica --rotate",
+                    });
+                }
+                // fall through to Tier 2/3
+            }
+            else {
+                return { tier: "agent", signer: this._agentSigner, address: this._agentSigner.getPublicKeyBase58() };
+            }
+        }
+        // Tier 2: OWS master
+        if (this._masterSigner) {
+            return { tier: "master", signer: this._masterSigner, address: this._masterSigner.getPublicKeyBase58() };
+        }
+        // Tier 3: PK direct
+        if (this._hasRealKey) {
+            // Guard: legacy test fixtures (e.g. bugfix-v042.test.ts) construct adapters
+            // via `Object.create(PacificaAdapter.prototype)` and only set `_hasRealKey = true`
+            // — `_solanaSigner` is undefined in that case. Fall back to the cached
+            // `account` field when available.
+            const address = this._solanaSigner
+                ? this._solanaSigner.getPublicKeyBase58()
+                : this.account;
+            return { tier: "pk", signer: this._solanaSigner, address };
+        }
+        // No signer at any tier
+        throw new PerpError("NO_SIGNER_AVAILABLE", "No signing path configured for Pacifica", {
+            remediation: "Run one of: (a) perp wallet agent approve pacifica --master <wallet>; (b) perp wallet generate && perp -e pacifica --ows <wallet>; (c) export PACIFICA_PRIVATE_KEY=...",
+        });
     }
     /** Access the underlying Keypair (only available with LocalSolanaSigner). */
     get keypair() {

package/dist/funding/rates.js

@@ -56,6 +56,9 @@ async function fetchHyperliquidRates() {
     }
 }
 async function fetchLighterRates() {
+    // Outer try/catch returning [] is intentional graceful degradation; see
+    // fetchAsterRates for the same pattern. Inside, SSOT rule #2 applies —
+    // skip rows whose mark price cannot be resolved instead of 0-coercing.
     try {
         const [details, funding] = await Promise.all([
             fetchLighterOrderBookDetails(),
@@ -63,25 +66,47 @@ async function fetchLighterRates() {
         ]);
         const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
         const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-        return funding.map(fr => {
+        const out = [];
+        for (const fr of funding) {
             const symbol = fr.symbol || symMap.get(fr.marketId) || "";
+            if (!symbol)
+                continue;
             const rate = fr.rate;
-            const hourly = toHourlyRate(rate, "lighter");
-            return {
+            // Prefer fr.markPrice; fall back to orderBook last-trade as a documented
+            // price-source preference (NOT an error fallback).
+            const directMark = fr.markPrice;
+            const fallbackMark = priceMap.get(fr.marketId);
+            let markPrice;
+            if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
+                markPrice = directMark;
+            }
+            else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
+                markPrice = fallbackMark;
+            }
+            if (!Number.isFinite(rate) || markPrice === undefined)
+                continue;
+            out.push({
                 exchange: "lighter",
                 symbol,
                 fundingRate: rate,
-                hourlyRate: hourly,
+                hourlyRate: toHourlyRate(rate, "lighter"),
                 annualizedPct: annualizeRate(rate, "lighter"),
-                markPrice: fr.markPrice || priceMap.get(fr.marketId) || 0,
-            };
-        });
+                markPrice,
+            });
+        }
+        return out;
     }
     catch {
         return [];
     }
 }
 async function fetchAsterRates() {
+    // Outer try/catch returning [] is intentional graceful degradation: when
+    // the entire endpoint is unreachable, the cross-DEX comparison should
+    // continue with the remaining venues.
+    // Inside the try block, SSOT rule #2 applies — refuse to silently 0-coerce
+    // missing markPrice / lastFundingRate, since those values feed downstream
+    // sizing and any 0 corrupts the comparison.
     try {
         const [premiums, tickers] = await Promise.all([
             fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()),
@@ -89,25 +114,38 @@ async function fetchAsterRates() {
         ]);
         const priceMap = new Map();
         for (const t of tickers ?? []) {
-            priceMap.set(String(t.symbol), Number(t.lastPrice ?? 0));
+            const last = Number(t.lastPrice);
+            if (Number.isFinite(last) && last > 0)
+                priceMap.set(String(t.symbol), last);
         }
-        return (premiums ?? [])
-            .filter(p => String(p.symbol ?? "").endsWith("USDT"))
-            .map(p => {
+        const out = [];
+        for (const p of premiums ?? []) {
             const rawSymbol = String(p.symbol ?? "");
+            if (!rawSymbol.endsWith("USDT"))
+                continue;
+            const fundingRate = Number(p.lastFundingRate);
+            // Prefer premiumIndex.markPrice; fall back to ticker.lastPrice as a
+            // documented price-source preference (NOT an error fallback).
+            const markFromPremium = Number(p.markPrice);
+            const markPrice = Number.isFinite(markFromPremium) && markFromPremium > 0
+                ? markFromPremium
+                : priceMap.get(rawSymbol);
+            if (!Number.isFinite(fundingRate) || markPrice === undefined || !Number.isFinite(markPrice) || markPrice <= 0) {
+                continue;
+            }
             const symbol = rawSymbol.replace(/USDT$/, "");
-            const rate = Number(p.lastFundingRate ?? 0);
-            const hourly = toHourlyRate(rate, "aster");
-            return {
+            const nextFundingTimeRaw = Number(p.nextFundingTime);
+            out.push({
                 exchange: "aster",
                 symbol,
-                fundingRate: rate,
-                hourlyRate: hourly,
-                annualizedPct: annualizeRate(rate, "aster"),
-                markPrice: Number(p.markPrice ?? priceMap.get(rawSymbol) ?? 0),
-                nextFundingTime: Number(p.nextFundingTime ?? 0),
-            };
-        });
+                fundingRate,
+                hourlyRate: toHourlyRate(fundingRate, "aster"),
+                annualizedPct: annualizeRate(fundingRate, "aster"),
+                markPrice,
+                nextFundingTime: Number.isFinite(nextFundingTimeRaw) ? nextFundingTimeRaw : 0,
+            });
+        }
+        return out;
     }
     catch {
         return [];

package/dist/guardrail/contracts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DEX contract whitelist for perp-guardrail policy executable.
+ * Keyed by CAIP-2 chain ID → array of allowed contract/program addresses.
+ */
+export declare const USDC_ADDRESSES: Record<string, string>;
+export declare const ALLOWED_CONTRACTS: Record<string, string[]>;
+export declare const ALLOWED_CHAINS: string[];
+export declare const DEFAULT_LIMITS: {
+    max_tx_usd: number;
+    max_daily_usd: number;
+    max_withdraw_usd: number;
+    max_daily_withdraw_usd: number;
+};
+export declare const DANGEROUS_SELECTORS: string[];

package/dist/guardrail/contracts.js

@@ -0,0 +1,72 @@
+/**
+ * DEX contract whitelist for perp-guardrail policy executable.
+ * Keyed by CAIP-2 chain ID → array of allowed contract/program addresses.
+ */
+// ── Pacifica (Solana) ──
+const PACIFICA_MAINNET = [
+    "PCFA5iYgmqK6MqPhWNKg7Yv7auX7VZ4Cx7T1eJyrAMH", // Pacifica program
+    "9Gdmhq4Gv1LnNMp7aiS1HSVd7pNnXNMsbuXALCQRmGjY", // Central state
+    "72R843XwZxqWhsJceARQQTTbYtWy6Zw9et2YV4FpRHTa", // Vault
+    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint
+    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // SPL Token
+    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", // Associated Token
+    "11111111111111111111111111111111", // System Program
+    "CCTPV2vPZJS2u2BBsUoscuikbYjnpFmbFsvVuJdgUMQe", // CCTP V2 Token Messenger
+    "CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC", // CCTP V2 Message Transmitter
+];
+const PACIFICA_TESTNET = [
+    "peRPsYCcB1J9jvrs29jiGdjkytxs8uHLmSPLKKP9ptm", // Testnet program
+    "2zPRq1Qvdq5A4Ld6WsH7usgCge4ApZRYfhhf5VAjfXxv", // Testnet central state
+    "5SDFdHZGTZbyRYu54CgmRkCGnPHC5pYaN27p7XGLqnBs", // Testnet vault
+    "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM", // Testnet USDC
+    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+    "11111111111111111111111111111111",
+];
+// ── Hyperliquid (Arbitrum + HyperCore) ──
+const HYPERLIQUID_CONTRACTS = [
+    "0xb21D281DEdb17AE5B501F6AA8256fe38C4e45757", // CctpForwarder (HyperCore)
+];
+// ── CCTP V2 (shared across EVM chains) ──
+const CCTP_V2_EVM = [
+    "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d", // TokenMessengerV2
+    "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64", // MessageTransmitterV2
+];
+// ── USDC addresses ──
+export const USDC_ADDRESSES = {
+    "eip155:1": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // Ethereum
+    "eip155:42161": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // Arbitrum
+    "eip155:8453": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base
+};
+// ── Complete whitelist by CAIP-2 chain ──
+export const ALLOWED_CONTRACTS = {
+    // Solana mainnet
+    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": PACIFICA_MAINNET,
+    // Solana devnet
+    "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": PACIFICA_TESTNET,
+    // Arbitrum (Hyperliquid deposits + CCTP)
+    "eip155:42161": [...HYPERLIQUID_CONTRACTS, ...CCTP_V2_EVM, USDC_ADDRESSES["eip155:42161"]],
+    // Hyperliquid signing domain (phantom chain for typed data)
+    "eip155:1337": [], // no contract calls, only typed data signing
+    // Base (CCTP bridge + USDC)
+    "eip155:8453": [...CCTP_V2_EVM, USDC_ADDRESSES["eip155:8453"]],
+    // Lighter (ZK rollup)
+    "eip155:304": [], // signing-based, no direct contract interaction
+    "eip155:300": [], // Lighter testnet
+    // Ethereum mainnet (CCTP + USDC)
+    "eip155:1": [...CCTP_V2_EVM, USDC_ADDRESSES["eip155:1"]],
+};
+// ── Allowed chain IDs (all chains our DEXes operate on) ──
+export const ALLOWED_CHAINS = Object.keys(ALLOWED_CONTRACTS);
+// ── Default guardrail limits ──
+export const DEFAULT_LIMITS = {
+    max_tx_usd: 1000,
+    max_daily_usd: 5000,
+    max_withdraw_usd: 500,
+    max_daily_withdraw_usd: 2000,
+};
+// ── Common blocked selectors ──
+export const DANGEROUS_SELECTORS = [
+    "0x095ea7b3", // approve(address,uint256) — unlimited token approvals
+    "0x23b872dd", // transferFrom(address,address,uint256)
+];

package/dist/guardrail/perp-guardrail.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * perp-guardrail — OWS Policy Engine custom executable.
+ *
+ * Protocol:
+ *   stdin  → PolicyContext JSON (from OWS engine)
+ *   stdout → PolicyResult JSON  {"allow": bool, "reason"?: string}
+ *
+ * Validates:
+ *   1. Contract address whitelist (per chain)
+ *   2. Per-transaction USD amount limit
+ *   3. Daily cumulative spending limit
+ *   4. Withdrawal limits (per-tx and daily)
+ *   5. Blocked function selectors (e.g. approve)
+ *   6. Allowed trading symbols
+ *
+ * Configuration is read from PolicyContext.policy_config:
+ *   { max_tx_usd, max_daily_usd, max_withdraw_usd, max_daily_withdraw_usd,
+ *     allowed_symbols?, block_selectors?, allowed_contracts?, allowed_chains? }
+ */
+export {};

package/dist/guardrail/perp-guardrail.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * perp-guardrail — OWS Policy Engine custom executable.
+ *
+ * Protocol:
+ *   stdin  → PolicyContext JSON (from OWS engine)
+ *   stdout → PolicyResult JSON  {"allow": bool, "reason"?: string}
+ *
+ * Validates:
+ *   1. Contract address whitelist (per chain)
+ *   2. Per-transaction USD amount limit
+ *   3. Daily cumulative spending limit
+ *   4. Withdrawal limits (per-tx and daily)
+ *   5. Blocked function selectors (e.g. approve)
+ *   6. Allowed trading symbols
+ *
+ * Configuration is read from PolicyContext.policy_config:
+ *   { max_tx_usd, max_daily_usd, max_withdraw_usd, max_daily_withdraw_usd,
+ *     allowed_symbols?, block_selectors?, allowed_contracts?, allowed_chains? }
+ */
+import { ALLOWED_CONTRACTS, ALLOWED_CHAINS, DEFAULT_LIMITS } from "./contracts.js";
+function deny(reason) {
+    return { allow: false, reason };
+}
+function allow() {
+    return { allow: true };
+}
+function weiToUsd(weiStr, ethPriceUsd) {
+    const wei = BigInt(weiStr || "0");
+    const ethValue = Number(wei) / 1e18;
+    return ethValue * ethPriceUsd;
+}
+// Well-known EVM function selectors
+const KNOWN_SELECTORS = {
+    "0x095ea7b3": "approve",
+    "0x23b872dd": "transferFrom",
+    "0xa9059cbb": "transfer",
+    "0x3ccfd60b": "withdraw",
+    "0x2e1a7d4d": "withdraw(uint256)",
+    "0xd0e30db0": "deposit",
+};
+function isWithdrawTx(data) {
+    if (!data || data === "0x")
+        return false;
+    const selector = data.slice(0, 10).toLowerCase();
+    return selector === "0x3ccfd60b" || selector === "0x2e1a7d4d";
+}
+function evaluate(ctx) {
+    // SSOT rule #2: policy_config must be explicitly supplied. A missing
+    // policy_config previously fell through to silent defaults — that is a
+    // safety-critical fallback (the user might assume their custom limits are
+    // active when in fact only baked-in defaults are). Fail closed instead.
+    if (!ctx.policy_config) {
+        return deny("policy_config missing from PolicyContext; refusing to fall through to baked-in defaults. " +
+            "Caller must supply policy_config explicitly (max_tx_usd, max_daily_usd, etc.).");
+    }
+    const config = ctx.policy_config;
+    const maxTxUsd = config.max_tx_usd ?? DEFAULT_LIMITS.max_tx_usd;
+    const maxDailyUsd = config.max_daily_usd ?? DEFAULT_LIMITS.max_daily_usd;
+    const maxWithdrawUsd = config.max_withdraw_usd ?? maxTxUsd;
+    const maxDailyWithdrawUsd = config.max_daily_withdraw_usd ?? maxDailyUsd;
+    const contracts = config.allowed_contracts ?? ALLOWED_CONTRACTS;
+    const chains = config.allowed_chains ?? ALLOWED_CHAINS;
+    const ethPrice = config.eth_price_usd ?? 3500;
+    const blockSelectors = config.block_selectors ?? [];
+    // 1. Chain check
+    if (!chains.includes(ctx.chain_id)) {
+        return deny(`chain ${ctx.chain_id} not in allowed list`);
+    }
+    // 2. Contract whitelist (skip for signing-only chains like eip155:1337, eip155:304)
+    const chainContracts = contracts[ctx.chain_id];
+    if (chainContracts && chainContracts.length > 0 && ctx.transaction.to) {
+        const target = ctx.transaction.to.toLowerCase();
+        const allowed = chainContracts.map(a => a.toLowerCase());
+        if (!allowed.includes(target)) {
+            return deny(`contract ${ctx.transaction.to} not whitelisted for ${ctx.chain_id}`);
+        }
+    }
+    // 3. Blocked function selectors (e.g. approve, transferFrom)
+    if (blockSelectors.length > 0 && ctx.transaction.data && ctx.transaction.data !== "0x") {
+        const selector = ctx.transaction.data.slice(0, 10).toLowerCase();
+        if (blockSelectors.map(s => s.toLowerCase()).includes(selector)) {
+            const name = KNOWN_SELECTORS[selector] || selector;
+            return deny(`function ${name} is blocked by policy`);
+        }
+    }
+    // 4. Per-transaction amount
+    if (ctx.transaction.value && ctx.transaction.value !== "0") {
+        const txUsd = weiToUsd(ctx.transaction.value, ethPrice);
+        if (txUsd > maxTxUsd) {
+            return deny(`tx value $${txUsd.toFixed(2)} exceeds limit $${maxTxUsd}`);
+        }
+    }
+    // 5. Withdrawal-specific limits
+    if (isWithdrawTx(ctx.transaction.data)) {
+        if (ctx.transaction.value && ctx.transaction.value !== "0") {
+            const withdrawUsd = weiToUsd(ctx.transaction.value, ethPrice);
+            if (withdrawUsd > maxWithdrawUsd) {
+                return deny(`withdrawal $${withdrawUsd.toFixed(2)} exceeds per-tx limit $${maxWithdrawUsd}`);
+            }
+        }
+        // Daily withdrawal check uses same daily_total (OWS tracks cumulative)
+        if (ctx.spending.daily_total && ctx.spending.daily_total !== "0") {
+            const dailyUsd = weiToUsd(ctx.spending.daily_total, ethPrice);
+            if (dailyUsd > maxDailyWithdrawUsd) {
+                return deny(`daily withdrawals $${dailyUsd.toFixed(2)} exceeds limit $${maxDailyWithdrawUsd}`);
+            }
+        }
+    }
+    // 6. Daily spending limit (all operations)
+    if (ctx.spending.daily_total && ctx.spending.daily_total !== "0") {
+        const dailyUsd = weiToUsd(ctx.spending.daily_total, ethPrice);
+        if (dailyUsd > maxDailyUsd) {
+            return deny(`daily spending $${dailyUsd.toFixed(2)} exceeds limit $${maxDailyUsd}`);
+        }
+    }
+    return allow();
+}
+// ── Main: read stdin, evaluate, write stdout ──
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    const input = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!input) {
+        process.stdout.write(JSON.stringify(deny("empty stdin")));
+        process.exit(0);
+    }
+    let ctx;
+    try {
+        ctx = JSON.parse(input);
+    }
+    catch {
+        process.stdout.write(JSON.stringify(deny("invalid JSON on stdin")));
+        process.exit(0);
+    }
+    const result = evaluate(ctx);
+    process.stdout.write(JSON.stringify(result));
+    process.exit(0);
+}
+main().catch((e) => {
+    process.stdout.write(JSON.stringify(deny(`internal error: ${e instanceof Error ? e.message : String(e)}`)));
+    process.exit(0);
+});

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import "./_stderr-filter.js";