@persistenceone/bridgekitty 0.3.0

package/dist/utils/gas-estimator.js

@@ -0,0 +1,340 @@
+/**
+ * Gas cost estimator for backends that don't provide gas fee estimates.
+ * Uses chain-aware gas unit estimates + live gas price + native token USD price.
+ *
+ * Also provides centralized RPC access with multi-endpoint failover:
+ *   getChainRpcUrls(chainId) — list of RPC URLs (env override → public defaults)
+ *   getChainRpcUrl(chainId)  — first URL only (backward compat, no failover)
+ *   getProvider(chainId)     — JsonRpcProvider with automatic failover across all RPCs
+ *
+ * Strategy:
+ * 1. Chain-aware gas units per backend type (L1 vs L2 differentiation)
+ * 2. Live gas price via eth_gasPrice RPC (cached 30s)
+ * 3. Native token USD price via LI.FI /v1/token or hardcoded fallback (cached 5min)
+ * 4. Calculate: gasUnits × gasPrice × nativeTokenPriceUSD
+ * 5. If we can't reliably estimate → return null (displayed as "unknown")
+ */
+import { ethers } from "ethers";
+const GAS_PRICE_CACHE_TTL_MS = 30_000; // 30 seconds
+const TOKEN_PRICE_CACHE_TTL_MS = 300_000; // 5 minutes
+const RPC_TIMEOUT_MS = 5_000;
+const LIFI_TIMEOUT_MS = 5_000;
+// Chain ID → env var name mapping for RPC overrides
+const CHAIN_RPC_ENV_KEYS = {
+    1: "RPC_ETHEREUM",
+    10: "RPC_OPTIMISM",
+    56: "RPC_BSC",
+    137: "RPC_POLYGON",
+    42161: "RPC_ARBITRUM",
+    43114: "RPC_AVALANCHE",
+    8453: "RPC_BASE",
+    59144: "RPC_LINEA",
+    534352: "RPC_SCROLL",
+    324: "RPC_ZKSYNC",
+    5000: "RPC_MANTLE",
+    81457: "RPC_BLAST",
+};
+// Default public RPCs per chain with failover (used when env var not set)
+// Ordered by measured latency (fastest first). Sourced from chainlist.org.
+// Base & BSC have extra endpoints since they're critical for XPRT farming.
+const DEFAULT_CHAIN_RPCS = {
+    1: ["https://eth.drpc.org", "https://1rpc.io/eth", "https://ethereum-rpc.publicnode.com"],
+    10: ["https://optimism.drpc.org", "https://1rpc.io/op", "https://optimism-rpc.publicnode.com"],
+    56: ["https://1rpc.io/bnb", "https://bsc.drpc.org", "https://bsc-rpc.publicnode.com", "https://bsc-dataseed1.defibit.io", "https://bsc-dataseed2.defibit.io"],
+    137: ["https://polygon.drpc.org", "https://1rpc.io/matic", "https://polygon-bor-rpc.publicnode.com"],
+    42161: ["https://arbitrum.drpc.org", "https://1rpc.io/arb", "https://arbitrum-one-rpc.publicnode.com"],
+    43114: ["https://avax.drpc.org", "https://1rpc.io/avax/c", "https://avalanche-c-chain-rpc.publicnode.com"],
+    8453: ["https://mainnet.base.org", "https://1rpc.io/base", "https://gateway.tenderly.co/public/base", "https://base-rpc.publicnode.com", "https://base.drpc.org"],
+    59144: ["https://linea.drpc.org", "https://1rpc.io/linea", "https://linea-rpc.publicnode.com"],
+    534352: ["https://scroll.drpc.org", "https://1rpc.io/scroll", "https://scroll-rpc.publicnode.com"],
+    324: ["https://zksync.drpc.org", "https://1rpc.io/zksync2-era", "https://zksync-era-rpc.publicnode.com"],
+    5000: ["https://mantle.drpc.org", "https://1rpc.io/mantle", "https://mantle-rpc.publicnode.com"],
+    81457: ["https://blast.drpc.org", "https://blast-rpc.publicnode.com"],
+};
+/** M-3: Validate that an RPC URL uses HTTPS (except localhost) */
+function validateRpcUrl(url) {
+    if (url.startsWith("https://"))
+        return url;
+    if (url.startsWith("http://localhost") || url.startsWith("http://127.0.0.1"))
+        return url;
+    throw new Error(`Insecure RPC URL rejected: only HTTPS URLs are allowed (got ${url.split("/").slice(0, 3).join("/")})`);
+}
+/** Resolve RPC URLs for a chain: env var override → default RPCs with failover */
+export function getChainRpcUrls(chainId) {
+    const envKey = CHAIN_RPC_ENV_KEYS[chainId];
+    if (envKey && process.env[envKey]) {
+        return [validateRpcUrl(process.env[envKey])];
+    }
+    const defaults = DEFAULT_CHAIN_RPCS[chainId];
+    return defaults ? defaults.map(validateRpcUrl) : [];
+}
+/** Resolve primary RPC URL for a chain (backward compat) */
+export function getChainRpcUrl(chainId) {
+    const urls = getChainRpcUrls(chainId);
+    return urls.length > 0 ? urls[0] : undefined;
+}
+const PROVIDER_TIMEOUT_MS = 8_000;
+const PROVIDER_CACHE_TTL_MS = 60_000; // Cache working providers for 60s
+/**
+ * Get a fresh (uncached) JsonRpcProvider for a specific RPC index.
+ * Used by the fill-detector polling loop to rotate across RPCs and avoid
+ * hitting the same stale eth_call cache on every poll.
+ *
+ * Unlike getProvider(), this:
+ * - Does NOT use the provider cache
+ * - Does NOT validate the provider (caller handles errors)
+ * - Creates a new provider instance each call
+ * - Caller MUST call provider.destroy() when done to prevent zombie retries
+ */
+export function getFreshProvider(chainId, index) {
+    const urls = getChainRpcUrls(chainId);
+    if (urls.length === 0)
+        return null;
+    return new ethers.JsonRpcProvider(urls[index % urls.length]);
+}
+/** Get the number of available RPC endpoints for a chain. */
+export function getRpcCount(chainId) {
+    return getChainRpcUrls(chainId).length;
+}
+// Provider cache: avoids creating new JsonRpcProviders (and zombie retry loops) on every call
+const providerCache = new Map();
+/**
+ * Get a working JsonRpcProvider for a chain, trying multiple RPCs with failover.
+ * Caches the working provider for 60s to avoid repeated connection overhead.
+ * Destroys failed providers to prevent ethers.js background retry loops.
+ * Throws if no RPC can be reached.
+ */
+export async function getProvider(chainId) {
+    // Return cached provider if still fresh
+    const cached = providerCache.get(chainId);
+    if (cached && Date.now() - cached.fetchedAt < PROVIDER_CACHE_TTL_MS) {
+        return cached.provider;
+    }
+    const urls = getChainRpcUrls(chainId);
+    if (urls.length === 0)
+        throw new Error(`No RPC configured for chain ${chainId}`);
+    let lastError = null;
+    for (const url of urls) {
+        const provider = new ethers.JsonRpcProvider(url);
+        try {
+            await Promise.race([
+                provider.getBlockNumber(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("RPC timeout")), PROVIDER_TIMEOUT_MS)),
+            ]);
+            // Cache the working provider
+            providerCache.set(chainId, { provider, fetchedAt: Date.now() });
+            return provider;
+        }
+        catch (err) {
+            lastError = err;
+            // Destroy failed provider to stop ethers.js internal retry loop
+            // (prevents "retry in 1s" messages flooding stderr indefinitely)
+            provider.destroy();
+        }
+    }
+    throw new Error(`All ${urls.length} RPCs failed for chain ${chainId}: ${lastError?.message}`);
+}
+// Native token address (used by LI.FI) — zero address for EVM chains
+const NATIVE_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";
+// Fallback gas prices in gwei (conservative estimates if RPC fails)
+const FALLBACK_GAS_PRICE_GWEI = {
+    1: 30, // Ethereum mainnet
+    10: 0.05, // Optimism (L2, very cheap)
+    56: 3, // BSC
+    137: 50, // Polygon
+    42161: 0.1, // Arbitrum (L2)
+    43114: 30, // Avalanche
+    8453: 0.05, // Base (L2)
+    59144: 0.1, // Linea (L2)
+    534352: 0.1, // Scroll (L2)
+    324: 0.25, // zkSync
+    5000: 0.05, // Mantle (L2)
+    81457: 0.05, // Blast (L2)
+};
+// L-4: Fallback native token USD prices — STALE DATA, used only when LI.FI API is unreachable.
+// Last updated: 2026-02-26. These values drift significantly; live prices are always preferred.
+const FALLBACK_NATIVE_PRICE_USD = {
+    1: 1850, // ETH
+    10: 1850, // ETH (Optimism)
+    56: 600, // BNB
+    137: 0.50, // MATIC/POL
+    42161: 1850, // ETH (Arbitrum)
+    43114: 35, // AVAX
+    8453: 1850, // ETH (Base)
+    59144: 1850, // ETH (Linea)
+    534352: 1850, // ETH (Scroll)
+    324: 1850, // ETH (zkSync)
+    5000: 0.60, // MNT (Mantle)
+    81457: 1850, // ETH (Blast)
+};
+// Ethereum mainnet chain ID
+const ETH_MAINNET = 1;
+// Caches
+const gasPriceCache = new Map();
+const nativePriceCache = new Map();
+/**
+ * Get estimated gas units for a backend's source chain transaction.
+ * Returns null if we can't reliably estimate (unknown backend or chain).
+ *
+ * These are estimates for the USER's on-chain transaction:
+ * - deBridge: createOrder (~65k on L2/BSC, ~150k on ETH mainnet)
+ * - Across: depositV3 (~65k on L2/BSC, ~120k on ETH mainnet)
+ * - Persistence: approve + escrow (~80k, only Base/BSC)
+ */
+export function getGasUnits(backend, chainId) {
+    switch (backend) {
+        case "debridge":
+            return chainId === ETH_MAINNET ? 150_000 : 65_000;
+        case "across":
+            return chainId === ETH_MAINNET ? 120_000 : 65_000;
+        case "relay":
+            return chainId === ETH_MAINNET ? 130_000 : 65_000;
+        case "skip":
+            return chainId === ETH_MAINNET ? 150_000 : 80_000;
+        case "persistence":
+            // Only supports Base (8453) and BSC (56)
+            if (chainId === 8453 || chainId === 56)
+                return 80_000;
+            return null;
+        default:
+            return null; // Unknown backend — can't estimate
+    }
+}
+/**
+ * Fetch gas price (in wei) from an EVM RPC node.
+ * Returns cached value if still fresh. Returns null on total failure
+ * for unknown chains (no RPC and no fallback).
+ */
+async function getGasPriceWei(chainId) {
+    const now = Date.now();
+    // Check cache
+    const cached = gasPriceCache.get(chainId);
+    if (cached && now - cached.fetchedAt < GAS_PRICE_CACHE_TTL_MS) {
+        return { priceWei: cached.priceWei, isFallback: false };
+    }
+    const rpcUrls = getChainRpcUrls(chainId);
+    if (rpcUrls.length === 0) {
+        // No RPC configured — use fallback if available
+        const fallbackGwei = FALLBACK_GAS_PRICE_GWEI[chainId];
+        if (fallbackGwei === undefined)
+            return null; // Truly unknown chain
+        return { priceWei: BigInt(Math.round(fallbackGwei * 1e9)), isFallback: true };
+    }
+    // Try each RPC in order until one succeeds
+    let lastError = null;
+    for (const rpcUrl of rpcUrls) {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), RPC_TIMEOUT_MS);
+            const res = await fetch(rpcUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    method: "eth_gasPrice",
+                    params: [],
+                    id: 1,
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!res.ok)
+                throw new Error(`RPC ${res.status}`);
+            const data = await res.json();
+            const hexPrice = data.result;
+            if (!hexPrice)
+                throw new Error("No result from eth_gasPrice");
+            const priceWei = BigInt(hexPrice);
+            // Cache it
+            gasPriceCache.set(chainId, { priceWei, fetchedAt: now });
+            return { priceWei, isFallback: false };
+        }
+        catch (err) {
+            lastError = err;
+            // Try next RPC
+        }
+    }
+    console.error(`[gas-estimator] eth_gasPrice failed for chain ${chainId} (tried ${rpcUrls.length} RPCs):`, lastError?.message);
+    // All RPCs failed — use fallback
+    const fallbackGwei = FALLBACK_GAS_PRICE_GWEI[chainId];
+    if (fallbackGwei === undefined)
+        return null;
+    return { priceWei: BigInt(Math.round(fallbackGwei * 1e9)), isFallback: true };
+}
+/**
+ * Fetch native token USD price via LI.FI /v1/token endpoint.
+ * Falls back to hardcoded prices on failure. Returns null for unknown chains.
+ * Returns { priceUsd, isFallback } to indicate data freshness.
+ */
+async function getNativeTokenPriceUsd(chainId) {
+    const now = Date.now();
+    // Check cache
+    const cached = nativePriceCache.get(chainId);
+    if (cached && now - cached.fetchedAt < TOKEN_PRICE_CACHE_TTL_MS) {
+        return { priceUsd: cached.priceUsd, isFallback: false };
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), LIFI_TIMEOUT_MS);
+        const url = `https://li.quest/v1/token?chain=${chainId}&token=${NATIVE_TOKEN_ADDRESS}`;
+        const res = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!res.ok)
+            throw new Error(`LI.FI token ${res.status}`);
+        const data = await res.json();
+        const priceUsd = data.priceUSD ? parseFloat(data.priceUSD) : 0;
+        if (priceUsd > 0) {
+            nativePriceCache.set(chainId, { priceUsd, fetchedAt: now });
+            return { priceUsd, isFallback: false };
+        }
+        throw new Error("No price returned");
+    }
+    catch (err) {
+        console.error(`[gas-estimator] LI.FI token price failed for chain ${chainId}:`, err.message);
+        // Fallback to hardcoded
+        const fallback = FALLBACK_NATIVE_PRICE_USD[chainId];
+        if (fallback === undefined)
+            return null; // Truly unknown chain
+        // Still cache the fallback briefly to avoid hammering a failing endpoint
+        nativePriceCache.set(chainId, { priceUsd: fallback, fetchedAt: now });
+        return { priceUsd: fallback, isFallback: true };
+    }
+}
+/**
+ * Estimate gas cost in USD for a transaction on the given chain.
+ *
+ * @param chainId - EVM chain ID
+ * @param gasUnits - Estimated gas units for the transaction, or null if unknown
+ * @returns Estimated cost with staleness indicator, or null if we can't estimate
+ */
+export async function estimateGasCostUsd(chainId, gasUnits) {
+    // If gas units are unknown, we can't estimate
+    if (gasUnits === null)
+        return null;
+    try {
+        const [gasPriceResult, nativePriceResult] = await Promise.all([
+            getGasPriceWei(chainId),
+            getNativeTokenPriceUsd(chainId),
+        ]);
+        // If either lookup failed completely, return null
+        if (gasPriceResult === null || nativePriceResult === null)
+            return null;
+        const usingFallbackPrices = gasPriceResult.isFallback || nativePriceResult.isFallback;
+        // gasCost in ETH = gasUnits * gasPriceWei / 1e18
+        // gasCost in USD = gasCost in ETH * nativePriceUsd
+        const gasCostWei = BigInt(gasUnits) * gasPriceResult.priceWei;
+        // (NEW-LOW-001) Divide in BigInt first to keep intermediate values within safe Number range
+        const gasCostEth = Number(gasCostWei / 10n ** 9n) / 1e9;
+        const gasCostUsd = gasCostEth * nativePriceResult.priceUsd;
+        // Round to 2 decimal places
+        return {
+            costUsd: Math.round(gasCostUsd * 100) / 100,
+            usingFallbackPrices,
+        };
+    }
+    catch (err) {
+        console.error(`[gas-estimator] estimation failed for chain ${chainId}:`, err.message);
+        // Can't estimate — return null instead of a misleading 0
+        return null;
+    }
+}

