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

Introduces a new @metamask/perps-controller package migrated from Mobile, providing platform-agnostic perps trading via dependency injection.

• Adds full PerpsController (~3k LOC) with DI, HIP-3 support, connection handling, and provider routing (direct HyperLiquidProvider and AggregatedPerpsProvider with SubscriptionMultiplexer)
• Includes constants/, types/, selectors, and utilities for fees, validation, market data, and performance metrics
• Implements services (Trading, MarketData, Account, Deposit, Eligibility, FeatureFlagConfiguration, RewardsIntegration, DataLake)
• Adds Jest config (ESM mock mapping for @nktkas/hyperliquid, lowered coverage thresholds) and test/mocks scaffolding (~40 tests)
• Updates package dependencies/peerDeps for controllers and HyperLiquid SDK; adds CHANGELOG and migration guide

^{Written by Cursor Bugbot for commit dede853. 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]

Caution

MetaMask internal reviewing guidelines:

• Do not ignore-all
• Each alert has instructions on how to review if you don't know what it means. If lost, ask your Security Liaison or the supply-chain group
• Copy-paste ignore lines for specific packages or a group of one kind with a note on what research you did to deem it safe.
  @SocketSecurity ignore npm/PACKAGE@VERSION

Action	Severity	Alert  (click "▶" to expand/collapse)
Block		Network access: npm @metamask/transaction-controller in module globalThis["fetch"] Module: globalThis["fetch"] Location: Package overview From: ? → npm/@metamask/[email protected] ℹ Read more on: This package | This alert | What is network access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: Packages should remove all network access that is functionally unnecessary. Consumers should audit network access to ensure legitimate use. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@metamask/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Network access: npm @nktkas/hyperliquid in module globalThis["fetch"] Module: globalThis["fetch"] Location: Package overview From: packages/perps-controller/package.json → npm/@nktkas/[email protected] ℹ Read more on: This package | This alert | What is network access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: Packages should remove all network access that is functionally unnecessary. Consumers should audit network access to ensure legitimate use. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@nktkas/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Network access: npm @noble/curves in module globalThis["fetch"] Module: globalThis["fetch"] Location: Package overview From: ? → npm/@nktkas/[email protected] → npm/@noble/[email protected] ℹ Read more on: This package | This alert | What is network access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: Packages should remove all network access that is functionally unnecessary. Consumers should audit network access to ensure legitimate use. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@noble/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potential code anomaly (AI signal): npm @metamask/transaction-controller is 75.0% likely to have a medium risk anomaly Notes: The code performs straightforward signature verification using ethers.js, returning true when the recovered signer matches the provided publicKey. While generally safe, the silent catch and potential mismatch between data formatting and signing process should be addressed to avoid silent failures. Overall, a benign utility with moderate input-format sensitivity. Confidence: 0.75 Severity: 0.50 From: ? → npm/@metamask/[email protected] ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at [email protected]. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@metamask/[email protected]. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

[cursor]

switchProvider doesn't update the active provider instance

High Severity

The switchProvider method updates state.activeProvider but doesn't update activeProviderInstance, which is what getActiveProvider() returns. After calling switchProvider('aggregated'), the state shows 'aggregated' but all operations still route through the original provider instance. The method returns { success: true } misleadingly, since the switch doesn't actually take effect until a full disconnect/reinit cycle. This causes a mismatch between reported state and actual behavior.

Additional Locations (1)

• packages/perps-controller/src/PerpsController.ts#L1336-L1346

 

[cursor]

Deposit request orphaned on early error in flow

Medium Severity

In depositWithConfirmation, if an error occurs after the deposit request is added to state.depositRequests (line 1581) but before the .then()/.catch() handlers are set up (line 1629), the outer catch block doesn't update the deposit request status to 'failed'. This happens when findNetworkClientIdForChain returns null (line 1587) or submit() throws synchronously. The deposit request remains permanently orphaned with status: 'pending'. Additionally, line 1729's comment is incorrect - lastDepositResult is not set in the outer catch for non-cancellation errors.

Additional Locations (1)

• packages/perps-controller/src/PerpsController.ts#L1558-L1582