@veridex/agentic-payments 0.1.1-beta.1

package/src/performance/ParallelRouteFinder.ts

@@ -0,0 +1,438 @@
+/**
+ * @packageDocumentation
+ * @module ParallelRouteFinder
+ * @description
+ * High-performance engine for discovering cross-chain payment paths.
+ * 
+ * Instead of querying chains sequentially, this module:
+ * 1. Multicasts balance queries to all configured chains simultaneously.
+ * 2. Races requests against a configurable timeout (default 5s).
+ * 3. Aggregates results and scores them based on the User's preference (Speed vs Cost).
+ * 
+ * Result: Finds optimal routes in milliseconds rather than seconds.
+ */
+
+export interface ChainBalance {
+    chain: number;
+    chainName: string;
+    token: string;
+    balance: bigint;
+    balanceUSD: number;
+}
+
+export interface RouteCandidate {
+    id: string;
+    sourceChain: number;
+    targetChain: number;
+    sourceToken: string;
+    targetToken: string;
+    estimatedFeeUSD: number;
+    estimatedTimeMs: number;
+    hops: RouteHop[];
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+
+export interface RouteHop {
+    type: 'transfer' | 'bridge' | 'swap';
+    fromChain: number;
+    toChain: number;
+    fromToken: string;
+    toToken: string;
+    estimatedFeeUSD: number;
+    estimatedTimeMs: number;
+    protocol?: string;
+}
+
+export interface RouteFindingConfig {
+    /** Maximum time to wait for all queries in ms */
+    timeoutMs: number;
+    /** Number of top routes to return */
+    maxRoutes: number;
+    /** Whether to include swap routes */
+    includeSwaps: boolean;
+    /** Whether to include bridge routes */
+    includeBridges: boolean;
+    /** Maximum number of hops allowed */
+    maxHops: number;
+    /** Prefer speed over cost (0-1) */
+    speedPreference: number;
+}
+
+export interface ChainClient {
+    getChainId(): number;
+    getChainName(): string;
+    getBalance(address: string, token?: string): Promise<bigint>;
+    getTokenPriceUSD(token: string): Promise<number>;
+    estimateTransferFee(to: string, amount: string, token: string): Promise<bigint>;
+}
+
+export interface RouteFindingResult {
+    routes: RouteCandidate[];
+    balances: ChainBalance[];
+    queryTimeMs: number;
+    timedOut: boolean;
+    errors: Array<{ chain: number; error: string }>;
+}
+
+const DEFAULT_CONFIG: RouteFindingConfig = {
+    timeoutMs: 5000,
+    maxRoutes: 5,
+    includeSwaps: true,
+    includeBridges: true,
+    maxHops: 3,
+    speedPreference: 0.5,
+};
+
+// Cache for balance queries
+interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+
+export class ParallelRouteFinder {
+    private clients: Map<number, ChainClient> = new Map();
+    private config: RouteFindingConfig;
+    private balanceCache: Map<string, CacheEntry<ChainBalance>> = new Map();
+    private readonly CACHE_TTL_MS = 10000; // 10 seconds
+
+    constructor(
+        clients: ChainClient[],
+        config: Partial<RouteFindingConfig> = {}
+    ) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        for (const client of clients) {
+            this.clients.set(client.getChainId(), client);
+        }
+    }
+
+    /**
+     * Add a chain client.
+     */
+    addClient(client: ChainClient): void {
+        this.clients.set(client.getChainId(), client);
+    }
+
+    /**
+     * Remove a chain client.
+     */
+    removeClient(chainId: number): boolean {
+        return this.clients.delete(chainId);
+    }
+
+    /**
+     * Find optimal routes for a payment.
+     */
+    async findRoutes(
+        address: string,
+        targetChain: number,
+        targetToken: string,
+        amountUSD: number,
+        options: Partial<RouteFindingConfig> = {}
+    ): Promise<RouteFindingResult> {
+        const config = { ...this.config, ...options };
+        const startTime = Date.now();
+        const errors: Array<{ chain: number; error: string }> = [];
+
+        // Create timeout promise
+        const timeoutPromise = new Promise<'timeout'>((resolve) =>
+            setTimeout(() => resolve('timeout'), config.timeoutMs)
+        );
+
+        // Query all balances in parallel
+        const balancePromises = Array.from(this.clients.entries()).map(
+            async ([chainId, client]): Promise<ChainBalance | null> => {
+                // Check cache first
+                const cacheKey = `${address}:${chainId}:${targetToken}`;
+                const cached = this.balanceCache.get(cacheKey);
+                if (cached && cached.expiresAt > Date.now()) {
+                    return cached.value;
+                }
+
+                try {
+                    const [balance, priceUSD] = await Promise.all([
+                        client.getBalance(address, targetToken),
+                        client.getTokenPriceUSD(targetToken),
+                    ]);
+
+                    const result: ChainBalance = {
+                        chain: chainId,
+                        chainName: client.getChainName(),
+                        token: targetToken,
+                        balance,
+                        balanceUSD: Number(balance) * priceUSD / 1e6, // Assuming 6 decimals
+                    };
+
+                    // Cache the result
+                    this.balanceCache.set(cacheKey, {
+                        value: result,
+                        expiresAt: Date.now() + this.CACHE_TTL_MS,
+                    });
+
+                    return result;
+                } catch (error) {
+                    errors.push({
+                        chain: chainId,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    });
+                    return null;
+                }
+            }
+        );
+
+        // Race against timeout
+        const balanceResults = await Promise.race([
+            Promise.all(balancePromises),
+            timeoutPromise,
+        ]);
+
+        let timedOut = false;
+        let balances: ChainBalance[];
+
+        if (balanceResults === 'timeout') {
+            timedOut = true;
+            // Get whatever results we have so far
+            balances = [];
+            for (const [chainId] of this.clients) {
+                const cacheKey = `${address}:${chainId}:${targetToken}`;
+                const cached = this.balanceCache.get(cacheKey);
+                if (cached) {
+                    balances.push(cached.value);
+                }
+            }
+        } else {
+            balances = balanceResults.filter((b): b is ChainBalance => b !== null);
+        }
+
+        // Find candidate routes
+        const routes = await this.generateRoutes(
+            balances,
+            targetChain,
+            targetToken,
+            amountUSD,
+            config
+        );
+
+        // Sort routes by score (lower is better)
+        routes.sort((a, b) => a.score - b.score);
+
+        return {
+            routes: routes.slice(0, config.maxRoutes),
+            balances,
+            queryTimeMs: Date.now() - startTime,
+            timedOut,
+            errors,
+        };
+    }
+
+    /**
+     * Generate candidate routes from available balances.
+     */
+    private async generateRoutes(
+        balances: ChainBalance[],
+        targetChain: number,
+        targetToken: string,
+        amountUSD: number,
+        config: RouteFindingConfig
+    ): Promise<RouteCandidate[]> {
+        const routes: RouteCandidate[] = [];
+
+        // Filter balances with sufficient funds
+        const sufficientBalances = balances.filter(b => b.balanceUSD >= amountUSD);
+
+        for (const balance of sufficientBalances) {
+            // Direct transfer (same chain)
+            if (balance.chain === targetChain) {
+                const route = await this.createDirectRoute(
+                    balance,
+                    targetChain,
+                    targetToken,
+                    amountUSD,
+                    config
+                );
+                if (route) routes.push(route);
+            }
+            // Bridge route (cross-chain)
+            else if (config.includeBridges) {
+                const route = await this.createBridgeRoute(
+                    balance,
+                    targetChain,
+                    targetToken,
+                    amountUSD,
+                    config
+                );
+                if (route) routes.push(route);
+            }
+        }
+
+        return routes;
+    }
+
+    /**
+     * Create a direct transfer route.
+     */
+    private async createDirectRoute(
+        balance: ChainBalance,
+        targetChain: number,
+        targetToken: string,
+        amountUSD: number,
+        config: RouteFindingConfig
+    ): Promise<RouteCandidate | null> {
+        const client = this.clients.get(balance.chain);
+        if (!client) return null;
+
+        try {
+            // Estimate transfer fee
+            const fee = await client.estimateTransferFee(
+                '0x0000000000000000000000000000000000000000', // Placeholder recipient
+                String(BigInt(Math.floor(amountUSD * 1e6))),
+                targetToken
+            );
+
+            const feeUSD = Number(fee) / 1e18 * 2000; // Rough ETH to USD conversion
+
+            const hop: RouteHop = {
+                type: 'transfer',
+                fromChain: balance.chain,
+                toChain: targetChain,
+                fromToken: targetToken,
+                toToken: targetToken,
+                estimatedFeeUSD: feeUSD,
+                estimatedTimeMs: balance.chain === 1 ? 15000 : 2000, // L1 vs L2
+            };
+
+            return {
+                id: `direct_${balance.chain}_${targetChain}`,
+                sourceChain: balance.chain,
+                targetChain,
+                sourceToken: targetToken,
+                targetToken,
+                estimatedFeeUSD: feeUSD,
+                estimatedTimeMs: hop.estimatedTimeMs,
+                hops: [hop],
+                score: this.calculateScore(feeUSD, hop.estimatedTimeMs, config),
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Create a bridge route.
+     */
+    private async createBridgeRoute(
+        balance: ChainBalance,
+        targetChain: number,
+        targetToken: string,
+        amountUSD: number,
+        config: RouteFindingConfig
+    ): Promise<RouteCandidate | null> {
+        // Estimate bridge parameters
+        const bridgeFeeUSD = 2.5; // Typical Wormhole fee
+        const bridgeTimeMs = 180000; // 3 minutes typical
+
+        const hops: RouteHop[] = [
+            {
+                type: 'bridge',
+                fromChain: balance.chain,
+                toChain: targetChain,
+                fromToken: targetToken,
+                toToken: targetToken,
+                estimatedFeeUSD: bridgeFeeUSD,
+                estimatedTimeMs: bridgeTimeMs,
+                protocol: 'wormhole',
+            },
+        ];
+
+        const totalFeeUSD = hops.reduce((sum, h) => sum + h.estimatedFeeUSD, 0);
+        const totalTimeMs = hops.reduce((sum, h) => sum + h.estimatedTimeMs, 0);
+
+        return {
+            id: `bridge_${balance.chain}_${targetChain}`,
+            sourceChain: balance.chain,
+            targetChain,
+            sourceToken: targetToken,
+            targetToken,
+            estimatedFeeUSD: totalFeeUSD,
+            estimatedTimeMs: totalTimeMs,
+            hops,
+            score: this.calculateScore(totalFeeUSD, totalTimeMs, config),
+        };
+    }
+
+    /**
+     * Calculate route score (lower is better).
+     */
+    private calculateScore(
+        feeUSD: number,
+        timeMs: number,
+        config: RouteFindingConfig
+    ): number {
+        // Normalize fee (assume max fee of $10)
+        const normalizedFee = Math.min(feeUSD / 10, 1);
+
+        // Normalize time (assume max time of 5 minutes)
+        const normalizedTime = Math.min(timeMs / (5 * 60 * 1000), 1);
+
+        // Weighted score based on preference
+        const costWeight = 1 - config.speedPreference;
+        const speedWeight = config.speedPreference;
+
+        return normalizedFee * costWeight + normalizedTime * speedWeight;
+    }
+
+    /**
+     * Get all chain balances in parallel.
+     */
+    async getAllBalances(
+        address: string,
+        tokens: string[] = ['USDC']
+    ): Promise<ChainBalance[]> {
+        const promises: Promise<ChainBalance | null>[] = [];
+
+        for (const [chainId, client] of this.clients) {
+            for (const token of tokens) {
+                promises.push(
+                    (async () => {
+                        try {
+                            const [balance, priceUSD] = await Promise.all([
+                                client.getBalance(address, token),
+                                client.getTokenPriceUSD(token),
+                            ]);
+
+                            return {
+                                chain: chainId,
+                                chainName: client.getChainName(),
+                                token,
+                                balance,
+                                balanceUSD: Number(balance) * priceUSD / 1e6,
+                            };
+                        } catch {
+                            return null;
+                        }
+                    })()
+                );
+            }
+        }
+
+        const results = await Promise.all(promises);
+        return results.filter((r): r is ChainBalance => r !== null);
+    }
+
+    /**
+     * Clear balance cache.
+     */
+    clearCache(): void {
+        this.balanceCache.clear();
+    }
+
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): { size: number; hitRate: number } {
+        return {
+            size: this.balanceCache.size,
+            hitRate: 0, // Would need to track hits/misses
+        };
+    }
+}

package/src/performance/TransactionPoller.ts

@@ -0,0 +1,201 @@
+/**
+ * @packageDocumentation
+ * @module TransactionPoller
+ * @description
+ * Reliable transaction confirmation tracking.
+ * 
+ * Unlike standard `await tx.wait()`, this poller:
+ * - Does NOT block the main thread.
+ * - Polls for status updates in the background (every 2s).
+ * - Emits events (`pending`, `confirmed`, `failed`) for UI updates.
+ * - Handles long-running cross-chain epochs without timing out the application.
+ */
+
+export type TransactionStatus = 'pending' | 'confirmed' | 'failed' | 'timeout';
+
+export interface PendingTransaction {
+    txHash: string;
+    chain: number;
+    submittedAt: number;
+    status: TransactionStatus;
+    confirmations?: number;
+    blockNumber?: number;
+}
+
+export interface ConfirmationEvent {
+    txHash: string;
+    status: TransactionStatus;
+    confirmations?: number;
+    blockNumber?: number;
+    error?: string;
+}
+
+type ConfirmationCallback = (event: ConfirmationEvent) => void;
+
+export class TransactionPoller {
+    private pending: Map<string, PendingTransaction> = new Map();
+    private callbacks: Map<string, ConfirmationCallback[]> = new Map();
+    private globalCallbacks: ConfirmationCallback[] = [];
+    private pollInterval: ReturnType<typeof setInterval> | null = null;
+    private readonly POLL_INTERVAL_MS = 2000;
+    private readonly TIMEOUT_MS = 300000; // 5 minutes
+    private checkConfirmation: (txHash: string, chain: number) => Promise<{ confirmed: boolean; confirmations?: number; blockNumber?: number }>;
+
+    constructor(
+        confirmationChecker: (txHash: string, chain: number) => Promise<{ confirmed: boolean; confirmations?: number; blockNumber?: number }>
+    ) {
+        this.checkConfirmation = confirmationChecker;
+    }
+
+    /**
+     * Start tracking a transaction.
+     */
+    track(txHash: string, chain: number, callback?: ConfirmationCallback): void {
+        const tx: PendingTransaction = {
+            txHash,
+            chain,
+            submittedAt: Date.now(),
+            status: 'pending',
+        };
+        this.pending.set(txHash, tx);
+
+        if (callback) {
+            if (!this.callbacks.has(txHash)) {
+                this.callbacks.set(txHash, []);
+            }
+            this.callbacks.get(txHash)!.push(callback);
+        }
+
+        this.startPolling();
+    }
+
+    /**
+     * Subscribe to all confirmation events.
+     */
+    onConfirmation(callback: ConfirmationCallback): () => void {
+        this.globalCallbacks.push(callback);
+        return () => {
+            const index = this.globalCallbacks.indexOf(callback);
+            if (index > -1) {
+                this.globalCallbacks.splice(index, 1);
+            }
+        };
+    }
+
+    /**
+     * Get status of a tracked transaction.
+     */
+    getStatus(txHash: string): PendingTransaction | undefined {
+        return this.pending.get(txHash);
+    }
+
+    /**
+     * Get all pending transactions.
+     */
+    getPending(): PendingTransaction[] {
+        return Array.from(this.pending.values()).filter(tx => tx.status === 'pending');
+    }
+
+    /**
+     * Stop tracking a transaction.
+     */
+    untrack(txHash: string): void {
+        this.pending.delete(txHash);
+        this.callbacks.delete(txHash);
+        this.maybeStopPolling();
+    }
+
+    /**
+     * Start the polling loop.
+     */
+    private startPolling(): void {
+        if (this.pollInterval) return;
+
+        this.pollInterval = setInterval(() => {
+            this.poll();
+        }, this.POLL_INTERVAL_MS);
+    }
+
+    /**
+     * Stop polling if no pending transactions.
+     */
+    private maybeStopPolling(): void {
+        if (this.getPending().length === 0 && this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+    }
+
+    /**
+     * Poll all pending transactions.
+     */
+    private async poll(): Promise<void> {
+        const pending = this.getPending();
+
+        for (const tx of pending) {
+            try {
+                // Check for timeout
+                if (Date.now() - tx.submittedAt > this.TIMEOUT_MS) {
+                    this.updateStatus(tx.txHash, 'timeout');
+                    continue;
+                }
+
+                const result = await this.checkConfirmation(tx.txHash, tx.chain);
+
+                if (result.confirmed) {
+                    tx.confirmations = result.confirmations;
+                    tx.blockNumber = result.blockNumber;
+                    this.updateStatus(tx.txHash, 'confirmed');
+                }
+            } catch (error) {
+                console.error(`[TransactionPoller] Error checking ${tx.txHash}:`, error);
+                // Don't fail immediately on network errors, just log
+            }
+        }
+
+        this.maybeStopPolling();
+    }
+
+    /**
+     * Update transaction status and emit events.
+     */
+    private updateStatus(txHash: string, status: TransactionStatus, error?: string): void {
+        const tx = this.pending.get(txHash);
+        if (!tx) return;
+
+        tx.status = status;
+
+        const event: ConfirmationEvent = {
+            txHash,
+            status,
+            confirmations: tx.confirmations,
+            blockNumber: tx.blockNumber,
+            error,
+        };
+
+        // Notify specific callbacks
+        const callbacks = this.callbacks.get(txHash) || [];
+        callbacks.forEach(cb => cb(event));
+
+        // Notify global callbacks
+        this.globalCallbacks.forEach(cb => cb(event));
+
+        // Clean up completed transactions
+        if (status !== 'pending') {
+            this.callbacks.delete(txHash);
+        }
+    }
+
+    /**
+     * Clean up all resources.
+     */
+    destroy(): void {
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+        this.pending.clear();
+        this.callbacks.clear();
+        this.globalCallbacks = [];
+    }
+}