Overview

This issue covers the native bridge integration for EOA (Externally Owned Account) support during user onboarding. Users will have two account creation options:

1. Seed Phrase Wallet
2. Secure Enclave/Hardware Wallet

The flow transitions from React Native onboarding pages to native implementation for secure key management and wallet initialization.

Figma Design

https://www.figma.com/design/ELsn1EA0ptswW1f21PZqWp/%F0%9F%9F%A2-Flow-Wallet?node-id=4229-38757&t=0LTkpe5eRmFO45cS-4

1. Seed Phrase Wallet Creation Flow

Process Overview

1. User selects seed phrase wallet creation option
2. RN generates and displays seed phrase using BIP39
3. User verifies seed phrase through fill-in-the-blank validation
4. RN extracts public key and registers with backend
5. Data handoff from RN to native layer
6. Native secure storage and Firebase authentication
7. Wallet-Kit initialization with fast Flow account discovery
8. Return to home page with optional notification permission

Sequence Diagram

sequenceDiagram
    participant User
    participant RN as React Native (Onboard Page)
    participant WalletSDK as Wallet Package SDK (BIP39)
    participant API as GoAPIService (Backend)
    participant Native as Native Layer (iOS/Android)
    participant Firebase
    participant WalletKit as Wallet-Kit

    Note over User, WalletKit: User Onboarding - Seed Phrase Wallet Creation

    User->>RN: Click "Create Seed Phrase Wallet"
    RN->>WalletSDK: Generate seed phrase using BIP39
    WalletSDK-->>RN: Return seed phrase

    RN->>User: Display seed phrase
    User->>RN: Click "Next"

    RN->>User: Show seed phrase verification (fill blanks)
    User->>RN: Complete verification
    
    RN->>WalletSDK: Extract public key from seed phrase
    WalletSDK-->>RN: Return public key
    RN->>API: Send create wallet request with public key
    Note right of API: Backend verifies public key
    API->>API: Verify public key validity
    API-->>RN: Return register response with txId

    RN->>Native: Pass (seed phrase, customToken/JWT, txId)

    Native->>Native: Save seed phrase key securely
    Native->>Firebase: Login with customToken (JWT)
    Firebase-->>Native: Authentication success

    Native->>WalletKit: Initialize with seed phrase key
    WalletKit-->>Native: Wallet-kit initialized
    Native->>WalletKit: Initialize wallet object with txId
    Note right of WalletKit: Fast Flow account discovery avoiding key indexer wait
    WalletKit-->>Native: Wallet object initialized

    Native->>RN: Close React Native view
    Native->>User: Return to home page
    
    opt Optional Step 13
        Native->>User: Trigger notification permission request
    end

2. Secure Enclave/Hardware Wallet Creation Flow

Process Overview

1. User selects hardware wallet creation option
2. RN calls native layer to start registration process
3. Native creates secure enclave key (reusing existing logic)
4. Native calls register API with public key (reusing existing logic)
5. RN navigates to loading page and clears navigation stack
6. Native secure storage and Firebase authentication
7. Wallet-Kit initialization with secure enclave key
8. Flow account discovery process
9. Navigate to backup page when Flow account is found

Sequence Diagram

