@metamask-previews/perps-controller 0.0.0-preview-ae46ab603 → 0.0.0-preview-e4aa1532

package/dist/providers/AggregatedPerpsProvider.mjs

@@ -0,0 +1,773 @@
+/* eslint-disable no-restricted-syntax, @typescript-eslint/naming-convention, jsdoc/require-param, jsdoc/check-param-names, jsdoc/require-returns */
+// TODO: Fix ESLint errors in this file - tracked for Phase 6 cleanup
+/**
+ * AggregatedPerpsProvider - Multi-provider aggregation wrapper
+ *
+ * Implements PerpsProvider interface to enable seamless multi-provider support.
+ * Aggregates read operations from all providers, routes write operations to specific
+ * providers based on params.providerId or default provider.
+ *
+ * Phase 1 Implementation:
+ * - Read operations: Aggregate from all providers using Promise.allSettled()
+ * - Write operations: Route to params.providerId ?? defaultProvider
+ * - Subscriptions: Multiplex via SubscriptionMultiplexer
+ * - Lifecycle: Delegate to default provider
+ *
+ * All returned data includes providerId field for UI differentiation.
+ */
+import { SubscriptionMultiplexer } from "../aggregation/SubscriptionMultiplexer.mjs";
+import { ProviderRouter } from "../routing/ProviderRouter.mjs";
+/**
+ * AggregatedPerpsProvider implements PerpsProvider by coordinating
+ * multiple backend providers.
+ *
+ * Design principles:
+ * 1. Read operations aggregate from all providers (parallel)
+ * 2. Write operations route to specific provider (explicit > default)
+ * 3. Lifecycle operations delegate to default provider
+ * 4. All returned data includes providerId for UI differentiation
+ *
+ * @example
+ * ```typescript
+ * const aggregated = new AggregatedPerpsProvider({
+ *   providers: new Map([
+ *     ['hyperliquid', hlProvider],
+ *     ['myx', myxProvider],
+ *   ]),
+ *   defaultProvider: 'hyperliquid',
+ *   infrastructure: deps,
+ * });
+ *
+ * // Read: returns positions from all providers
+ * const positions = await aggregated.getPositions();
+ *
+ * // Write: routes to specific or default provider
+ * await aggregated.placeOrder({ symbol: 'BTC', providerId: 'myx', ... });
+ * ```
+ */
+export class AggregatedPerpsProvider {
+    /**
+     * Create a new AggregatedPerpsProvider.
+     *
+     * @param config - Configuration for the aggregated provider
+     */
+    constructor(config) {
+        this.protocolId = 'aggregated';
+        this.providers = config.providers;
+        this.defaultProvider = config.defaultProvider;
+        this.aggregationMode = config.aggregationMode ?? 'all';
+        this.deps = config.infrastructure;
+        // Initialize router with default provider
+        this.router = new ProviderRouter({
+            defaultProvider: this.defaultProvider,
+        });
+        // Initialize subscription multiplexer with logger for error reporting
+        this.subscriptionMux = new SubscriptionMultiplexer({
+            logger: this.deps.logger,
+        });
+        this.deps.debugLogger.log('[AggregatedPerpsProvider] Initialized', {
+            providers: Array.from(this.providers.keys()),
+            defaultProvider: this.defaultProvider,
+            aggregationMode: this.aggregationMode,
+        });
+    }
+    // ============================================================================
+    // Helper Methods
+    // ============================================================================
+    /**
+     * Get list of active providers as tuples for iteration.
+     * Returns array of [providerId, provider] pairs.
+     *
+     * @returns Array of provider tuples
+     */
+    getActiveProviders() {
+        return Array.from(this.providers.entries());
+    }
+    /**
+     * Get the default provider instance.
+     * Throws if default provider is not available.
+     *
+     * @returns Default provider instance
+     */
+    getDefaultProvider() {
+        const provider = this.providers.get(this.defaultProvider);
+        if (!provider) {
+            throw new Error(`[AggregatedPerpsProvider] Default provider '${this.defaultProvider}' not available`);
+        }
+        return provider;
+    }
+    /**
+     * Get provider by ID, falling back to default if not found.
+     *
+     * @param providerId - Optional provider ID
+     * @returns Tuple of [providerId, provider]
+     */
+    getProviderOrDefault(providerId) {
+        const id = providerId ?? this.defaultProvider;
+        const provider = this.providers.get(id);
+        if (!provider) {
+            this.deps.debugLogger.log(`[AggregatedPerpsProvider] Provider '${id}' not found, using default`);
+            return [this.defaultProvider, this.getDefaultProvider()];
+        }
+        return [id, provider];
+    }
+    /**
+     * Extract successful results from Promise.allSettled.
+     * Logs errors for failed promises.
+     *
+     * @param results - Results from Promise.allSettled
+     * @param context - Context string for logging
+     * @returns Array of successful values
+     */
+    extractSuccessfulResults(results, context) {
+        const successful = [];
+        results.forEach((result, index) => {
+            if (result.status === 'fulfilled') {
+                successful.push(result.value);
+            }
+            else {
+                this.deps.debugLogger.log(`[AggregatedPerpsProvider] ${context} failed for provider ${index}`, { error: result.reason });
+            }
+        });
+        return successful;
+    }
+    // ============================================================================
+    // Asset Routes (Synchronous - delegate to default provider)
+    // ============================================================================
+    /**
+     * Get deposit routes from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Array of asset routes
+     */
+    getDepositRoutes(params) {
+        return this.getDefaultProvider().getDepositRoutes(params);
+    }
+    /**
+     * Get withdrawal routes from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Array of asset routes
+     */
+    getWithdrawalRoutes(params) {
+        return this.getDefaultProvider().getWithdrawalRoutes(params);
+    }
+    // ============================================================================
+    // Read Operations (Aggregate from all providers)
+    // ============================================================================
+    /**
+     * Get positions from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated positions with providerId
+     */
+    async getPositions(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const positions = await provider.getPositions(params);
+            return positions.map((pos) => ({ ...pos, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getPositions').flat();
+    }
+    /**
+     * Get account state from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Account state with providerId
+     */
+    async getAccountState(params) {
+        // Return account state from default provider with providerId injected
+        const provider = this.getDefaultProvider();
+        const state = await provider.getAccountState(params);
+        return { ...state, providerId: this.defaultProvider };
+    }
+    /**
+     * Get markets from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Deduplicated markets with providerId
+     */
+    async getMarkets(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const markets = await provider.getMarkets(params);
+            return markets.map((market) => ({ ...market, providerId: id }));
+        }));
+        const allMarkets = this.extractSuccessfulResults(results, 'getMarkets').flat();
+        // Deduplicate markets by name (keep first occurrence)
+        const seen = new Set();
+        return allMarkets.filter((market) => {
+            // Use providerId:name as unique key to allow same market from different providers
+            const key = `${market.providerId}:${market.name}`;
+            if (seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+    }
+    /**
+     * Get market data with prices from all providers.
+     *
+     * @returns Aggregated market data with providerId
+     */
+    async getMarketDataWithPrices() {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const data = await provider.getMarketDataWithPrices();
+            return data.map((item) => ({ ...item, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getMarketDataWithPrices').flat();
+    }
+    /**
+     * Get order fills from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated order fills with providerId
+     */
+    async getOrderFills(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const fills = await provider.getOrderFills(params);
+            return fills.map((fill) => ({ ...fill, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getOrderFills').flat();
+    }
+    /**
+     * Get orders from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated orders with providerId
+     */
+    async getOrders(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const orders = await provider.getOrders(params);
+            return orders.map((order) => ({ ...order, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getOrders').flat();
+    }
+    /**
+     * Get open orders from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated open orders with providerId
+     */
+    async getOpenOrders(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const orders = await provider.getOpenOrders(params);
+            return orders.map((order) => ({ ...order, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getOpenOrders').flat();
+    }
+    /**
+     * Get funding from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated funding data
+     */
+    async getFunding(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([_providerId, provider]) => {
+            const funding = await provider.getFunding(params);
+            // Funding type doesn't have providerId - we could add it if needed
+            return funding;
+        }));
+        return this.extractSuccessfulResults(results, 'getFunding').flat();
+    }
+    /**
+     * Get historical portfolio from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Historical portfolio result
+     */
+    async getHistoricalPortfolio(params) {
+        // Delegate to default provider
+        return this.getDefaultProvider().getHistoricalPortfolio(params);
+    }
+    /**
+     * Get user non-funding ledger updates from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Raw ledger updates
+     */
+    async getUserNonFundingLedgerUpdates(params) {
+        // Delegate to default provider (protocol-specific)
+        return this.getDefaultProvider().getUserNonFundingLedgerUpdates(params);
+    }
+    /**
+     * Get user history from all providers.
+     *
+     * @param params - Optional parameters
+     * @returns Aggregated user history with providerId
+     */
+    async getUserHistory(params) {
+        const results = await Promise.allSettled(this.getActiveProviders().map(async ([id, provider]) => {
+            const history = await provider.getUserHistory(params);
+            return history.map((item) => ({ ...item, providerId: id }));
+        }));
+        return this.extractSuccessfulResults(results, 'getUserHistory').flat();
+    }
+    // ============================================================================
+    // Write Operations (Route to specific provider)
+    // ============================================================================
+    /**
+     * Place an order via routed provider.
+     *
+     * @param params - Order parameters
+     * @returns Order result with providerId
+     */
+    async placeOrder(params) {
+        const [providerId, provider] = this.getProviderOrDefault(params.providerId);
+        this.deps.debugLogger.log('[AggregatedPerpsProvider] placeOrder routing', {
+            requestedProvider: params.providerId,
+            actualProvider: providerId,
+            symbol: params.symbol,
+        });
+        const result = await provider.placeOrder(params);
+        return { ...result, providerId };
+    }
+    /**
+     * Edit an order via routed provider.
+     *
+     * @param params - Edit order parameters
+     * @returns Order result with providerId
+     */
+    async editOrder(params) {
+        // EditOrderParams contains OrderParams in newOrder which may have providerId
+        const [providerId, provider] = this.getProviderOrDefault(params.newOrder.providerId);
+        const result = await provider.editOrder(params);
+        return { ...result, providerId };
+    }
+    /**
+     * Cancel an order via routed provider.
+     *
+     * @param params - Cancel order parameters
+     * @returns Cancel result with providerId
+     */
+    async cancelOrder(params) {
+        const [providerId, provider] = this.getProviderOrDefault(params.providerId);
+        const result = await provider.cancelOrder(params);
+        return { ...result, providerId };
+    }
+    /**
+     * Cancel multiple orders via default provider.
+     *
+     * @param params - Batch cancel parameters
+     * @returns Batch cancel result
+     */
+    async cancelOrders(params) {
+        // Batch cancel delegates to default provider
+        const provider = this.getDefaultProvider();
+        if (!provider.cancelOrders) {
+            return {
+                success: false,
+                successCount: 0,
+                failureCount: params.length,
+                results: params.map((param) => ({
+                    orderId: param.orderId,
+                    symbol: param.symbol,
+                    success: false,
+                    error: 'Batch cancel not supported',
+                })),
+            };
+        }
+        return provider.cancelOrders(params);
+    }
+    /**
+     * Close a position via routed provider.
+     *
+     * @param params - Close position parameters
+     * @returns Order result with providerId
+     */
+    async closePosition(params) {
+        const [providerId, provider] = this.getProviderOrDefault(params.providerId);
+        const result = await provider.closePosition(params);
+        return { ...result, providerId };
+    }
+    /**
+     * Close multiple positions via default provider.
+     *
+     * @param params - Close positions parameters
+     * @returns Batch close result
+     */
+    async closePositions(params) {
+        // Batch close delegates to default provider
+        const provider = this.getDefaultProvider();
+        if (!provider.closePositions) {
+            return {
+                success: false,
+                successCount: 0,
+                failureCount: 0,
+                results: [],
+            };
+        }
+        return provider.closePositions(params);
+    }
+    /**
+     * Update position TP/SL via routed provider.
+     *
+     * @param params - Update TP/SL parameters
+     * @returns Order result with providerId
+     */
+    async updatePositionTPSL(params) {
+        const [providerId, provider] = this.getProviderOrDefault(params.providerId);
+        const result = await provider.updatePositionTPSL(params);
+        return { ...result, providerId };
+    }
+    /**
+     * Update margin via routed provider.
+     *
+     * @param params - Update margin parameters
+     * @returns Margin result
+     */
+    async updateMargin(params) {
+        const [, provider] = this.getProviderOrDefault(params.providerId);
+        return provider.updateMargin(params);
+    }
+    /**
+     * Withdraw via routed provider.
+     *
+     * @param params - Withdraw parameters
+     * @returns Withdraw result
+     */
+    async withdraw(params) {
+        const [, provider] = this.getProviderOrDefault(params.providerId);
+        return provider.withdraw(params);
+    }
+    // ============================================================================
+    // Validation (Route to specific provider)
+    // ============================================================================
+    /**
+     * Validate deposit via default provider.
+     *
+     * @param params - Deposit parameters
+     * @returns Validation result
+     */
+    async validateDeposit(params) {
+        return this.getDefaultProvider().validateDeposit(params);
+    }
+    /**
+     * Validate order via routed provider.
+     *
+     * @param params - Order parameters
+     * @returns Validation result
+     */
+    async validateOrder(params) {
+        const [, provider] = this.getProviderOrDefault(params.providerId);
+        return provider.validateOrder(params);
+    }
+    /**
+     * Validate close position via routed provider.
+     *
+     * @param params - Close position parameters
+     * @returns Validation result
+     */
+    async validateClosePosition(params) {
+        const [, provider] = this.getProviderOrDefault(params.providerId);
+        return provider.validateClosePosition(params);
+    }
+    /**
+     * Validate withdrawal via routed provider.
+     *
+     * @param params - Withdraw parameters
+     * @returns Validation result
+     */
+    async validateWithdrawal(params) {
+        const [, provider] = this.getProviderOrDefault(params.providerId);
+        return provider.validateWithdrawal(params);
+    }
+    // ============================================================================
+    // Protocol Calculations (Delegate to default or route)
+    // ============================================================================
+    /**
+     * Calculate liquidation price via default provider.
+     *
+     * @param params - Liquidation price parameters
+     * @returns Liquidation price as string
+     */
+    async calculateLiquidationPrice(params) {
+        return this.getDefaultProvider().calculateLiquidationPrice(params);
+    }
+    /**
+     * Calculate maintenance margin via default provider.
+     *
+     * @param params - Maintenance margin parameters
+     * @returns Maintenance margin as number
+     */
+    async calculateMaintenanceMargin(params) {
+        return this.getDefaultProvider().calculateMaintenanceMargin(params);
+    }
+    /**
+     * Get max leverage for asset via default provider.
+     *
+     * @param asset - Asset symbol
+     * @returns Max leverage as number
+     */
+    async getMaxLeverage(asset) {
+        return this.getDefaultProvider().getMaxLeverage(asset);
+    }
+    /**
+     * Calculate fees via default provider.
+     *
+     * @param params - Fee calculation parameters
+     * @returns Fee calculation result
+     */
+    async calculateFees(params) {
+        return this.getDefaultProvider().calculateFees(params);
+    }
+    // ============================================================================
+    // Subscriptions (Multiplex via SubscriptionMultiplexer)
+    // ============================================================================
+    /**
+     * Subscribe to prices from all providers.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToPrices(params) {
+        return this.subscriptionMux.subscribeToPrices({
+            ...params,
+            providers: this.getActiveProviders(),
+            aggregationMode: 'merge',
+        });
+    }
+    /**
+     * Subscribe to positions from all providers.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToPositions(params) {
+        return this.subscriptionMux.subscribeToPositions({
+            ...params,
+            providers: this.getActiveProviders(),
+        });
+    }
+    /**
+     * Subscribe to order fills from all providers.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToOrderFills(params) {
+        return this.subscriptionMux.subscribeToOrderFills({
+            ...params,
+            providers: this.getActiveProviders(),
+        });
+    }
+    /**
+     * Subscribe to orders from all providers.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToOrders(params) {
+        return this.subscriptionMux.subscribeToOrders({
+            ...params,
+            providers: this.getActiveProviders(),
+        });
+    }
+    /**
+     * Subscribe to account from default provider.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToAccount(params) {
+        // For account subscriptions, we emit as array for multi-provider
+        // but the callback expects single AccountState
+        // Delegate to default provider for now
+        return this.getDefaultProvider().subscribeToAccount(params);
+    }
+    /**
+     * Subscribe to OI caps from default provider.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToOICaps(params) {
+        // Delegate to default provider
+        return this.getDefaultProvider().subscribeToOICaps(params);
+    }
+    /**
+     * Subscribe to candles from default provider.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToCandles(params) {
+        // Delegate to default provider
+        return this.getDefaultProvider().subscribeToCandles(params);
+    }
+    /**
+     * Subscribe to order book from default provider.
+     *
+     * @param params - Subscription parameters
+     * @returns Unsubscribe function
+     */
+    subscribeToOrderBook(params) {
+        // Delegate to default provider
+        return this.getDefaultProvider().subscribeToOrderBook(params);
+    }
+    // ============================================================================
+    // Configuration
+    // ============================================================================
+    /**
+     * Set live data config on all providers.
+     *
+     * @param config - Partial live data config
+     */
+    setLiveDataConfig(config) {
+        // Apply config to all providers
+        this.providers.forEach((provider) => {
+            provider.setLiveDataConfig(config);
+        });
+    }
+    /**
+     * Set user fee discount on all providers.
+     *
+     * @param discountBips - Discount in basis points
+     */
+    setUserFeeDiscount(discountBips) {
+        // Apply to all providers that support it
+        this.providers.forEach((provider) => {
+            if (provider.setUserFeeDiscount) {
+                provider.setUserFeeDiscount(discountBips);
+            }
+        });
+    }
+    // ============================================================================
+    // Lifecycle (Delegate to default provider)
+    // ============================================================================
+    /**
+     * Toggle testnet on default provider.
+     *
+     * @returns Toggle result
+     */
+    async toggleTestnet() {
+        return this.getDefaultProvider().toggleTestnet();
+    }
+    /**
+     * Initialize the default provider.
+     *
+     * @returns Initialize result
+     */
+    async initialize() {
+        // Initialize default provider
+        const result = await this.getDefaultProvider().initialize();
+        // Optionally initialize other providers in background
+        // For Phase 1, we only initialize default provider
+        return result;
+    }
+    /**
+     * Check if ready to trade via default provider.
+     *
+     * @returns Ready to trade result
+     */
+    async isReadyToTrade() {
+        return this.getDefaultProvider().isReadyToTrade();
+    }
+    /**
+     * Disconnect all providers.
+     *
+     * @returns Disconnect result
+     */
+    async disconnect() {
+        // Disconnect all providers
+        const results = await Promise.allSettled(this.getActiveProviders().map(([, provider]) => provider.disconnect()));
+        // Clear subscription cache
+        this.subscriptionMux.clearCache();
+        // Return success if at least one succeeded
+        const successCount = results.filter((res) => res.status === 'fulfilled' && res.value.success).length;
+        return {
+            success: successCount > 0,
+        };
+    }
+    /**
+     * Ping default provider.
+     *
+     * @param timeoutMs - Optional timeout in milliseconds
+     */
+    async ping(timeoutMs) {
+        return this.getDefaultProvider().ping(timeoutMs);
+    }
+    // ============================================================================
+    // Block Explorer
+    // ============================================================================
+    /**
+     * Get block explorer URL from default provider.
+     *
+     * @param address - Optional address
+     * @returns Block explorer URL
+     */
+    getBlockExplorerUrl(address) {
+        return this.getDefaultProvider().getBlockExplorerUrl(address);
+    }
+    // ============================================================================
+    // HIP-3 (Optional)
+    // ============================================================================
+    /**
+     * Get available DEXs from default provider.
+     *
+     * @param params - Optional parameters
+     * @returns Array of DEX names
+     */
+    async getAvailableDexs(params) {
+        const provider = this.getDefaultProvider();
+        if (!provider.getAvailableDexs) {
+            return [];
+        }
+        return provider.getAvailableDexs(params);
+    }
+    // ============================================================================
+    // Provider Management
+    // ============================================================================
+    /**
+     * Add a new provider to the aggregated provider.
+     *
+     * @param providerId - Unique identifier for the provider
+     * @param provider - Provider instance
+     */
+    addProvider(providerId, provider) {
+        this.providers.set(providerId, provider);
+        this.deps.debugLogger.log('[AggregatedPerpsProvider] Provider added', {
+            providerId,
+        });
+    }
+    /**
+     * Remove a provider from the aggregated provider.
+     *
+     * @param providerId - Provider to remove
+     * @returns true if removed, false if not found
+     */
+    removeProvider(providerId) {
+        const removed = this.providers.delete(providerId);
+        if (removed) {
+            this.deps.debugLogger.log('[AggregatedPerpsProvider] Provider removed', {
+                providerId,
+            });
+        }
+        return removed;
+    }
+    /**
+     * Get list of all registered provider IDs.
+     *
+     * @returns Array of provider IDs
+     */
+    getProviderIds() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+     * Check if a provider is registered.
+     *
+     * @param providerId - Provider ID to check
+     * @returns true if registered
+     */
+    hasProvider(providerId) {
+        return this.providers.has(providerId);
+    }
+    /**
+     * Get the router instance for external configuration.
+     *
+     * @returns Provider router
+     */
+    getRouter() {
+        return this.router;
+    }
+}
+//# sourceMappingURL=AggregatedPerpsProvider.mjs.map