feat(perps-controller): add Lighter perps venue (initial implementation, flag-gated)

packages/perps-controller/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add Lighter as a perps venue (initial implementation, disabled by default) ([#9889](https://github.com/MetaMask/core/pull/9889))
+  - **BREAKING:** `PerpsProviderType` gains `'lighter'`. Consumers with exhaustive provider switches must handle the new value. Enablement requires client opt-in: `providerCredentials.lighter.enabled`, or the `perpsLighterProviderEnabled` remote feature flag combined with a client-supplied `providerCredentials.lighter.signerBridge` (without a bridge the provider is read-only). Lighter follows the global network toggle on both testnet and mainnet (reads and writes).
+  - The client-supplied signer bridge owns venue-key creation and persistence; Core never derives or receives the venue-key seed/private key. Lighter deposits are not advertised until the provider can build the required approval plus bridge-deposit call.
+  - New Lighter types/constants exports, `KeyringController:signPersonalMessage` in the allowed messenger actions (type-only), and durable-settlement surfacing on the controller: `getPendingManualRecoveries`, `getRecoveredDispatches`, `acknowledgeRecoveredDispatch` actions with `PerpsPendingManualRecovery` / `PerpsRecoveredDispatch` exported types and `OrderResult.partialState`.
+  - `LiquidationPriceParams` and `MaintenanceMarginParams` gain an optional `providerId`, and `getMaxLeverage` accepts the same optional route, so aggregated calculations use the provider that owns the market or position.
+
 ### Fixed
 
 - Preserve accepted HyperLiquid Scale orders when part of a batch is rejected ([#9989](https://github.com/MetaMask/core/pull/9989))

packages/perps-controller/src/PerpsController-method-action-types.ts

@@ -376,6 +376,43 @@ export type PerpsControllerGetOrderFillsAction = {
   handler: PerpsController['getOrderFills'];
 };
 
+/**
+ * List TP/SL protection changes the active provider parked for
+ * explicit manual re-establishment. Providers without durable
+ * settlement state return an empty list.
+ *
+ * @returns Pending manual-recovery entries.
+ */
+export type PerpsControllerGetPendingManualRecoveriesAction = {
+  type: `PerpsController:getPendingManualRecoveries`;
+  handler: PerpsController['getPendingManualRecoveries'];
+};
+
+/**
+ * READ-ONLY list of the active provider's recovered-dispatch outcomes
+ * (previously ambiguous submissions later resolved). Providers without
+ * durable dispatch state return an empty list.
+ *
+ * @returns Pending recovered-dispatch outcomes.
+ */
+export type PerpsControllerGetRecoveredDispatchesAction = {
+  type: `PerpsController:getRecoveredDispatches`;
+  handler: PerpsController['getRecoveredDispatches'];
+};
+
+/**
+ * Acknowledge ONE recovered-dispatch outcome by its stable id, after
+ * refreshing venue state. Throws when the active provider has no
+ * durable dispatch state or the id no longer matches.
+ *
+ * @param recoveryId - Stable id from {@link getRecoveredDispatches}.
+ * @returns Resolves when the outcome is acknowledged.
+ */
+export type PerpsControllerAcknowledgeRecoveredDispatchAction = {
+  type: `PerpsController:acknowledgeRecoveredDispatch`;
+  handler: PerpsController['acknowledgeRecoveredDispatch'];
+};
+
 /**
  * Get historical user orders (order lifecycle)
  * Thin delegation to MarketDataService
@@ -569,6 +606,7 @@ export type PerpsControllerCalculateMaintenanceMarginAction = {
  * Get maximum leverage allowed for an asset
  *
  * @param asset - The asset identifier.
+ * @param providerId - Optional provider route for aggregated markets.
  * @returns A promise that resolves to the numeric result.
  */
 export type PerpsControllerGetMaxLeverageAction = {
@@ -1313,6 +1351,9 @@ export type PerpsControllerMethodActions =
   | PerpsControllerWithdrawAction
   | PerpsControllerGetPositionsAction
   | PerpsControllerGetOrderFillsAction
+  | PerpsControllerGetPendingManualRecoveriesAction
+  | PerpsControllerGetRecoveredDispatchesAction
+  | PerpsControllerAcknowledgeRecoveredDispatchAction
   | PerpsControllerGetOrdersAction
   | PerpsControllerGetOpenOrdersAction
   | PerpsControllerGetFundingAction

packages/perps-controller/src/PerpsController.ts

@@ -115,6 +115,8 @@ import type {
   PerpsControllerConfig,
   PerpsMarketData,
   PerpsOrderCapabilities,
+  PerpsPendingManualRecovery,
+  PerpsRecoveredDispatch,
   Position,
   SubscribeAccountParams,
   SubscribeCandlesParams,
@@ -149,6 +151,10 @@ import type {
   MYXCredentials,
 } from './types/index.js';
 import type { SortDirection } from './types/index.js';
+import type {
+  LighterAuthConfig,
+  LighterSignerBridge,
+} from './types/lighter-types.js';
 import type {
   PerpsControllerAllowedActions,
   PerpsControllerAllowedEvents,
@@ -963,9 +969,12 @@ const MESSENGER_EXPOSED_METHODS = [
   'getOrderCapabilities',
   'getOrderFills',
   'getOrders',
+  'getPendingManualRecoveries',
   'getPendingTradeConfiguration',
   'getPositions',
   'getSelectedOrderType',
+  'getRecoveredDispatches',
+  'acknowledgeRecoveredDispatch',
   'getTradeConfiguration',
   'getRecentlyViewedMarkets',
   'getVisibleCandleCount',
@@ -1057,6 +1066,8 @@ export class PerpsController extends BaseController<
   /** Tracks the async MYX dynamic import so performInitialization can await it. */
   #myxRegistrationPromise: Promise<void> | null = null;
 
+  #lighterRegistrationPromise: Promise<void> | null = null;
+
   protected blockedRegionList: BlockedRegionList = {
     list: [],
     source: 'fallback',
@@ -1140,6 +1151,48 @@ export class PerpsController extends BaseController<
     }
   }
 
+  /**
+   * Check if the Lighter provider is enabled.
+   *
+   * Local override (`providerCredentials.lighter.enabled`) wins; otherwise
+   * the remote `perpsLighterProviderEnabled` feature flag decides — but only
+   * for clients that wired the venue signer bridge. A remote flag must not
+   * be able to register a trading provider the client never mounted a
+   * signer for (the gates would otherwise split between core and client).
+   *
+   * @returns True if the condition is met.
+   */
+  #isLighterProviderEnabled(): boolean {
+    const lighter = this.#options.clientConfig?.providerCredentials?.lighter;
+
+    if (lighter?.enabled) {
+      return true;
+    }
+    if (!lighter?.signerBridge) {
+      return false;
+    }
+
+    try {
+      const remoteState = this.messenger.call(
+        'RemoteFeatureFlagController:getState',
+      );
+      const remoteFlag =
+        remoteState.remoteFeatureFlags?.perpsLighterProviderEnabled;
+
+      if (isVersionGatedFeatureFlag(remoteFlag)) {
+        const validated =
+          this.#options.infrastructure.featureFlags.validateVersionGated(
+            remoteFlag,
+          );
+        return validated ?? false;
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Active provider instance for routing operations.
    * When activeProvider is 'hyperliquid' or 'myx': points to specific provider directly
@@ -1382,6 +1435,7 @@ export class PerpsController extends BaseController<
       if (
         providerId === 'hyperliquid' ||
         (providerId === 'myx' && this.#isMYXProviderEnabled()) ||
+        (providerId === 'lighter' && this.#isLighterProviderEnabled()) ||
         this.providers.has(providerId as PerpsProviderType)
       ) {
         providerIds.add(providerId);
@@ -2244,8 +2298,10 @@ export class PerpsController extends BaseController<
         await Promise.all([
           wait(PERPS_CONSTANTS.ReconnectionCleanupDelayMs),
           this.#myxRegistrationPromise,
+          this.#lighterRegistrationPromise,
         ]);
         this.#myxRegistrationPromise = null;
+        this.#lighterRegistrationPromise = null;
 
         this.#assignActiveProvider();
 
@@ -2384,6 +2440,24 @@ export class PerpsController extends BaseController<
         })
         .catch((error: unknown) => this.handleMYXImportError(error));
     }
+
+    // Register Lighter provider if enabled (POC). Same dynamic-import pattern
+    // as MYX so clients that do not ship the Lighter files skip registration
+    // silently.
+    const isLighterEnabled = this.#isLighterProviderEnabled();
+    if (isLighterEnabled) {
+      // NOTE: Keep the path in a variable so ts-bridge does not rewrite the
+      // import argument and strip the webpackIgnore magic comment in core dist.
+      const lighterModulePath = './providers/LighterProvider';
+      this.#lighterRegistrationPromise = import(
+        /* webpackIgnore: true */ lighterModulePath
+      )
+        .then(({ LighterProvider }) => {
+          this.registerLighterProvider(LighterProvider);
+          return undefined;
+        })
+        .catch((error: unknown) => this.handleLighterImportError(error));
+    }
   }
 
   /**
@@ -2444,6 +2518,69 @@ export class PerpsController extends BaseController<
     }
   }
 
+  /**
+   * Registers the Lighter provider after dynamic import resolves.
+   *
+   * Extracted from the import().then() callback so it can be tested directly
+   * (Jest cannot resolve dynamic imports without --experimental-vm-modules).
+   *
+   * @param LighterProviderClass - Constructor class for the Lighter provider.
+   */
+  protected registerLighterProvider(
+    LighterProviderClass: new (opts: {
+      isTestnet: boolean;
+      platformDependencies: PerpsPlatformDependencies;
+      messenger: PerpsControllerMessenger;
+      lighterAuthConfig: LighterAuthConfig;
+      signerBridge?: LighterSignerBridge;
+    }) => PerpsProvider,
+  ): void {
+    const lighterIsTestnet =
+      PROVIDER_CONFIG.LIGHTER_TESTNET_ONLY || this.state.isTestnet;
+    const lighter =
+      this.#options.clientConfig?.providerCredentials?.lighter ?? {};
+    const lighterProvider = new LighterProviderClass({
+      isTestnet: lighterIsTestnet,
+      platformDependencies: this.#options.infrastructure,
+      messenger: this.messenger,
+      signerBridge: lighter.signerBridge,
+      lighterAuthConfig: {
+        enabled: lighter.enabled,
+        accountIndex: lighterIsTestnet
+          ? lighter.accountIndexTestnet
+          : lighter.accountIndexMainnet,
+        apiKeyIndex: lighter.apiKeyIndex,
+      },
+    });
+    this.providers.set('lighter', lighterProvider);
+    this.#debugLog('PerpsController: Lighter provider registered', {
+      isTestnet: lighterIsTestnet,
+    });
+  }
+
+  /**
+   * Handles errors from the Lighter dynamic import.
+   *
+   * Module-not-found errors are expected (clients may not ship Lighter) →
+   * debug log. Other errors indicate constructor/config problems → Sentry.
+   *
+   * @param error - The caught error from the dynamic import or constructor.
+   */
+  protected handleLighterImportError(error: unknown): void {
+    const isModuleError =
+      (error as Record<string, unknown>)?.code === 'MODULE_NOT_FOUND';
+    if (isModuleError) {
+      this.#debugLog(
+        'PerpsController: Lighter provider module not available, skipping registration',
+      );
+    } else {
+      this.#logError(
+        error instanceof Error ? error : new Error(String(error)),
+        this.#getErrorContext('createProviders.lighter'),
+      );
+    }
+  }
+
   /**
    * Assigns the active provider instance based on the current activeProvider state.
    * Separated from #createProviders so it runs after async MYX registration settles.
@@ -2473,13 +2610,13 @@ export class PerpsController extends BaseController<
       this.#debugLog(
         `PerpsController: Using direct provider (${activeProvider})`,
       );
-    } else if (activeProvider === 'myx') {
-      const myxProvider = this.providers.get('myx');
-      if (myxProvider) {
-        this.activeProviderInstance = myxProvider;
+    } else if (activeProvider === 'myx' || activeProvider === 'lighter') {
+      const directProvider = this.providers.get(activeProvider);
+      if (directProvider) {
+        this.activeProviderInstance = directProvider;
       } else {
         this.#debugLog(
-          'PerpsController: MYX provider not available, falling back to hyperliquid',
+          `PerpsController: ${activeProvider} provider not available, falling back to hyperliquid`,
         );
         this.activeProviderInstance = hyperLiquidProvider;
         this.update((state) => {
@@ -2491,7 +2628,7 @@ export class PerpsController extends BaseController<
       );
     } else {
       throw new Error(
-        `Unsupported provider: ${String(activeProvider)}. Currently only 'hyperliquid', 'myx', and 'aggregated' are supported.`,
+        `Unsupported provider: ${String(activeProvider)}. Currently only 'hyperliquid', 'myx', 'lighter', and 'aggregated' are supported.`,
       );
     }
   }
@@ -3701,6 +3838,54 @@ export class PerpsController extends BaseController<
     });
   }
 
+  /**
+   * List TP/SL protection changes the active provider parked for
+   * explicit manual re-establishment. Providers without durable
+   * settlement state return an empty list.
+   *
+   * @returns Pending manual-recovery entries.
+   */
+  async getPendingManualRecoveries(): Promise<PerpsPendingManualRecovery[]> {
+    const provider = await this.#getActiveProviderWhenReady();
+    if (!provider.getPendingManualRecoveries) {
+      return [];
+    }
+    return provider.getPendingManualRecoveries();
+  }
+
+  /**
+   * READ-ONLY list of the active provider's recovered-dispatch outcomes
+   * (previously ambiguous submissions later resolved). Providers without
+   * durable dispatch state return an empty list.
+   *
+   * @returns Pending recovered-dispatch outcomes.
+   */
+  async getRecoveredDispatches(): Promise<PerpsRecoveredDispatch[]> {
+    const provider = await this.#getActiveProviderWhenReady();
+    if (!provider.getRecoveredDispatches) {
+      return [];
+    }
+    return provider.getRecoveredDispatches();
+  }
+
+  /**
+   * Acknowledge ONE recovered-dispatch outcome by its stable id, after
+   * refreshing venue state. Throws when the active provider has no
+   * durable dispatch state or the id no longer matches.
+   *
+   * @param recoveryId - Stable id from {@link getRecoveredDispatches}.
+   * @returns Resolves when the outcome is acknowledged.
+   */
+  async acknowledgeRecoveredDispatch(recoveryId: string): Promise<void> {
+    const provider = await this.#getActiveProviderWhenReady();
+    if (!provider.acknowledgeRecoveredDispatch) {
+      throw new Error(
+        'The active perps provider has no recovered dispatches to acknowledge',
+      );
+    }
+    return provider.acknowledgeRecoveredDispatch(recoveryId);
+  }
+
   /**
    * Get historical user orders (order lifecycle)
    * Thin delegation to MarketDataService
@@ -4869,12 +5054,21 @@ export class PerpsController extends BaseController<
    * Get maximum leverage allowed for an asset
    *
    * @param asset - The asset identifier.
+   * @param providerId - Optional provider route for aggregated markets.
    * @returns A promise that resolves to the numeric result.
    */
-  async getMaxLeverage(asset: string): Promise<number> {
+  async getMaxLeverage(
+    asset: string,
+    providerId?: PerpsProviderType,
+  ): Promise<number> {
     const provider = this.getActiveProvider();
     const context = this.#createServiceContext('getMaxLeverage');
-    return this.#marketDataService.getMaxLeverage({ provider, asset, context });
+    return this.#marketDataService.getMaxLeverage({
+      provider,
+      asset,
+      ...(providerId === undefined ? {} : { providerId }),
+      context,
+    });
   }
 
   /**

packages/perps-controller/src/constants/index.ts

@@ -9,3 +9,4 @@ export * from './perpsConfig.js';
 export * from './transactionsHistoryConfig.js';
 export * from './performanceMetrics.js';
 export * from './myxConfig.js';
+export * from './lighterConfig.js';