chore: add segment error tracking to vault issues (MetaMask#19425)

## **Description**

This PR standardizes vault corruption tracking across MetaMask Mobile by
replacing inconsistent direct tracking calls with the centralized
`trackVaultCorruption` utility in multiple components.

**What is the reason for the change?**
1. **Inconsistent Tracking Implementation**: Multiple components (Login,
LockScreen, App, Authentication, EngineService) were using different
approaches to track vault corruption events
2. **Bypassed Utility Logic**: Some components used direct `track()`
calls that bypassed the `trackVaultCorruption` utility's error filtering
and MetaMetrics enabled state checking
3. **Missing Tracking Coverage**: Some critical vault corruption
scenarios (lockscreen failures, app startup failures, engine
initialization failures, migration issues) weren't being tracked at all
4. **Code Duplication**: Similar vault corruption tracking logic was
duplicated across multiple files

**What is the improvement/solution?**
1. **Standardized all vault corruption tracking** to use the
`trackVaultCorruption` utility across Login, LockScreen, App,
Authentication, EngineService, and migration components
2. **Added missing tracking coverage** for previously untracked vault
corruption scenarios
3. **Ensured consistent error filtering** using the utility's
`isVaultRelatedError()` function
4. **Proper MetaMetrics state checking** before tracking events
5. **Cleaned up debug logs** from the tracking utility

## **Analytics Tracking Information**

**Event Name:** `Vault Corruption Detected`

**Key Error Types to Monitor:**

**Login & Authentication Failures:**
- `vault_error` - Core vault unlock failures ("Cannot unlock without a
previous vault.")
- `json_parse_error` - Vault data corruption (JSON parsing issues)
- `lockscreen_authentication_failure` - Lock screen unlock failures
- `authentication_service_failure` - System authentication failures
- `app_startup_authentication_failure` - App startup authentication
issues

**Vault Recovery & Handling:**
- `vault_corruption_handling` - When vault recovery process is initiated
- `vault_corruption_handling_failed` - When vault recovery attempts fail

**System & Migration Issues:**
- `engine_initialization_failure` - Core engine startup failures ("Error
creating the vault")
- `migration_missing_vault` - Existing users missing vault during app
updates

**Context Information:**
- `login_authentication` - Errors during login flow
- `vault_corruption_recovery_attempt` - During vault recovery process
- `lockscreen_unlock_failed` - Lock screen specific failures
- `app_initialization_unlock_failed` - App startup unlock issues
- `engine_service_startup` - Engine initialization context
- `migration_existing_user_validation` - Migration-specific issues
- `app_triggered_auth_failed` - Authentication service failures

**Additional Properties:**
- `oauth_login` - Whether user was in OAuth/social login flow
- `migration_number` - Specific migration version for migration errors
- `has_existing_state` - Whether engine had existing state during
initialization

**Common Error Messages to Look For:**
- "Cannot unlock without a previous vault." - Login vault unlock
failures
- "Error creating the vault" - Engine/system vault creation issues
- "No vault in backup" - Backup restoration failures
- "Password does not exist when calling
SecureKeychain.getGenericPassword" - Keychain access failures
- "Migration X: Existing user missing vault in KeyringController" -
Migration vault issues

**What to Look For:**
- Spikes in vault corruption events across different components
- Patterns in specific error types that indicate systemic issues
- Migration-related vault corruption during app updates
- Authentication failures that could indicate keychain/storage problems

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: #[issue-number]

## **Manual testing steps**

```gherkin
Feature: Standardized vault corruption tracking across components

  Scenario: Login component vault corruption tracking
    Given user attempts to login with corrupted vault
    When login fails with "Cannot unlock without a previous vault."
    Then vault corruption is tracked using trackVaultCorruption utility
    And event includes error_type="vault_error" and context="login_authentication"

  Scenario: LockScreen component vault corruption tracking
    Given user attempts to unlock from lock screen
    When unlock fails with vault/authentication errors
    Then vault corruption is tracked with error_type="lockscreen_authentication_failure"
    And uses same utility as other components

  Scenario: App startup vault corruption tracking
    Given app starts with corrupted vault state
    When authentication fails during startup
    Then vault corruption is tracked with error_type="app_startup_authentication_failure"
    And follows same tracking pattern as other components

  Scenario: Engine initialization vault corruption tracking
    Given engine fails to initialize due to vault issues
    When EngineService catches "Error creating the vault" errors
    Then vault corruption is tracked with error_type="engine_initialization_failure"
    And includes has_existing_state property

  Scenario: Migration vault corruption tracking
    Given existing user during app migration
    When migration detects missing vault
    Then vault corruption is tracked with error_type="migration_missing_vault"
    And includes migration_number property
```

## **Screenshots/Recordings**

<img width="1681" height="818" alt="image"
src="https://github.com/user-attachments/assets/794380b6-150d-412d-9807-874c95c62542"
/>


<!-- This is an analytics standardization with no UI changes -->

### **Before**

- Inconsistent vault corruption tracking across components
- Some components missing vault corruption tracking entirely
- Direct track calls bypassing utility's error filtering and state
checking
- Different tracking patterns and property structures across files

### **After**

- Standardized `trackVaultCorruption` utility usage across all
components
- Comprehensive vault corruption tracking coverage
- Consistent error filtering and MetaMetrics state checking
- Uniform event structure and properties across all tracking points

## **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.

---

**Technical Implementation Details:**

**Files Modified:**
- `app/components/Views/Login/index.tsx` - Replaced 3 direct `track()`
calls with `trackVaultCorruption()` calls
- `app/components/Views/LockScreen/index.js` - Added
`trackVaultCorruption()` for lockscreen authentication failures
- `app/components/Nav/App/App.tsx` - Added `trackVaultCorruption()` for
app startup authentication failures
- `app/core/Authentication/Authentication.ts` - Added
`trackVaultCorruption()` for authentication service failures
- `app/core/EngineService/EngineService.ts` - Added
`trackVaultCorruption()` for engine initialization failures
- `app/store/migrations/util/index.tsx` - Added `trackVaultCorruption()`
for migration vault validation failures
- `app/core/Analytics/MetaMetrics.events.ts` - Added
`VAULT_CORRUPTION_DETECTED` event definition
- `app/util/analytics/vaultCorruptionTracking.ts` - Removed debug
`console.log` statements

**Key Changes Made:**

1. **Login Component**: Replaced direct
`track(MetaMetricsEvents.VAULT_CORRUPTION_DETECTED, ...)` calls with
`trackVaultCorruption(...)` calls
2. **LockScreen Component**: Added new tracking for authentication
failures during unlock
3. **App Component**: Added new tracking for app startup authentication
failures
4. **Authentication Service**: Added new tracking for authentication
service failures
5. **EngineService**: Added new tracking for engine initialization
failures
6. **Migration Utility**: Added new tracking for existing users missing
vault during migrations

**Benefits:**
- **Comprehensive Coverage**: All major vault corruption scenarios now
tracked consistently
- **Standardized Implementation**: Single utility function used across
all components
- **Proper State Checking**: MetaMetrics enabled state checked before
all tracking
- **Error Filtering**: All tracking benefits from
`isVaultRelatedError()` filtering
- **Maintainability**: Centralized tracking logic easier to maintain and
update
- **Analytics Consistency**: Uniform event structure across all tracking
points


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds centralized vault corruption tracking utility and integrates it
across login, lock screen, app startup, engine init, auth service, and
migrations, plus defines event and tests.
> 
> - **Analytics**:
> - Add `trackVaultCorruption` utility with `isVaultRelatedError` in
`app/util/analytics/vaultCorruptionTracking.ts` and comprehensive tests.
> - Define new event `VAULT_CORRUPTION_DETECTED` in
`app/core/Analytics/MetaMetrics.events.ts`.
> - **UI/Flows**:
> - `Login`: Track vault corruption on detection, handling attempts, and
failures using `trackVaultCorruption`.
>   - `LockScreen`: Track auth failures during unlock.
>   - `Nav/App`: Track auth failures on app startup.
> - **Core Services**:
> - `Authentication.appTriggeredAuth`: Track authentication failures
suggesting vault/keychain issues.
> - `EngineService.start`: Track engine initialization failures and
route to vault recovery.
> - **Migrations**:
> - Log and track when existing users are missing
`KeyringController.vault` in migration validation.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b2a9cc6. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: tommasini

app/components/Nav/App/App.tsx

@@ -154,6 +154,7 @@ import { SmartAccountModal } from '../../Views/MultichainAccounts/AccountDetails
 import TradeWalletActions from '../../Views/TradeWalletActions';
 import { BIP44AccountPermissionWrapper } from '../../Views/MultichainAccounts/MultichainPermissionsSummary/BIP44AccountPermissionWrapper';
 import { useEmptyNavHeaderForConfirmations } from '../../Views/confirmations/hooks/ui/useEmptyNavHeaderForConfirmations';
+import { trackVaultCorruption } from '../../../util/analytics/vaultCorruptionTracking';
 
 const clearStackNavigatorOptions = {
   headerShown: false,
@@ -1125,6 +1126,12 @@ const App: React.FC = () => {
         const locked =
           errorMessage === AUTHENTICATION_APP_TRIGGERED_AUTH_NO_CREDENTIALS;
 
+        // Track vault corruption with enabled state checking
+        trackVaultCorruption(errorMessage, {
+          error_type: 'app_startup_authentication_failure',
+          context: 'app_initialization_unlock_failed',
+        });
+
         // Only call lockApp if there is an existing user to prevent unnecessary calls
         await Authentication.lockApp({ reset: false, locked });
         trackErrorAsAnalytics(

app/components/Views/LockScreen/index.js

@@ -7,8 +7,8 @@ import { Authentication } from '../../../core';
 import Routes from '../../../constants/navigation/Routes';
 import { CommonActions } from '@react-navigation/native';
 import trackErrorAsAnalytics from '../../../util/metrics/TrackError/trackErrorAsAnalytics';
+import { trackVaultCorruption } from '../../../util/analytics/vaultCorruptionTracking';
 import FoxLoader from '../../UI/FoxLoader';
-
 /**
  * Main view component for the Lock screen
  */
@@ -79,6 +79,15 @@ class LockScreen extends PureComponent {
       Logger.log('Lockscreen::unlockKeychain - authentication successful');
     } catch (error) {
       this.lock();
+
+      if (error?.message) {
+        // Track vault corruption with enabled state checking
+        trackVaultCorruption(error.message, {
+          error_type: 'lockscreen_authentication_failure',
+          context: 'lockscreen_unlock_failed',
+        });
+      }
+
       trackErrorAsAnalytics(
         'Lockscreen: Authentication failed',
         error?.message,

app/components/Views/Login/index.tsx

@@ -55,6 +55,7 @@ import { containsErrorMessage } from '../../../util/errorHandling';
 import { MetaMetricsEvents } from '../../../core/Analytics';
 import { LoginViewSelectors } from '../../../../e2e/selectors/wallet/LoginView.selectors';
 import trackErrorAsAnalytics from '../../../util/metrics/TrackError/trackErrorAsAnalytics';
+import { trackVaultCorruption } from '../../../util/analytics/vaultCorruptionTracking';
 import { downloadStateLogs } from '../../../util/logs';
 import {
   trace,
@@ -279,6 +280,13 @@ const Login: React.FC<LoginProps> = ({ saveOnboardingEvent }) => {
   const handleVaultCorruption = async () => {
     const LOGIN_VAULT_CORRUPTION_TAG = 'Login/ handleVaultCorruption:';
 
+    // Track vault corruption handling attempt
+    trackVaultCorruption(VAULT_ERROR, {
+      error_type: 'vault_corruption_handling',
+      context: 'vault_corruption_recovery_attempt',
+      oauth_login: isComingFromOauthOnboarding,
+    });
+
     // No need to check password requirements here, it will be checked in onLogin
     try {
       setLoading(true);
@@ -314,8 +322,16 @@ const Login: React.FC<LoginProps> = ({ saveOnboardingEvent }) => {
         throw new Error(`${LOGIN_VAULT_CORRUPTION_TAG} ${backupResult.error}`);
       }
     } catch (e: unknown) {
+      // Track vault corruption handling failure
+      trackVaultCorruption((e as Error).message, {
+        error_type: 'vault_corruption_handling_failed',
+        context: 'vault_corruption_recovery_failed',
+        oauth_login: isComingFromOauthOnboarding,
+      });
+
       Logger.error(e as Error);
       setLoading(false);
+
       setError(strings('login.invalid_password'));
     }
   };
@@ -506,6 +522,7 @@ const Login: React.FC<LoginProps> = ({ saveOnboardingEvent }) => {
     }
 
     setLoading(false);
+
     setError(strings('login.invalid_password'));
     trackErrorAsAnalytics('Login: Invalid Password', loginErrorMessage);
   };
@@ -550,6 +567,15 @@ const Login: React.FC<LoginProps> = ({ saveOnboardingEvent }) => {
       containsErrorMessage(loginError, VAULT_ERROR) ||
       containsErrorMessage(loginError, JSON_PARSE_ERROR_UNEXPECTED_TOKEN)
     ) {
+      // Track vault corruption detected
+      trackVaultCorruption(loginErrorMessage, {
+        error_type: containsErrorMessage(loginError, VAULT_ERROR)
+          ? 'vault_error'
+          : 'json_parse_error',
+        context: 'login_authentication',
+        oauth_login: isComingFromOauthOnboarding,
+      });
+
       await handleVaultCorruption();
     } else if (toLowerCaseEquals(loginErrorMessage, DENY_PIN_ERROR_ANDROID)) {
       updateBiometryChoice(false);

app/core/Analytics/MetaMetrics.events.ts

@@ -403,6 +403,7 @@ enum EVENT_NAME {
   CHANGE_DAPP_PERMISSIONS = 'Changed dapp permissions',
 
   // Vault Corruption
+  VAULT_CORRUPTION_DETECTED = 'Vault Corruption Detected',
   VAULT_CORRUPTION_RESTORE_WALLET_SCREEN_VIEWED = 'Vault Corruption Restore Wallet Screen Viewed',
   VAULT_CORRUPTION_RESTORE_WALLET_BUTTON_PRESSED = 'Vault Corruption Restore Wallet Button Pressed',
   VAULT_CORRUPTION_WALLET_SUCCESSFULLY_RESTORED_SCREEN_VIEWED = 'Vault Corruption Wallet Successfully Restored Screen Viewed',
@@ -1039,6 +1040,7 @@ const events = {
   BROWSER_SWITCH_TAB: generateOpt(EVENT_NAME.BROWSER_SWITCH_TAB),
 
   // Vault corruption
+  VAULT_CORRUPTION_DETECTED: generateOpt(EVENT_NAME.VAULT_CORRUPTION_DETECTED),
   VAULT_CORRUPTION_RESTORE_WALLET_SCREEN_VIEWED: generateOpt(
     EVENT_NAME.VAULT_CORRUPTION_RESTORE_WALLET_SCREEN_VIEWED,
   ),

app/core/Authentication/Authentication.ts

@@ -72,6 +72,7 @@ import { toChecksumHexAddress } from '@metamask/controller-utils';
 import AccountTreeInitService from '../../multichain-accounts/AccountTreeInitService';
 import { renewSeedlessControllerRefreshTokens } from '../OAuthService/SeedlessControllerHelper';
 import { EntropySourceId } from '@metamask/keyring-api';
+import { trackVaultCorruption } from '../../util/analytics/vaultCorruptionTracking';
 
 /**
  * Holds auth data used to determine auth configuration
@@ -621,7 +622,6 @@ class AuthenticationService {
       // TODO: Replace "any" with type
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const credentials: any = await SecureKeychain.getGenericPassword();
-
       const password = credentials?.password;
       if (!password) {
         throw new AuthenticationError(
@@ -658,10 +658,18 @@ class AuthenticationService {
       // TODO: Replace "any" with type
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     } catch (e: any) {
+      const errorMessage = (e as Error).message;
+
+      // Track authentication failures that could indicate vault/keychain issues to Segment
+      trackVaultCorruption(errorMessage, {
+        error_type: 'authentication_service_failure',
+        context: 'app_triggered_auth_failed',
+      });
+
       ReduxService.store.dispatch(authError(bioStateMachineId));
       !disableAutoLogout && this.lockApp({ reset: false });
       throw new AuthenticationError(
-        (e as Error).message,
+        errorMessage,
         AUTHENTICATION_APP_TRIGGERED_AUTH_ERROR,
         this.authData,
       );

app/core/EngineService/EngineService.ts

@@ -18,6 +18,7 @@ import NavigationService from '../NavigationService';
 import Routes from '../../constants/navigation/Routes';
 import { MetaMetrics } from '../Analytics';
 import { VaultBackupResult } from './types';
+import { trackVaultCorruption } from '../../util/analytics/vaultCorruptionTracking';
 import { INIT_BG_STATE_KEY, UPDATE_BG_STATE_KEY, LOG_TAG } from './constants';
 
 export class EngineService {
@@ -83,6 +84,12 @@ export class EngineService {
       // `Engine.init()` call mutates `typeof UntypedEngine` to `TypedEngine`
       this.updateControllers(Engine as unknown as TypedEngine);
     } catch (error) {
+      trackVaultCorruption((error as Error).message, {
+        error_type: 'engine_initialization_failure',
+        context: 'engine_service_startup',
+        has_existing_state: Object.keys(state).length > 0,
+      });
+
       Logger.error(
         error as Error,
         'Failed to initialize Engine! Falling back to vault recovery.',

app/store/migrations/util/index.tsx

@@ -1,6 +1,7 @@
 import { captureException } from '@sentry/react-native';
 import { hasProperty, isObject } from '@metamask/utils';
 import Logger from '../../../util/Logger';
+import { trackVaultCorruption } from '../../../util/analytics/vaultCorruptionTracking';
 
 export interface ValidState {
   engine: {
@@ -65,6 +66,16 @@ export function ensureValidState<T>(
         'Is vault defined at KeyringController at migration when existingUser',
         hasVault,
       );
+
+      // Track vault corruption if existing user has no vault
+      if (!hasVault) {
+        const errorMessage = `Migration ${migrationNumber}: Existing user missing vault in KeyringController`;
+        trackVaultCorruption(errorMessage, {
+          error_type: 'migration_missing_vault',
+          context: 'migration_existing_user_validation',
+          migration_number: migrationNumber,
+        });
+      }
     } catch (error) {
       Logger.error(
         new Error(