@persistenceone/bridgekitty 0.3.0

package/dist/index.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { LiFiBackend } from "./backends/lifi.js";
+import { PersistenceBackend } from "./backends/persistence.js";
+import { DeBridgeBackend } from "./backends/debridge.js";
+import { RelayBackend } from "./backends/relay.js";
+import { AcrossBackend } from "./backends/across.js";
+import { SquidBackend } from "./backends/squid.js";
+import { RoutingEngine } from "./routing/engine.js";
+import { CircuitBreaker } from "./utils/circuit-breaker.js";
+import { registerGetQuote } from "./tools/get-quote.js";
+import { registerExecuteBridge } from "./tools/execute-bridge.js";
+import { registerCheckStatus } from "./tools/check-status.js";
+import { registerGetChains } from "./tools/get-chains.js";
+import { registerGetTokens } from "./tools/get-tokens.js";
+import { registerXprtFarmTools } from "./tools/xprt-farm.js";
+import { registerWalletTools, getKey, getConfigDir } from "./tools/wallet.js";
+import { registerHelpTool } from "./tools/help.js";
+import { registerXprtRewardsCheck } from "./tools/xprt-rewards.js";
+import { registerMultiQuote } from "./tools/multi-quote.js";
+import { registerOnboardTool } from "./tools/onboard.js";
+import { registerXprtStakingTools } from "./tools/xprt-staking.js";
+import * as fs from "fs";
+import * as path from "path";
+// Auto-load .env from stable config directory (~/.bridgekitty/ or BRIDGEKITTY_HOME)
+function loadDotEnv() {
+    const envPath = path.resolve(getConfigDir(), ".env");
+    if (!fs.existsSync(envPath))
+        return;
+    // L-1: Warn if .env permissions are too permissive
+    try {
+        const stat = fs.statSync(envPath);
+        const mode = stat.mode & 0o777;
+        if (mode > 0o600) {
+            console.error(`⚠️  WARNING: .env file has permissive permissions (${mode.toString(8)}). ` +
+                `Recommended: chmod 600 .env (currently readable by group/others).`);
+        }
+    }
+    catch { /* stat failed — non-fatal */ }
+    const content = fs.readFileSync(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const value = trimmed.slice(eqIdx + 1).trim();
+        if (!process.env[key]) {
+            process.env[key] = value;
+        }
+    }
+}
+loadDotEnv();
+// Migration hint: if old CWD-based .env exists but config dir one doesn't, warn user
+try {
+    const oldEnvPath = path.resolve(process.cwd(), ".env");
+    const newEnvPath = path.resolve(getConfigDir(), ".env");
+    if (oldEnvPath !== newEnvPath && fs.existsSync(oldEnvPath) && !fs.existsSync(newEnvPath)) {
+        const oldContent = fs.readFileSync(oldEnvPath, "utf-8");
+        if (oldContent.includes("PRIVATE_KEY")) {
+            console.error(`⚠️  Found .env with PRIVATE_KEY at ${oldEnvPath} (old CWD-based location). ` +
+                `BridgeKitty now uses ${path.resolve(getConfigDir(), ".env")}. ` +
+                `Move your .env: mv "${oldEnvPath}" "${newEnvPath}"`);
+        }
+    }
+}
+catch { /* non-fatal */ }
+// MEDIUM-002: Immediately move sensitive keys from process.env to in-memory store.
+// loadDotEnv puts everything into process.env; calling getKey() moves them to the
+// in-memory keyStore and deletes from process.env, minimizing the exposure window.
+getKey("privateKey");
+getKey("mnemonic");
+getKey("solanaKey");
+// ─── BridgeKitty fee configuration (hardcoded — not user-configurable) ────────
+// These are the BridgeKitty project's integrator/affiliate addresses.
+// Revenue from bridge fees funds ongoing development.
+// Persistence Interop routes are always fee-free (direct protocol integration).
+const BRIDGEKITTY_FEE_WALLET = "0xb24aCFcda187135490d81517ab56709FdDe6a81A";
+const BRIDGEKITTY_DEBRIDGE_FEE = undefined; // disabled for now
+const BRIDGEKITTY_LIFI_FEE = undefined; // needs portal.li.fi registration first
+const BRIDGEKITTY_LIFI_INTEGRATOR = undefined; // needs portal.li.fi registration first
+const BRIDGEKITTY_RELAY_FEE = undefined; // disabled for now
+function createEngine() {
+    const lifi = new LiFiBackend(process.env.LIFI_API_KEY, BRIDGEKITTY_LIFI_INTEGRATOR, BRIDGEKITTY_LIFI_FEE);
+    const persistence = new PersistenceBackend();
+    const debridge = new DeBridgeBackend(BRIDGEKITTY_DEBRIDGE_FEE, BRIDGEKITTY_FEE_WALLET);
+    const relay = new RelayBackend(BRIDGEKITTY_FEE_WALLET, BRIDGEKITTY_RELAY_FEE);
+    const across = new AcrossBackend(BRIDGEKITTY_FEE_WALLET);
+    const squid = new SquidBackend(process.env.SQUID_INTEGRATOR_ID);
+    const circuitBreaker = new CircuitBreaker();
+    return new RoutingEngine([lifi, persistence, debridge, relay, across, squid], circuitBreaker);
+}
+// Read version from package.json to avoid duplication
+const PKG_VERSION = (() => {
+    try {
+        const pkgPath = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "0.1.0";
+    }
+    catch {
+        return "0.1.0";
+    }
+})();
+async function main() {
+    // TTY detection: if run directly in a terminal (not piped), show help and exit.
+    // MCP servers communicate over stdio JSON-RPC — running in a TTY means the user
+    // probably ran `npx bridgekitty` directly instead of configuring it as an MCP server.
+    if (process.stdin.isTTY && !process.argv.includes("--stdio")) {
+        console.log(`BridgeKitty 🐱 v${PKG_VERSION} — Cross-chain bridge aggregator MCP server\n`);
+        console.log("This is an MCP (Model Context Protocol) server. Add it to your AI tool's config:\n");
+        console.log("  Claude Desktop / Claude Code:");
+        console.log('    { "mcpServers": { "bridgekitty": { "command": "npx", "args": ["bridgekitty"] } } }\n');
+        console.log("  Cursor:");
+        console.log("    Add to .cursor/mcp.json with the same format.\n");
+        console.log("  Direct (stdio):");
+        console.log("    npx bridgekitty --stdio\n");
+        console.log("Config: ~/.bridgekitty/.env (override with BRIDGEKITTY_HOME env var)");
+        console.log("Docs:   https://github.com/persistenceOne/bridgekitty");
+        process.exit(0);
+    }
+    const engine = createEngine();
+    const server = new McpServer({
+        name: "bridgekitty",
+        version: PKG_VERSION,
+    });
+    registerGetQuote(server, engine);
+    registerExecuteBridge(server, engine);
+    registerCheckStatus(server, engine);
+    registerGetChains(server, engine);
+    registerGetTokens(server, engine);
+    registerWalletTools(server);
+    registerXprtFarmTools(server, engine);
+    registerXprtStakingTools(server);
+    registerHelpTool(server);
+    registerXprtRewardsCheck(server);
+    registerMultiQuote(server, engine);
+    registerOnboardTool(server, engine);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("BridgeKitty 🐱 MCP server running on stdio");
+}
+main().catch((err) => {
+    // Sanitize fatal errors to avoid leaking keys/paths in crash output
+    const msg = err instanceof Error ? err.message : String(err);
+    const safeMsg = msg
+        .replace(/\/[\w./-]+\.(ts|js|json|env)/g, "[path]")
+        .replace(/0x[a-fA-F0-9]{20,}/g, "[hex-data]")
+        .replace(/\b[a-fA-F0-9]{64}\b/g, "[key-redacted]");
+    console.error("Fatal error:", safeMsg);
+    process.exit(1);
+});

