Implement Wallet Creation and Restoration

[CodeByMAB]

Epic Reference

Part of Epic: Breez SDK Integration for Expo App (epic:97fd7dcb-10ec-46a8-b681-b2805eb0eb56)
SRS Spec: spec:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/a8f8bef7-d1c5-4113-a9ad-6092120bfe76

Overview

Implement wallet creation with BIP39 mnemonic, wallet restoration from seed phrase, and security (PIN/biometric). Private keys must be encrypted and stored in device keychain.

Related SRS Requirements: FR-WM-001, FR-WM-002, FR-WM-003

Tasks

• Implement BIP39 mnemonic generation (12 or 24 word)
• Implement BIP44 derivation path m/84'/0'/0' for native SegWit
• Encrypt private keys with AES-256-GCM; store in React Native Keychain (iOS/Android)
• Wallet creation flow: generate → display seed → user confirms backup → derive keys → encrypt & store
• Wallet restoration: accept 12/24 word mnemonic, validate checksum, derive keys, sync via Breez SDK
• Support optional BIP39 passphrase on restore
• Implement PIN (6-digit min) and biometric (Face ID / fingerprint)
• Require auth on app launch and before sensitive operations (send, export)
• Rate-limit failed auth (3 attempts, 30-second lockout); exponential backoff
• Biometric fallback to PIN when unavailable

Acceptance Criteria

• AC-WM-001-01: System generates 12-word or 24-word mnemonic
• AC-WM-001-02: User must confirm they have backed up the seed phrase
• AC-WM-001-03: System derives wallet keys using BIP44
• AC-WM-001-04: Private keys encrypted with AES-256, stored in device keychain
• AC-WM-001-05: Wallet creation completes within 5 seconds
• AC-WM-002-01 to 05: Restore accepts mnemonic, validates, derives, syncs; completes within 30s (excl. sync)
• AC-WM-003-01 to 05: PIN/biometric on launch and sensitive ops; rate limit; biometric fallback

Security Requirements

• Use expo-secure-store / React Native Keychain for secrets
• Store PIN hash (bcrypt) in secure storage
• Never log or display mnemonic after backup confirmation

Dependencies

• Setup Expo Project with Breez SDK Integration #1 Setup Expo Project with Breez SDK Integration

---

Ticket ID: ticket:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/08b75777-3b05-4a6d-adb0-d25258d13502

[traycerai]

Plan

Observations

The repository is in its initial state with minimal setup. This is a greenfield implementation for a Lightning Network wallet using Expo and Breez SDK. The ticket requires implementing BIP39 mnemonic generation, BIP84 (not BIP44) derivation for native SegWit, AES-256-GCM encryption, secure storage, and biometric/PIN authentication. The implementation must follow React Native security best practices with hardware-backed secure storage and proper key management. Note: The ticket mentions BIP44 with path m/84'/0'/0', but this is actually BIP84 standard for native SegWit addresses.

Approach

The implementation will follow a modular, security-first architecture organized into feature-based modules. The wallet functionality will be separated into distinct services: cryptography (mnemonic/key generation), secure storage (encryption/keychain), authentication (PIN/biometric), and wallet management (creation/restoration). This approach ensures separation of concerns, testability, and maintainability. The implementation will leverage native secure storage mechanisms (iOS Keychain/Android Keystore) through expo-secure-store, with additional AES-256-GCM encryption layer for private keys, and integrate with Breez SDK for Lightning Network synchronization.

Implementation Steps

1. Dependencies Installation

Install required npm packages for wallet functionality:

npm install @breeztech/react-native-breez-sdk
npm install @mfellner/react-native-bip39
npm install bitcoinjs-lib
npm install react-native-aes-gcm-crypto
npm install expo-secure-store
npm install expo-local-authentication
npm install bcryptjs
npm install @types/bcryptjs --save-dev

2. Project Structure Setup

Create the following directory structure under /src:

/src
  /modules
    /wallet
      /services
        - CryptoService.ts
        - SecureStorageService.ts
        - WalletService.ts
      /hooks
        - useWallet.ts
      /screens
        - WalletCreationScreen.tsx
        - SeedPhraseDisplayScreen.tsx
        - SeedPhraseConfirmationScreen.tsx
        - WalletRestoreScreen.tsx
      /components
        - MnemonicDisplay.tsx
        - MnemonicInput.tsx
        - WordConfirmation.tsx
    /auth
      /services
        - AuthService.ts
        - BiometricService.ts
      /hooks
        - useAuth.ts
      /screens
        - PINSetupScreen.tsx
        - PINEntryScreen.tsx
        - BiometricPromptScreen.tsx
      /components
        - PINInput.tsx
        - BiometricButton.tsx
  /constants
    - WalletConstants.ts
    - SecurityConstants.ts
  /types
    - wallet.types.ts
    - auth.types.ts
  /utils
    - validation.ts

3. Cryptography Service Implementation

Create file:src/modules/wallet/services/CryptoService.ts:

Responsibilities:

