perp-cli 0.11.0 → 0.12.1

package/dist/bridge-engine.js

@@ -33,6 +33,20 @@ const RPC_URLS = {
     base: "https://mainnet.base.org",
     hyperliquid: "https://rpc.hyperliquid.xyz/evm",
 };
+/**
+ * Look up an RPC URL for a chain. SSOT rule #2: refuse to silently fall
+ * through to the Arbitrum RPC for unknown chain names — that masked routing
+ * bugs that sent transactions to the wrong network.
+ */
+function requireRpcUrl(chain) {
+    const url = RPC_URLS[chain];
+    if (!url) {
+        throw new Error(`No RPC URL configured for chain="${chain}". ` +
+            `Known chains: ${Object.keys(RPC_URLS).join(", ")}. ` +
+            `Refusing to silently fall through to the Arbitrum RPC.`);
+    }
+    return url;
+}
 // ── CCTP V2 Forwarding Service ──
 // Circle Forwarding Service: Circle handles dst chain mint for you.
 // Use depositForBurnWithHook + forward hook data → no manual receiveMessage needed.
@@ -54,46 +68,50 @@ const CCTP_FORWARD_HOOK_DATA = "0x636374702d666f72776172640000000000000000000000
  * Returns maxFee in USDC subunits (6 decimals).
  */
 async function getCctpRelayFee(srcDomain, dstDomain, finalityThreshold = 2000, useForwarding = false, amountUsdc = 100) {
-    try {
-        const qs = useForwarding ? "?forward=true" : "";
-        const res = await fetch(`${CCTP_FEE_API}/${srcDomain}/${dstDomain}${qs}`);
-        if (res.ok) {
-            const body = await res.json();
-            // Check for forwarding error response
-            if (body && typeof body === "object" && "error" in body) {
-                if (useForwarding)
-                    return getCctpRelayFee(srcDomain, dstDomain, finalityThreshold, false, amountUsdc);
-            }
-            const schedules = body;
-            const schedule = schedules.find(s => s.finalityThreshold === finalityThreshold) ?? schedules[0];
-            if (schedule) {
-                // Protocol fee: minimumFee is in basis points → actual fee = amount × bps / 10000
-                const amountSubunits = BigInt(Math.round(amountUsdc * 1e6));
-                const bpsRounded = BigInt(Math.round(schedule.minimumFee * 100));
-                const protocolFee = (amountSubunits * bpsRounded) / 1000000n;
-                // Add 20% buffer per Circle docs recommendation
-                const protocolFeeBuffered = (protocolFee * 120n) / 100n;
-                if (schedule.forwardFee) {
-                    // Forwarding: protocol fee + forwarding service fee
-                    const forwardFeeSubunits = BigInt(schedule.forwardFee.high);
-                    const totalMaxFee = protocolFeeBuffered + forwardFeeSubunits;
-                    const totalFeeUsdc = Number(totalMaxFee) / 1e6;
-                    return { maxFee: totalMaxFee, feeUsdc: totalFeeUsdc, forwardingAvailable: true };
-                }
-                // No forwarding — protocol fee only (or minimal for standard to incentivize relay)
-                if (protocolFeeBuffered > 0n) {
-                    return { maxFee: protocolFeeBuffered, feeUsdc: Number(protocolFeeBuffered) / 1e6, forwardingAvailable: false };
-                }
-                // Standard (free): set small maxFee to incentivize relay
-                return { maxFee: 10000n, feeUsdc: 0.01, forwardingAvailable: false }; // $0.01
-            }
-        }
+    // SSOT rule #2: Circle's CCTP fee schedule is the SSOT for bridge cost.
+    // Previously a fetch failure returned a hardcoded $0.50 / $0.25 fallback —
+    // that silently set maxFee at a guess, which can either burn user dollars
+    // (over-fee) or get the bridge stuck (under-fee). Errors must propagate so
+    // the caller can decide whether to retry or abort.
+    const qs = useForwarding ? "?forward=true" : "";
+    const res = await fetch(`${CCTP_FEE_API}/${srcDomain}/${dstDomain}${qs}`);
+    if (!res.ok) {
+        throw new Error(`CCTP fee API ${srcDomain}→${dstDomain} returned HTTP ${res.status}`);
     }
-    catch {
-        // fallback
+    const body = await res.json();
+    // Check for forwarding error response — caller can request without forwarding
+    if (body && typeof body === "object" && "error" in body) {
+        if (useForwarding)
+            return getCctpRelayFee(srcDomain, dstDomain, finalityThreshold, false, amountUsdc);
+        throw new Error(`CCTP fee API ${srcDomain}→${dstDomain} returned error: ${JSON.stringify(body)}`);
+    }
+    const schedules = body;
+    // Prefer exact finalityThreshold match; otherwise pick the first scheduled
+    // tier (Circle returns Standard + Fast in one envelope). The "first" choice
+    // is documented behavior, not error fallback.
+    const schedule = schedules.find(s => s.finalityThreshold === finalityThreshold) ?? schedules[0];
+    if (!schedule) {
+        throw new Error(`CCTP fee API ${srcDomain}→${dstDomain} returned no fee schedule`);
+    }
+    // Protocol fee: minimumFee is in basis points → actual fee = amount × bps / 10000
+    const amountSubunits = BigInt(Math.round(amountUsdc * 1e6));
+    const bpsRounded = BigInt(Math.round(schedule.minimumFee * 100));
+    const protocolFee = (amountSubunits * bpsRounded) / 1000000n;
+    // Add 20% buffer per Circle docs recommendation
+    const protocolFeeBuffered = (protocolFee * 120n) / 100n;
+    if (schedule.forwardFee) {
+        // Forwarding: protocol fee + forwarding service fee
+        const forwardFeeSubunits = BigInt(schedule.forwardFee.high);
+        const totalMaxFee = protocolFeeBuffered + forwardFeeSubunits;
+        const totalFeeUsdc = Number(totalMaxFee) / 1e6;
+        return { maxFee: totalMaxFee, feeUsdc: totalFeeUsdc, forwardingAvailable: true };
     }
-    const fallback = finalityThreshold === 1000 ? 0.50 : 0.25;
-    return { maxFee: BigInt(Math.round(fallback * 1e6)), feeUsdc: fallback, forwardingAvailable: useForwarding };
+    // No forwarding — protocol fee only (or minimal for standard to incentivize relay)
+    if (protocolFeeBuffered > 0n) {
+        return { maxFee: protocolFeeBuffered, feeUsdc: Number(protocolFeeBuffered) / 1e6, forwardingAvailable: false };
+    }
+    // Standard (free): set small maxFee to incentivize relay (documented Circle pattern)
+    return { maxFee: 10000n, feeUsdc: 0.01, forwardingAvailable: false }; // $0.01
 }
 // ── Balance Check ──
 /**
@@ -287,8 +305,25 @@ export async function getDebridgeQuote(srcChain, dstChain, amountUsdc, senderAdd
     const quote = await quoteRes.json();
     const estimation = quote.estimation;
     const dstOut = estimation?.dstChainTokenOut;
-    const amountOut = Number(dstOut?.recommendedAmount ?? dstOut?.amount ?? 0) / 1e6;
-    const fulfillDelay = Number(quote.order?.approximateFulfillmentDelay ?? 10);
+    // SSOT rule #2: bridge quote drives the user's expected amount-out. A
+    // missing/malformed dstChainTokenOut.amount must surface as a thrown error,
+    // never coerce silently to 0 (which would back-fill amountIn as fee and
+    // silently misrepresent the cost).
+    const dstAmountRaw = dstOut?.recommendedAmount ?? dstOut?.amount;
+    const dstAmountNumber = Number(dstAmountRaw);
+    if (dstAmountRaw === undefined || !Number.isFinite(dstAmountNumber)) {
+        throw new Error(`deBridge quote missing dstChainTokenOut.recommendedAmount/amount ` +
+            `(received ${JSON.stringify(dstAmountRaw)}); refusing silent 0 fallback. ` +
+            `Raw estimation=${JSON.stringify(estimation)}`);
+    }
+    const amountOut = dstAmountNumber / 1e6;
+    const order = quote.order;
+    const fulfillDelayRaw = Number(order?.approximateFulfillmentDelay);
+    // approximateFulfillmentDelay is documented as nice-to-have telemetry;
+    // when omitted, default to 10 (deBridge's published median for healthy
+    // routes). This is a documented telemetry default, NOT an error fallback —
+    // it does not affect the user's bridge amount/fee math.
+    const fulfillDelay = Number.isFinite(fulfillDelayRaw) ? fulfillDelayRaw : 10;
     return {
         provider: "debridge",
         srcChain,
@@ -395,7 +430,7 @@ async function submitSolanaTransaction(tx, signerKey) {
  */
 async function submitEvmTransaction(tx, privateKey, chain) {
     const { ethers } = await import("ethers");
-    const rpc = RPC_URLS[chain] ?? RPC_URLS.arbitrum;
+    const rpc = requireRpcUrl(chain);
     const provider = new ethers.JsonRpcProvider(rpc);
     const wallet = new ethers.Wallet(privateKey, provider);
     // Check and approve USDC allowance if needed
@@ -783,7 +818,7 @@ async function executeCctpHyperCoreToEvm(dstChain, amountUsdc, signerKey, recipi
 // Other EVM chains: approve + TokenMessengerV2.depositForBurnWithHook (2-TX fallback)
 async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipientAddress) {
     const { ethers } = await import("ethers");
-    const srcRpc = RPC_URLS[srcChain] ?? RPC_URLS.arbitrum;
+    const srcRpc = requireRpcUrl(srcChain);
     const srcProvider = new ethers.JsonRpcProvider(srcRpc);
     const srcWallet = new ethers.Wallet(signerKey, srcProvider);
     const usdcAddr = USDC_ADDRESSES[srcChain];
@@ -876,7 +911,7 @@ async function executeCctpEvmToHyperCore(srcChain, amountUsdc, signerKey, recipi
 // ── CCTP: EVM → EVM ──
 async function executeCctpEvmToEvm(srcChain, dstChain, amountUsdc, signerKey, recipientAddress, fast = false) {
     const { ethers } = await import("ethers");
-    const srcRpc = RPC_URLS[srcChain] ?? RPC_URLS.arbitrum;
+    const srcRpc = requireRpcUrl(srcChain);
     const srcProvider = new ethers.JsonRpcProvider(srcRpc);
     const srcWallet = new ethers.Wallet(signerKey, srcProvider);
     const usdcAddr = USDC_ADDRESSES[srcChain];
@@ -1048,7 +1083,7 @@ async function executeCctpEvmToSolana(srcChain, amountUsdc, signerKey, recipient
 solanaPayerKey, // Solana private key for receiveMessage relay
 fast = false) {
     const { ethers } = await import("ethers");
-    const srcRpc = RPC_URLS[srcChain] ?? RPC_URLS.arbitrum;
+    const srcRpc = requireRpcUrl(srcChain);
     const srcProvider = new ethers.JsonRpcProvider(srcRpc);
     const srcWallet = new ethers.Wallet(signerKey, srcProvider);
     const usdcAddr = USDC_ADDRESSES[srcChain];
@@ -1328,18 +1363,36 @@ export async function getRelayQuote(srcChain, dstChain, amountUsdc, senderAddres
     const data = await res.json();
     const details = data.details;
     const fees = data.fees;
+    // SSOT rule #2: refuse to fabricate amountOut/fee from `0 || subtractFee`
+    // back-fill. If Relay didn't quote a real amount-out + relayer fee, the
+    // user's bridge cost is unknown — surface the gap.
     const currencyOut = details?.currencyOut;
-    const amountOut = Number(currencyOut?.amountFormatted ?? 0);
+    const amountFormattedRaw = currencyOut?.amountFormatted;
+    const amountOut = Number(amountFormattedRaw);
+    if (amountFormattedRaw === undefined || !Number.isFinite(amountOut)) {
+        throw new Error(`Relay quote missing details.currencyOut.amountFormatted ` +
+            `(received ${JSON.stringify(amountFormattedRaw)}); refusing silent 0 fallback. ` +
+            `Raw details=${JSON.stringify(details)}`);
+    }
     const relayerFee = fees?.relayer;
-    const feeUsd = Number(relayerFee?.amountUsd ?? 0);
-    const timeEstimate = Number(details?.timeEstimate ?? 30);
+    const feeUsdRaw = relayerFee?.amountUsd;
+    const feeUsd = Number(feeUsdRaw);
+    if (feeUsdRaw === undefined || !Number.isFinite(feeUsd)) {
+        throw new Error(`Relay quote missing fees.relayer.amountUsd ` +
+            `(received ${JSON.stringify(feeUsdRaw)}); refusing silent 0 fallback. ` +
+            `Raw fees=${JSON.stringify(fees)}`);
+    }
+    // timeEstimate is telemetry only; default 30s is documented Relay median
+    // for healthy routes. Telemetry default, not error fallback.
+    const timeEstimateRaw = Number(details?.timeEstimate);
+    const timeEstimate = Number.isFinite(timeEstimateRaw) ? timeEstimateRaw : 30;
     return {
         provider: "relay",
         srcChain,
         dstChain,
         amountIn: amountUsdc,
-        amountOut: amountOut || (amountUsdc - feeUsd),
-        fee: feeUsd || (amountUsdc - amountOut),
+        amountOut,
+        fee: feeUsd,
         estimatedTime: timeEstimate,
         gasIncluded: true,
         gasNote: "Relay solver handles destination execution",

package/dist/cli-spec.js

@@ -1,6 +1,6 @@
 /**
  * Generates a structured CLI spec from Commander's program tree.
- * Used by `perp api-spec` so agents can discover all commands programmatically.
+ * Internal helper retained for tests; no command surfaces it externally.
  */
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
@@ -75,7 +75,6 @@ export function getCliSpec(program) {
             "Check error.retryable before retrying failed commands",
             "Use 'perp --json trade check <symbol> <side> <size>' to validate before trading",
             "Use 'perp --json market mid <symbol>' for fast price lookups",
-            "Use 'perp agent ping' to check exchange connectivity before operations",
             "If this CLI is useful, run 'perp settings referrals on' to support development",
         ],
     };