@persistenceone/bridgekitty 0.3.0

package/dist/backends/lifi.js

@@ -0,0 +1,295 @@
+import { formatTokenAmount } from "../utils/tokens.js";
+import { buildApproveData } from "../utils/evm.js";
+import { sanitizeError } from "../utils/sanitize-error.js";
+const BASE_URL = "https://li.quest/v1";
+const TIMEOUT_MS = 30_000;
+async function fetchJson(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { ...init, signal: controller.signal });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`LI.FI ${res.status}: ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class LiFiBackend {
+    name = "lifi";
+    apiKey;
+    integrator;
+    integratorFee;
+    constructor(apiKey, integrator, integratorFee) {
+        this.apiKey = apiKey;
+        this.integrator = integrator;
+        this.integratorFee = integratorFee;
+    }
+    headers() {
+        const h = { Accept: "application/json" };
+        if (this.apiKey)
+            h["x-lifi-api-key"] = this.apiKey;
+        return h;
+    }
+    async getQuote(params) {
+        const quotes = await this.getQuotes(params);
+        return quotes.length > 0 ? quotes[0] : null;
+    }
+    /**
+     * Fetch multiple routes via LI.FI /advanced/routes endpoint.
+     * Returns up to 5 route options with full fee breakdowns.
+     */
+    async getQuotes(params) {
+        try {
+            const body = {
+                fromChainId: params.fromChainId,
+                toChainId: params.toChainId,
+                fromTokenAddress: params.fromTokenAddress,
+                toTokenAddress: params.toTokenAddress,
+                fromAmount: params.amountRaw,
+                fromAddress: params.fromAddress,
+                toAddress: params.toAddress || params.fromAddress,
+                options: {
+                    order: params.preference === "fastest" ? "FASTEST" : "CHEAPEST",
+                    slippage: 0.03,
+                    maxPriceImpact: 0.4,
+                    allowSwitchChain: false,
+                },
+            };
+            if (this.integrator) {
+                body.options.integrator = this.integrator;
+                if (this.integratorFee)
+                    body.options.fee = parseFloat(this.integratorFee);
+            }
+            let data;
+            try {
+                data = await fetchJson(`${BASE_URL}/advanced/routes`, {
+                    method: "POST",
+                    headers: { ...this.headers(), "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (err) {
+                // If fee param caused the error, retry without it
+                if (this.integratorFee && body.options?.fee !== undefined) {
+                    console.warn("[lifi] quote failed with integrator fee, retrying without fee:", err.message);
+                    delete body.options.fee;
+                    data = await fetchJson(`${BASE_URL}/advanced/routes`, {
+                        method: "POST",
+                        headers: { ...this.headers(), "Content-Type": "application/json" },
+                        body: JSON.stringify(body),
+                    });
+                }
+                else {
+                    throw err;
+                }
+            }
+            const routes = data.routes ?? [];
+            if (routes.length === 0)
+                return [];
+            // Filter to single-step routes only — our buildTransaction() only handles step[0],
+            // so multi-step routes would silently drop subsequent steps. Let LI.FI handle
+            // complex multi-hop routes internally; we only expose atomic single-step bridges.
+            const singleStepRoutes = routes.filter((r) => (r.steps?.length ?? 0) === 1);
+            if (singleStepRoutes.length === 0)
+                return [];
+            const integratorFeePercent = this.integratorFee
+                ? `${(parseFloat(this.integratorFee) * 100).toFixed(1)}%`
+                : null;
+            return singleStepRoutes.slice(0, 5).map((route) => {
+                const steps = route.steps ?? [];
+                const firstStep = steps[0];
+                const lastStep = steps[steps.length - 1];
+                // Fee breakdown from route data
+                const gasCostUsd = route.gasCostUSD ? parseFloat(route.gasCostUSD) : 0;
+                // Extract protocol fees from step fee costs
+                let protocolFeeUsd = 0;
+                let integratorFeeUsd = 0;
+                for (const step of steps) {
+                    const estimate = step.estimate ?? {};
+                    const feeCosts = estimate.feeCosts ?? [];
+                    for (const fee of feeCosts) {
+                        const usd = parseFloat(fee.amountUSD || "0");
+                        if (fee.name?.toLowerCase().includes("integrator") ||
+                            fee.name?.toLowerCase().includes("affiliate")) {
+                            integratorFeeUsd += usd;
+                        }
+                        else {
+                            protocolFeeUsd += usd;
+                        }
+                    }
+                }
+                const totalFeeUsd = gasCostUsd + protocolFeeUsd + integratorFeeUsd;
+                const feeBreakdown = {
+                    gasCostUsd: Math.round(gasCostUsd * 100) / 100,
+                    protocolFeeUsd: Math.round(protocolFeeUsd * 100) / 100,
+                    integratorFeeUsd: Math.round(integratorFeeUsd * 100) / 100,
+                    integratorFeePercent,
+                    totalFeeUsd: Math.round(totalFeeUsd * 100) / 100,
+                };
+                // Build human-readable route description
+                const toolNames = steps
+                    .map((s) => s.toolDetails?.name ?? s.tool ?? "?")
+                    .join(" → ");
+                const fromSymbol = firstStep?.action?.fromToken?.symbol ?? "?";
+                const toSymbol = lastStep?.action?.toToken?.symbol ?? "?";
+                const toDecimals = lastStep?.action?.toToken?.decimals ?? 18;
+                // Extract minimum output amount (after slippage)
+                // LI.FI provides toAmountMin at the route level
+                const minOutputRaw = route.toAmountMin ?? route.toAmount ?? "0";
+                return {
+                    backendName: "lifi",
+                    provider: `${toolNames} via LI.FI`,
+                    outputAmount: route.toAmount
+                        ? formatTokenAmount(route.toAmount, toDecimals)
+                        : "0",
+                    outputAmountRaw: route.toAmount ?? "0",
+                    minOutputAmount: formatTokenAmount(minOutputRaw, toDecimals),
+                    minOutputAmountRaw: minOutputRaw,
+                    outputDecimals: toDecimals,
+                    estimatedGasCostUsd: Math.round(gasCostUsd * 100) / 100,
+                    estimatedFeeUsd: totalFeeUsd,
+                    feeBreakdown,
+                    estimatedTimeSeconds: steps.reduce((sum, s) => sum + (s.estimate?.executionDuration ?? 0), 0) || 300,
+                    route: `${fromSymbol} → ${toolNames} → ${toSymbol}`,
+                    quoteData: route,
+                    // LI.FI quotes are volatile (DEX prices shift rapidly) — use 30s expiry
+                    expiresAt: Date.now() + 60_000,
+                };
+            });
+        }
+        catch (err) {
+            console.error("[lifi] advanced/routes error:", err.message);
+            return [];
+        }
+    }
+    async buildTransaction(quote) {
+        const route = quote.quoteData;
+        // For /advanced/routes, get step transaction from the first step
+        const step = route.steps?.[0];
+        if (!step)
+            throw new Error("No steps in LI.FI route");
+        // Call /advanced/stepTransaction to get the actual tx data
+        const stepData = await fetchJson(`${BASE_URL}/advanced/stepTransaction`, {
+            method: "POST",
+            headers: { ...this.headers(), "Content-Type": "application/json" },
+            body: JSON.stringify(step),
+        });
+        const txReq = stepData.transactionRequest;
+        if (!txReq)
+            throw new Error("No transactionRequest in LI.FI step response");
+        const toolName = step.tool ?? step.toolDetails?.name ?? "unknown";
+        const result = {
+            to: txReq.to,
+            data: txReq.data,
+            value: txReq.value ?? "0x0",
+            chainId: txReq.chainId,
+            gasLimit: txReq.gasLimit,
+            provider: "lifi",
+            trackingId: `lifi:${toolName}:${Date.now()}`,
+        };
+        // Check if approval is needed
+        const estimate = stepData.estimate ?? step.estimate;
+        const action = stepData.action ?? step.action;
+        if (estimate?.approvalAddress && action?.fromToken?.address) {
+            const tokenAddr = action.fromToken.address;
+            // Non-native tokens may need approval
+            if (tokenAddr !== "0x0000000000000000000000000000000000000000") {
+                // MEDIUM-001: Sanity-check approval amount against quoted input
+                let approvalAmount = action.fromAmount;
+                const quotedInput = route.steps?.[0]?.action?.fromAmount ?? route.fromAmount;
+                if (quotedInput && approvalAmount) {
+                    const approvalBn = BigInt(approvalAmount);
+                    const quotedBn = BigInt(quotedInput);
+                    const maxAllowed = (quotedBn * 110n) / 100n; // 110% of quoted
+                    if (approvalBn > maxAllowed) {
+                        console.warn(`[lifi] Approval amount ${approvalAmount} exceeds 110% of quoted input ${quotedInput}. Capping to ${maxAllowed.toString()}.`);
+                        approvalAmount = maxAllowed.toString();
+                    }
+                }
+                result.approvalTx = {
+                    to: tokenAddr,
+                    data: buildApproveData(estimate.approvalAddress, approvalAmount),
+                    value: "0x0",
+                    chainId: txReq.chainId,
+                };
+            }
+        }
+        return result;
+    }
+    async getStatus(trackingId, meta) {
+        try {
+            const txHash = meta?.txHash;
+            const fromChain = meta?.fromChain;
+            const toChain = meta?.toChain;
+            if (!txHash) {
+                return {
+                    state: "unknown",
+                    humanReadable: "No transaction hash provided for status check",
+                    provider: "lifi",
+                    elapsed: 0,
+                };
+            }
+            const url = new URL(`${BASE_URL}/status`);
+            url.searchParams.set("txHash", txHash);
+            if (fromChain)
+                url.searchParams.set("fromChain", fromChain);
+            if (toChain)
+                url.searchParams.set("toChain", toChain);
+            const data = await fetchJson(url.toString(), { headers: this.headers() });
+            const stateMap = {
+                NOT_FOUND: "pending",
+                PENDING: "pending",
+                DONE: "completed",
+                FAILED: "failed",
+            };
+            const elapsed = data.sending?.timestamp
+                ? Math.floor((Date.now() - data.sending.timestamp * 1000) / 1000)
+                : 0;
+            return {
+                state: stateMap[data.status] ?? "in_progress",
+                humanReadable: `Bridge via ${data.tool ?? "LI.FI"}: ${data.status ?? "unknown"}${data.substatus ? ` (${data.substatus})` : ""}`,
+                sourceTxHash: data.sending?.txHash,
+                destTxHash: data.receiving?.txHash,
+                provider: "lifi",
+                elapsed,
+            };
+        }
+        catch (err) {
+            return {
+                state: "unknown",
+                humanReadable: `Status check failed: ${sanitizeError(err)}`,
+                provider: "lifi",
+                elapsed: 0,
+            };
+        }
+    }
+    async getSupportedChains() {
+        const data = await fetchJson(`${BASE_URL}/chains`, {
+            headers: this.headers(),
+        });
+        return (data.chains ?? []).map((c) => ({
+            id: c.id,
+            name: c.name,
+            key: c.key,
+            logoURI: c.logoURI,
+            providers: ["lifi"],
+        }));
+    }
+    async getSupportedTokens(chainId) {
+        const data = await fetchJson(`${BASE_URL}/tokens?chains=${chainId}`, { headers: this.headers() });
+        const tokens = data.tokens?.[String(chainId)] ?? [];
+        return tokens.slice(0, 50).map((t) => ({
+            symbol: t.symbol,
+            name: t.name,
+            address: t.address,
+            decimals: t.decimals,
+            chainId: t.chainId,
+            logoURI: t.logoURI,
+        }));
+    }
+}
+// buildApproveData imported from ../utils/evm.js

package/dist/backends/persistence.d.ts

@@ -0,0 +1,86 @@
+import { ethers } from "ethers";
+import type { BridgeBackend, BridgeQuote, BridgeStatus, ChainInfo, QuoteParams, TransactionRequest } from "./types.js";
+import { BackendValidationError } from "./types.js";
+/**
+ * @deprecated Use BackendValidationError from types.ts instead.
+ * Kept as re-export for backward compatibility.
+ */
+export declare const PersistenceValidationError: typeof BackendValidationError;
+declare const PERMIT2_WITNESS_TYPES: {
+    CrossChainOrder: {
+        name: string;
+        type: string;
+    }[];
+    PermitWitnessTransferFrom: {
+        name: string;
+        type: string;
+    }[];
+    TokenPermissions: {
+        name: string;
+        type: string;
+    }[];
+};
+/** Prepared order data ready for signing */
+export interface PreparedOrder {
+    order: {
+        settlementContract: string;
+        swapper: string;
+        nonce: bigint;
+        originChainId: number;
+        initiateDeadline: number;
+        fillDeadline: number;
+        orderData: string;
+    };
+    eip712Domain: {
+        name: string;
+        chainId: number;
+        verifyingContract: string;
+    };
+    eip712Types: typeof PERMIT2_WITNESS_TYPES;
+    eip712Value: Record<string, unknown>;
+    inputToken: string;
+    inputAmount: string;
+    approvalTx: {
+        to: string;
+        data: string;
+        value: string;
+        chainId: number;
+    };
+}
+export declare class PersistenceBackend implements BridgeBackend {
+    name: string;
+    /**
+     * Validate amount against Persistence Interop caps.
+     * Caps are defined in 8-decimal BTC units (MIN_AMOUNT_RAW=5000, MAX_AMOUNT_RAW=100000).
+     * BTCB uses 18 decimals, cbBTC uses 8 decimals — normalize before comparing.
+     */
+    private validateAmount;
+    getQuote(params: QuoteParams): Promise<BridgeQuote | null>;
+    /**
+     * Prepare a CrossChainOrder for signing. This calls the settlement contract
+     * on-chain to get a properly formed order with nonce and orderData.
+     */
+    prepareOrder(quote: BridgeQuote, swapperAddress: string): Promise<PreparedOrder>;
+    /**
+     * Build transaction data for the MCP flow (no server-side signing).
+     * Calls prepareOrder() via on-chain view to get the EIP-712 typed data
+     * and Permit2 approval tx that the agent/wallet must sign externally.
+     *
+     * Use signAndExecute() for flows where a signer (private key) is available.
+     */
+    buildTransaction(quote: BridgeQuote): Promise<TransactionRequest>;
+    /**
+     * Full sign-and-execute flow for when a signer (private key) is available.
+     * This is used by test scripts and the ACP listener.
+     *
+     * Returns the source chain tx hash and order ID for tracking.
+     */
+    signAndExecute(quote: BridgeQuote, signer: ethers.Wallet): Promise<{
+        txHash: string;
+        orderId: string;
+        trackingId: string;
+    }>;
+    getStatus(trackingId: string, meta?: Record<string, string>): Promise<BridgeStatus>;
+    getSupportedChains(): Promise<ChainInfo[]>;
+}
+export {};