package/dist/routing/engine.d.ts

@@ -0,0 +1,49 @@
+import type { BridgeBackend, BridgeQuote, QuoteParams } from "../backends/types.js";
+import { CircuitBreaker } from "../utils/circuit-breaker.js";
+export interface CachedQuote extends BridgeQuote {
+    quoteId: string;
+}
+export interface FailedProvider {
+    provider: string;
+    reason: string;
+}
+export declare class RoutingEngine {
+    private backends;
+    private quoteCache;
+    private quoteResponseCache;
+    private circuitBreaker;
+    /** Track per-request backend outcomes for error differentiation */
+    private lastRequestErrors;
+    /** Track per-request backend failure reasons */
+    private lastFailedProviders;
+    constructor(backends: BridgeBackend[], circuitBreaker?: CircuitBreaker);
+    getQuotes(params: QuoteParams): Promise<CachedQuote[]>;
+    getCachedQuote(quoteId: string): BridgeQuote | null;
+    /**
+     * Get a cached quote even if it's expired. Returns { quote, expired } so callers
+     * can decide to auto-refresh. Does NOT delete expired entries.
+     */
+    getCachedQuoteWithExpiry(quoteId: string): {
+        quote: BridgeQuote;
+        expired: boolean;
+    } | null;
+    getBackend(name: string): BridgeBackend | undefined;
+    getAllBackends(): BridgeBackend[];
+    /**
+     * Get the circuit breaker instance (for monitoring/testing).
+     */
+    getCircuitBreaker(): CircuitBreaker;
+    /**
+     * Get the list of providers that failed or returned no results in the last request.
+     */
+    getLastFailedProviders(): FailedProvider[];
+    /**
+     * Differentiate why no quotes were returned.
+     * Call after getQuotes returns empty to understand the cause.
+     */
+    getLastRequestDiagnosis(): {
+        allErrored: boolean;
+        allEmpty: boolean;
+        circuitBroken: string[];
+    };
+}

