MetaMask
diff --git a/‎app/controllers/perps/constants/eventNames.ts‎
Lines changed: 4 additions & 0 deletions b/‎app/controllers/perps/constants/eventNames.ts‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎app/controllers/perps/providers/HyperLiquidProvider.test.ts‎
Lines changed: 206 additions & 0 deletions b/‎app/controllers/perps/providers/HyperLiquidProvider.test.ts‎
Lines changed: 206 additions & 0 deletions
@@ -360,6 +360,10 @@ export const PERPS_EVENT_VALUE = {
     SUCCESS: 'success',
     ALREADY_ENABLED: 'already_enabled',
     MIGRATION_REQUIRED: 'migration_required',
+    // Emitted when a migration attempt is skipped because it is not applicable
+    // (e.g. the user has no Hyperliquid account yet — nothing to migrate).
+    // Distinguishes expected no-ops from real failures in dashboards.
+    NOT_APPLICABLE: 'not_applicable',
   },
   SCREEN_TYPE: {
     MARKETS: 'markets',
 
@@ -10838,4 +10838,210 @@ describe('HyperLiquidProvider', () => {
       await expect(provider.getExchangeClient()).rejects.toBe(bomb);
     });
   });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // Proactive "user does not exist" gate
+  //
+  // Hyperliquid creates user accounts server-side on first USDC deposit.
+  // Before that, exchange writes (`agentSetAbstraction`, `userSetAbstraction`,
+  // `setReferrer`, ...) reject with
+  //     ApiRequestError: User or API Wallet 0x... does not exist.
+  // and the catch in `#ensureUnifiedAccountEnabled` forwards them to Sentry.
+  //
+  // The provider probes `infoClient.clearinghouseState` first and defers
+  // migration when every existence signal is zero/empty. The classifier in
+  // the catch acts as a safety net for races (probe succeeded but write
+  // still rejected).
+  //
+  // Sentry source: METAMASK-MOBILE-4XB5 (iOS) / 4Q4M (Android).
+  // Standalone repro: scripts/repro-hl-user-not-found.mjs.
+  // ──────────────────────────────────────────────────────────────────────
+  describe('wallet-not-on-hyperliquid gate (ensureUnifiedAccountEnabled)', () => {
+    const USER_ADDRESS = '0x1234567890123456789012345678901234567890';
+
+    const withdrawParams = {
+      amount: '1000',
+      destination: USER_ADDRESS as Hex,
+      assetId:
+        'eip155:42161/erc20:0xa0b86a33e6776e681a06e0e1622c5e5e3e6a8b13/usdc' as CaipAssetId,
+    };
+
+    const stubGetAccountState = (availableBalance: string) =>
+      Object.defineProperty(provider, 'getAccountState', {
+        value: jest.fn().mockResolvedValue({ availableBalance }),
+        writable: true,
+      });
+
+    it('defers migration without firing exchange writes when the wallet has no HL ledger history', async () => {
+      const exchangeClient = createMockExchangeClient();
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(
+        createMockInfoClient({
+          // Empty ledger = wallet has never deposited / withdrawn / interacted.
+          userNonFundingLedgerUpdates: jest.fn().mockResolvedValue([]),
+          userAbstraction: jest.fn().mockResolvedValue('default'),
+        }),
+      );
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      // Critical: neither migration write is called for unfunded wallets.
+      expect(exchangeClient.agentSetAbstraction).not.toHaveBeenCalled();
+      expect(exchangeClient.userSetAbstraction).not.toHaveBeenCalled();
+      // And no `logger.error` → no Sentry event.
+      expect(mockPlatformDependencies.logger.error).not.toHaveBeenCalled();
+
+      const trackCalls = (
+        mockPlatformDependencies.metrics.trackPerpsEvent as jest.Mock
+      ).mock.calls.filter((call) => call[0] === 'Perp Account Setup');
+      const notApplicable = trackCalls.find(
+        (call) => call[1]?.status === 'not_applicable',
+      );
+      expect(notApplicable?.[1]).toEqual(
+        expect.objectContaining({
+          status: 'not_applicable',
+          error_message: 'no_hl_account',
+        }),
+      );
+    });
+
+    it('classifier safety net: suppresses Sentry when agentSetAbstraction races and rejects with user-not-found', async () => {
+      // Funded probe — gate passes — but the exchange write still rejects
+      // (deposit not yet visible, address reuse across networks, ...).
+      const userNotFound = new Error(
+        `User or API Wallet ${USER_ADDRESS} does not exist.`,
+      );
+      const exchangeClient = createMockExchangeClient();
+      exchangeClient.agentSetAbstraction = jest
+        .fn()
+        .mockRejectedValue(userNotFound);
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(
+        createMockInfoClient({
+          // Funded clearinghouseState → gate passes
+          userAbstraction: jest.fn().mockResolvedValue('default'),
+        }),
+      );
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      expect(exchangeClient.agentSetAbstraction).toHaveBeenCalled();
+      expect(mockPlatformDependencies.logger.error).not.toHaveBeenCalled();
+
+      const trackCalls = (
+        mockPlatformDependencies.metrics.trackPerpsEvent as jest.Mock
+      ).mock.calls.filter((call) => call[0] === 'Perp Account Setup');
+      expect(
+        trackCalls.find((call) => call[1]?.status === 'not_applicable'),
+      ).toBeDefined();
+      expect(
+        trackCalls.find((call) => call[1]?.status === 'failed'),
+      ).toBeUndefined();
+    });
+
+    it('regression: unrelated exchange write failures still reach logger.error', async () => {
+      const exchangeClient = createMockExchangeClient();
+      exchangeClient.agentSetAbstraction = jest
+        .fn()
+        .mockRejectedValue(new Error('Insufficient margin'));
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(
+        createMockInfoClient({
+          userAbstraction: jest.fn().mockResolvedValue('default'),
+        }),
+      );
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      expect(mockPlatformDependencies.logger.error).toHaveBeenCalled();
+
+      const trackCalls = (
+        mockPlatformDependencies.metrics.trackPerpsEvent as jest.Mock
+      ).mock.calls.filter((call) => call[0] === 'Perp Account Setup');
+      expect(
+        trackCalls.find((call) => call[1]?.status === 'failed'),
+      ).toBeDefined();
+    });
+
+    it('funded wallets are unaffected: existing migration path runs as before', async () => {
+      const exchangeClient = createMockExchangeClient();
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(
+        createMockInfoClient({
+          // Default funded clearinghouseState from factory
+          userAbstraction: jest.fn().mockResolvedValue('default'),
+        }),
+      );
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      expect(exchangeClient.agentSetAbstraction).toHaveBeenCalledWith({
+        // SDK wire format: 'u' = unifiedAccount (see HL_ABSTRACTION_WIRE).
+        abstraction: 'u',
+      });
+      expect(mockPlatformDependencies.logger.error).not.toHaveBeenCalled();
+    });
+
+    it('walletRegistered cache hit skips the probe entirely', async () => {
+      // Arrange: pre-warm the walletRegistered cache so #isWalletOnHyperliquid
+      // returns true without calling userNonFundingLedgerUpdates.
+      const mockedCache = TradingReadinessCache as jest.Mocked<
+        typeof TradingReadinessCache
+      >;
+      mockedCache.getWalletRegistered.mockReturnValue({
+        known: true,
+        registered: true,
+      });
+
+      const exchangeClient = createMockExchangeClient();
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      const infoClient = createMockInfoClient({
+        userAbstraction: jest.fn().mockResolvedValue('unifiedAccount'),
+      });
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(infoClient);
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      // The ledger probe should never fire because the cache was hit.
+      expect(infoClient.userNonFundingLedgerUpdates).not.toHaveBeenCalled();
+    });
+
+    it('probe failure fails open — allows migration to proceed', async () => {
+      // Arrange: probe throws (transient network), should fail open (return true)
+      // and allow the migration to proceed.
+      const exchangeClient = createMockExchangeClient();
+      mockClientService.getExchangeClient = jest
+        .fn()
+        .mockReturnValue(exchangeClient);
+      mockClientService.getInfoClient = jest.fn().mockReturnValue(
+        createMockInfoClient({
+          userAbstraction: jest.fn().mockResolvedValue('default'),
+          userNonFundingLedgerUpdates: jest
+            .fn()
+            .mockRejectedValue(new Error('Network timeout')),
+        }),
+      );
+      stubGetAccountState('5000');
+
+      await provider.withdraw(withdrawParams).catch(() => undefined);
+
+      // Probe failed open → migration ran → agentSetAbstraction was called.
+      expect(exchangeClient.agentSetAbstraction).toHaveBeenCalled();
+    });
+  });
 });