docs(perps): perps controller isolation update (MetaMask#25959)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->
Update perps docs to refer to new ADR-42 arch for perps.

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: null

## **Related issues**

Fixes:

## **Manual testing steps**

```gherkin
Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only changes (path updates, structure clarification, and
deletion of a migration doc) with no runtime or behavioral impact.
> 
> **Overview**
> Updates Perps docs to reflect the controller/UI split introduced by
ADR-042, pointing architectural references and “related files” to
`app/controllers/perps/*` instead of the former UI-layer controller
paths.
> 
> Expands `perps-architecture.md` with the new controller directory
structure and multi-provider architecture notes (HyperLiquid +
feature-flagged MYX via `AggregatedPerpsProvider`/routing), and removes
the now-redundant `perps-controller-migration.md` document.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
82c04d3. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abretonc7s

docs/perps/hyperliquid/order-types-reference.md

@@ -408,7 +408,7 @@ const availableBalance = state.marginSummary.accountValue;
 
 **Codebase**:
 
-- `app/components/UI/Perps/controllers/providers/HyperLiquidProvider.ts:765` - Production orders
+- `app/controllers/perps/providers/HyperLiquidProvider.ts:765` - Production orders
 - `app/components/UI/Perps/utils/hyperLiquidAdapter.ts:64-71` - Adapter patterns
 - `app/components/UI/Perps/Debug/HIP3DebugView.tsx:500,717` - Debug/testing
 

docs/perps/perps-architecture.md

@@ -4,7 +4,10 @@
 
 The Perps feature enables perpetual futures trading in MetaMask Mobile. This document provides a high-level architectural overview of the codebase structure, key patterns, and references to detailed documentation.
 
-**Location**: `app/components/UI/Perps/`
+**Locations**:
+
+- **Controller**: `app/controllers/perps/` — business logic, providers, services, types (portable, no mobile-specific imports)
+- **UI**: `app/components/UI/Perps/` — React components, hooks, views, contexts
 
 ## Quick Navigation
 
@@ -49,21 +52,54 @@ graph TD
 
 ## Directory Structure
 
+### Controller (`app/controllers/perps/`)
+
+The controller is isolated from mobile-specific code and published as `@metamask/perps-controller`.
+See [ADR-042](https://github.com/MetaMask/core/blob/main/docs/adr/ADR-042-perps-controller-location.md) for the architectural decision.
+
+```
+app/controllers/perps/
+├── PerpsController.ts      - Main controller (state, lifecycle, provider mgmt)
+├── index.ts                - Package entry point
+├── perpsErrorCodes.ts      - Error code definitions
+├── selectors.ts            - Redux state selectors
+├── providers/              - Protocol-specific implementations
+│   ├── HyperLiquidProvider.ts
+│   ├── MYXProvider.ts
+│   └── AggregatedPerpsProvider.ts
+├── services/               - Business logic services
+│   ├── AccountService.ts
+│   ├── TradingService.ts
+│   ├── MarketDataService.ts
+│   ├── EligibilityService.ts
+│   ├── DepositService.ts
+│   ├── DataLakeService.ts
+│   ├── RewardsIntegrationService.ts
+│   ├── FeatureFlagConfigurationService.ts
+│   ├── HyperLiquidClientService.ts
+│   ├── HyperLiquidSubscriptionService.ts
+│   ├── HyperLiquidWalletService.ts
+│   ├── MYXClientService.ts
+│   ├── TradingReadinessCache.ts
+│   └── ServiceContext.ts
+├── routing/                - Provider routing logic
+├── aggregation/            - Multi-provider aggregation
+├── types/                  - TypeScript type definitions
+├── constants/              - Configuration values
+└── utils/                  - Pure utility functions
+```
+
+### UI (`app/components/UI/Perps/`)
+
 ```
-/Perps
+app/components/UI/Perps/
 ├── components/       - Reusable UI components
 ├── Views/           - Main screen-level components
 ├── hooks/           - React hooks for data access and logic
 │   └── stream/      - WebSocket subscription hooks (real-time data)
-├── controllers/     - Business logic and Redux state
-│   └── providers/   - Protocol-specific implementations
 ├── providers/       - React context providers
-├── services/        - External integrations (WebSocket, HTTP, wallet)
-├── utils/           - Pure utility functions
-├── types/           - TypeScript type definitions
-├── constants/       - Configuration values
-├── contexts/        - React contexts
 ├── selectors/       - Redux selectors by domain
+├── contexts/        - React contexts
 ├── styles/          - Shared style utilities
 ├── Debug/           - Developer tools
 ├── animations/      - Rive animation files
@@ -185,23 +221,35 @@ React hooks organized by category:
 - `usePerpsDepositStatus` - Deposit status tracking
 - `usePerpsWithdrawStatus` - Withdrawal status tracking
 
-### Controllers
+### Controller (`app/controllers/perps/`)
 
-Business logic and Redux state management:
+Business logic and Redux state management. Isolated from mobile-specific code — uses `PerpsPlatformDependencies` for dependency injection of platform-specific services (logging, metrics, feature flags, etc.).
 
-- **PerpsController** (`controllers/PerpsController.ts`) - Main controller managing providers, orders, positions, market data
-- **PerpsProvider** (`controllers/providers/HyperLiquidProvider.ts`) - HyperLiquid protocol implementation
-- **Selectors** (`controllers/selectors.ts`) - Redux state selectors
-- **Error Codes** (`controllers/perpsErrorCodes.ts`) - Error code definitions
+- **PerpsController** (`app/controllers/perps/PerpsController.ts`) - Main controller managing providers, orders, positions, market data
+- **HyperLiquidProvider** (`app/controllers/perps/providers/HyperLiquidProvider.ts`) - HyperLiquid protocol implementation
+- **MYXProvider** (`app/controllers/perps/providers/MYXProvider.ts`) - MYX protocol implementation
+- **AggregatedPerpsProvider** (`app/controllers/perps/providers/AggregatedPerpsProvider.ts`) - Multi-protocol aggregation via `ProviderRouter`
+- **Selectors** (`app/controllers/perps/selectors.ts`) - Redux state selectors
+- **Error Codes** (`app/controllers/perps/perpsErrorCodes.ts`) - Error code definitions
 
-### Services
+### Services (`app/controllers/perps/services/`)
 
-External integrations and infrastructure:
+Business logic services instantiated with platform dependencies:
 
-- **HyperLiquidClientService** - HTTP client for REST API
+- **AccountService** - Account state, balances, withdrawals
+- **TradingService** - Order placement, cancellation, position management
+- **MarketDataService** - Market info, candles, funding rates
+- **EligibilityService** - User eligibility and geo-blocking
+- **DepositService** - Deposit flow with transaction confirmation
+- **DataLakeService** - Historical data queries
+- **RewardsIntegrationService** - Rewards program integration
+- **FeatureFlagConfigurationService** - Remote feature flag configuration (HIP-3, geo-blocking)
+- **HyperLiquidClientService** - HTTP client for HyperLiquid REST API
 - **HyperLiquidSubscriptionService** - WebSocket subscription management
-- **HyperLiquidWalletService** - Wallet operations
-- **PerpsConnectionManager** - Connection lifecycle orchestration (singleton)
+- **HyperLiquidWalletService** - Wallet operations and signing
+- **MYXClientService** - HTTP client for MYX protocol
+- **TradingReadinessCache** - Cached trading readiness state
+- **PerpsConnectionManager** (`app/components/UI/Perps/services/`) - Connection lifecycle orchestration (mobile-specific singleton, stays in UI layer)
 
 ### Providers
 
@@ -526,13 +574,27 @@ The codebase maintains high quality standards:
 
 ## Protocol Integration
 
-Currently integrated with HyperLiquid protocol:
+Multi-protocol architecture with provider abstraction:
+
+### HyperLiquid (primary)
 
 - **REST API** - Account queries, order placement, market data
 - **WebSocket** - Real-time prices, order fills, position updates
 - **Wallet Integration** - Ethereum signing for orders
 
-**See [hyperliquid/](./hyperliquid/) directory for protocol-specific documentation.**
+### MYX (feature-flagged)
+
+- MYX protocol support via `MYXProvider` and `MYXClientService`
+- Enabled via `perpsMyxProviderEnabled` remote feature flag with version gating
+- When enabled alongside HyperLiquid, uses `AggregatedPerpsProvider` with `ProviderRouter`
+
+### Multi-Protocol Architecture
+
+- **`ProviderRouter`** (`routing/`) - Routes operations to the correct provider based on market
+- **`AggregatedPerpsProvider`** - Wraps multiple providers behind the `PerpsProvider` interface
+- **`SubscriptionMultiplexer`** - Merges WebSocket subscriptions from multiple providers
+
+**See [hyperliquid/](./hyperliquid/) directory for HyperLiquid-specific documentation.**
 
 ## Migration Notes
 

docs/perps/perps-controller-migration.md

@@ -263,7 +263,7 @@ The `minimumVersion` field ensures features only activate on compatible app vers
 - **Tests:** `app/components/UI/Perps/selectors/featureFlags/index.test.ts`
 - **Version validation:** `app/util/remoteFeatureFlag/index.ts`
 - **Controller init:** `app/core/Engine/controllers/remote-feature-flag-controller-init.ts`
-- **Configuration service:** `app/components/UI/Perps/controllers/services/FeatureFlagConfigurationService.ts`
+- **Configuration service:** `app/controllers/perps/services/FeatureFlagConfigurationService.ts`
 
 ---
 

docs/perps/perps-feature-flags.md

@@ -42,7 +42,7 @@ track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
 
 ### 2. Controller Tracking (Transactions)
 
-**Location:** `app/components/UI/Perps/controllers/PerpsController.ts`
+**Location:** `app/controllers/perps/PerpsController.ts`
 
 ```typescript
 import MetaMetrics from '../../../../core/Analytics/MetaMetrics';
@@ -549,5 +549,5 @@ usePerpsEventTracking({
 - **Event Tracking Hook**: `app/components/UI/Perps/hooks/usePerpsEventTracking.ts`
 - **Events**: `app/core/Analytics/MetaMetrics.events.ts`
 - **Properties & Values**: `app/components/UI/Perps/constants/eventNames.ts`
-- **Controller**: `app/components/UI/Perps/controllers/PerpsController.ts`
-- **Trading Service**: `app/components/UI/Perps/controllers/services/TradingService.ts`
+- **Controller**: `app/controllers/perps/PerpsController.ts`
+- **Trading Service**: `app/controllers/perps/services/TradingService.ts`