• Generate 12 or 24-word BIP39 mnemonic using @mfellner/react-native-bip39
• Validate mnemonic checksum
• Derive HD wallet keys using BIP84 derivation path (m/84'/0'/0') with bitcoinjs-lib
• Support optional BIP39 passphrase
• Generate entropy using secure random number generation

Key Methods:

• generateMnemonic(wordCount: 12 | 24): Promise<string> - Generate new mnemonic
• validateMnemonic(mnemonic: string): boolean - Validate checksum and word count
• mnemonicToSeed(mnemonic: string, passphrase?: string): Promise<Buffer> - Convert to seed
• deriveBIP84Keys(seed: Buffer): Promise<{ privateKey: string, publicKey: string }> - Derive keys using m/84'/0'/0' path
• validateWordCount(mnemonic: string): boolean - Ensure 12 or 24 words

Implementation Notes:

• Use bip39.generateMnemonic() with 128 bits (12 words) or 256 bits (24 words) entropy
• Use bip39.validateMnemonic() for checksum validation
• Use bitcoinjs-lib.BIP32Factory for hierarchical deterministic key derivation
• Implement proper error handling for invalid mnemonics

4. Secure Storage Service Implementation

Create file:src/modules/wallet/services/SecureStorageService.ts:

Responsibilities:

• Encrypt private keys using AES-256-GCM via react-native-aes-gcm-crypto
• Store encrypted keys in device keychain using expo-secure-store
• Generate and manage encryption keys
• Secure deletion of sensitive data

Key Methods:

• encryptPrivateKey(privateKey: string, pin: string): Promise<{ encrypted: string, iv: string, tag: string }> - Encrypt with AES-256-GCM
• decryptPrivateKey(encrypted: string, iv: string, tag: string, pin: string): Promise<string> - Decrypt private key
• storeEncryptedKey(keyId: string, encryptedData: object): Promise<void> - Store in keychain
• retrieveEncryptedKey(keyId: string): Promise<object | null> - Retrieve from keychain
• deleteKey(keyId: string): Promise<void> - Securely delete key
• keyExists(keyId: string): Promise<boolean> - Check if key exists

Storage Keys:

• WALLET_ENCRYPTED_PRIVATE_KEY - Encrypted private key
• WALLET_PUBLIC_KEY - Public key (can be stored unencrypted)
• WALLET_DERIVATION_PATH - Derivation path used
• WALLET_CREATED_AT - Timestamp of wallet creation

Implementation Notes:

• Use expo-secure-store with SecureStore.setItemAsync() and SecureStore.getItemAsync()
• Derive AES key from PIN using PBKDF2 with high iteration count (100,000+)
• Store IV and authentication tag alongside encrypted data
• Never log or expose encryption keys

5. Authentication Service Implementation

Create file:src/modules/auth/services/AuthService.ts:

Responsibilities:

• Hash and verify PIN using bcryptjs
• Manage authentication state
• Implement rate limiting for failed attempts
• Handle exponential backoff

Key Methods:

• setupPIN(pin: string): Promise<void> - Hash and store PIN (min 6 digits)
• verifyPIN(pin: string): Promise<boolean> - Verify entered PIN
• changePIN(oldPin: string, newPin: string): Promise<void> - Change PIN
• incrementFailedAttempts(): Promise<void> - Track failed attempts
• resetFailedAttempts(): Promise<void> - Reset on successful auth
• isLocked(): Promise<{ locked: boolean, remainingTime?: number }> - Check lockout status
• validatePINFormat(pin: string): boolean - Ensure 6+ digits

Rate Limiting Logic:

• 3 failed attempts → 30-second lockout
• 6 failed attempts → 5-minute lockout
• 9 failed attempts → 30-minute lockout
• Store attempt count and lockout timestamp in expo-secure-store

Implementation Notes:

• Use bcryptjs.hash() with salt rounds of 10 for PIN hashing
• Store PIN hash in secure storage with key AUTH_PIN_HASH
• Store failed attempts count with key AUTH_FAILED_ATTEMPTS
• Store lockout timestamp with key AUTH_LOCKOUT_UNTIL

Create file:src/modules/auth/services/BiometricService.ts:

Responsibilities:

• Check biometric availability
• Authenticate using biometrics with PIN fallback
• Handle biometric enrollment status

Key Methods:

• isBiometricAvailable(): Promise<boolean> - Check if device supports biometrics
• getBiometricType(): Promise<'fingerprint' | 'faceId' | 'iris' | null> - Get available biometric type
• authenticateWithBiometric(promptMessage: string): Promise<boolean> - Authenticate with fallback to PIN
• isEnrolled(): Promise<boolean> - Check if biometrics are enrolled

Implementation Notes:

• Use expo-local-authentication.authenticateAsync() with disableDeviceFallback: false
• Customize promptMessage for different operations (app launch, send, export)
• Handle LocalAuthenticationResult success/failure states

6. Wallet Service Implementation

Create file:src/modules/wallet/services/WalletService.ts:

Responsibilities:

• Orchestrate wallet creation and restoration flows
• Integrate with Breez SDK for Lightning functionality
• Manage wallet state and lifecycle

Key Methods:

• createWallet(wordCount: 12 | 24, pin: string): Promise<{ mnemonic: string, publicKey: string }> - Full wallet creation flow
• restoreWallet(mnemonic: string, pin: string, passphrase?: string): Promise<{ publicKey: string }> - Restore from seed
• initializeBreezSDK(seed: Buffer): Promise<void> - Initialize Breez SDK with derived keys
• syncWallet(): Promise<void> - Sync wallet state via Breez SDK
• getWalletInfo(): Promise<{ publicKey: string, balance: number, derivationPath: string }> - Get wallet details
• deleteWallet(pin: string): Promise<void> - Securely delete wallet

Wallet Creation Flow:

1. Validate PIN format (6+ digits)
2. Generate mnemonic via CryptoService.generateMnemonic()
3. Return mnemonic to UI for display and user confirmation
4. After user confirms backup, derive keys via CryptoService.deriveBIP84Keys()
5. Encrypt private key via SecureStorageService.encryptPrivateKey()
6. Store encrypted key and metadata
7. Initialize Breez SDK with derived seed
8. Return public key and success status

Wallet Restoration Flow:

1. Validate mnemonic format and checksum via CryptoService.validateMnemonic()
2. Accept optional BIP39 passphrase
3. Derive seed via CryptoService.mnemonicToSeed()
4. Derive keys via CryptoService.deriveBIP84Keys()
5. Encrypt and store private key
6. Initialize Breez SDK
7. Trigger wallet sync via syncWallet()
8. Return public key and success status

Performance Requirements:

• Wallet creation must complete within 5 seconds (excluding user confirmation)
• Wallet restoration must complete within 30 seconds (excluding Breez SDK sync)

7. Wallet Creation UI Flow

Screen 1: file:src/modules/wallet/screens/WalletCreationScreen.tsx

• Present option to create new wallet (12 or 24 words)
• Trigger WalletService.createWallet()
• Navigate to seed phrase display on success

Screen 2: file:src/modules/wallet/screens/SeedPhraseDisplayScreen.tsx

• Display generated mnemonic using file:src/modules/wallet/components/MnemonicDisplay.tsx
• Show numbered word list (1-12 or 1-24)
• Include security warnings: "Never share your seed phrase", "Write it down on paper"
• Provide "I have written it down" checkbox
• Navigate to confirmation screen only after checkbox is checked

Screen 3: file:src/modules/wallet/screens/SeedPhraseConfirmationScreen.tsx

• Use file:src/modules/wallet/components/WordConfirmation.tsx
• Randomly select 3-4 words from the mnemonic
• Ask user to enter selected words in correct order
• Validate user input matches original mnemonic
• On success, complete wallet creation (derive keys, encrypt, store)
• Navigate to main wallet screen

Component: file:src/modules/wallet/components/MnemonicDisplay.tsx

• Display mnemonic words in a grid layout (2 columns)
• Each word numbered and clearly visible
• Copy-to-clipboard functionality (with warning)
• Blur/hide option for privacy

8. Wallet Restoration UI Flow

Screen: file:src/modules/wallet/screens/WalletRestoreScreen.tsx

• Use file:src/modules/wallet/components/MnemonicInput.tsx for word entry
• Support 12 or 24-word input
• Auto-detect word count
• Provide word suggestions from BIP39 wordlist
• Optional passphrase input field (collapsed by default)
• Validate mnemonic on submit via CryptoService.validateMnemonic()
• Show error if checksum invalid: "Invalid seed phrase. Please check your words."
• On valid mnemonic, trigger WalletService.restoreWallet()
• Show loading indicator during restoration and sync
• Navigate to main wallet screen on success

Component: file:src/modules/wallet/components/MnemonicInput.tsx

• Text input with word-by-word entry
• Auto-complete from BIP39 wordlist
• Word count indicator (e.g., "8/12 words")
• Clear individual words or entire phrase
• Paste support (split by spaces)

9. Authentication UI Flow

Screen: file:src/modules/auth/screens/PINSetupScreen.tsx

• Shown during initial wallet creation
• Use file:src/modules/auth/components/PINInput.tsx
• Require 6-digit minimum PIN
• Confirm PIN entry (enter twice)
• Validate PIN format via AuthService.validatePINFormat()
• Store PIN hash via AuthService.setupPIN()

Screen: file:src/modules/auth/screens/PINEntryScreen.tsx

• Shown on app launch and before sensitive operations
• Use file:src/modules/auth/components/PINInput.tsx
• Verify PIN via AuthService.verifyPIN()
• Show failed attempt count after 1st failure
• Display lockout timer if rate limit exceeded
• Option to use biometric authentication via file:src/modules/auth/components/BiometricButton.tsx

Component: file:src/modules/auth/components/BiometricButton.tsx

• Check availability via BiometricService.isBiometricAvailable()
• Display appropriate icon (fingerprint/face)
• Trigger BiometricService.authenticateWithBiometric()
• Fallback to PIN on biometric failure
• Show "Use PIN instead" option

10. Security Implementation Details

Mnemonic Security:

• Never log mnemonic to console or analytics
• Clear mnemonic from memory after encryption
• Warn user if screenshot is detected during seed phrase display
• Implement screen capture prevention on seed phrase screens (iOS/Android)

Key Storage Security:

• Use expo-secure-store with SecureStore.WHEN_UNLOCKED accessibility option (iOS)
• Enable requireAuthentication option for keychain access
• Store encryption metadata (IV, tag) separately from encrypted data
• Implement secure key deletion on wallet reset

Authentication Security:

• Implement exponential backoff: 30s → 5m → 30m
• Clear sensitive data from memory after authentication
• Require re-authentication after app backgrounding for 5+ minutes
• Log authentication events (success/failure) for audit trail

Network Security:

• Ensure Breez SDK uses TLS for all communications
• Validate SSL certificates
• Implement timeout for network operations (30s)

11. Constants and Types

Create file:src/constants/WalletConstants.ts:

export const DERIVATION_PATH_BIP84 = "m/84'/0'/0'";
export const MNEMONIC_WORD_COUNT_12 = 12;
export const MNEMONIC_WORD_COUNT_24 = 24;
export const WALLET_CREATION_TIMEOUT = 5000; // 5 seconds
export const WALLET_RESTORE_TIMEOUT = 30000; // 30 seconds

Create file:src/constants/SecurityConstants.ts:

export const MIN_PIN_LENGTH = 6;
export const MAX_FAILED_ATTEMPTS_TIER1 = 3;
export const MAX_FAILED_ATTEMPTS_TIER2 = 6;
export const MAX_FAILED_ATTEMPTS_TIER3 = 9;
export const LOCKOUT_DURATION_TIER1 = 30000; // 30 seconds
export const LOCKOUT_DURATION_TIER2 = 300000; // 5 minutes
export const LOCKOUT_DURATION_TIER3 = 1800000; // 30 minutes
export const BCRYPT_SALT_ROUNDS = 10;
export const PBKDF2_ITERATIONS = 100000;
export const AES_KEY_SIZE = 256;

Create file:src/types/wallet.types.ts:

export interface WalletKeys {
  privateKey: string;
  publicKey: string;
  derivationPath: string;
}

export interface EncryptedWalletData {
  encrypted: string;
  iv: string;
  tag: string;
}

export interface WalletInfo {
  publicKey: string;
  balance: number;
  derivationPath: string;
  createdAt: number;
}

Create file:src/types/auth.types.ts:

export interface AuthState {
  isAuthenticated: boolean;
  failedAttempts: number;
  lockedUntil: number | null;
}

export interface BiometricInfo {
  available: boolean;
  type: 'fingerprint' | 'faceId' | 'iris' | null;
  enrolled: boolean;
}

12. Custom Hooks

Create file:src/modules/wallet/hooks/useWallet.ts:

• Wrap WalletService methods in React hooks
• Manage wallet state (loading, error, success)
• Provide methods: createWallet(), restoreWallet(), getWalletInfo(), syncWallet()
• Handle error states and user feedback

Create file:src/modules/auth/hooks/useAuth.ts:

• Wrap AuthService and BiometricService methods
• Manage authentication state
• Provide methods: setupPIN(), verifyPIN(), authenticateWithBiometric(), checkLockout()
• Handle rate limiting and lockout UI updates

13. Validation Utilities

Create file:src/utils/validation.ts:

• validatePINFormat(pin: string): boolean - Check 6+ digits, numeric only
• validateMnemonicWordCount(mnemonic: string): boolean - Check 12 or 24 words
• sanitizeMnemonicInput(input: string): string - Trim, lowercase, normalize spaces
• isValidBIP39Word(word: string): boolean - Check against BIP39 wordlist

14. Integration with Breez SDK

In file:src/modules/wallet/services/WalletService.ts, implement Breez SDK integration:

Initialization:

• Import @breeztech/react-native-breez-sdk
• Call BreezSDK.connect() with derived seed and configuration
• Handle connection events and errors
• Store Breez SDK node ID in secure storage

Synchronization:

• Implement syncWallet() to fetch latest state from Breez SDK
• Update local balance and transaction history
• Handle sync errors gracefully with retry logic
• Show sync progress to user during restoration

Configuration:

• Use Breez SDK API key (request from contact@breez.technology)
• Configure network (mainnet/testnet) based on environment
• Set appropriate timeouts and retry policies

15. Error Handling and User Feedback

Error Types:

• WalletCreationError - Failed to create wallet
• WalletRestorationError - Failed to restore wallet
• InvalidMnemonicError - Invalid seed phrase
• AuthenticationError - PIN/biometric verification failed
• EncryptionError - Failed to encrypt/decrypt keys
• NetworkError - Breez SDK connection issues

User Feedback:

• Show loading indicators during async operations
• Display clear error messages with actionable guidance
• Provide success confirmations for completed operations
• Implement toast notifications for non-critical updates
• Use modal dialogs for critical errors requiring user action

16. Testing Considerations

While not explicitly required, consider these testing points:

Unit Tests:

• Test CryptoService mnemonic generation and validation
• Test AuthService PIN hashing and verification
• Test rate limiting logic
• Test encryption/decryption roundtrip

Integration Tests:

• Test full wallet creation flow
• Test wallet restoration with valid/invalid mnemonics
• Test authentication flow with biometric fallback

Security Tests:

• Verify encrypted data cannot be decrypted without PIN
• Verify rate limiting prevents brute force
• Verify sensitive data is cleared from memory

Architecture Diagram

sequenceDiagram
    participant User
    participant UI
    participant WalletService
    participant CryptoService
    participant SecureStorage
    participant AuthService
    participant BreezSDK

    Note over User,BreezSDK: Wallet Creation Flow
    User->>UI: Create New Wallet (12/24 words)
    UI->>WalletService: createWallet(wordCount, pin)
    WalletService->>CryptoService: generateMnemonic(wordCount)
    CryptoService-->>WalletService: mnemonic
    WalletService-->>UI: mnemonic
    UI->>User: Display Seed Phrase
    User->>UI: Confirm Backup
    UI->>WalletService: confirmBackup()
    WalletService->>CryptoService: deriveBIP84Keys(seed)
    CryptoService-->>WalletService: { privateKey, publicKey }
    WalletService->>SecureStorage: encryptPrivateKey(privateKey, pin)
    SecureStorage-->>WalletService: encryptedData
    WalletService->>SecureStorage: storeEncryptedKey(encryptedData)
    WalletService->>BreezSDK: connect(seed)
    BreezSDK-->>WalletService: connected
    WalletService-->>UI: success
    UI->>User: Wallet Created

    Note over User,BreezSDK: Wallet Restoration Flow
    User->>UI: Enter Seed Phrase
    UI->>WalletService: restoreWallet(mnemonic, pin, passphrase)
    WalletService->>CryptoService: validateMnemonic(mnemonic)
    CryptoService-->>WalletService: valid
    WalletService->>CryptoService: mnemonicToSeed(mnemonic, passphrase)
    CryptoService-->>WalletService: seed
    WalletService->>CryptoService: deriveBIP84Keys(seed)
    CryptoService-->>WalletService: { privateKey, publicKey }
    WalletService->>SecureStorage: encryptPrivateKey(privateKey, pin)
    SecureStorage-->>WalletService: encryptedData
    WalletService->>SecureStorage: storeEncryptedKey(encryptedData)
    WalletService->>BreezSDK: connect(seed)
    BreezSDK-->>WalletService: connected
    WalletService->>BreezSDK: syncWallet()
    BreezSDK-->>WalletService: synced
    WalletService-->>UI: success
    UI->>User: Wallet Restored

    Note over User,BreezSDK: Authentication Flow
    User->>UI: App Launch
    UI->>AuthService: checkLockout()
    AuthService-->>UI: not locked
    UI->>User: Enter PIN or Biometric
    User->>UI: Provide Auth
    UI->>AuthService: verifyPIN(pin) or authenticateWithBiometric()
    AuthService-->>UI: authenticated
    UI->>User: Access Granted

Loading

Key Files Reference

• file:src/modules/wallet/services/CryptoService.ts - BIP39/BIP84 cryptography
• file:src/modules/wallet/services/SecureStorageService.ts - AES-256-GCM encryption and keychain storage
• file:src/modules/wallet/services/WalletService.ts - Wallet orchestration and Breez SDK integration
• file:src/modules/auth/services/AuthService.ts - PIN management and rate limiting
• file:src/modules/auth/services/BiometricService.ts - Biometric authentication
• file:src/modules/wallet/screens/SeedPhraseDisplayScreen.tsx - Seed phrase display UI
• file:src/modules/wallet/screens/SeedPhraseConfirmationScreen.tsx - Backup confirmation UI
• file:src/modules/wallet/screens/WalletRestoreScreen.tsx - Restoration UI
• file:src/modules/auth/screens/PINEntryScreen.tsx - Authentication UI
• file:src/constants/WalletConstants.ts - Wallet configuration constants
• file:src/constants/SecurityConstants.ts - Security configuration constants

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repository is in its initial state with minimal setup. This is a greenfield implementation for a Lightning Network wallet using Expo and Breez SDK. The ticket requires implementing BIP39 mnemonic generation, BIP84 (not BIP44) derivation for native SegWit, AES-256-GCM encryption, secure storage, and biometric/PIN authentication. The implementation must follow React Native security best practices with hardware-backed secure storage and proper key management. Note: The ticket mentions BIP44 with path m/84'/0'/0', but this is actually BIP84 standard for native SegWit addresses.

## Approach

The implementation will follow a modular, security-first architecture organized into feature-based modules. The wallet functionality will be separated into distinct services: cryptography (mnemonic/key generation), secure storage (encryption/keychain), authentication (PIN/biometric), and wallet management (creation/restoration). This approach ensures separation of concerns, testability, and maintainability. The implementation will leverage native secure storage mechanisms (iOS Keychain/Android Keystore) through expo-secure-store, with additional AES-256-GCM encryption layer for private keys, and integrate with Breez SDK for Lightning Network synchronization.

## Implementation Steps

### 1. Dependencies Installation

Install required npm packages for wallet functionality:

```bash
npm install @breeztech/react-native-breez-sdk
npm install @mfellner/react-native-bip39
npm install bitcoinjs-lib
npm install react-native-aes-gcm-crypto
npm install expo-secure-store
npm install expo-local-authentication
npm install bcryptjs
npm install @types/bcryptjs --save-dev
```

### 2. Project Structure Setup

Create the following directory structure under `/src`:

```
/src
  /modules
    /wallet
      /services
        - CryptoService.ts
        - SecureStorageService.ts
        - WalletService.ts
      /hooks
        - useWallet.ts
      /screens
        - WalletCreationScreen.tsx
        - SeedPhraseDisplayScreen.tsx
        - SeedPhraseConfirmationScreen.tsx
        - WalletRestoreScreen.tsx
      /components
        - MnemonicDisplay.tsx
        - MnemonicInput.tsx
        - WordConfirmation.tsx
    /auth
      /services
        - AuthService.ts
        - BiometricService.ts
      /hooks
        - useAuth.ts
      /screens
        - PINSetupScreen.tsx
        - PINEntryScreen.tsx
        - BiometricPromptScreen.tsx
      /components
        - PINInput.tsx
        - BiometricButton.tsx
  /constants
    - WalletConstants.ts
    - SecurityConstants.ts
  /types
    - wallet.types.ts
    - auth.types.ts
  /utils
    - validation.ts
```

### 3. Cryptography Service Implementation

Create `file:src/modules/wallet/services/CryptoService.ts`:

**Responsibilities:**
- Generate 12 or 24-word BIP39 mnemonic using `@mfellner/react-native-bip39`
- Validate mnemonic checksum
- Derive HD wallet keys using BIP84 derivation path (m/84'/0'/0') with `bitcoinjs-lib`
- Support optional BIP39 passphrase
- Generate entropy using secure random number generation

**Key Methods:**
- `generateMnemonic(wordCount: 12 | 24): Promise<string>` - Generate new mnemonic
- `validateMnemonic(mnemonic: string): boolean` - Validate checksum and word count
- `mnemonicToSeed(mnemonic: string, passphrase?: string): Promise<Buffer>` - Convert to seed
- `deriveBIP84Keys(seed: Buffer): Promise<{ privateKey: string, publicKey: string }>` - Derive keys using m/84'/0'/0' path
- `validateWordCount(mnemonic: string): boolean` - Ensure 12 or 24 words

**Implementation Notes:**
- Use `bip39.generateMnemonic()` with 128 bits (12 words) or 256 bits (24 words) entropy
- Use `bip39.validateMnemonic()` for checksum validation
- Use `bitcoinjs-lib.BIP32Factory` for hierarchical deterministic key derivation
- Implement proper error handling for invalid mnemonics

### 4. Secure Storage Service Implementation

Create `file:src/modules/wallet/services/SecureStorageService.ts`:

**Responsibilities:**
- Encrypt private keys using AES-256-GCM via `react-native-aes-gcm-crypto`
- Store encrypted keys in device keychain using `expo-secure-store`
- Generate and manage encryption keys
- Secure deletion of sensitive data

**Key Methods:**
- `encryptPrivateKey(privateKey: string, pin: string): Promise<{ encrypted: string, iv: string, tag: string }>` - Encrypt with AES-256-GCM
- `decryptPrivateKey(encrypted: string, iv: string, tag: string, pin: string): Promise<string>` - Decrypt private key
- `storeEncryptedKey(keyId: string, encryptedData: object): Promise<void>` - Store in keychain
- `retrieveEncryptedKey(keyId: string): Promise<object | null>` - Retrieve from keychain
- `deleteKey(keyId: string): Promise<void>` - Securely delete key
- `keyExists(keyId: string): Promise<boolean>` - Check if key exists

**Storage Keys:**
- `WALLET_ENCRYPTED_PRIVATE_KEY` - Encrypted private key
- `WALLET_PUBLIC_KEY` - Public key (can be stored unencrypted)
- `WALLET_DERIVATION_PATH` - Derivation path used
- `WALLET_CREATED_AT` - Timestamp of wallet creation

**Implementation Notes:**
- Use `expo-secure-store` with `SecureStore.setItemAsync()` and `SecureStore.getItemAsync()`
- Derive AES key from PIN using PBKDF2 with high iteration count (100,000+)
- Store IV and authentication tag alongside encrypted data
- Never log or expose encryption keys

### 5. Authentication Service Implementation

Create `file:src/modules/auth/services/AuthService.ts`:

**Responsibilities:**
- Hash and verify PIN using bcryptjs
- Manage authentication state
- Implement rate limiting for failed attempts
- Handle exponential backoff

**Key Methods:**
- `setupPIN(pin: string): Promise<void>` - Hash and store PIN (min 6 digits)
- `verifyPIN(pin: string): Promise<boolean>` - Verify entered PIN
- `changePIN(oldPin: string, newPin: string): Promise<void>` - Change PIN
- `incrementFailedAttempts(): Promise<void>` - Track failed attempts
- `resetFailedAttempts(): Promise<void>` - Reset on successful auth
- `isLocked(): Promise<{ locked: boolean, remainingTime?: number }>` - Check lockout status
- `validatePINFormat(pin: string): boolean` - Ensure 6+ digits

**Rate Limiting Logic:**
- 3 failed attempts → 30-second lockout
- 6 failed attempts → 5-minute lockout
- 9 failed attempts → 30-minute lockout
- Store attempt count and lockout timestamp in `expo-secure-store`

**Implementation Notes:**
- Use `bcryptjs.hash()` with salt rounds of 10 for PIN hashing
- Store PIN hash in secure storage with key `AUTH_PIN_HASH`
- Store failed attempts count with key `AUTH_FAILED_ATTEMPTS`
- Store lockout timestamp with key `AUTH_LOCKOUT_UNTIL`

Create `file:src/modules/auth/services/BiometricService.ts`:

**Responsibilities:**
- Check biometric availability
- Authenticate using biometrics with PIN fallback
- Handle biometric enrollment status

**Key Methods:**
- `isBiometricAvailable(): Promise<boolean>` - Check if device supports biometrics
- `getBiometricType(): Promise<'fingerprint' | 'faceId' | 'iris' | null>` - Get available biometric type
- `authenticateWithBiometric(promptMessage: string): Promise<boolean>` - Authenticate with fallback to PIN
- `isEnrolled(): Promise<boolean>` - Check if biometrics are enrolled

**Implementation Notes:**
- Use `expo-local-authentication.authenticateAsync()` with `disableDeviceFallback: false`
- Customize `promptMessage` for different operations (app launch, send, export)
- Handle `LocalAuthenticationResult` success/failure states

### 6. Wallet Service Implementation

Create `file:src/modules/wallet/services/WalletService.ts`:

**Responsibilities:**
- Orchestrate wallet creation and restoration flows
- Integrate with Breez SDK for Lightning functionality
- Manage wallet state and lifecycle

**Key Methods:**
- `createWallet(wordCount: 12 | 24, pin: string): Promise<{ mnemonic: string, publicKey: string }>` - Full wallet creation flow
- `restoreWallet(mnemonic: string, pin: string, passphrase?: string): Promise<{ publicKey: string }>` - Restore from seed
- `initializeBreezSDK(seed: Buffer): Promise<void>` - Initialize Breez SDK with derived keys
- `syncWallet(): Promise<void>` - Sync wallet state via Breez SDK
- `getWalletInfo(): Promise<{ publicKey: string, balance: number, derivationPath: string }>` - Get wallet details
- `deleteWallet(pin: string): Promise<void>` - Securely delete wallet

**Wallet Creation Flow:**
1. Validate PIN format (6+ digits)
2. Generate mnemonic via `CryptoService.generateMnemonic()`
3. Return mnemonic to UI for display and user confirmation
4. After user confirms backup, derive keys via `CryptoService.deriveBIP84Keys()`
5. Encrypt private key via `SecureStorageService.encryptPrivateKey()`
6. Store encrypted key and metadata
7. Initialize Breez SDK with derived seed
8. Return public key and success status

**Wallet Restoration Flow:**
1. Validate mnemonic format and checksum via `CryptoService.validateMnemonic()`
2. Accept optional BIP39 passphrase
3. Derive seed via `CryptoService.mnemonicToSeed()`
4. Derive keys via `CryptoService.deriveBIP84Keys()`
5. Encrypt and store private key
6. Initialize Breez SDK
7. Trigger wallet sync via `syncWallet()`
8. Return public key and success status

**Performance Requirements:**
- Wallet creation must complete within 5 seconds (excluding user confirmation)
- Wallet restoration must complete within 30 seconds (excluding Breez SDK sync)

### 7. Wallet Creation UI Flow

**Screen 1: `file:src/modules/wallet/screens/WalletCreationScreen.tsx`**
- Present option to create new wallet (12 or 24 words)
- Trigger `WalletService.createWallet()`
- Navigate to seed phrase display on success

**Screen 2: `file:src/modules/wallet/screens/SeedPhraseDisplayScreen.tsx`**
- Display generated mnemonic using `file:src/modules/wallet/components/MnemonicDisplay.tsx`
- Show numbered word list (1-12 or 1-24)
- Include security warnings: "Never share your seed phrase", "Write it down on paper"
- Provide "I have written it down" checkbox
- Navigate to confirmation screen only after checkbox is checked

**Screen 3: `file:src/modules/wallet/screens/SeedPhraseConfirmationScreen.tsx`**
- Use `file:src/modules/wallet/components/WordConfirmation.tsx`
- Randomly select 3-4 words from the mnemonic
- Ask user to enter selected words in correct order
- Validate user input matches original mnemonic
- On success, complete wallet creation (derive keys, encrypt, store)
- Navigate to main wallet screen

**Component: `file:src/modules/wallet/components/MnemonicDisplay.tsx`**
- Display mnemonic words in a grid layout (2 columns)
- Each word numbered and clearly visible
- Copy-to-clipboard functionality (with warning)
- Blur/hide option for privacy

### 8. Wallet Restoration UI Flow

**Screen: `file:src/modules/wallet/screens/WalletRestoreScreen.tsx`**
- Use `file:src/modules/wallet/components/MnemonicInput.tsx` for word entry
- Support 12 or 24-word input
- Auto-detect word count
- Provide word suggestions from BIP39 wordlist
- Optional passphrase input field (collapsed by default)
- Validate mnemonic on submit via `CryptoService.validateMnemonic()`
- Show error if checksum invalid: "Invalid seed phrase. Please check your words."
- On valid mnemonic, trigger `WalletService.restoreWallet()`
- Show loading indicator during restoration and sync
- Navigate to main wallet screen on success

**Component: `file:src/modules/wallet/components/MnemonicInput.tsx`**
- Text input with word-by-word entry
- Auto-complete from BIP39 wordlist
- Word count indicator (e.g., "8/12 words")
- Clear individual words or entire phrase
- Paste support (split by spaces)

### 9. Authentication UI Flow

**Screen: `file:src/modules/auth/screens/PINSetupScreen.tsx`**
- Shown during initial wallet creation
- Use `file:src/modules/auth/components/PINInput.tsx`
- Require 6-digit minimum PIN
- Confirm PIN entry (enter twice)
- Validate PIN format via `AuthService.validatePINFormat()`
- Store PIN hash via `AuthService.setupPIN()`

**Screen: `file:src/modules/auth/screens/PINEntryScreen.tsx`**
- Shown on app launch and before sensitive operations
- Use `file:src/modules/auth/components/PINInput.tsx`
- Verify PIN via `AuthService.verifyPIN()`
- Show failed attempt count after 1st failure
- Display lockout timer if rate limit exceeded
- Option to use biometric authentication via `file:src/modules/auth/components/BiometricButton.tsx`

**Component: `file:src/modules/auth/components/BiometricButton.tsx`**
- Check availability via `BiometricService.isBiometricAvailable()`
- Display appropriate icon (fingerprint/face)
- Trigger `BiometricService.authenticateWithBiometric()`
- Fallback to PIN on biometric failure
- Show "Use PIN instead" option

### 10. Security Implementation Details

**Mnemonic Security:**
- Never log mnemonic to console or analytics
- Clear mnemonic from memory after encryption
- Warn user if screenshot is detected during seed phrase display
- Implement screen capture prevention on seed phrase screens (iOS/Android)

**Key Storage Security:**
- Use `expo-secure-store` with `SecureStore.WHEN_UNLOCKED` accessibility option (iOS)
- Enable `requireAuthentication` option for keychain access
- Store encryption metadata (IV, tag) separately from encrypted data
- Implement secure key deletion on wallet reset

**Authentication Security:**
- Implement exponential backoff: 30s → 5m → 30m
- Clear sensitive data from memory after authentication
- Require re-authentication after app backgrounding for 5+ minutes
- Log authentication events (success/failure) for audit trail

**Network Security:**
- Ensure Breez SDK uses TLS for all communications
- Validate SSL certificates
- Implement timeout for network operations (30s)

### 11. Constants and Types

Create `file:src/constants/WalletConstants.ts`:
```typescript
export const DERIVATION_PATH_BIP84 = "m/84'/0'/0'";
export const MNEMONIC_WORD_COUNT_12 = 12;
export const MNEMONIC_WORD_COUNT_24 = 24;
export const WALLET_CREATION_TIMEOUT = 5000; // 5 seconds
export const WALLET_RESTORE_TIMEOUT = 30000; // 30 seconds
```

Create `file:src/constants/SecurityConstants.ts`:
```typescript
export const MIN_PIN_LENGTH = 6;
export const MAX_FAILED_ATTEMPTS_TIER1 = 3;
export const MAX_FAILED_ATTEMPTS_TIER2 = 6;
export const MAX_FAILED_ATTEMPTS_TIER3 = 9;
export const LOCKOUT_DURATION_TIER1 = 30000; // 30 seconds
export const LOCKOUT_DURATION_TIER2 = 300000; // 5 minutes
export const LOCKOUT_DURATION_TIER3 = 1800000; // 30 minutes
export const BCRYPT_SALT_ROUNDS = 10;
export const PBKDF2_ITERATIONS = 100000;
export const AES_KEY_SIZE = 256;
```

Create `file:src/types/wallet.types.ts`:
```typescript
export interface WalletKeys {
  privateKey: string;
  publicKey: string;
  derivationPath: string;
}

export interface EncryptedWalletData {
  encrypted: string;
  iv: string;
  tag: string;
}

export interface WalletInfo {
  publicKey: string;
  balance: number;
  derivationPath: string;
  createdAt: number;
}
```

Create `file:src/types/auth.types.ts`:
```typescript
export interface AuthState {
  isAuthenticated: boolean;
  failedAttempts: number;
  lockedUntil: number | null;
}

export interface BiometricInfo {
  available: boolean;
  type: 'fingerprint' | 'faceId' | 'iris' | null;
  enrolled: boolean;
}
```

### 12. Custom Hooks

Create `file:src/modules/wallet/hooks/useWallet.ts`:
- Wrap `WalletService` methods in React hooks
- Manage wallet state (loading, error, success)
- Provide methods: `createWallet()`, `restoreWallet()`, `getWalletInfo()`, `syncWallet()`
- Handle error states and user feedback

Create `file:src/modules/auth/hooks/useAuth.ts`:
- Wrap `AuthService` and `BiometricService` methods
- Manage authentication state
- Provide methods: `setupPIN()`, `verifyPIN()`, `authenticateWithBiometric()`, `checkLockout()`
- Handle rate limiting and lockout UI updates

### 13. Validation Utilities

Create `file:src/utils/validation.ts`:
- `validatePINFormat(pin: string): boolean` - Check 6+ digits, numeric only
- `validateMnemonicWordCount(mnemonic: string): boolean` - Check 12 or 24 words
- `sanitizeMnemonicInput(input: string): string` - Trim, lowercase, normalize spaces
- `isValidBIP39Word(word: string): boolean` - Check against BIP39 wordlist

### 14. Integration with Breez SDK

In `file:src/modules/wallet/services/WalletService.ts`, implement Breez SDK integration:

**Initialization:**
- Import `@breeztech/react-native-breez-sdk`
- Call `BreezSDK.connect()` with derived seed and configuration
- Handle connection events and errors
- Store Breez SDK node ID in secure storage

**Synchronization:**
- Implement `syncWallet()` to fetch latest state from Breez SDK
- Update local balance and transaction history
- Handle sync errors gracefully with retry logic
- Show sync progress to user during restoration

**Configuration:**
- Use Breez SDK API key (request from contact@breez.technology)
- Configure network (mainnet/testnet) based on environment
- Set appropriate timeouts and retry policies

### 15. Error Handling and User Feedback

**Error Types:**
- `WalletCreationError` - Failed to create wallet
- `WalletRestorationError` - Failed to restore wallet
- `InvalidMnemonicError` - Invalid seed phrase
- `AuthenticationError` - PIN/biometric verification failed
- `EncryptionError` - Failed to encrypt/decrypt keys
- `NetworkError` - Breez SDK connection issues

**User Feedback:**
- Show loading indicators during async operations
- Display clear error messages with actionable guidance
- Provide success confirmations for completed operations
- Implement toast notifications for non-critical updates
- Use modal dialogs for critical errors requiring user action

### 16. Testing Considerations

While not explicitly required, consider these testing points:

**Unit Tests:**
- Test `CryptoService` mnemonic generation and validation
- Test `AuthService` PIN hashing and verification
- Test rate limiting logic
- Test encryption/decryption roundtrip

**Integration Tests:**
- Test full wallet creation flow
- Test wallet restoration with valid/invalid mnemonics
- Test authentication flow with biometric fallback

**Security Tests:**
- Verify encrypted data cannot be decrypted without PIN
- Verify rate limiting prevents brute force
- Verify sensitive data is cleared from memory

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant UI
    participant WalletService
    participant CryptoService
    participant SecureStorage
    participant AuthService
    participant BreezSDK

    Note over User,BreezSDK: Wallet Creation Flow
    User->>UI: Create New Wallet (12/24 words)
    UI->>WalletService: createWallet(wordCount, pin)
    WalletService->>CryptoService: generateMnemonic(wordCount)
    CryptoService-->>WalletService: mnemonic
    WalletService-->>UI: mnemonic
    UI->>User: Display Seed Phrase
    User->>UI: Confirm Backup
    UI->>WalletService: confirmBackup()
    WalletService->>CryptoService: deriveBIP84Keys(seed)
    CryptoService-->>WalletService: { privateKey, publicKey }
    WalletService->>SecureStorage: encryptPrivateKey(privateKey, pin)
    SecureStorage-->>WalletService: encryptedData
    WalletService->>SecureStorage: storeEncryptedKey(encryptedData)
    WalletService->>BreezSDK: connect(seed)
    BreezSDK-->>WalletService: connected
    WalletService-->>UI: success
    UI->>User: Wallet Created

    Note over User,BreezSDK: Wallet Restoration Flow
    User->>UI: Enter Seed Phrase
    UI->>WalletService: restoreWallet(mnemonic, pin, passphrase)
    WalletService->>CryptoService: validateMnemonic(mnemonic)
    CryptoService-->>WalletService: valid
    WalletService->>CryptoService: mnemonicToSeed(mnemonic, passphrase)
    CryptoService-->>WalletService: seed
    WalletService->>CryptoService: deriveBIP84Keys(seed)
    CryptoService-->>WalletService: { privateKey, publicKey }
    WalletService->>SecureStorage: encryptPrivateKey(privateKey, pin)
    SecureStorage-->>WalletService: encryptedData
    WalletService->>SecureStorage: storeEncryptedKey(encryptedData)
    WalletService->>BreezSDK: connect(seed)
    BreezSDK-->>WalletService: connected
    WalletService->>BreezSDK: syncWallet()
    BreezSDK-->>WalletService: synced
    WalletService-->>UI: success
    UI->>User: Wallet Restored

    Note over User,BreezSDK: Authentication Flow
    User->>UI: App Launch
    UI->>AuthService: checkLockout()
    AuthService-->>UI: not locked
    UI->>User: Enter PIN or Biometric
    User->>UI: Provide Auth
    UI->>AuthService: verifyPIN(pin) or authenticateWithBiometric()
    AuthService-->>UI: authenticated
    UI->>User: Access Granted
```

## Key Files Reference

- `file:src/modules/wallet/services/CryptoService.ts` - BIP39/BIP84 cryptography
- `file:src/modules/wallet/services/SecureStorageService.ts` - AES-256-GCM encryption and keychain storage
- `file:src/modules/wallet/services/WalletService.ts` - Wallet orchestration and Breez SDK integration
- `file:src/modules/auth/services/AuthService.ts` - PIN management and rate limiting
- `file:src/modules/auth/services/BiometricService.ts` - Biometric authentication
- `file:src/modules/wallet/screens/SeedPhraseDisplayScreen.tsx` - Seed phrase display UI
- `file:src/modules/wallet/screens/SeedPhraseConfirmationScreen.tsx` - Backup confirmation UI
- `file:src/modules/wallet/screens/WalletRestoreScreen.tsx` - Restoration UI
- `file:src/modules/auth/screens/PINEntryScreen.tsx` - Authentication UI
- `file:src/constants/WalletConstants.ts` - Wallet configuration constants
- `file:src/constants/SecurityConstants.ts` - Security configuration constants

---

Execution Information

Branch: main
Commit: 342104b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.