package/dist/utils/sanitize-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Structured error format returned to agents.
+ * Agents can switch on errorType for programmatic handling.
+ */
+export interface BridgeKittyError {
+    errorType: string;
+    message: string;
+    chain?: string;
+    retryAfterSeconds?: number;
+    rpcProvider?: string;
+    rpcRetries?: number;
+}
+/**
+ * Detect and wrap upstream RPC rate-limit / tier-limit errors.
+ * Returns a structured BridgeKittyError if detected, null otherwise.
+ */
+export declare function detectRpcError(err: Error, chainId?: number): BridgeKittyError | null;
+/**
+ * M-1: Sanitize error messages before returning to MCP clients.
+ * Strips file paths, RPC URLs, and internal details.
+ * Never passes through raw upstream error messages.
+ */
+export declare function sanitizeError(err: Error): string;

package/dist/utils/sanitize-error.js

@@ -0,0 +1,101 @@
+/**
+ * Detect and wrap upstream RPC rate-limit / tier-limit errors.
+ * Returns a structured BridgeKittyError if detected, null otherwise.
+ */
+export function detectRpcError(err, chainId) {
+    const msg = err.message || "";
+    const lowerMsg = msg.toLowerCase();
+    // Rate limit detection patterns
+    if (lowerMsg.includes("rate limit") ||
+        lowerMsg.includes("too many requests") ||
+        lowerMsg.includes("429") ||
+        lowerMsg.includes("upgrade your tier") ||
+        lowerMsg.includes("please upgrade") ||
+        lowerMsg.includes("capacity exceeded") ||
+        lowerMsg.includes("request limit")) {
+        return {
+            errorType: "rpc_rate_limit",
+            message: "RPC rate limit reached. Retrying with a different provider.",
+            chain: chainId ? `chain ${chainId}` : undefined,
+            retryAfterSeconds: 5,
+        };
+    }
+    // Timeout detection
+    if (lowerMsg.includes("timeout") ||
+        lowerMsg.includes("timed out") ||
+        lowerMsg.includes("etimedout") ||
+        lowerMsg.includes("econnaborted")) {
+        return {
+            errorType: "rpc_timeout",
+            message: "RPC request timed out. Retrying with a different provider.",
+            chain: chainId ? `chain ${chainId}` : undefined,
+            retryAfterSeconds: 3,
+        };
+    }
+    // Connection refused / network errors
+    if (lowerMsg.includes("econnrefused") ||
+        lowerMsg.includes("enotfound") ||
+        lowerMsg.includes("network error") ||
+        lowerMsg.includes("fetch failed")) {
+        return {
+            errorType: "rpc_unavailable",
+            message: "RPC provider is unavailable. Trying alternative provider.",
+            chain: chainId ? `chain ${chainId}` : undefined,
+            retryAfterSeconds: 2,
+        };
+    }
+    // All RPCs exhausted
+    if (lowerMsg.includes("all rpcs failed") ||
+        lowerMsg.includes("no rpc available")) {
+        return {
+            errorType: "rpc_exhausted",
+            message: "All RPC providers failed. Please retry after a short delay.",
+            chain: chainId ? `chain ${chainId}` : undefined,
+            retryAfterSeconds: 15,
+        };
+    }
+    return null;
+}
+/**
+ * M-1: Sanitize error messages before returning to MCP clients.
+ * Strips file paths, RPC URLs, and internal details.
+ * Never passes through raw upstream error messages.
+ */
+export function sanitizeError(err) {
+    let msg = err.message || "Unknown error";
+    // First check for known RPC error patterns and return clean message
+    const rpcError = detectRpcError(err);
+    if (rpcError) {
+        return rpcError.message;
+    }
+    // Strip file paths (Unix and Windows)
+    msg = msg.replace(/\/[\w./-]+\.(ts|js|json|env)/g, "[path]");
+    msg = msg.replace(/[A-Z]:\\[\w.\\-]+\.(ts|js|json|env)/gi, "[path]");
+    // Strip RPC/HTTP URLs (but keep domain for context)
+    msg = msg.replace(/https?:\/\/[^\s"',)]+/g, (url) => {
+        try {
+            const u = new URL(url);
+            return `[${u.hostname}]`;
+        }
+        catch {
+            return "[url]";
+        }
+    });
+    // Strip stack traces
+    msg = msg.replace(/\n\s+at\s+.*/g, "");
+    // Strip hex data dumps (long hex strings > 20 chars)
+    msg = msg.replace(/0x[a-fA-F0-9]{20,}/g, "[hex-data]");
+    // Strip bare hex private keys (64 hex chars not prefixed with 0x)
+    msg = msg.replace(/\b[a-fA-F0-9]{64}\b/g, "[key-redacted]");
+    // Strip mnemonic phrases (sequences of 12+ lowercase words that look like BIP-39)
+    msg = msg.replace(/\b([a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/g, "[mnemonic-redacted]");
+    // Strip base58 strings (Solana private keys are 44-88 base58 chars)
+    msg = msg.replace(/[1-9A-HJ-NP-Za-km-z]{43,88}/g, "[key-redacted]");
+    // Strip raw upstream "upgrade your tier" messages
+    msg = msg.replace(/please upgrade[^.]*\./gi, "RPC provider rate limit reached.");
+    // Truncate overly long messages
+    if (msg.length > 300) {
+        msg = msg.slice(0, 297) + "...";
+    }
+    return msg;
+}

package/dist/utils/token-registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Verified Token Registry
+ *
+ * Security-first token symbol resolution. Only resolves to verified, canonical
+ * token addresses from official deployments. NEVER falls back to unverified tokens.
+ *
+ * Sources:
+ * - Circle's official USDC deployments
+ * - Tether's official USDT deployments
+ * - LI.FI's verified token list
+ * - CoinGecko verified contracts
+ * - Official bridge/wrapper contracts per chain
+ *
+ * If a token is not in this registry, resolution fails with a clear error.
+ * Agents can always pass raw 0x addresses to bypass the registry.
+ */
+export interface VerifiedToken {
+    /** Canonical symbol (uppercase) */
+    symbol: string;
+    /** Human-readable name */
+    name: string;
+    /** Default token decimals */
+    decimals: number;
+    /** Per-chain decimal overrides (e.g. USDT is 18 decimals on BSC, 6 elsewhere) */
+    decimalOverrides?: Record<number, number>;
+    /** chainId → verified contract address */
+    addresses: Record<number, string>;
+}
+export type TokenResolveResult = {
+    ok: true;
+    address: string;
+    decimals: number;
+    symbol: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const VERIFIED_TOKENS: VerifiedToken[];
+/**
+ * Resolve a token input (symbol or 0x address) to a verified address.
+ *
+ * Security rules:
+ * - If input is a 0x address: pass through unchanged (with known decimals if available)
+ * - If input is a symbol: ONLY resolve to verified canonical addresses
+ * - If symbol is unknown: return error with guidance
+ * - If symbol is ambiguous (multiple tokens): return error listing options
+ * - NEVER falls back to unverified tokens
+ */
+export declare function resolveToken(input: string, chainId: number): TokenResolveResult;
+/**
+ * Look up a verified token by address on a specific chain.
+ * Returns null if not in the registry (the token may still be valid, just not curated).
+ */
+export declare function lookupByAddress(address: string, chainId: number): VerifiedToken | null;
+/**
+ * Get all verified tokens available on a specific chain.
+ */
+export declare function getVerifiedTokensForChain(chainId: number): Array<{
+    symbol: string;
+    name: string;
+    address: string;
+    decimals: number;
+}>;
+/**
+ * Get the total number of unique tokens in the registry.
+ */
+export declare function getRegistryStats(): {
+    tokenCount: number;
+    chainCount: number;
+};