package/dist/routing/engine.js

@@ -0,0 +1,336 @@
+import crypto from "node:crypto";
+import { BackendValidationError } from "../backends/types.js";
+import { isValidEvmAddress } from "../utils/evm.js";
+import { CircuitBreaker } from "../utils/circuit-breaker.js";
+import { getAllChains, isCosmosChain, isSolanaChain } from "../utils/chains.js";
+/** Minimum buffer (ms) before a quote's expiry — quotes expiring within this window are filtered out. */
+const EXPIRY_BUFFER_MS = 5_000;
+/** Timeout for each backend quote request (ms). */
+const BACKEND_TIMEOUT_MS = 10_000;
+/** Quote response cache TTL (ms). Same params within this window return cached results. */
+const QUOTE_CACHE_TTL_MS = 15_000;
+/**
+ * Validate quote params before sending to any backend.
+ * Throws BackendValidationError for invalid inputs.
+ */
+function validateQuoteParams(params) {
+    // Chain IDs must be positive integers
+    if (!Number.isInteger(params.fromChainId) || params.fromChainId <= 0) {
+        throw new BackendValidationError(`Invalid source chain ID: ${params.fromChainId}. Must be a positive integer.`);
+    }
+    if (!Number.isInteger(params.toChainId) || params.toChainId <= 0) {
+        throw new BackendValidationError(`Invalid destination chain ID: ${params.toChainId}. Must be a positive integer.`);
+    }
+    // Cannot bridge to same chain
+    if (params.fromChainId === params.toChainId) {
+        throw new BackendValidationError(`Source and destination chains are the same (${params.fromChainId}). Use a DEX for same-chain swaps.`);
+    }
+    // Amount must be positive
+    let amountBig;
+    try {
+        amountBig = BigInt(params.amountRaw);
+    }
+    catch {
+        throw new BackendValidationError(`Invalid amount: "${params.amountRaw}" is not a valid number.`);
+    }
+    if (amountBig <= 0n) {
+        throw new BackendValidationError(`Amount must be positive. Got: ${params.amountRaw}`);
+    }
+    // Determine if source/destination are non-EVM chains (relaxed address validation)
+    const fromIsCosmos = isCosmosChain(params.fromChainId);
+    const toIsCosmos = isCosmosChain(params.toChainId);
+    const fromIsSolana = isSolanaChain(params.fromChainId);
+    const toIsSolana = isSolanaChain(params.toChainId);
+    // Validate sender address based on source chain ecosystem
+    if (!fromIsCosmos && !fromIsSolana && !isValidEvmAddress(params.fromAddress)) {
+        throw new BackendValidationError(`Invalid sender address: "${params.fromAddress}". Expected 0x followed by 40 hex characters.`);
+    }
+    // Solana addresses are base58 encoded, 32-44 characters
+    if (fromIsSolana && !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(params.fromAddress)) {
+        throw new BackendValidationError(`Invalid Solana sender address: "${params.fromAddress}". Expected base58-encoded address.`);
+    }
+    // Validate recipient address based on destination chain ecosystem
+    if (params.toAddress) {
+        if (!toIsCosmos && !toIsSolana && !isValidEvmAddress(params.toAddress)) {
+            throw new BackendValidationError(`Invalid recipient address: "${params.toAddress}". Expected 0x followed by 40 hex characters.`);
+        }
+        if (toIsSolana && !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(params.toAddress)) {
+            throw new BackendValidationError(`Invalid Solana recipient address: "${params.toAddress}". Expected base58-encoded address.`);
+        }
+    }
+    // Token addresses: must look like EVM addresses, Cosmos denoms, or Solana base58 mint addresses
+    const isValidTokenAddress = (addr, chainIsCosmos, chainIsSolana) => {
+        if (isValidEvmAddress(addr))
+            return true;
+        if (chainIsCosmos && /^[a-z][a-z0-9/]{1,128}$/.test(addr))
+            return true;
+        if (chainIsSolana && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(addr))
+            return true;
+        return false;
+    };
+    if (!isValidTokenAddress(params.fromTokenAddress, fromIsCosmos, fromIsSolana)) {
+        throw new BackendValidationError(`Invalid source token address: "${params.fromTokenAddress}". Provide a valid 0x address or a recognized token symbol.`);
+    }
+    if (!isValidTokenAddress(params.toTokenAddress, toIsCosmos, toIsSolana)) {
+        throw new BackendValidationError(`Invalid destination token address: "${params.toTokenAddress}". Provide a valid 0x address or a recognized token symbol.`);
+    }
+}
+/**
+ * Normalize a chain identifier for cache key consistency.
+ * Ensures "bsc", "56", "BSC" all produce the same cache key component.
+ * Since the engine already resolves chain IDs to numbers before reaching here,
+ * this is mainly for defensive normalization.
+ */
+function normalizeChainForCache(chainId) {
+    return String(chainId);
+}
+/**
+ * Build a cache key from normalized quote params.
+ * All addresses are lowercased and chain IDs are stringified for consistency.
+ */
+function buildQuoteCacheKey(params) {
+    return [
+        normalizeChainForCache(params.fromChainId),
+        normalizeChainForCache(params.toChainId),
+        params.fromTokenAddress.toLowerCase(),
+        params.toTokenAddress.toLowerCase(),
+        params.amountRaw,
+        params.fromAddress.toLowerCase(),
+        params.preference,
+    ].join(":");
+}
+export class RoutingEngine {
+    backends;
+    quoteCache = new Map();
+    quoteResponseCache = new Map();
+    circuitBreaker;
+    /** Track per-request backend outcomes for error differentiation */
+    lastRequestErrors = new Map();
+    /** Track per-request backend failure reasons */
+    lastFailedProviders = [];
+    constructor(backends, circuitBreaker) {
+        this.backends = backends;
+        this.circuitBreaker = circuitBreaker ?? new CircuitBreaker();
+    }
+    async getQuotes(params) {
+        // Validate inputs before calling any backend
+        validateQuoteParams(params);
+        // Validate chain IDs against known supported chains (NEW-LOW-003)
+        const supportedChains = getAllChains();
+        const supportedIds = supportedChains.map((c) => c.id);
+        const supportedList = supportedChains.map((c) => `${c.name} (${c.id})`).join(", ");
+        if (!supportedIds.includes(params.fromChainId)) {
+            throw new BackendValidationError(`Unsupported source chain ID: ${params.fromChainId}. Supported chains: ${supportedList}`);
+        }
+        if (!supportedIds.includes(params.toChainId)) {
+            throw new BackendValidationError(`Unsupported destination chain ID: ${params.toChainId}. Supported chains: ${supportedList}`);
+        }
+        // Check quote response cache
+        const cacheKey = buildQuoteCacheKey(params);
+        const cached = this.quoteResponseCache.get(cacheKey);
+        if (cached && Date.now() - cached.fetchedAt < QUOTE_CACHE_TTL_MS) {
+            // Return cached quotes that haven't expired
+            const now = Date.now();
+            const valid = cached.quotes.filter((q) => q.expiresAt > now + EXPIRY_BUFFER_MS);
+            if (valid.length > 0)
+                return valid;
+        }
+        // Reset error tracking for this request
+        this.lastRequestErrors.clear();
+        this.lastFailedProviders = [];
+        // Filter backends by providers filter (if specified)
+        let eligibleBackends = this.backends;
+        if (params.providers && params.providers.length > 0) {
+            const allowed = new Set(params.providers.map(p => p.toLowerCase()));
+            eligibleBackends = this.backends.filter((b) => allowed.has(b.name.toLowerCase()));
+            // Track filtered-out providers
+            for (const b of this.backends) {
+                if (!allowed.has(b.name.toLowerCase())) {
+                    this.lastFailedProviders.push({ provider: b.name, reason: "filtered out by providers parameter" });
+                }
+            }
+        }
+        // Filter out backends that don't support Solana chains
+        const involvesSolana = isSolanaChain(params.fromChainId) || isSolanaChain(params.toChainId);
+        if (involvesSolana) {
+            const solanaCapable = new Set(["debridge"]); // Only deBridge supports Solana
+            const preFilter = eligibleBackends;
+            eligibleBackends = eligibleBackends.filter((b) => solanaCapable.has(b.name.toLowerCase()));
+            for (const b of preFilter) {
+                if (!solanaCapable.has(b.name.toLowerCase())) {
+                    this.lastFailedProviders.push({ provider: b.name, reason: "chain not supported (Solana)" });
+                }
+            }
+        }
+        // Filter backends by circuit breaker state
+        const allowedBackends = eligibleBackends.filter((b) => {
+            const allowed = this.circuitBreaker.isAllowed(b.name);
+            if (!allowed) {
+                this.lastRequestErrors.set(b.name, "error"); // circuit-broken = effectively errored
+                this.lastFailedProviders.push({ provider: b.name, reason: "circuit breaker open (too many recent failures)" });
+            }
+            return allowed;
+        });
+        // Use getQuotes (multi-route) when available, fall back to getQuote (single)
+        const results = await Promise.allSettled(allowedBackends.map((b) => Promise.race([
+            (b.getQuotes
+                ? b.getQuotes(params)
+                : b.getQuote(params).then((q) => (q ? [q] : []))).then((quotes) => ({ backendName: b.name, quotes })),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Backend ${b.name} timed out after ${BACKEND_TIMEOUT_MS}ms`)), BACKEND_TIMEOUT_MS)),
+        ])));
+        // Check for validation errors from backends and propagate the first one
+        for (const r of results) {
+            if (r.status === "rejected" && r.reason instanceof BackendValidationError) {
+                throw r.reason;
+            }
+        }
+        const now = Date.now();
+        // Process results and track circuit breaker state
+        const allQuotes = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            const backendName = allowedBackends[i].name;
+            if (r.status === "rejected") {
+                this.circuitBreaker.recordFailure(backendName);
+                this.lastRequestErrors.set(backendName, "error");
+                const errMsg = r.reason instanceof Error ? r.reason.message : String(r.reason);
+                // Classify the error
+                let reason = "unknown error";
+                if (errMsg.includes("timed out"))
+                    reason = `timeout after ${BACKEND_TIMEOUT_MS / 1000}s`;
+                else if (errMsg.includes("rate limit") || errMsg.includes("429"))
+                    reason = "rate limited";
+                else if (errMsg.includes("ECONNREFUSED") || errMsg.includes("ENOTFOUND"))
+                    reason = "connection failed";
+                else
+                    reason = errMsg.slice(0, 100);
+                this.lastFailedProviders.push({ provider: backendName, reason });
+                continue;
+            }
+            const quotes = r.value.quotes.filter((q) => q !== null);
+            if (quotes.length === 0) {
+                // Empty result is not a failure for circuit breaker (route might not exist)
+                this.circuitBreaker.recordSuccess(backendName);
+                this.lastRequestErrors.set(backendName, "empty");
+                this.lastFailedProviders.push({ provider: backendName, reason: "no routes for this token pair" });
+            }
+            else {
+                this.circuitBreaker.recordSuccess(backendName);
+                this.lastRequestErrors.set(backendName, "success");
+                allQuotes.push(...quotes);
+            }
+        }
+        // Filter expired quotes (with buffer)
+        const validQuotes = allQuotes.filter((q) => q.expiresAt > now + EXPIRY_BUFFER_MS);
+        // Sort by preference
+        if (params.preference === "fastest") {
+            validQuotes.sort((a, b) => a.estimatedTimeSeconds - b.estimatedTimeSeconds);
+        }
+        else {
+            // Cheapest = highest output amount (BigInt raw), with gas as tiebreaker
+            // (NEW-MEDIUM-001: don't mix token units with USD gas costs)
+            validQuotes.sort((a, b) => {
+                try {
+                    const aOutputRaw = BigInt(a.minOutputAmountRaw);
+                    const bOutputRaw = BigInt(b.minOutputAmountRaw);
+                    // Normalize to 18 decimals for cross-backend comparison (V3-MEDIUM-001)
+                    const aOutput = aOutputRaw * 10n ** BigInt(18 - (a.outputDecimals ?? 18));
+                    const bOutput = bOutputRaw * 10n ** BigInt(18 - (b.outputDecimals ?? 18));
+                    // Primary sort: highest output wins
+                    // Use gas as tiebreaker only when outputs are within 0.1% of each other
+                    const larger = aOutput > bOutput ? aOutput : bOutput;
+                    const diff = aOutput > bOutput ? aOutput - bOutput : bOutput - aOutput;
+                    const isNearEqual = larger > 0n && diff * 1000n <= larger; // within 0.1%
+                    if (!isNearEqual) {
+                        // Outputs differ meaningfully — highest output wins
+                        return bOutput > aOutput ? 1 : bOutput < aOutput ? -1 : 0;
+                    }
+                    // Outputs are near-equal — use gas cost as tiebreaker (lower gas wins)
+                    const aGas = a.estimatedGasCostUsd ?? Infinity;
+                    const bGas = b.estimatedGasCostUsd ?? Infinity;
+                    if (aGas !== bGas)
+                        return aGas - bGas;
+                    // Gas also equal — fall back to raw output
+                    return bOutput > aOutput ? 1 : bOutput < aOutput ? -1 : 0;
+                }
+                catch {
+                    return 0;
+                }
+            });
+        }
+        // Cache quotes for execution and assign stable IDs
+        const cachedQuotes = [];
+        for (const q of validQuotes) {
+            const quoteId = crypto.randomUUID();
+            this.quoteCache.set(quoteId, { quote: q, expiresAt: q.expiresAt });
+            cachedQuotes.push({ ...q, quoteId });
+        }
+        // Store in response cache
+        this.quoteResponseCache.set(cacheKey, { quotes: cachedQuotes, fetchedAt: now });
+        // Clean expired entries
+        for (const [key, val] of this.quoteCache) {
+            if (val.expiresAt < now)
+                this.quoteCache.delete(key);
+        }
+        // Clean old response cache entries
+        for (const [key, val] of this.quoteResponseCache) {
+            if (now - val.fetchedAt > QUOTE_CACHE_TTL_MS)
+                this.quoteResponseCache.delete(key);
+        }
+        return cachedQuotes;
+    }
+    getCachedQuote(quoteId) {
+        const entry = this.quoteCache.get(quoteId);
+        if (!entry || entry.expiresAt < Date.now()) {
+            this.quoteCache.delete(quoteId);
+            return null;
+        }
+        return entry.quote;
+    }
+    /**
+     * Get a cached quote even if it's expired. Returns { quote, expired } so callers
+     * can decide to auto-refresh. Does NOT delete expired entries.
+     */
+    getCachedQuoteWithExpiry(quoteId) {
+        const entry = this.quoteCache.get(quoteId);
+        if (!entry)
+            return null;
+        return { quote: entry.quote, expired: entry.expiresAt < Date.now() };
+    }
+    getBackend(name) {
+        return this.backends.find((b) => b.name === name);
+    }
+    getAllBackends() {
+        return this.backends;
+    }
+    /**
+     * Get the circuit breaker instance (for monitoring/testing).
+     */
+    getCircuitBreaker() {
+        return this.circuitBreaker;
+    }
+    /**
+     * Get the list of providers that failed or returned no results in the last request.
+     */
+    getLastFailedProviders() {
+        return this.lastFailedProviders;
+    }
+    /**
+     * Differentiate why no quotes were returned.
+     * Call after getQuotes returns empty to understand the cause.
+     */
+    getLastRequestDiagnosis() {
+        const outcomes = Array.from(this.lastRequestErrors.values());
+        const circuitBroken = [];
+        for (const [name] of this.lastRequestErrors) {
+            if (this.circuitBreaker.getState(name) === "OPEN") {
+                circuitBroken.push(name);
+            }
+        }
+        return {
+            allErrored: outcomes.length > 0 && outcomes.every((o) => o === "error"),
+            allEmpty: outcomes.length > 0 && outcomes.every((o) => o === "empty" || o === "success"),
+            circuitBroken,
+        };
+    }
+}

package/dist/tools/check-status.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RoutingEngine } from "../routing/engine.js";
+export declare function registerCheckStatus(server: McpServer, engine: RoutingEngine): void;

package/dist/tools/check-status.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { sanitizeError } from "../utils/sanitize-error.js";
+export function registerCheckStatus(server, engine) {
+    server.tool("bridge_status", "Check the status of a cross-chain bridge transfer. " +
+        "Supports all providers: LI.FI, Squid Router, deBridge, Across, Relay, Persistence Interop. " +
+        "Provide the tracking ID from bridge_execute, or a transaction hash with provider name. " +
+        "Returns: status (pending/in_progress/completed/failed), source/destination tx hashes, elapsed time, and estimated remaining time.", {
+        trackingId: z
+            .string()
+            .optional()
+            .describe("Tracking ID from bridge_execute"),
+        txHash: z
+            .string()
+            .optional()
+            .describe("Source chain transaction hash"),
+        fromChain: z
+            .string()
+            .optional()
+            .describe("Source chain ID (needed with txHash for LI.FI)"),
+        toChain: z
+            .string()
+            .optional()
+            .describe("Destination chain ID (needed with txHash for LI.FI)"),
+        provider: z
+            .string()
+            .optional()
+            .describe("Bridge provider (e.g. 'lifi', 'persistence')"),
+    }, async (params) => {
+        // Validate: at least one of trackingId or txHash must be provided
+        if (!params.trackingId && !params.txHash) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Please provide either a trackingId (from bridge_execute) or a txHash to check bridge status.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Determine which backend to query
+        let providerName = params.provider;
+        if (!providerName && params.trackingId) {
+            providerName = params.trackingId.split(":")[0];
+        }
+        if (!providerName)
+            providerName = "lifi"; // default
+        const backend = engine.getBackend(providerName);
+        if (!backend) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown provider: ${providerName}. Available: ${engine.getAllBackends().map((b) => b.name).join(", ")}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const meta = {};
+            if (params.txHash)
+                meta.txHash = params.txHash;
+            if (params.fromChain)
+                meta.fromChain = params.fromChain;
+            if (params.toChain)
+                meta.toChain = params.toChain;
+            const status = await backend.getStatus(params.trackingId ?? params.txHash ?? "", meta);
+            const response = {
+                status: status.state,
+                summary: status.humanReadable,
+                provider: status.provider,
+                sourceTx: status.sourceTxHash ?? null,
+                destinationTx: status.destTxHash ?? null,
+                elapsedSeconds: status.elapsed,
+                estimatedRemainingSeconds: status.estimatedRemaining ?? null,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Status check failed: ${sanitizeError(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/execute-bridge.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RoutingEngine } from "../routing/engine.js";
+export declare function registerExecuteBridge(server: McpServer, engine: RoutingEngine): void;