dop-wallet-v6 1.2.11 → 1.2.13

package/DOP_WALLET_V6_REACT_NATIVE_INTEGRATION_GUIDE.md

@@ -0,0 +1,2174 @@
+# DOP Wallet v6 React Native Integration Guide
+
+This comprehensive guide covers the integration of DOP Wallet v6 (dop-wallet-v6) into React Native applications, providing privacy-focused features for both ERC-20 tokens and ERC-721 NFTs on Ethereum, Polygon, and BNB Chain.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Installation](#installation)
+3. [Initialize Engine](#initialize-engine)
+4. [Wallet Management](#wallet-management)
+   - [Wallet Creation Functions](#wallet-creation-functions)
+   - [Input Requirements](#input-requirements)
+   - [React Native Wallet Creation](#react-native-wallet-creation)
+   - [Complete Examples](#complete-examples)
+   - [Error Handling](#error-handling)
+   - [Best Practices for React Native](#best-practices-for-react-native)
+   - [Migration from Old API](#migration-from-old-api)
+5. [ERC-20 Token Features](#erc-20-token-features)
+   - [Balances](#erc-20-balances)
+   - [Syncing](#erc-20-syncing)
+   - [Encrypt, Send, Decrypt](#erc-20-encrypt-send-decrypt)
+   - [Transaction History](#erc-20-transaction-history)
+   - [Selective Transparency and Proof Verification](#erc-20-selective-transparency)
+6. [ERC-721 NFT Features](#erc-721-nft-features)
+   - [Balances](#erc-721-balances)
+   - [Syncing](#erc-721-syncing)
+   - [Encrypt, Send, Decrypt](#erc-721-encrypt-send-decrypt)
+   - [Transaction History](#erc-721-transaction-history)
+   - [Selective Transparency and Proof Verification](#erc-721-selective-transparency)
+7. [Advanced Features](#advanced-features)
+   - [Transaction History with Wallet Visibility](#transaction-history-visibility)
+8. [Complete Example](#complete-example)
+9. [Testing](#testing)
+10. [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+- React Native 0.65+
+- Node.js 16+
+- TypeScript support
+- React Native async storage or compatible storage solution
+- LevelDB compatible database for React Native
+
+## Installation
+
+### 1. Install the DOP Wallet SDK
+
+```bash
+npm install dop-wallet-v6
+# or
+yarn add dop-wallet-v6
+```
+
+### 2. Install Required Peer Dependencies
+
+The SDK requires AsyncStorage for React Native persistence:
+
+```bash
+npm install @react-native-async-storage/async-storage
+# or
+yarn add @react-native-async-storage/async-storage
+```
+
+**Note**: If you encounter issues with `startDopEngineReactNative` being undefined, ensure all dependencies are properly installed:
+
+```bash
+# Force reinstall dependencies if needed
+npm install --legacy-peer-deps
+# or
+yarn install
+```
+
+### 3. Install React Native Dependencies
+
+Install the required React Native-specific dependencies:
+
+```bash
+npm install @react-native-async-storage/async-storage
+```
+
+**Or with Yarn:**
+
+```bash
+yarn add @react-native-async-storage/async-storage
+```
+
+> **Important**: The SDK now uses an in-memory database (memdown) for React Native compatibility. AsyncStorage is used only for artifact caching and user preferences.
+
+> **Important**: These polyfills are essential for the SDK to function properly. Missing them will cause errors like "Cannot read property 'call' of undefined" or other runtime failures.
+
+### 3. Metro Configuration
+
+Create or update your `metro.config.js` file to include Node.js core module aliases:
+
+```javascript
+const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+// Add Node.js core module aliases
+config.resolver.alias = {
+  ...config.resolver.alias,
+  'stream': require.resolve('stream-browserify'),
+  'crypto': require.resolve('crypto-browserify'),
+  'http': require.resolve('stream-http'),
+  'https': require.resolve('https-browserify'),
+  'url': require.resolve('url'),
+  'util': require.resolve('util'),
+  'zlib': require.resolve('browserify-zlib'),
+  'path': require.resolve('path-browserify'),
+};
+
+// Add required packages to Metro's resolver
+config.resolver.extraNodeModules = {
+  ...config.resolver.extraNodeModules,
+  'stream': require.resolve('stream-browserify'),
+  'crypto': require.resolve('crypto-browserify'),
+  'http': require.resolve('stream-http'),
+  'https': require.resolve('https-browserify'),
+  'url': require.resolve('url'),
+  'util': require.resolve('util'),
+  'zlib': require.resolve('browserify-zlib'),
+  'path': require.resolve('path-browserify'),
+};
+
+module.exports = config;
+```
+
+**Install the additional browserify modules:**
+
+```bash
+npm install stream-browserify crypto-browserify stream-http https-browserify url util browserify-zlib path-browserify
+
+# or with yarn
+yarn add stream-browserify crypto-browserify stream-http https-browserify url util browserify-zlib path-browserify
+```
+
+> **Note**: We removed `react-native-level-fs` from Metro aliases as the SDK now uses `asyncstorage-down` directly for better React Native compatibility.
+
+### 4. Essential Polyfills Setup
+
+Import the required polyfills at the **very top** of your app's entry point (usually `App.js` or `index.js`) **before** importing the DOP Wallet SDK:
+
+```typescript
+// CRITICAL: These imports must come FIRST, before any other imports
+import 'react-native-get-random-values';
+import 'react-native-url-polyfill/auto';
+import { Buffer } from 'buffer';
+
+// Make Buffer available globally
+global.Buffer = global.Buffer || Buffer;
+
+// Now import the DOP Wallet shims
+import 'dop-wallet-v6/react-native-shims';
+
+// Your other imports...
+import React from 'react';
+import { AppRegistry } from 'react-native';
+// ... rest of your app
+```
+
+> **⚠️ Critical Order**: The polyfills must be imported in this exact order before any other imports, including the DOP Wallet SDK imports. This prevents "Cannot read property 'call' of undefined" and similar errors.
+
+### 5. Complete Dependencies List
+
+Your `package.json` should include all these dependencies. Here's a complete reference:
+
+```json
+{
+  "dependencies": {
+    "dop-wallet-v6": "^1.2.10",
+    "asyncstorage-down": "^4.2.0",
+    "@react-native-async-storage/async-storage": "^1.19.0",
+    "react-native-get-random-values": "^1.9.0",
+    "react-native-url-polyfill": "^2.0.0",
+    "buffer": "^6.0.3",
+    "util": "^0.12.5",
+    "stream-browserify": "^3.0.0",
+    "crypto-browserify": "^3.12.0",
+    "stream-http": "^3.2.0",
+    "https-browserify": "^1.0.0",
+    "url": "^0.11.3",
+    "browserify-zlib": "^0.2.0",
+    "path-browserify": "^1.0.1"
+  },
+  "devDependencies": {
+    "metro-config": "^0.76.0"
+  }
+}
+```
+
+**Install all at once:**
+```bash
+npm install dop-wallet-v6 asyncstorage-down @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer util stream-browserify crypto-browserify stream-http https-browserify url browserify-zlib path-browserify
+
+npm install --save-dev metro-config
+```
+
+### 6. React Native Shims
+
+The SDK provides additional shims that handle crypto operations and other Node.js specific functionality. These are automatically loaded when you import the polyfill above.
+
+### 7. Platform-specific Setup
+
+#### iOS
+Add to `ios/Podfile`:
+
+```ruby
+pod 'RNFS', :path => '../node_modules/react-native-fs'
+```
+
+Then run:
+```bash
+cd ios && pod install && cd ..
+```
+
+#### Android
+Add to `android/app/build.gradle` in the `android` section:
+
+```gradle
+android {
+    ...
+    packagingOptions {
+        pickFirst '**/libc++_shared.so'
+        pickFirst '**/libjsc.so'
+    }
+}
+```
+
+### 8. Verification Setup
+
+You can verify your setup is working by creating a simple test:
+
+```typescript
+// TestSetup.js
+import 'react-native-get-random-values';
+import 'react-native-url-polyfill/auto';
+import { Buffer } from 'buffer';
+
+global.Buffer = global.Buffer || Buffer;
+
+import 'dop-wallet-v6/react-native-shims';
+
+console.log('✓ Polyfills loaded successfully');
+console.log('✓ Buffer available:', typeof Buffer !== 'undefined');
+console.log('✓ Crypto available:', typeof global.crypto !== 'undefined');
+
+export const testSetup = () => {
+  try {
+    // Test crypto.getRandomValues
+    const array = new Uint8Array(16);
+    crypto.getRandomValues(array);
+    console.log('✓ crypto.getRandomValues working');
+    
+    // Test Buffer
+    const buffer = Buffer.from('test');
+    console.log('✓ Buffer working');
+    
+    return true;
+  } catch (error) {
+    console.error('❌ Setup verification failed:', error);
+    return false;
+  }
+};
+```
+
+Import and run this test in your App component to verify everything is working.
+
+## Initialize Engine
+
+The DOP Engine must be initialized before any wallet operations can be performed.
+
+```typescript
+import { startDopEngineReactNative, ArtifactStore } from 'dop-wallet-v6';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// Configure artifact store for React Native
+class ReactNativeArtifactStore implements ArtifactStore {
+  async getItem(key: string): Promise<string | null> {
+    return AsyncStorage.getItem(`artifact_${key}`);
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    await AsyncStorage.setItem(`artifact_${key}`, value);
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await AsyncStorage.removeItem(`artifact_${key}`);
+  }
+
+  async clear(): Promise<void> {
+    const keys = await AsyncStorage.getAllKeys();
+    const artifactKeys = keys.filter(key => key.startsWith('artifact_'));
+    await AsyncStorage.multiRemove(artifactKeys);
+  }
+}
+
+export const initializeDopEngine = async () => {
+  try {
+    const walletSource = 'myapp'; // Your app identifier (max 16 chars, lowercase)
+    const shouldDebug = __DEV__; // Enable debug in development
+    const artifactStore = new ReactNativeArtifactStore();
+    const useNativeArtifacts = true; // TRUE for mobile
+    const skipMerkletreeScans = false; // FALSE to enable full functionality
+    const verboseScanLogging = __DEV__;
+
+    // Simplified React Native initialization - database handled internally
+    await startDopEngineReactNative(
+      walletSource,
+      shouldDebug,
+      artifactStore,
+      useNativeArtifacts,
+      skipMerkletreeScans,
+      verboseScanLogging
+    );
+
+    console.log('DOP Engine initialized successfully');
+  } catch (error) {
+    console.error('Failed to initialize DOP Engine:', error);
+    throw error;
+  }
+};
+```
+
+> **Note**: The `startDopEngineReactNative` function automatically handles database setup with persistence using AsyncStorage. Data is stored in memory for fast access and automatically persisted to AsyncStorage for data retention between app sessions.
+
+## Wallet Management
+
+This section covers all wallet creation and management options available in DOP Wallet v6, including automatic mnemonic generation and importing existing mnemonics.
+
+### Wallet Creation Functions
+
+#### 1. `createOrImportDopWallet` - **Recommended** ⭐
+
+This is the most comprehensive and user-friendly function that supports both creating new wallets and importing existing ones with React Native compatibility.
+
+```typescript
+import { createOrImportDopWallet, testCircomlibjs } from 'dop-wallet-v6';
+import { NetworkName } from 'dop-sharedmodels-v3';
+
+// Create a new wallet with auto-generated mnemonic
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey);
+
+// Create a new wallet with 24-word mnemonic
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonicStrength: 256 // 256 bits = 24 words
+});
+
+// Import an existing wallet
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonic: 'your existing twelve word mnemonic phrase goes here like this example'
+});
+```
+
+**Parameters:**
+- `encryptionKey`: string | Buffer | Uint8Array (32 bytes)
+- `options.mnemonic?`: string - Import this mnemonic (if undefined, generates new)
+- `options.creationBlockNumbers?`: Optional block numbers for faster sync
+- `options.dopWalletDerivationIndex?`: number (default: 0)
+- `options.timeout?`: number (default: 60000ms, recommended: 90000ms for React Native)
+- `options.mnemonicStrength?`: 128 | 192 | 256 (default: 128 = 12 words)
+
+**Returns:**
+```typescript
+{
+  walletInfo: DopWalletInfo, // Wallet details (ID, address, etc.)
+  mnemonic: string          // The mnemonic (generated or imported)
+}
+```
+
+#### 2. `createDopWalletSafe` - Safe Creation with Timeout
+
+For when you already have a mnemonic and want safe creation with React Native compatibility.
+
+```typescript
+import { createDopWalletSafe } from 'dop-wallet-v6';
+
+const walletInfo = await createDopWalletSafe(
+  encryptionKey,
+  mnemonic,
+  creationBlockNumbers,
+  derivationIndex,
+  timeout // Recommended: 90000ms for React Native
+);
+```
+
+#### 3. `createDopWallet` - Basic Creation
+
+The original function for creating wallets from existing mnemonics.
+
+```typescript
+import { createDopWallet } from 'dop-wallet-v6';
+
+const walletInfo = await createDopWallet(
+  encryptionKey,
+  mnemonic,
+  creationBlockNumbers,
+  derivationIndex
+);
+```
+
+### Input Requirements
+
+#### Encryption Key
+The encryption key must be a **32-byte** value in one of these formats:
+- `string`: Hex string (64 characters)
+- `Buffer`: 32-byte buffer
+- `Uint8Array`: 32-byte array
+
+```typescript
+import { randomBytes } from 'crypto';
+
+// Examples of valid encryption keys
+const encryptionKey1 = randomBytes(32).toString('hex'); // string
+const encryptionKey2 = randomBytes(32); // Buffer
+const encryptionKey3 = new Uint8Array(32); // Uint8Array
+```
+
+#### Mnemonic Options
+
+| Strength | Bits | Words | Security Level |
+|----------|------|-------|----------------|
+| 128      | 128  | 12    | Standard ✅ |
+| 192      | 192  | 18    | High |
+| 256      | 256  | 24    | Maximum 🔒 |
+
+```typescript
+// Generate different mnemonic lengths
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonicStrength: 128 // 12 words (default)
+});
+
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonicStrength: 192 // 18 words
+});
+
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonicStrength: 256 // 24 words (most secure)
+});
+```
+
+### React Native Wallet Creation
+
+For React Native apps, use these functions which include circomlibjs compatibility testing:
+
+```typescript
+import { createOrImportDopWallet, testCircomlibjs } from 'dop-wallet-v6';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { NetworkName } from 'dop-sharedmodels-v3';
+
+// Test compatibility first (optional but recommended)
+const isCompatible = await testCircomlibjs();
+if (!isCompatible) {
+  throw new Error('Cryptography not compatible with this environment');
+}
+
+// Create wallet with React Native optimizations
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  timeout: 90000, // Increase timeout for React Native
+  mnemonicStrength: 256 // 24 words for maximum security
+});
+```
+
+### Complete Examples
+
+#### Example 1: Create New Wallet (Auto-Generate Mnemonic)
+
+```typescript
+import { createOrImportDopWallet } from 'dop-wallet-v6';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { randomBytes } from 'crypto';
+import { NetworkName } from 'dop-sharedmodels-v3';
+
+export const createNewWallet = async () => {
+  try {
+    // Generate encryption key
+    const encryptionKey = randomBytes(32);
+    
+    // Optional: Specify creation block numbers for faster initial sync
+    const creationBlockNumbers = {
+      [NetworkName.Ethereum]: 18000000, // Recent block number
+      [NetworkName.Polygon]: 45000000,
+      [NetworkName.BNBChain]: 30000000,
+    };
+    
+    // Create wallet with auto-generated mnemonic
+    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+      creationBlockNumbers,
+      mnemonicStrength: 256, // 24 words for maximum security
+      timeout: 90000 // 90 seconds timeout for React Native
+    });
+    
+    console.log('✅ New wallet created!');
+    console.log('Wallet ID:', walletInfo.id);
+    console.log('Address:', walletInfo.dopAddress);
+    console.log('Mnemonic (SAVE THIS!):', mnemonic);
+    
+    // Store securely in AsyncStorage
+    await AsyncStorage.multiSet([
+      ['encryption_key', encryptionKey.toString('hex')],
+      ['wallet_mnemonic', mnemonic],
+      ['wallet_id', walletInfo.id],
+      ['wallet_address', walletInfo.dopAddress]
+    ]);
+    
+    return walletInfo;
+  } catch (error) {
+    console.error('Failed to create wallet:', error);
+    throw error;
+  }
+};
+```
+
+#### Example 2: Import Existing Wallet
+
+```typescript
+import { createOrImportDopWallet } from 'dop-wallet-v6';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export const importWalletFromMnemonic = async (userMnemonic: string) => {
+  try {
+    // Get stored encryption key or create new one
+    let encryptionKey = await AsyncStorage.getItem('encryption_key');
+    if (!encryptionKey) {
+      encryptionKey = randomBytes(32).toString('hex');
+      await AsyncStorage.setItem('encryption_key', encryptionKey);
+    }
+    
+    // Import wallet from mnemonic
+    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+      mnemonic: userMnemonic.trim().toLowerCase(),
+      timeout: 90000 // Increase timeout for React Native
+    });
+    
+    console.log('✅ Wallet imported successfully!');
+    console.log('Wallet ID:', walletInfo.id);
+    console.log('Address:', walletInfo.dopAddress);
+    
+    // Store wallet info
+    await AsyncStorage.multiSet([
+      ['wallet_mnemonic', mnemonic],
+      ['wallet_id', walletInfo.id],
+      ['wallet_address', walletInfo.dopAddress]
+    ]);
+    
+    return walletInfo;
+  } catch (error) {
+    if (error.message.includes('Invalid mnemonic')) {
+      throw new Error('Please check your mnemonic phrase and try again');
+    }
+    throw error;
+  }
+};
+```
+
+#### Example 3: Export Wallet Mnemonic
+
+```typescript
+import { getWalletMnemonic } from 'dop-wallet-v6';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export const exportWalletMnemonic = async (walletId: string) => {
+  try {
+    const encryptionKey = await AsyncStorage.getItem('encryption_key');
+    if (!encryptionKey) {
+      throw new Error('No encryption key found');
+    }
+    
+    const mnemonic = await getWalletMnemonic(encryptionKey, walletId);
+    return mnemonic;
+  } catch (error) {
+    console.error('Failed to export mnemonic:', error);
+    throw error;
+  }
+};
+```
+
+### Error Handling
+
+```typescript
+try {
+  const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+    mnemonic: userInputMnemonic,
+    timeout: 90000
+  });
+  
+  console.log('Wallet created:', walletInfo.id);
+  console.log('Address:', walletInfo.dopAddress);
+  
+  // IMPORTANT: Securely store the mnemonic
+  await AsyncStorage.setItem('wallet_mnemonic', mnemonic);
+  
+} catch (error) {
+  if (error.message.includes('Invalid mnemonic')) {
+    // Handle invalid mnemonic input
+    console.error('The provided mnemonic is invalid');
+  } else if (error.message.includes('timed out')) {
+    // Handle timeout (usually circomlibjs hanging)
+    console.error('Wallet creation timed out, try restarting the app');
+  } else if (error.message.includes('Cryptography not compatible')) {
+    // Handle circomlibjs compatibility issues
+    console.error('Crypto library not compatible, check shims and polyfills');
+  } else {
+    // Handle other errors
+    console.error('Wallet creation failed:', error);
+  }
+}
+```
+
+### Best Practices for React Native
+
+1. **Always test circomlibjs compatibility** before wallet creation:
+   ```typescript
+   const isCompatible = await testCircomlibjs();
+   if (!isCompatible) {
+     throw new Error('Cryptography not compatible');
+   }
+   ```
+
+2. **Use increased timeouts** for React Native (90+ seconds):
+   ```typescript
+   const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+     timeout: 90000
+   });
+   ```
+
+3. **Handle timeout errors gracefully** - suggest app restart:
+   ```typescript
+   if (error.message.includes('timed out')) {
+     Alert.alert(
+       'Wallet Creation Timeout',
+       'Please restart the app and try again.',
+       [{ text: 'OK' }]
+     );
+   }
+   ```
+
+4. **Use secure storage** for encryption keys and mnemonics:
+   ```typescript
+   import AsyncStorage from '@react-native-async-storage/async-storage';
+   
+   // Store securely
+   await AsyncStorage.multiSet([
+     ['encryption_key', encryptionKey.toString('hex')],
+     ['wallet_mnemonic', mnemonic]
+   ]);
+   ```
+
+5. **Validate user input mnemonics** before importing:
+   ```typescript
+   if (userMnemonic && !Mnemonic.validate(userMnemonic)) {
+     throw new Error('Invalid mnemonic phrase');
+   }
+   ```
+
+6. **Use 24-word mnemonics** for maximum security:
+   ```typescript
+   const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+     mnemonicStrength: 256 // 24 words
+   });
+   ```
+
+### Migration from Old API
+
+If you're upgrading from older wallet creation methods:
+
+```typescript
+// OLD WAY ❌
+const walletInfo = await createDopWallet(encryptionKey, mnemonic, creationBlockNumbers);
+
+// NEW WAY ✅
+const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+  mnemonic: existingMnemonic, // or leave undefined to generate
+  creationBlockNumbers,
+  timeout: 90000 // Add timeout for React Native
+});
+```
+
+The new API provides the mnemonic in the response, making it easier to handle both wallet creation and mnemonic storage in one step.
+
+## ERC-20 Token Features
+
+### ERC-20 Balances
+
+```typescript
+import { 
+  refreshBalances,
+  getSerializedERC20Balances,
+  getSerializedNFTBalances
+} from 'dop-wallet-v6';
+import { NetworkName, NETWORK_CONFIG, Chain } from 'dop-sharedmodels-v3';
+
+export const refreshERC20Balances = async (
+  walletId: string, 
+  networkName: NetworkName
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain: Chain = network.chain;
+    
+    // Refresh balances for the wallet
+    await refreshBalances(chain, [walletId]);
+    
+    console.log('Balance refresh initiated successfully');
+    return true;
+  } catch (error) {
+    console.error('Failed to refresh balances:', error);
+    throw error;
+  }
+};
+
+export const getERC20Balances = async (tokenBalances: any) => {
+  try {
+    // Get serialized ERC20 balances from wallet token balances
+    const erc20Balances = getSerializedERC20Balances(tokenBalances);
+    
+    return erc20Balances.map(balance => ({
+      tokenAddress: balance.tokenAddress,
+      amount: balance.amount.toString(),
+      symbol: balance.symbol,
+      decimals: balance.decimals,
+    }));
+  } catch (error) {
+    console.error('Failed to get ERC20 balances:', error);
+    throw error;
+  }
+}; 
+  networkName: NetworkName
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain = network.chain;
+    
+    await refreshBalances(chain, [walletId]);
+    console.log('Balance refresh initiated');
+  } catch (error) {
+    console.error('Failed to refresh balances:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-20 Syncing
+
+```typescript
+import { 
+  setOnUTXOMerkletreeScanCallback,
+  setOnTXIDMerkletreeScanCallback,
+  rescanFullUTXOMerkletreesAndWallets
+} from 'dop-wallet-v6';
+import { MerkletreeScanUpdateEvent } from 'dop-sharedmodels-v3';
+
+export const setupSyncCallbacks = () => {
+  // Monitor UTXO scan progress
+  setOnUTXOMerkletreeScanCallback((scanData: MerkletreeScanUpdateEvent) => {
+    console.log('UTXO Scan Progress:', {
+      chain: scanData.chain,
+      status: scanData.scanStatus,
+      progress: scanData.progress,
+    });
+    
+    // Update UI with scan progress
+    // Example: setScanProgress(scanData.progress);
+  });
+
+  // Monitor TXID scan progress
+  setOnTXIDMerkletreeScanCallback((scanData: MerkletreeScanUpdateEvent) => {
+    console.log('TXID Scan Progress:', {
+      chain: scanData.chain,
+      status: scanData.scanStatus,
+      progress: scanData.progress,
+    });
+  });
+};
+
+export const performFullSync = async (
+  walletId: string,
+  networkName: NetworkName
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain = network.chain;
+    
+    await rescanFullUTXOMerkletreesAndWallets(chain, [walletId]);
+    console.log('Full sync initiated');
+  } catch (error) {
+    console.error('Failed to perform full sync:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-20 Encrypt, Send, Decrypt
+
+```typescript
+import { 
+  generateTransferProofInternal,
+  populateEncrypt,
+  generateDecryptToOriginProof,
+  populateProvedTransfer,
+  gasEstimateForEncrypt,
+  gasEstimateForUnprovenTransfer,
+  mnemonicTo0xPKey
+} from 'dop-wallet-v6';
+import { 
+  NetworkName, 
+  NETWORK_CONFIG,
+  TXIDVersion,
+  DopERC20AmountRecipient,
+  TransactionGasDetails,
+  EVMGasType
+} from 'dop-sharedmodels-v3';
+import { Wallet, JsonRpcProvider } from 'ethers';
+
+export const encryptERC20Token = async (
+  walletId: string,
+  networkName: NetworkName,
+  tokenAddress: string,
+  amount: string,
+  mnemonic: string
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const txidVersion = TXIDVersion.V2_PoseidonMerkle; // or V3_PoseidonMerkle
+    
+    const erc20AmountRecipients: DopERC20AmountRecipient[] = [
+      {
+        tokenAddress,
+        amount: BigInt(amount),
+        recipientAddress: walletId, // Self-encrypt
+      }
+    ];
+
+    // Get encrypt private key (simplified - in practice this should be derived securely)
+    const encryptPrivateKey = mnemonicTo0xPKey(mnemonic);
+
+    // Generate encrypt transaction
+    const encryptResponse = await populateEncrypt(
+      txidVersion,
+      networkName,
+      encryptPrivateKey,
+      erc20AmountRecipients,
+      [], // nftAmountRecipients
+      undefined // gasDetails - add if needed
+    );
+
+    // Broadcast using ethers (you'll need to implement this based on your provider setup)
+    const provider = new JsonRpcProvider(network.rpcUrl);
+    const wallet = new Wallet(encryptPrivateKey, provider);
+    const txResponse = await wallet.sendTransaction(encryptResponse.transaction);
+
+    console.log('Encryption transaction:', txResponse.hash);
+    return txResponse;
+  } catch (error) {
+    console.error('Failed to encrypt token:', error);
+    throw error;
+  }
+};
+
+export const sendERC20Token = async (
+  walletId: string,
+  networkName: NetworkName,
+  tokenAddress: string,
+  amount: string,
+  recipientAddress: string,
+  encryptionKey: string,
+  mnemonic: string,
+  memoText?: string
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const txidVersion = TXIDVersion.V2_PoseidonMerkle; // or V3_PoseidonMerkle
+    
+    const erc20AmountRecipients: DopERC20AmountRecipient[] = [
+      {
+        tokenAddress,
+        amount: BigInt(amount),
+        recipientAddress,
+      }
+    ];
+
+    // First generate the proof
+    await generateTransferProofInternal(
+      txidVersion,
+      networkName,
+      walletId,
+      encryptionKey,
+      false, // showSenderAddressToRecipient
+      memoText,
+      erc20AmountRecipients,
+      [], // nftAmountRecipients
+      undefined, // broadcasterFeeERC20AmountRecipient
+      true, // sendWithPublicWallet
+      undefined, // overallBatchMinGasPrice
+      (progress) => console.log('Proof generation progress:', progress)
+    );
+
+    // Get gas details
+    const gasDetails: TransactionGasDetails = {
+      evmGasType: EVMGasType.Type2,
+      gasEstimate: 200000n,
+      gasPrice: 20000000000n, // 20 gwei
+      maxFeePerGas: 30000000000n, // 30 gwei
+      maxPriorityFeePerGas: 2000000000n, // 2 gwei
+    };
+
+    // Populate the proved transaction
+    const populateResponse = await populateProvedTransfer(
+      txidVersion,
+      networkName,
+      walletId,
+      false, // showSenderAddressToRecipient
+      memoText,
+      erc20AmountRecipients,
+      [], // nftAmountRecipients
+      undefined, // broadcasterFeeERC20AmountRecipient
+      true, // sendWithPublicWallet
+      undefined, // overallBatchMinGasPrice
+      gasDetails
+    );
+
+    // Broadcast using ethers
+    const privateKey = mnemonicTo0xPKey(mnemonic);
+    const provider = new JsonRpcProvider(network.rpcUrl);
+    const wallet = new Wallet(privateKey, provider);
+    const txResponse = await wallet.sendTransaction(populateResponse.transaction);
+
+    console.log('Transfer transaction:', txResponse.hash);
+    return txResponse;
+  } catch (error) {
+    console.error('Failed to send token:', error);
+    throw error;
+  }
+};
+
+export const decryptERC20Token = async (
+  walletId: string,
+  networkName: NetworkName,
+  originalEncryptTxid: string,
+  encryptionKey: string,
+  mnemonic: string,
+  tokenAddress: string,
+  amount: string
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const txidVersion = TXIDVersion.V2_PoseidonMerkle;
+    
+    const erc20AmountRecipients: DopERC20AmountRecipient[] = [
+      {
+        tokenAddress,
+        amount: BigInt(amount),
+        recipientAddress: walletId, // Decrypt to self
+      }
+    ];
+
+    // Generate decrypt proof
+    await generateDecryptToOriginProof(
+      originalEncryptTxid,
+      txidVersion,
+      networkName,
+      walletId,
+      encryptionKey,
+      erc20AmountRecipients,
+      [], // nftAmountRecipients
+      (progress) => console.log('Decrypt proof generation progress:', progress),
+      BigInt(amount)
+    );
+
+    // Note: You'll need to implement the transaction broadcasting part
+    // similar to the above examples using ethers and the cached proved transaction
+
+    console.log('Decrypt proof generated successfully');
+    return { success: true };
+  } catch (error) {
+    console.error('Failed to decrypt token:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-20 Transaction History
+
+```typescript
+import { getWalletTransactionHistory } from 'dop-wallet-v6';
+import { 
+  TransactionHistoryItem,
+  TransactionHistoryItemCategory,
+  NetworkName,
+  NETWORK_CONFIG,
+  Chain
+} from 'dop-sharedmodels-v3';
+
+export const getERC20TransactionHistory = async (
+  walletId: string,
+  networkName: NetworkName,
+  startIndex = 0
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain: Chain = network.chain;
+    
+    const history = await getWalletTransactionHistory(
+      chain,
+      walletId,
+      startIndex
+    );
+
+    return history;
+    const chain = network.chain;
+    
+    const history = await getTransactionHistory(
+      walletId,
+      chain,
+      startIndex,
+      maxCount
+    );
+
+    // Filter for ERC20 transactions
+    const erc20History = history.filter(item => 
+      item.category === TransactionHistoryItemCategory.TransferERC20Send ||
+      item.category === TransactionHistoryItemCategory.TransferERC20Receive ||
+      item.category === TransactionHistoryItemCategory.EncryptERC20 ||
+      item.category === TransactionHistoryItemCategory.DecryptERC20
+    );
+
+    return erc20History.map(item => ({
+      id: item.id,
+      timestamp: item.timestamp,
+      category: item.category,
+      txHash: item.txHash,
+      blockNumber: item.blockNumber,
+      tokenAddress: item.tokenAddress,
+      amount: item.amount,
+      recipientAddress: item.recipientAddress,
+      senderAddress: item.senderAddress,
+      memoText: item.memoText,
+      status: item.status,
+    }));
+  } catch (error) {
+    console.error('Failed to get transaction history:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-20 Selective Transparency
+
+```typescript
+import { 
+  getDopWalletPrivateViewingKey,
+  getWalletShareableViewingKey,
+  createViewOnlyDopWallet,
+  signWithWalletViewingKey
+} from 'dop-wallet-v6';
+
+export const generateViewingKey = async (walletId: string) => {
+  try {
+    const shareableViewingKey = await getWalletShareableViewingKey(walletId);
+    return shareableViewingKey;
+  } catch (error) {
+    console.error('Failed to generate viewing key:', error);
+    throw error;
+  }
+};
+
+export const createViewOnlyWallet = async (
+  encryptionKey: string,
+  shareableViewingKey: string
+) => {
+  try {
+    const walletInfo = await createViewOnlyDopWallet(
+      encryptionKey,
+      shareableViewingKey,
+      undefined
+    );
+
+    console.log('View-only wallet created:', walletInfo);
+    return walletInfo;
+  } catch (error) {
+    console.error('Failed to create view-only wallet:', error);
+    throw error;
+  }
+};
+
+export const verifyTransactionProof = async (
+  walletId: string,
+  message: string
+) => {
+  try {
+    const signature = await signWithWalletViewingKey(walletId, message);
+    return signature;
+  } catch (error) {
+    console.error('Failed to verify proof:', error);
+    throw error;
+  }
+};
+```
+
+## ERC-721 NFT Features
+
+### ERC-721 Balances
+
+```typescript
+export const getERC721Balances = async (tokenBalances: any) => {
+  try {
+    // Get serialized NFT balances from wallet token balances
+    const nftBalances = getSerializedNFTBalances(tokenBalances);
+    
+    return nftBalances.map(balance => ({
+      contractAddress: balance.nftAddress,
+      tokenId: balance.tokenSubID,
+      tokenURI: balance.tokenURI,
+    }));
+  } catch (error) {
+    console.error('Failed to get NFT balances:', error);
+    throw error;
+  }
+};
+      amount: balance.amount.toString(),
+      nftTokenType: balance.nftTokenType,
+    }));
+  } catch (error) {
+    console.error('Failed to get NFT balances:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-721 Syncing
+
+```typescript
+export const refreshNFTBalances = async (
+  walletId: string, 
+  networkName: NetworkName
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain = network.chain;
+    
+    await refreshBalances(chain, [walletId]);
+    console.log('NFT balance refresh initiated');
+  } catch (error) {
+    console.error('Failed to refresh NFT balances:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-721 Encrypt, Send, Decrypt
+
+```typescript
+export const encryptNFT = async (
+  walletId: string,
+  networkName: NetworkName,
+  contractAddress: string,
+  tokenId: string
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    
+    const encryptTxRequest = {
+      walletId,
+      tokenAddress: contractAddress,
+      tokenId,
+      recipientAddress: null, // Self-encrypt
+    };
+
+    const proof = await generateEncryptProof(
+      network.chain,
+      encryptTxRequest
+    );
+
+    const txResponse = await broadcastTransaction(
+      network.chain,
+      proof.transaction
+    );
+
+    console.log('NFT encryption transaction:', txResponse.hash);
+    return txResponse;
+  } catch (error) {
+    console.error('Failed to encrypt NFT:', error);
+    throw error;
+  }
+};
+
+export const sendNFT = async (
+  walletId: string,
+  networkName: NetworkName,
+  contractAddress: string,
+  tokenId: string,
+  recipientAddress: string,
+  memoText?: string
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    
+    const transferTxRequest = {
+      walletId,
+      tokenAddress: contractAddress,
+      tokenId,
+      recipientAddress,
+      memoText,
+    };
+
+    const proof = await generateTransferProof(
+      network.chain,
+      transferTxRequest
+    );
+
+    const txResponse = await broadcastTransaction(
+      network.chain,
+      proof.transaction
+    );
+
+    console.log('NFT transfer transaction:', txResponse.hash);
+    return txResponse;
+  } catch (error) {
+    console.error('Failed to send NFT:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-721 Transaction History
+
+```typescript
+export const getNFTTransactionHistory = async (
+  walletId: string,
+  networkName: NetworkName,
+  startIndex = 0,
+  maxCount = 50
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain = network.chain;
+    
+    const history = await getTransactionHistory(
+      walletId,
+      chain,
+      startIndex,
+      maxCount
+    );
+
+    // Filter for NFT transactions
+    const nftHistory = history.filter(item => 
+      item.category === TransactionHistoryItemCategory.TransferNFTSend ||
+      item.category === TransactionHistoryItemCategory.TransferNFTReceive ||
+      item.category === TransactionHistoryItemCategory.EncryptNFT ||
+      item.category === TransactionHistoryItemCategory.DecryptNFT
+    );
+
+    return nftHistory.map(item => ({
+      id: item.id,
+      timestamp: item.timestamp,
+      category: item.category,
+      txHash: item.txHash,
+      blockNumber: item.blockNumber,
+      contractAddress: item.tokenAddress,
+      tokenId: item.tokenId,
+      recipientAddress: item.recipientAddress,
+      senderAddress: item.senderAddress,
+      memoText: item.memoText,
+      status: item.status,
+    }));
+  } catch (error) {
+    console.error('Failed to get NFT transaction history:', error);
+    throw error;
+  }
+};
+```
+
+### ERC-721 Selective Transparency
+
+NFT selective transparency works the same way as ERC-20 tokens, using the same viewing key mechanisms described in the ERC-20 section.
+
+## Advanced Features
+
+### Transaction History with Wallet Visibility
+
+```typescript
+export const getAllTransactionHistory = async (
+  walletId: string,
+  networkName: NetworkName,
+  includeVisible = false,
+  startIndex = 0,
+  maxCount = 100
+) => {
+  try {
+    const network = NETWORK_CONFIG[networkName];
+    const chain = network.chain;
+    
+    const history = await getTransactionHistory(
+      walletId,
+      chain,
+      startIndex,
+      maxCount
+    );
+
+    // Option to filter visible transactions
+    const filteredHistory = includeVisible 
+      ? history 
+      : history.filter(item => !item.isVisible);
+
+    return filteredHistory.map(item => ({
+      id: item.id,
+      timestamp: item.timestamp,
+      category: item.category,
+      txHash: item.txHash,
+      blockNumber: item.blockNumber,
+      tokenType: item.tokenType,
+      tokenAddress: item.tokenAddress,
+      tokenId: item.tokenId,
+      amount: item.amount,
+      recipientAddress: item.recipientAddress,
+      senderAddress: item.senderAddress,
+      memoText: item.memoText,
+      status: item.status,
+      isVisible: item.isVisible,
+      gasFee: item.gasFee,
+    }));
+  } catch (error) {
+    console.error('Failed to get transaction history:', error);
+    throw error;
+  }
+};
+
+export const makeWalletVisible = async (
+  walletId: string,
+  networkName: NetworkName
+) => {
+  try {
+    // Implementation depends on specific visibility requirements
+    // This might involve generating proofs or updating wallet settings
+    console.log('Making wallet visible for network:', networkName);
+    
+    // Add specific implementation based on DOP requirements
+  } catch (error) {
+    console.error('Failed to make wallet visible:', error);
+    throw error;
+  }
+};
+```
+
+## Complete Example
+
+Here's a complete setup showing the proper import order and React Native component:
+
+### App.js (Entry Point)
+
+```typescript
+// CRITICAL: Import polyfills FIRST, in this exact order
+import 'react-native-get-random-values';
+import 'react-native-url-polyfill/auto';
+import { Buffer } from 'buffer';
+
+// Make Buffer available globally
+global.Buffer = global.Buffer || Buffer;
+
+// Import DOP Wallet shims
+import 'dop-wallet-v6/react-native-shims';
+
+// Now safe to import React and other modules
+import React from 'react';
+import { AppRegistry } from 'react-native';
+import DopWalletExample from './DopWalletExample';
+
+const App = () => {
+  return <DopWalletExample />;
+};
+
+AppRegistry.registerComponent('YourAppName', () => App);
+```
+
+### DopWalletExample.js (Main Component)
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { View, Text, Button, Alert, StyleSheet } from 'react-native';
+import { NetworkName } from 'dop-sharedmodels-v3';
+import { 
+  initializeDopEngine,
+  createNewWallet,
+  getERC20Balances,
+  sendERC20Token,
+  setupSyncCallbacks,
+  getAllTransactionHistory
+} from './dopWalletService'; // Your service file
+
+const DopWalletExample = () => {
+  const [walletId, setWalletId] = useState<string | null>(null);
+  const [balances, setBalances] = useState<any[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [syncProgress, setSyncProgress] = useState(0);
+
+  useEffect(() => {
+    initializeWallet();
+    setupSyncCallbacks();
+  }, []);
+
+  const initializeWallet = async () => {
+    try {
+      setIsLoading(true);
+      
+      // Initialize DOP Engine
+      await initializeDopEngine();
+      
+      // Create or load wallet
+      const encryptionKey = 'your-secure-encryption-key';
+      const wallet = await createNewWallet(encryptionKey);
+      setWalletId(wallet.id);
+      
+      console.log('Wallet initialized:', wallet.dopAddress);
+    } catch (error) {
+      Alert.alert('Error', 'Failed to initialize wallet');
+      console.error(error);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const loadBalances = async () => {
+    if (!walletId) return;
+    
+    try {
+      setIsLoading(true);
+      const erc20Balances = await getERC20Balances(walletId, NetworkName.Ethereum);
+      setBalances(erc20Balances);
+    } catch (error) {
+      Alert.alert('Error', 'Failed to load balances');
+      console.error(error);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const handleSendToken = async () => {
+    if (!walletId) return;
+
+    try {
+      setIsLoading(true);
+      
+      const result = await sendERC20Token(
+        walletId,
+        NetworkName.Ethereum,
+        '0x...', // Token contract address
+        '1000000000000000000', // 1 token (18 decimals)
+        '0x...', // Recipient address
+        'Hello from DOP!'
+      );
+      
+      Alert.alert('Success', `Transaction sent: ${result.hash}`);
+    } catch (error) {
+      Alert.alert('Error', 'Failed to send token');
+      console.error(error);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>DOP Wallet Integration</Text>
+      
+      {walletId && (
+        <Text style={styles.walletId}>Wallet ID: {walletId}</Text>
+      )}
+      
+      {syncProgress > 0 && (
+        <Text style={styles.progress}>
+          Sync Progress: {(syncProgress * 100).toFixed(1)}%
+        </Text>
+      )}
+      
+      <Button
+        title="Load Balances"
+        onPress={loadBalances}
+        disabled={isLoading || !walletId}
+      />
+      
+      <Button
+        title="Send Token"
+        onPress={handleSendToken}
+        disabled={isLoading || !walletId}
+      />
+      
+      {balances.length > 0 && (
+        <View style={styles.balanceContainer}>
+          <Text style={styles.balanceTitle}>Balances:</Text>
+          {balances.map((balance, index) => (
+            <Text key={index} style={styles.balanceItem}>
+              {balance.tokenAddress}: {balance.spendable}
+            </Text>
+          ))}
+        </View>
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    justifyContent: 'center',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 20,
+    textAlign: 'center',
+  },
+  walletId: {
+    fontSize: 12,
+    marginBottom: 10,
+    textAlign: 'center',
+  },
+  progress: {
+    fontSize: 14,
+    marginBottom: 10,
+    textAlign: 'center',
+  },
+  balanceContainer: {
+    marginTop: 20,
+  },
+  balanceTitle: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    marginBottom: 10,
+  },
+  balanceItem: {
+    fontSize: 14,
+    marginBottom: 5,
+  },
+});
+
+export default DopWalletExample;
+```
+
+## Testing
+
+### Unit Testing
+
+Create test files to validate each integration step:
+
+```typescript
+// __tests__/dopWallet.test.ts
+import { initializeDopEngine, createNewWallet } from '../dopWalletService';
+
+describe('DOP Wallet Integration', () => {
+  beforeAll(async () => {
+    await initializeDopEngine();
+  });
+
+  test('should create a new wallet', async () => {
+    const encryptionKey = 'test-encryption-key';
+    const wallet = await createNewWallet(encryptionKey);
+    
+    expect(wallet.id).toBeDefined();
+    expect(wallet.dopAddress).toBeDefined();
+  });
+
+  test('should load balances', async () => {
+    // Add balance loading tests
+  });
+
+  test('should handle transactions', async () => {
+    // Add transaction tests
+  });
+});
+```
+
+### Integration Testing
+
+1. Test wallet creation and import
+2. Verify balance loading and syncing
+3. Test ERC-20 token operations
+4. Test ERC-721 NFT operations
+5. Verify transaction history
+6. Test selective transparency features
+
+## Troubleshooting
+
+### Wallet Creation Issues
+
+#### ⚠️ **MOST COMMON ISSUE**: Wallet Creation Hangs Indefinitely
+
+**Problem**: `createDopWallet()` hangs without errors, never completes in React Native.
+
+**Root Cause**: `circomlibjs` (cryptographic library) hangs when trying to use Web Workers or WebAssembly in React Native.
+
+**✅ SOLUTION**: Use the new safe wallet creation functions:
+
+```typescript
+import { testCircomlibjs, createOrImportDopWallet } from 'dop-wallet-v6';
+
+export const createNewWalletSafely = async (encryptionKey: string) => {
+  try {
+    // First test if circomlibjs is working
+    const isCompatible = await testCircomlibjs();
+    if (!isCompatible) {
+      throw new Error('Cryptography not compatible with this environment');
+    }
+    console.log('✅ CircomLibJS test passed');
+    
+    // Use the comprehensive creation method with timeout
+    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+      timeout: 90000, // 90 second timeout for React Native
+      mnemonicStrength: 256 // 24 words for maximum security
+    });
+    
+    console.log('✅ Wallet created successfully');
+    console.log('Generated mnemonic:', mnemonic);
+    return { walletInfo, mnemonic };
+  } catch (error) {
+    console.error('❌ Safe wallet creation failed:', error);
+    
+    if (error.message.includes('timed out')) {
+      throw new Error('Wallet creation timed out. This indicates circomlibjs compatibility issues. Please restart the app and try again.');
+    }
+    
+    throw error;
+  }
+};
+```
+
+#### "Invalid mnemonic phrase" Errors
+
+**Problem**: Getting "Invalid mnemonic phrase provided" when importing wallet.
+
+**Solutions**:
+1. **Check word count**: Ensure mnemonic has exactly 12, 18, or 24 words
+2. **Remove extra spaces**: Trim and normalize the mnemonic
+3. **Verify BIP39 wordlist**: Check if all words are valid BIP39 words
+
+```typescript
+import { createOrImportDopWallet } from 'dop-wallet-v6';
+
+const importWalletSafely = async (userMnemonic: string, encryptionKey: string) => {
+  try {
+    // Clean and validate the mnemonic
+    const cleanMnemonic = userMnemonic.trim().toLowerCase();
+    const words = cleanMnemonic.split(/\s+/);
+    
+    if (![12, 18, 24].includes(words.length)) {
+      throw new Error(`Invalid mnemonic: expected 12, 18, or 24 words, got ${words.length}`);
+    }
+    
+    // Import with validation
+    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+      mnemonic: cleanMnemonic,
+      timeout: 90000
+    });
+    
+    return { walletInfo, mnemonic };
+  } catch (error) {
+    if (error.message.includes('Invalid mnemonic')) {
+      throw new Error('Please check your mnemonic phrase. Ensure it has 12, 18, or 24 valid words with no typos.');
+    }
+    throw error;
+  }
+};
+```
+
+#### "Wallet creation timed out" Errors
+
+**Problem**: Wallet creation times out after 60-90 seconds.
+
+**Causes & Solutions**:
+
+1. **CircomLibJS hanging** (most common):
+   ```typescript
+   // Solution: Test circomlibjs first
+   const isCompatible = await testCircomlibjs();
+   if (!isCompatible) {
+     // Restart the app and try again
+     Alert.alert('Compatibility Issue', 'Please restart the app and try again.');
+     return;
+   }
+   ```
+
+2. **Insufficient timeout for React Native**:
+   ```typescript
+   // Solution: Increase timeout
+   const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+     timeout: 120000 // 2 minutes for slower devices
+   });
+   ```
+
+3. **Missing shims or polyfills**:
+   ```typescript
+   // Solution: Ensure proper import order in App.js/index.js
+   import 'react-native-get-random-values';
+   import 'react-native-url-polyfill/auto';
+   import { Buffer } from 'buffer';
+   global.Buffer = global.Buffer || Buffer;
+   import 'dop-wallet-v6/react-native-shims'; // Critical!
+   ```
+
+#### "Cryptography not compatible" Errors
+
+**Problem**: `testCircomlibjs()` returns false or throws an error.
+
+**Solutions**:
+
+1. **Check shim loading**:
+   ```typescript
+   // Ensure react-native-shims.js is imported BEFORE any wallet operations
+   import 'dop-wallet-v6/react-native-shims';
+   import { testCircomlibjs } from 'dop-wallet-v6';
+   ```
+
+2. **Verify Metro configuration**:
+   ```javascript
+   // metro.config.js
+   config.resolver.alias = {
+     'crypto': require.resolve('crypto-browserify'),
+     'stream': require.resolve('stream-browserify'),
+     // ... other aliases
+   };
+   ```
+
+3. **Force restart Metro**:
+   ```bash
+   npx react-native start --reset-cache
+   ```
+
+#### "Cannot read property 'call' of undefined" Errors
+
+**Problem**: Getting undefined property errors during wallet operations.
+
+**Root Cause**: Missing or incorrectly loaded polyfills.
+
+**Solution**: Ensure correct polyfill order:
+
+```typescript
+// At the very top of App.js or index.js (FIRST imports)
+import 'react-native-get-random-values';
+import 'react-native-url-polyfill/auto';
+import { Buffer } from 'buffer';
+
+// Make Buffer global
+global.Buffer = global.Buffer || Buffer;
+
+// Load DOP Wallet shims
+import 'dop-wallet-v6/react-native-shims';
+
+// Then your app imports
+import React from 'react';
+import { AppRegistry } from 'react-native';
+// ... rest of app
+```
+
+#### Performance Issues (Slow Wallet Creation)
+
+**Problem**: Wallet creation takes 30+ seconds but eventually succeeds.
+
+**Solutions**:
+
+1. **Use creation block numbers** for faster sync:
+   ```typescript
+   import { NetworkName } from 'dop-sharedmodels-v3';
+   
+   const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+     creationBlockNumbers: {
+       [NetworkName.Ethereum]: 18500000, // Recent block
+       [NetworkName.Polygon]: 50000000,
+       [NetworkName.BNBChain]: 35000000,
+     }
+   });
+   ```
+
+2. **Show loading UI** with progress indication:
+   ```typescript
+   const [creationProgress, setCreationProgress] = useState('Initializing...');
+   
+   const createWallet = async () => {
+     try {
+       setCreationProgress('Testing cryptography...');
+       await testCircomlibjs();
+       
+       setCreationProgress('Creating wallet...');
+       const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+         timeout: 120000
+       });
+       
+       setCreationProgress('Wallet created successfully!');
+       return { walletInfo, mnemonic };
+     } catch (error) {
+       setCreationProgress('Creation failed');
+       throw error;
+     }
+   };
+   ```
+
+#### Debug Mode for Wallet Creation
+
+When troubleshooting wallet creation issues, use this debug approach:
+
+```typescript
+import { testCircomlibjs, createOrImportDopWallet } from 'dop-wallet-v6';
+
+const debugWalletCreation = async (encryptionKey: string) => {
+  console.log('🔍 Starting wallet creation debug...');
+  
+  try {
+    // Step 1: Test environment
+    console.log('Step 1: Testing React Native environment...');
+    console.log('- Buffer available:', typeof Buffer !== 'undefined');
+    console.log('- Crypto available:', typeof crypto !== 'undefined');
+    console.log('- TextEncoder available:', typeof TextEncoder !== 'undefined');
+    
+    // Step 2: Test circomlibjs
+    console.log('Step 2: Testing circomlibjs...');
+    const startTime = Date.now();
+    const isCompatible = await testCircomlibjs();
+    const testDuration = Date.now() - startTime;
+    console.log(`- CircomLibJS test: ${isCompatible ? '✅ PASS' : '❌ FAIL'} (${testDuration}ms)`);
+    
+    if (!isCompatible) {
+      throw new Error('CircomLibJS compatibility test failed');
+    }
+    
+    // Step 3: Create wallet with debug logging
+    console.log('Step 3: Creating wallet...');
+    const creationStart = Date.now();
+    
+    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
+      timeout: 120000, // 2 minute timeout
+      mnemonicStrength: 128 // Start with 12 words for faster creation
+    });
+    
+    const creationDuration = Date.now() - creationStart;
+    console.log(`✅ Wallet created successfully in ${creationDuration}ms`);
+    console.log('- Wallet ID:', walletInfo.id);
+    console.log('- Address:', walletInfo.dopAddress);
+    console.log('- Mnemonic words:', mnemonic.split(' ').length);
+    
+    return { walletInfo, mnemonic };
+    
+  } catch (error) {
+    console.error('❌ Debug wallet creation failed:', error);
+    console.error('Error details:', {
+      message: error.message,
+      stack: error.stack
+    });
+    throw error;
+  }
+};
+```
+
+### General React Native Issues
+
+#### Missing Dependencies
+
+**Error**: `Module not found` or `Cannot resolve module`
+
+**Solution**: Install all required dependencies:
+```bash
+npm install dop-wallet-v6 @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer util stream-browserify crypto-browserify
+```
+
+#### Metro Bundle Issues
+
+**Error**: Bundle transformation errors or module resolution failures
+
+**Solution**: Update Metro configuration and clear cache:
+```bash
+# Clear Metro cache
+npx react-native start --reset-cache
+
+# Clean project
+cd ios && xcodebuild clean && cd ..
+cd android && ./gradlew clean && cd ..
+```
+
+#### iOS Build Issues
+
+**Error**: Build failures on iOS
+
+**Solution**: 
+1. Install pods: `cd ios && pod install && cd ..`
+2. Clean build folder in Xcode
+3. Ensure iOS deployment target is 11.0+
+
+#### Android Build Issues
+
+**Error**: Build failures on Android
+
+**Solution**:
+1. Ensure `minSdkVersion` is 21+
+2. Enable Hermes if disabled
+3. Add proguard rules if using release builds
+
+```typescript
+import { testCircomlibjs } from 'dop-wallet-v6';
+
+// Test circomlibjs in isolation first
+export const debugCircomlibjs = async () => {
+  try {
+    console.log('🔍 Testing circomlibjs components...');
+    
+    // Test individual operations with timeout
+    const timeoutPromise = new Promise((_, reject) => 
+      setTimeout(() => reject(new Error('Operation timed out')), 30000)
+    );
+    
+    await Promise.race([
+      testCircomlibjs(),
+      timeoutPromise
+    ]);
+    
+    console.log('✅ All circomlibjs tests passed');
+    return true;
+  } catch (error) {
+    console.error('❌ CircomLibJS debug failed:', error);
+    
+    // Provide specific guidance based on error
+    if (error.message.includes('timed out')) {
+      console.error('⚠️  SOLUTION: Add these to your App.js BEFORE importing dop-wallet-v6:');
+      console.error(`
+// Add this at the very top of App.js:
+global.Worker = undefined;
+global.WebAssembly = undefined;
+global.navigator = { ...global.navigator, serviceWorker: undefined };
+      `);
+    }
+    
+    return false;
+  }
+};
+```
+
+### Critical Setup Issues
+
+#### 1. "startDopEngineReactNative is undefined" Error
+
+**Cause**: Missing dependencies or failed module loading during import.
+
+**Solution**:
+```bash
+# Ensure all dependencies are installed
+npm install --legacy-peer-deps
+# or
+yarn install
+
+# If the issue persists, try installing memdown explicitly
+npm install memdown@^6.1.1
+```
+
+**Alternative Import** (temporary workaround):
+```typescript
+// If main import fails, use direct import
+import { startDopEngineReactNative } from 'dop-wallet-v6/dist/services/dop/core/react-native-init';
+```
+
+#### 2. "Cannot read property 'call' of undefined" Error
+
+**Cause**: Missing required polyfills or incorrect import order.
+
+**Solution**:
+```typescript
+// ❌ WRONG - This will cause the error
+import { createDopWallet } from 'dop-wallet-v6';
+import 'react-native-get-random-values';
+
+// ✅ CORRECT - Polyfills must come FIRST
+import 'react-native-get-random-values';
+import 'react-native-url-polyfill/auto';
+import { Buffer } from 'buffer';
+global.Buffer = global.Buffer || Buffer;
+import 'dop-wallet-v6/react-native-shims';
+
+import { createDopWallet } from 'dop-wallet-v6';
+```
+
+#### 3. "Module not found" Errors for Node.js Core Modules
+
+**Cause**: Missing Metro configuration for Node.js core modules.
+
+**Error Examples**:
+- `Module not found: Can't resolve 'stream'`
+- `Module not found: Can't resolve 'crypto'`
+- `Module not found: Can't resolve 'url'`
+
+**Solution**: Ensure your `metro.config.js` includes all the aliases mentioned in the Metro Configuration section above.
+
+#### 3. "AsyncStorage has been removed from react-native core"
+
+**Cause**: This error should no longer occur in the latest version, but if you see it:
+
+**Solution**:
+```bash
+npm install @react-native-async-storage/async-storage
+```
+
+#### 4. Bundle/Build Failures
+
+**Cause**: Metro not properly configured or missing browserify dependencies.
+
+**Solution**:
+1. Clear Metro cache: `npx react-native start --reset-cache`
+2. Ensure all browserify packages are installed:
+   ```bash
+   npm install stream-browserify crypto-browserify stream-http https-browserify url browserify-zlib path-browserify
+   ```
+3. Restart Metro bundler completely
+
+#### 5. Wallet Initialization Fails
+
+**Error**: `Error creating wallet: TypeError: Cannot read property 'call' of undefined`
+
+**Solution Checklist**:
+- [ ] All polyfills imported in correct order
+- [ ] Metro config includes Node.js aliases
+- [ ] All browserify dependencies installed
+- [ ] React Native shims imported
+- [ ] Buffer made available globally
+
+#### 6. Level-FS Database Errors
+
+**Error Examples**:
+- `TypeError: LevelFS.level is not a function (it is undefined)`
+- `TypeError: _reactNativeLevelFs.default is not a function (it is Object)`
+- `TypeError: 0, _$$_REQUIRE(...).level is not a function (it is undefined)`
+
+**Root Cause**: `react-native-level-fs` is a filesystem shim, not a LevelDB constructor. The DOP Engine requires an `AbstractLevelDOWN` compatible database instance.
+
+**Incorrect Approach** (causes the error):
+```typescript
+// ❌ Wrong - this returns a filesystem interface, not a database
+import level from 'react-native-level-fs';
+const db = level('./path'); // This is NOT a valid LevelDB instance
+```
+
+**Correct Solution**:
+```typescript
+// ✅ Correct - use startDopEngineReactNative (SDK v1.2.10+)
+import { startDopEngineReactNative } from 'dop-wallet-v6';
+await startDopEngineReactNative(walletSource, shouldDebug, artifactStore, ...);
+```
+
+**Migration Steps**:
+1. **Update imports**: Replace database imports with `startDopEngineReactNative`
+2. **Update initialization**: Use the new React Native-specific function
+3. **Remove database code**: No need to manage LevelDB instances manually
+4. **Test persistence**: Data now automatically persists between app sessions
+
+### Common Runtime Issues
+
+#### 1. Engine Initialization Fails
+   - Ensure all dependencies are properly installed
+   - Check that React Native shims are imported
+   - Verify database path is writable
+   - Confirm ArtifactStore implementation is correct
+
+#### 2. Balance Loading Issues
+   - Ensure network is properly configured
+   - Check wallet is properly synced
+   - Verify token contracts are supported
+   - Check internet connectivity
+
+#### 3. Transaction Failures
+   - Check gas settings and network fees
+   - Ensure sufficient balance for transactions
+   - Verify recipient addresses are valid
+   - Confirm network supports the transaction type
+
+#### 4. Performance Issues
+   - Use native artifacts on mobile (`useNativeArtifacts: true`)
+   - Implement proper caching strategies
+   - Optimize sync frequency
+   - Consider using creation block numbers for faster initial sync
+
+### Debug Mode
+
+Enable debug mode during development for detailed logging:
+
+```typescript
+const shouldDebug = __DEV__;
+const verboseScanLogging = __DEV__;
+
+await startDopEngine(
+  walletSource,
+  db,
+  shouldDebug,        // Enable debug logging
+  artifactStore,
+  useNativeArtifacts,
+  skipMerkletreeScans,
+  verboseScanLogging  // Enable verbose scan logging
+);
+```
+
+### Complete Dependency Checklist
+
+Ensure you have all these dependencies installed:
+
+**Core Dependencies**:
+- ✅ `dop-wallet-v6`
+- ✅ `asyncstorage-down`
+- ✅ `@react-native-async-storage/async-storage`
+
+**Polyfills**:
+- ✅ `react-native-get-random-values`
+- ✅ `react-native-url-polyfill`
+- ✅ `buffer`
+- ✅ `util`
+
+**Browserify Modules**:
+- ✅ `stream-browserify`
+- ✅ `crypto-browserify`
+- ✅ `stream-http`
+- ✅ `https-browserify`
+- ✅ `url`
+- ✅ `util`
+- ✅ `browserify-zlib`
+- ✅ `path-browserify`
+
+**Dev Dependencies**:
+- ✅ `metro-config` (if using custom Metro config)
+
+### Quick Setup Verification Script
+
+Use this script to verify your setup is correct:
+
+```typescript
+// SetupVerification.js
+export const verifyDopWalletSetup = () => {
+  const checks = {
+    buffer: typeof Buffer !== 'undefined',
+    crypto: typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function',
+    url: typeof URL !== 'undefined',
+    util: (() => {
+      try {
+        const util = require('util');
+        return typeof util.promisify === 'function';
+      } catch {
+        return false;
+      }
+    })(),
+    randomValues: (() => {
+      try {
+        const array = new Uint8Array(1);
+        crypto.getRandomValues(array);
+        return true;
+      } catch {
+        return false;
+      }
+    })(),
+  };
+
+  console.log('DOP Wallet Setup Verification:');
+  Object.entries(checks).forEach(([check, passed]) => {
+    console.log(`${passed ? '✅' : '❌'} ${check}: ${passed ? 'OK' : 'FAILED'}`);
+  });
+
+  const allPassed = Object.values(checks).every(Boolean);
+  console.log(`\nOverall setup: ${allPassed ? '✅ READY' : '❌ NEEDS FIXES'}`);
+  
+  return allPassed;
+};
+```
+
+Run this before initializing the DOP Wallet SDK to ensure everything is properly configured.
+
+## Conclusion
+
+This guide provides a comprehensive foundation for integrating DOP Wallet v6 into React Native applications. The SDK enables privacy-focused features for both ERC-20 tokens and ERC-721 NFTs across multiple blockchain networks.
+
+For additional support and advanced features, refer to the official DOP documentation and community resources.
+
+---
+
+**Note**: This integration guide is based on the DOP Wallet v6 SDK. Always refer to the latest documentation for the most up-to-date API references and best practices.