feat(perps): perps controller migration from mobile

[abretonc7s]

Explanation

This PR migrates the complete PerpsController implementation from MetaMask Mobile to the Core monorepo as @metamask/perps-controller.

Background

The Perps (Perpetual Futures) feature was initially developed in MetaMask Mobile. To enable sharing this functionality across platforms (Mobile, Extension) and maintain a single source of truth, we are migrating the controller logic to the Core monorepo.

What's Included

Core Controller (~3,000 lines)

• PerpsController.ts - Main controller extending BaseController with full trading functionality
• selectors.ts - 8 state selectors for UI integration

Types & Constants

• types/ - Comprehensive TypeScript type definitions for all Perps operations
• constants/ - Configuration (perpsConfig, hyperLiquidConfig, errorCodes, eventNames)

Services (8 modules)

• TradingService - Order placement, cancellation, position management
• MarketDataService - Market info, prices, order book
• AccountService - Account state management
• DepositService - Deposit flow handling
• EligibilityService - User eligibility checks
• FeatureFlagConfigurationService - Remote feature flag integration
• RewardsIntegrationService - MetaMask rewards integration
• DataLakeService - Analytics data collection

Providers

• HyperLiquidProvider - Full HyperLiquid protocol integration (~7,000 lines)
• AggregatedPerpsProvider - Multi-provider aggregation layer
• ProviderRouter - Routing logic for multi-provider support

Platform Services

• HyperLiquidClientService - HTTP client for HyperLiquid API
• HyperLiquidSubscriptionService - WebSocket subscription management
• HyperLiquidWalletService - Wallet signing operations

Utilities (18 modules)

• Calculation utilities (margin, PnL, position, order)
• Formatting utilities (prices, amounts, dates)
• Validation utilities (orders, TP/SL, HyperLiquid-specific)
• Adapter utilities (HyperLiquid data transformation)

Architecture

The package uses dependency injection via PerpsPlatformDependencies interface to remain platform-agnostic:

type PerpsPlatformDependencies = {
  logger: PerpsLogger;           // Error logging (Sentry on Mobile)
  debugLogger: PerpsDebugLogger; // Dev logging
  metrics: PerpsMetrics;         // Analytics
  tracer: PerpsTracer;           // Performance tracing
  performance: PerpsPerformance; // Timing
  streamManager: PerpsStreamManager; // WebSocket control
  controllers: PerpsControllerAccess; // External controllers
};

This allows Mobile and Extension to provide their own implementations of these dependencies while sharing the core business logic.

ESLint Compliance

Most files pass Core ESLint rules. The following files have ESLint rules temporarily disabled due to the volume of code migrated:

• PerpsController.ts
• HyperLiquidProvider.ts
• HyperLiquidSubscriptionService.ts

These suppressions allow the migration to proceed while maintaining functionality. They can be addressed incrementally in follow-up PRs.

Test Coverage

• 40 unit tests covering controller initialization and all 8 selectors
• Test mocks provided for:
  • @nktkas/hyperliquid SDK (ESM module)
  • Platform dependencies (serviceMocks.ts)
  • Provider interfaces (providerMocks.ts)

Coverage thresholds are currently set to 0% to allow incremental test migration. Full test coverage will be added in follow-up PRs.

References

• Related to MetaMask Mobile Perps feature
• This is the Core monorepo portion of the Perps migration effort

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note: This is a new package, so there are no breaking changes for existing consumers.

---

Note

High Risk
High risk because this lands a large, security- and funds-adjacent controller that orchestrates trading, deposits/withdrawals, and WebSocket live data, plus new external controller/feature-flag integrations. The surface area is large and test coverage thresholds are temporarily disabled, increasing regression risk.

Overview
Introduces a complete PerpsController implementation (migrated from Mobile) with a real persisted state model + metadata, an explicit init()/reinit flow, dependency-injected infrastructure, and messenger actions/events for trading, market data, deposits/withdrawals, eligibility, and UI preferences.

Adds HyperLiquid-first provider setup with optional aggregated routing, plus a new SubscriptionMultiplexer to fan-out WebSocket subscriptions across providers and tag/aggregate updates.

Updates package tooling/docs for the migration: adds HyperLiquid SDK + supporting deps and required peer deps, adds Jest ESM module mapping to a new hyperliquidMock, drops perps-controller coverage thresholds to 0 during migration, expands controller tests with infrastructure mocks, and documents/changelogs the migration.

^{Written by Cursor Bugbot for commit e4aa153. This will update automatically on new commits. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​nktkas/​hyperliquid@​0.30.3

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

• @noble/curves@2.0.1
• @nktkas/hyperliquid@0.30.3

View full report

[abretonc7s]

@SocketSecurity ignore npm/@nktkas/hyperliquid@0.30.3

[abretonc7s]

@SocketSecurity ignore npm/@noble/curves@2.0.1

[abretonc7s]

@SocketSecurity ignore npm/@metamask/transaction-controller@62.10.0

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[aganglada]

I think we need to update the "@metamask/transaction-controller": "^62.11.0" in the package.json