sequenceDiagram
    participant User
    participant RN as React Native (Onboard Page)
    participant Native as Native Layer (iOS/Android)
    participant SecureEnclave as Secure Enclave
    participant API as GoAPIService (Backend)
    participant Firebase
    participant WalletKit as Wallet-Kit

    Note over User, WalletKit: User Onboarding - Secure Enclave Wallet Creation

    User->>RN: Click "Create Hardware Wallet"
    RN->>Native: Call native registration flow
    
    Note over Native: Reuse existing registration logic
    Native->>SecureEnclave: Create secure enclave key
    Note over SecureEnclave: Reuse existing key creation logic
    SecureEnclave-->>Native: Return secure key pair
    
    Native->>API: Call register API with public key
    Note over API: Reuse existing registration logic
    API->>API: Verify public key validity
    API-->>Native: Return register response with (txId, customToken/JWT)
    
    Native->>RN: Registration success, navigate to loading page
    RN->>RN: Clear navigation stack (prevent back navigation)
    RN->>User: Show loading page
    
    Native->>Native: Save secure key securely
    Native->>Firebase: Login with customToken (JWT)
    Firebase-->>Native: Authentication success
    
    Native->>WalletKit: Initialize with secure enclave key
    WalletKit-->>Native: Wallet-kit initialized
    Native->>WalletKit: Initialize wallet object with txId
    Note right of WalletKit: Fast Flow account discovery avoiding key indexer wait
    WalletKit-->>Native: Searching for Flow account...
    
    WalletKit->>WalletKit: Flow account discovery process
    WalletKit-->>Native: Flow account found and initialized
    
    Native->>RN: Flow account ready, navigate to backup page
    RN->>User: Navigate to backup page

Step-by-Step Breakdown

Seed Phrase Wallet (Steps 1-13)

1. User Interaction: User clicks "Create Seed Phrase Wallet" option
2. Seed Phrase Generation: RN uses Wallet Package SDK's BIP39 implementation to generate seed phrase
3. Display Phase: Show generated seed phrase to user, user clicks next
4. Verification Phase: User completes seed phrase verification through fill-in-the-blank
5. Public Key Extraction: RN extracts public key from validated seed phrase using Wallet SDK
6. Backend Registration: RN sends create wallet request with public key to GoAPIService backend
7. Data Handoff: RN passes (seed phrase, customToken/JWT, txId) to native layer
8. Secure Storage: Native layer saves seed phrase key securely
9. Firebase Authentication: Native uses custom token to authenticate with Firebase
10. Wallet-Kit Initialization: Native initializes wallet-kit with seed phrase key
11. Fast Account Discovery: Native uses txId to initialize wallet object for fast Flow account discovery
12. UI Transition: Native closes React Native view and returns user to home page
13. Optional Notification: Native may trigger notification permission request

Secure Enclave Wallet (Steps 1-12)

1. User Interaction: User clicks "Create Hardware Wallet" option
2. Native Bridge Call: RN calls native layer to start registration process
3. Secure Key Creation: Native creates secure enclave key (reusing existing logic)
4. Backend Registration: Native calls register API with public key (reusing existing logic)
5. Navigation Management: RN navigates to loading page and clears navigation stack to prevent back navigation
6. Secure Storage: Native saves secure key securely
7. Firebase Authentication: Native uses customToken to login to Firebase
8. Wallet-Kit Initialization: Native initializes wallet-kit with secure enclave key
9. Flow Account Search: Native's wallet-kit uses txId to initialize wallet object for fast Flow account discovery
10. Account Discovery Process: Wallet-Kit searches for Flow account, avoiding key indexer wait
11. Discovery Completion: When Flow account is found, process completes
12. Navigate to Backup: Native notifies RN to navigate to backup page

Key Differences Between Flows

Seed Phrase Flow

• UI-Heavy: More user interaction in RN (display, verification)
• Manual Validation: User manually verifies seed phrase
• Direct Handoff: All data passed to native at once
• Immediate Completion: Returns to home page directly

Secure Enclave Flow

• Native-Heavy: Most operations handled by native layer
• Automatic Process: No manual user verification required
• Existing Logic Reuse: Leverages current secure enclave and registration code
• Async Completion: Waits for Flow account discovery before proceeding
• Backup Flow: Proceeds to backup page instead of home

Implementation Notes

• Both flows reuse existing native logic for security and consistency
• Navigation stack management prevents users from going back during sensitive operations
• Fast Flow account discovery using txId optimizes user experience
• Firebase authentication ensures secure user session management
• Wallet-Kit integration provides robust Flow blockchain interaction

Next Steps

• Define native bridge APIs for both flows
• Implement navigation stack management
• Add error handling and recovery mechanisms
• Create backup page flow documentation
• Test secure enclave key creation and storage