[EPIC] 🚀 Upgrade React Native from 0.76.9 to 0.81

### Overview
Upgrade the MetaMask Mobile application from React Native 0.76.9 to 0.81.x to leverage the latest features, performance improvements, and security patches.

### Current State
- **Current Version**: React Native 0.76.9
- **Current React Version**: 18.3.1
- **Current Node Version**: 20.18.0

### Target State
- **Target RN Version**: React Native 0.81.1
- **Target React Version**: 19.1.0
- **Target Node Version**: 20.19.4+ (minimum requirement)

---

### 📋 Breaking Changes & Requirements

#### Environment Requirements
- [ ] **Node.js**: Upgrade minimum requirement to 20.19.4+
- [ ] **Xcode**: Upgrade to Xcode 16.1+ for iOS builds
- [ ] **Ruby**: Verify compatibility with current Ruby version
- [ ] **Gradle**: May need updates for Android builds

#### Deprecated APIs & Components
- [ ] **SafeAreaView Deprecation**: Migrate all instances to `react-native-safe-area-context`
- Already using `react-native-safe-area-context` (v5.4.0) - verify all SafeAreaView usage
- [ ] **JavaScriptCore (JSC)**: Verify JSC engine - built-in version removed, must use community package if needed
- [ ] **Error Reporting**: Update error handling for new error reporting format

#### Core Dependencies to Update
- [ ] `react-native`: `0.76.9` → `0.81.1`
- [ ] `react`: `18.3.1` → `19.1.0`
- [ ] `react-test-renderer`: `18.3.1` → `19.1.0`
- [ ] `@react-native/babel-preset`: `0.76.9` → `0.81.x`
- [ ] `@react-native/eslint-config`: `0.76.9` → `0.81.x`
- [ ] `@react-native/typescript-config`: `0.76.9` → `0.81.x`
- [ ] `@react-native/metro-config`: `0.76.9` → `0.81.x`
- [ ] `metro-react-native-babel-preset`: `~0.76.9` → `~0.81.x`
- [ ] `metro-react-native-babel-transformer`: `~0.76.9` → `~0.81.x`

---

### 🔨 Implementation Tasks

