@persistenceone/bridgekitty 0.3.0

package/dist/tools/help.js

@@ -0,0 +1,204 @@
+import { z } from "zod";
+const HELP_CONTENT = {
+    overview: [
+        "BridgeKitty is a cross-chain bridge aggregator MCP server connecting EVM chains, Solana, and Cosmos chains (including Persistence and Cosmoshub).",
+        "",
+        "It provides 6 bridge backends:",
+        "  - LI.FI: Aggregator covering 30+ bridges with the widest chain/token coverage.",
+        "  - Squid Router (Skip Protocol): 120+ chains including 62+ Cosmos/IBC chains.",
+        "  - deBridge DLN: Fast intent-based bridging with Solana support.",
+        "  - Across: Fastest fills (~6 seconds average).",
+        "  - Relay: Gas-optimized bridging for cost-sensitive transfers.",
+        "  - Persistence Interop: Direct BTCB<>cbBTC bridging with XPRT farming rewards.",
+        "",
+        "Available tool categories:",
+        "  Bridging: bridge_get_quote, bridge_execute, bridge_status, bridge_quote_multi",
+        "  Discovery: bridge_chains, bridge_tokens",
+        "  Wallet: wallet_status, wallet_setup, wallet_import, wallet_balance",
+        "  XPRT Farming: xprt_farm_prepare, xprt_farm_start, xprt_farm_status, xprt_farm_boost, xprt_rewards_check",
+        "  XPRT Staking: xprt_stake, xprt_unstake, xprt_claim_rewards",
+        "  Onboarding: xprt_onboard",
+        "",
+        "Use bridgekitty_help with a specific topic for detailed guidance: 'bridging', 'farming', 'wallet', or 'troubleshooting'.",
+    ].join("\n"),
+    bridging: [
+        "Cross-Chain Bridging Guide",
+        "=========================",
+        "",
+        "Recommended flow:",
+        "  1. bridge_get_quote  - Compare quotes across all backends for your route.",
+        "  2. bridge_execute    - Get unsigned transaction data for the best quote.",
+        "  3. bridge_status     - Track your bridge transfer progress until completion.",
+        "",
+        "Parameters for bridge_get_quote:",
+        "  - fromChain / toChain: Chain name (e.g. 'base', 'arbitrum') or chain ID (e.g. '8453').",
+        "  - fromToken / toToken: Token symbol (e.g. 'USDC', 'ETH') or contract address (0x...).",
+        "  - amount: Human-readable amount (e.g. '100' for 100 USDC).",
+        "  - fromAddress: Your wallet address (0x...).",
+        "  - preference: 'cheapest' or 'fastest' (default: 'fastest').",
+        "",
+        "For multi-hop routes (e.g. ETH on Base to XPRT on Persistence):",
+        "  Use bridge_quote_multi which automatically finds optimal intermediate hops.",
+        "",
+        "Common pitfalls:",
+        "  - Quotes expire quickly (30-60s). Always get a fresh quote before executing.",
+        "  - Some routes require token approval before the bridge tx. bridge_execute will",
+        "    return both an approvalTransaction and the main transaction when needed.",
+        "  - Ensure you have enough native gas token on the source chain.",
+        "  - Token symbols are resolved against a verified registry. If a symbol is not found,",
+        "    use the raw contract address instead.",
+        "",
+        "Example: Bridge 100 USDC from Base to Arbitrum:",
+        "  1. bridge_get_quote(fromChain='base', toChain='arbitrum', fromToken='USDC',",
+        "     toToken='USDC', amount='100', fromAddress='0x...')",
+        "  2. bridge_execute(quoteId='<from step 1>')",
+        "  3. Sign and send the returned transaction(s)",
+        "  4. bridge_status(trackingId='<from step 2>')",
+    ].join("\n"),
+    farming: [
+        "XPRT Farming Guide",
+        "===================",
+        "",
+        "Earn XPRT rewards by bridging BTC variants (cbBTC <> BTCB) via Persistence Interop.",
+        "",
+        "Recommended flow:",
+        "  1. xprt_farm_prepare - Convert ETH or other tokens to cbBTC and bridge gas to BSC.",
+        "  2. xprt_farm_start   - Run automated BTC round-trip swaps to accumulate volume.",
+        "  3. xprt_farm_status  - Check wallet link status, balances, and current epoch info.",
+        "  4. xprt_rewards_check - View earned XPRT rewards, pending amounts, and multiplier tier.",
+        "",
+        "Multiplier Tiers:",
+        "  - Explorer (1x): Default, no staking required",
+        "  - Voyager (2x): Stake ≥ 10,000 XPRT",
+        "  - Pioneer (5x): Stake ≥ 1,000,000 XPRT",
+        "",
+        "Staking tools to boost multiplier:",
+        "  - xprt_stake: Delegate existing liquid XPRT to a validator",
+        "  - xprt_unstake: Initiate unbonding of staked XPRT (21-day period)",
+        "  - xprt_claim_rewards: Claim pending staking rewards",
+        "  - xprt_farm_boost: Buy and auto-stake XPRT from ETH or other tokens",
+        "",
+        "Use xprt_stake to delegate XPRT and increase your multiplier.",
+        "",
+        "Quick start with xprt_onboard:",
+        "  Run xprt_onboard for a personalized action plan based on your current wallet state.",
+        "",
+        "Key details:",
+        "  - Minimum per-leg amount: 0.00005 BTC (~$5 at current prices).",
+        "  - Maximum per-leg amount: 0.001 BTC (~$100 at current prices).",
+        "  - Rewards are distributed daily as airdrops (estimated, not guaranteed).",
+        "  - You need gas on both Base (ETH) and BSC (BNB) for round-trip farming.",
+        "  - Link your Persistence address to receive XPRT rewards.",
+        "",
+        "Common pitfalls:",
+        "  - Running out of gas on BSC (BNB) is the most common issue. xprt_farm_prepare",
+        "    automatically bridges some ETH to BNB for gas.",
+        "  - If rounds time out, the solver may be congested. Increase fillTimeout or try later.",
+        "  - Loss protection: xprt_farm_start has maxLossBps (default 200 = 2%) and maxFailures",
+        "    (default 3) to prevent excessive losses.",
+    ].join("\n"),
+    wallet: [
+        "Wallet Management Guide",
+        "=======================",
+        "",
+        "Recommended flow:",
+        "  1. wallet_status   - Check if a wallet is already configured.",
+        "  2. wallet_setup    - Generate new wallets for all chains (EVM + Cosmos + Solana).",
+        "     OR wallet_import - Import existing mnemonic or private key.",
+        "  3. wallet_balance  - Check balances across all configured chains.",
+        "",
+        "Key details:",
+        "  - Keys are stored in ~/.bridgekitty/.env (or BRIDGEKITTY_HOME env var).",
+        "  - A single mnemonic derives wallets for all chains:",
+        "    - EVM: BIP-44 path m/44'/60'/0'/0/0 (same address on all EVM chains).",
+        "    - Cosmos: persistence prefix for Persistence chain.",
+        "    - Solana: BIP-44 path m/44'/501'/0'/0'.",
+        "  - wallet_setup refuses to overwrite existing keys (safety feature).",
+        "  - wallet_import with overwrite=true will replace existing keys (back up first!).",
+        "",
+        "Security notes:",
+        "  - Keys are loaded into an in-memory store at startup and cleared from process.env.",
+        "  - The .env file should have 0600 permissions (owner read/write only).",
+        "  - Never share your mnemonic or private key.",
+        "  - Back up your .env file immediately after wallet creation.",
+        "",
+        "Common pitfalls:",
+        "  - Forgetting to back up keys before overwriting.",
+        "  - Running wallet_setup when keys already exist (it will refuse -- use wallet_import).",
+        "  - Importing only a privateKey gives EVM-only access. Use a mnemonic for full multi-chain support.",
+    ].join("\n"),
+    troubleshooting: [
+        "Troubleshooting Guide",
+        "=====================",
+        "",
+        "Rate Limits:",
+        "  - bridge_get_quote is limited to 10 requests per route per minute.",
+        "  - If you hit rate limits, wait 60 seconds before retrying the same route.",
+        "  - Different routes have independent rate limits.",
+        "",
+        "RPC Timeouts:",
+        "  - BridgeKitty uses multiple RPCs per chain with automatic failover.",
+        "  - If you see RPC timeout errors, the chain may be congested. Retry after a few minutes.",
+        "  - wallet_balance may show 'error' for individual chains while others succeed.",
+        "",
+        "Token Not Found:",
+        "  - Token symbols are resolved against a curated verified registry.",
+        "  - If a symbol is not found, use the raw contract address (0x...) instead.",
+        "  - Common aliases: 'ETH' works on all L2s, 'BNB' on BSC, 'MATIC'/'POL' on Polygon.",
+        "",
+        "No Routes Found:",
+        "  - Some token pairs or chain combinations may not be supported by any backend.",
+        "  - Try bridge_quote_multi for routes that need intermediate hops.",
+        "  - Check bridge_chains and bridge_tokens to verify chain/token support.",
+        "",
+        "Transaction Simulation Failed:",
+        "  - The bridge transaction would revert on-chain. Common causes:",
+        "    - Insufficient token balance or allowance.",
+        "    - Quote expired (get a fresh quote).",
+        "    - Insufficient gas (native token balance too low).",
+        "  - Always get a fresh quote and try again.",
+        "",
+        "XPRT Farming Issues:",
+        "  - 'Insufficient BTC balance': Run xprt_farm_prepare or send BTC to your wallet.",
+        "  - 'Balance below minimum': You need at least 0.00005 BTC per leg.",
+        "  - Timeouts during farming: Increase fillTimeout parameter (default 180s).",
+        "  - High loss: Adjust maxLossBps or reduce round count.",
+        "",
+        "Circuit Breaker:",
+        "  - Backends that fail repeatedly are temporarily disabled (circuit broken).",
+        "  - They automatically recover after a cooldown period.",
+        "  - If all backends are down, wait a few minutes and retry.",
+    ].join("\n"),
+};
+export function registerHelpTool(server) {
+    server.tool("bridgekitty_help", "Get help and guidance on using BridgeKitty. Topics: overview (default), bridging, farming, wallet, troubleshooting. " +
+        "Returns structured guides with recommended tool sequences and common pitfalls.", {
+        topic: z
+            .enum(["overview", "bridging", "farming", "wallet", "troubleshooting"])
+            .optional()
+            .default("overview")
+            .describe("Help topic: 'overview', 'bridging', 'farming', 'wallet', or 'troubleshooting'"),
+    }, async (params) => {
+        const topic = params.topic ?? "overview";
+        const content = HELP_CONTENT[topic];
+        if (!content) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Unknown topic: ${topic}. Available topics: overview, bridging, farming, wallet, troubleshooting.`,
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        topic,
+                        guide: content,
+                        availableTopics: ["overview", "bridging", "farming", "wallet", "troubleshooting"],
+                    }, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/multi-quote.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 registerMultiQuote(server: McpServer, engine: RoutingEngine): void;

package/dist/tools/multi-quote.js

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import { resolveChainId, getChainName } from "../utils/chains.js";
+import { resolveToken } from "../utils/token-registry.js";
+import { parseTokenAmount } from "../utils/tokens.js";
+// Common intermediary tokens used for multi-hop routing
+const INTERMEDIARIES = [
+    { symbol: "USDC", label: "USDC" },
+    { symbol: "ETH", label: "ETH" },
+    { symbol: "CBBTC", label: "cbBTC" },
+    { symbol: "WBTC", label: "WBTC" },
+];
+export function registerMultiQuote(server, engine) {
+    server.tool("bridge_quote_multi", "Get quotes for multi-hop routes across supported EVM chains. Resolves optimal path internally " +
+        "-- e.g., ETH on Base to USDC on Arbitrum may route through WBTC. Returns the full route " +
+        "as ordered hops with per-hop detail. " +
+        "Note: For Cosmos destinations (Persistence, Cosmos Hub), use xprt_farm_boost or bridge_get_quote with Squid Router.", {
+        fromChain: z
+            .string()
+            .describe("Source chain (e.g. 'base', 'ethereum', or chain ID like '8453')"),
+        fromToken: z
+            .string()
+            .describe("Token to send -- symbol (e.g. 'USDC', 'ETH') or contract address (0x...)"),
+        toChain: z
+            .string()
+            .describe("Destination chain (e.g. 'arbitrum', 'bsc', or chain ID)"),
+        toToken: z
+            .string()
+            .describe("Token to receive -- symbol (e.g. 'USDC', 'ETH') or contract address (0x...)"),
+        amount: z
+            .string()
+            .describe("Amount in human-readable units (e.g. '100' for 100 USDC)"),
+        fromAddress: z
+            .string()
+            .describe("Sender wallet address (0x...)"),
+        optimize: z
+            .enum(["cheapest", "fastest"])
+            .default("cheapest")
+            .describe("Optimize for lowest cost or fastest delivery"),
+    }, async (params) => {
+        // Resolve chains
+        const fromChainId = resolveChainId(params.fromChain);
+        const toChainId = resolveChainId(params.toChain);
+        if (!fromChainId) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Unknown source chain: ${params.fromChain}. Use chain name (e.g. 'base') or ID (e.g. '8453').`,
+                    }],
+                isError: true,
+            };
+        }
+        if (!toChainId) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Unknown destination chain: ${params.toChain}. Use chain name (e.g. 'arbitrum') or ID.`,
+                    }],
+                isError: true,
+            };
+        }
+        // Resolve tokens
+        const fromTokenResult = resolveToken(params.fromToken, fromChainId);
+        if (!fromTokenResult.ok) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Token resolution failed",
+                            token: params.fromToken,
+                            chain: getChainName(fromChainId),
+                            message: fromTokenResult.error,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const toTokenResult = resolveToken(params.toToken, toChainId);
+        if (!toTokenResult.ok) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Token resolution failed",
+                            token: params.toToken,
+                            chain: getChainName(toChainId),
+                            message: toTokenResult.error,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const fromTokenAddress = fromTokenResult.address;
+        const toTokenAddress = toTokenResult.address;
+        const fromDecimals = fromTokenResult.decimals;
+        const toDecimals = toTokenResult.decimals;
+        const fromSymbol = fromTokenResult.symbol;
+        const toSymbol = toTokenResult.symbol;
+        // Validate amount
+        const amountTrimmed = params.amount.trim();
+        if (!amountTrimmed || !/^\d+\.?\d*$/.test(amountTrimmed)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid amount",
+                            message: `Amount must be a positive number. Got: "${params.amount}"`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const amountRaw = parseTokenAmount(amountTrimmed, fromDecimals);
+        const routes = [];
+        // ── Strategy 1: Try direct route ────────────────────────────────────────
+        try {
+            const directQuotes = await engine.getQuotes({
+                fromChainId,
+                toChainId,
+                fromTokenAddress,
+                toTokenAddress,
+                amountRaw,
+                fromAddress: params.fromAddress,
+                preference: params.optimize,
+                fromTokenDecimals: fromDecimals,
+                toTokenDecimals: toDecimals,
+            });
+            for (const q of directQuotes.slice(0, 2)) {
+                routes.push({
+                    hops: [{
+                            hopNumber: 1,
+                            provider: q.provider,
+                            fromChain: getChainName(fromChainId),
+                            toChain: getChainName(toChainId),
+                            fromToken: fromSymbol,
+                            toToken: toSymbol,
+                            estimatedOutput: q.minOutputAmount,
+                            estimatedFeeUsd: q.estimatedFeeUsd,
+                            estimatedTimeSeconds: q.estimatedTimeSeconds,
+                        }],
+                    estimatedOutput: `${q.minOutputAmount} ${toSymbol}`,
+                    totalFeeUsd: q.estimatedFeeUsd,
+                    estimatedTotalTimeSeconds: `${q.estimatedTimeSeconds}s`,
+                    routeLabel: `Direct: ${fromSymbol} -> ${toSymbol} via ${q.provider}`,
+                });
+            }
+        }
+        catch {
+            // Direct route failed -- continue to multi-hop
+        }
+        // ── Strategy 2: Try 2-hop routes via intermediaries ─────────────────────
+        if (routes.length < 3) {
+            const intermediaryPromises = INTERMEDIARIES
+                .filter((mid) => {
+                // Skip if intermediary is the same as source or destination token
+                return mid.symbol.toUpperCase() !== fromSymbol.toUpperCase() &&
+                    mid.symbol.toUpperCase() !== toSymbol.toUpperCase();
+            })
+                .map(async (mid) => {
+                try {
+                    // Resolve intermediary on source chain (for hop 1 destination)
+                    const midOnSourceResult = resolveToken(mid.symbol, fromChainId);
+                    if (!midOnSourceResult.ok)
+                        return null;
+                    // Resolve intermediary on destination chain (for hop 2 source)
+                    const midOnDestResult = resolveToken(mid.symbol, toChainId);
+                    if (!midOnDestResult.ok)
+                        return null;
+                    // Hop 1: fromToken on fromChain -> intermediary on fromChain (same-chain swap)
+                    // Then cross-chain: intermediary fromChain -> intermediary toChain
+                    // For simplicity, try direct cross-chain: fromToken -> intermediary on toChain
+                    // Then intermediary -> toToken on toChain
+                    // Hop 1: fromToken -> midToken cross-chain (fromChain -> toChain)
+                    let hop1Quotes;
+                    try {
+                        hop1Quotes = await engine.getQuotes({
+                            fromChainId,
+                            toChainId,
+                            fromTokenAddress,
+                            toTokenAddress: midOnDestResult.address,
+                            amountRaw,
+                            fromAddress: params.fromAddress,
+                            preference: params.optimize,
+                            fromTokenDecimals: fromDecimals,
+                            toTokenDecimals: midOnDestResult.decimals,
+                        });
+                    }
+                    catch {
+                        return null;
+                    }
+                    if (!hop1Quotes || hop1Quotes.length === 0)
+                        return null;
+                    const hop1 = hop1Quotes[0];
+                    // Hop 2: midToken -> toToken on toChain (same-chain swap)
+                    const hop1OutputRaw = hop1.minOutputAmountRaw;
+                    let hop2Quotes;
+                    try {
+                        hop2Quotes = await engine.getQuotes({
+                            fromChainId: toChainId,
+                            toChainId: toChainId,
+                            fromTokenAddress: midOnDestResult.address,
+                            toTokenAddress,
+                            amountRaw: hop1OutputRaw,
+                            fromAddress: params.fromAddress,
+                            preference: params.optimize,
+                            fromTokenDecimals: midOnDestResult.decimals,
+                            toTokenDecimals: toDecimals,
+                        });
+                    }
+                    catch {
+                        // Same-chain swap may not be supported by cross-chain engine
+                        return null;
+                    }
+                    if (!hop2Quotes || hop2Quotes.length === 0)
+                        return null;
+                    const hop2 = hop2Quotes[0];
+                    const totalTimeSec = hop1.estimatedTimeSeconds + hop2.estimatedTimeSeconds;
+                    const fee1 = hop1.estimatedFeeUsd;
+                    const fee2 = hop2.estimatedFeeUsd;
+                    const totalFeeUsd = (fee1 !== null && fee2 !== null) ? fee1 + fee2 : null;
+                    return {
+                        hops: [
+                            {
+                                hopNumber: 1,
+                                provider: hop1.provider,
+                                fromChain: getChainName(fromChainId),
+                                toChain: getChainName(toChainId),
+                                fromToken: fromSymbol,
+                                toToken: mid.label,
+                                estimatedOutput: hop1.minOutputAmount,
+                                estimatedFeeUsd: hop1.estimatedFeeUsd,
+                                estimatedTimeSeconds: hop1.estimatedTimeSeconds,
+                            },
+                            {
+                                hopNumber: 2,
+                                provider: hop2.provider,
+                                fromChain: getChainName(toChainId),
+                                toChain: getChainName(toChainId),
+                                fromToken: mid.label,
+                                toToken: toSymbol,
+                                estimatedOutput: hop2.minOutputAmount,
+                                estimatedFeeUsd: hop2.estimatedFeeUsd,
+                                estimatedTimeSeconds: hop2.estimatedTimeSeconds,
+                            },
+                        ],
+                        estimatedOutput: `${hop2.minOutputAmount} ${toSymbol}`,
+                        totalFeeUsd,
+                        estimatedTotalTimeSeconds: `${totalTimeSec}s`,
+                        routeLabel: `${fromSymbol} -> ${mid.label} -> ${toSymbol} via ${hop1.provider} + ${hop2.provider}`,
+                    };
+                }
+                catch {
+                    return null;
+                }
+            });
+            const intermediaryResults = await Promise.allSettled(intermediaryPromises);
+            for (const result of intermediaryResults) {
+                if (result.status === "fulfilled" && result.value) {
+                    routes.push(result.value);
+                }
+            }
+        }
+        if (routes.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "No routes found",
+                            message: `No direct or multi-hop routes found for ${params.amount} ${fromSymbol} from ${getChainName(fromChainId)} to ${toSymbol} on ${getChainName(toChainId)}. This route may not be supported.`,
+                            suggestions: [
+                                "Try different token pairs (e.g. bridge to USDC first, then swap).",
+                                "Check bridge_chains and bridge_tokens for supported chains/tokens.",
+                                "Use bridge_get_quote for direct single-hop routes.",
+                            ],
+                        }, null, 2),
+                    }],
+            };
+        }
+        // Sort routes by optimization preference
+        if (params.optimize === "cheapest") {
+            routes.sort((a, b) => {
+                // Parse output amounts for comparison (higher is better)
+                const outA = parseFloat(a.estimatedOutput) || 0;
+                const outB = parseFloat(b.estimatedOutput) || 0;
+                return outB - outA;
+            });
+        }
+        else {
+            routes.sort((a, b) => {
+                const timeA = parseInt(a.estimatedTotalTimeSeconds) || 0;
+                const timeB = parseInt(b.estimatedTotalTimeSeconds) || 0;
+                return timeA - timeB;
+            });
+        }
+        // Limit to top 3
+        const topRoutes = routes.slice(0, 3);
+        const response = {
+            routes: topRoutes,
+            totalRoutesFound: routes.length,
+            optimizedFor: params.optimize,
+            summary: `Found ${routes.length} route(s) for ${params.amount} ${fromSymbol} (${getChainName(fromChainId)}) -> ${toSymbol} (${getChainName(toChainId)}). Best: ${topRoutes[0].routeLabel}, output: ${topRoutes[0].estimatedOutput}.`,
+            note: "Multi-hop routes require executing each hop sequentially. Use bridge_get_quote + bridge_execute for each hop.",
+        };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(response, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/onboard.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 registerOnboardTool(server: McpServer, engine: RoutingEngine): void;