#### Phase 1: Pre-Upgrade Preparation
- [ ] Create dedicated upgrade branch: `upgrade/react-native-0.81`
- [ ] Document current app functionality and test coverage
- [ ] Review [React Native 0.81 Release Notes](https://reactnative.dev/blog/2025/08/12/react-native-0.81)
- [ ] Use [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/?from=0.76.9&to=0.81.1) to generate diff
- [ ] Audit codebase for deprecated API usage:
```bash
# Search for SafeAreaView usage
grep -r "SafeAreaView" app/
# Search for JSC-specific code
grep -r "jsc" .
```
- [ ] Check compatibility of all native dependencies with RN 0.81
- [ ] Review and update CI/CD environment configurations

#### Phase 2: Dependency Updates
- [ ] Update `package.json` core dependencies
- [ ] Update and required [patches](https://github.com/MetaMask/metamask-mobile/tree/main/patches)
- [ ] Update peer dependencies to match React 19 requirements
- [ ] Update native module dependencies:
- [ ] `@react-native-async-storage/async-storage`
- [ ] `@react-native-clipboard/clipboard`
- [ ] `@react-native-community/*` packages
- [ ] `@react-native-firebase/*` packages
- [ ] `react-native-reanimated`
- [ ] `react-native-gesture-handler`
- [ ] `react-native-screens`
- [ ] Review all other native dependencies for compatibility
- [ ] Run `yarn install` and resolve conflicts
- [ ] Update TypeScript types if needed

#### Phase 3: iOS Platform Updates
- [ ] Update `ios/Podfile` dependencies
- [ ] Verify minimum deployment target matches RN 0.81 requirements
- [ ] Update Xcode project settings
- [ ] Update build scripts in `package.json` if needed
- [ ] Clean build artifacts:
```bash
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData
cd ios && pod install && cd ..
```
- [ ] Test build on iOS:
```bash
yarn build:ios:main:dev
```
- [ ] Fix any iOS-specific compilation errors

#### Phase 4: Android Platform Updates
- [ ] Update `android/build.gradle` if needed
- [ ] Update `android/app/build.gradle` if needed
- [ ] Update Gradle version if required
- [ ] Update Android Gradle Plugin version if required
- [ ] Update `gradle.properties` settings
- [ ] Clean build artifacts:
```bash
rm -rf android/app/build android/.gradle
cd android && ./gradlew clean && cd ..
```
- [ ] Test build on Android:
```bash
yarn build:android:main:dev
```
- [ ] Fix any Android-specific compilation errors

#### Phase 5: Code Migration
- [ ] Migrate all `SafeAreaView` imports from `react-native` to `react-native-safe-area-context`
- Search locations: `app/components/`, `app/Views/`
- [ ] Update error handling code for new error reporting format
- [ ] Review and update any JSC-specific code
- [ ] Update any deprecated API usage identified in Phase 1
- [ ] Fix TypeScript errors resulting from React 19 types
- [ ] Update tests to work with React 19 and new RN version

#### Phase 6: Metro & Build Configuration
- [ ] Update `metro.config.js` for RN 0.81 compatibility
- [ ] Update `babel.config.js` if needed
- [ ] Update `react-native.config.js` if needed
- [ ] Verify module resolution works correctly
- [ ] Test Metro bundler performance

#### Phase 7: Expo Integration
- [ ] Verify Expo SDK compatibility with RN 0.81
- [ ] Update Expo-related packages if needed:
- `expo` (currently ~52.0.47)
- `expo-*` packages
- [ ] Test Expo development builds
- [ ] Update Expo build configuration if needed

#### Phase 8: Third-Party Library Updates
- [ ] Update `@react-navigation/*` packages if needed
- [ ] Update Detox for e2e testing compatibility
- [ ] Update Storybook packages
- [ ] Update testing libraries:
- [ ] `@testing-library/react`
- [ ] `@testing-library/react-native`
- [ ] `jest`
- [ ] `react-test-renderer`
- [ ] Verify all patched packages (in `patches/`) still work

---

### 🧪 Testing Strategy

#### Unit Testing
- [ ] Run full test suite: `yarn test:unit`
- [ ] Fix any failing unit tests
- [ ] Ensure test coverage remains above thresholds
- [ ] Test Redux sagas and reducers
- [ ] Test custom hooks

#### Integration Testing
- [ ] Test React Navigation flows
- [ ] Test deep linking
- [ ] Test WebView interactions
- [ ] Test native module interactions
- [ ] Test push notifications (Firebase)
- [ ] SES Compatibility (crashes during runtime, Sentry logging, etc...)

#### E2E Testing
- [ ] Run Detox e2e tests: `yarn test:e2e:ios:debug:run`
- [ ] Run Detox e2e tests: `yarn test:e2e:android:debug:run`
- [ ] Fix any failing e2e tests
- [ ] Test critical user flows:
- Onboarding
- Account creation/import
- Transaction sending
- Token swaps
- NFT viewing
- Snap interactions
- Multichain functionality

#### Manual Testing
- [ ] Test on physical iOS devices
- [ ] Test on iOS simulators
- [ ] Test on physical Android devices
- [ ] Test on Android emulators
- [ ] Test all MetaMask build variants (main, QA, Flask)
- [ ] Test performance (startup time, navigation smoothness)
- [ ] Test memory usage and identify any leaks

#### Platform-Specific Testing
- [ ] Test iOS dark mode
- [ ] Test Android dark mode
- [ ] Test landscape orientation
- [ ] Test tablet layouts
- [ ] Test accessibility features
- [ ] Test biometric authentication
- [ ] Test camera permissions (QR scanner)

---

### 📦 Dependencies & Blockers

- **Node Version Update**: Team members need to upgrade to Node 20.19.4+
- **Xcode Update**: iOS developers need Xcode 16.1+
- **CI/CD Environment**: Update Bitrise/CI environments with new Node/Xcode versions
- **Native Dependency Compatibility**: Some native modules may not yet support RN 0.81
- **React 19 Adoption**: React 19 brings breaking changes that may affect third-party libraries

---

### ⚠️ Risks & Considerations

1. **Breaking Changes**: React 19 and RN 0.81 have significant breaking changes
2. **Third-Party Dependencies**: Not all libraries may support RN 0.81 yet
3. **Build Time**: Clean builds will be required, increasing build times temporarily
4. **Development Environment**: All team members must update their local environments
5. **Patches**: Existing yarn patches may break and need regeneration
6. **Rollback Plan**: Maintain ability to revert if critical issues are discovered

---

### 🎯 Success Criteria

- [ ] App builds successfully on iOS (debug and release)
- [ ] App builds successfully on Android (debug and release)
- [ ] All unit tests pass
- [ ] All e2e tests pass
- [ ] No regression in critical user flows
- [ ] Performance metrics match or exceed current version
- [ ] No increase in crash rate
- [ ] CI/CD pipeline passes all checks

---

### 📚 Resources

- [React Native 0.81 Release Notes](https://reactnative.dev/blog/2025/08/12/react-native-0.81)
- [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/?from=0.76.9&to=0.81.1)
- [React 19 Upgrade Guide](https://react.dev/blog/2025/08/12/react-19)
- [MetaMask Mobile Contributor Docs](https://github.com/MetaMask/contributor-docs)
- [MetaMask Mobile Architecture Docs](./docs/readme/architecture.md)

---

### 📝 Notes

- This is a major version upgrade spanning several minor versions (0.76 → 0.81)
- Consider breaking this into smaller incremental upgrades if needed (0.76 → 0.77 → 0.78, etc.)
- Coordinate with team for a low-activity period to merge this change
- Plan for potential follow-up fixes after merge
- Update documentation after successful upgrade

### Stakeholder review needed before the work gets merged

- [x] Engineering (needed in most cases)
- [ ] Design
- [x] Product
- [ ] QA (automation tests are required to pass before merging PRs but not all changes are covered by automation tests - please review if QA is needed beyond automation tests)
- [ ] Security
- [ ] Legal
- [ ] Marketing
- [ ] Management (please specify)
- [ ] Other (please specify)

### References

_No response_

Start with package.json and the React Native 0.81 release notes plus Upgrade Helper diff, then inspect ios/Podfile, android/build.gradle, android/app/build.gradle, metro.config.js, and babel.config.js. Run the listed iOS, Android, unit, and Detox commands as applicable; done means both platform builds, all tests, CI, and the stated critical flows pass.

Written by the indexing model from the issue text.