dop-wallet-v6 1.2.14 → 1.2.15

package/REACT_NATIVE_INTEGRATION_FIXES.md

@@ -0,0 +1,167 @@
+# React Native Integration Fixes
+
+## Problem Summary
+
+Users were experiencing critical setup issues when integrating the DOP Wallet v6 SDK into React Native applications:
+
+1. **"Cannot read property 'call' of undefined" errors** during wallet initialization
+2. **Missing polyfill documentation** - essential polyfills were not documented
+3. **Metro configuration requirements** - Node.js core modules needed browserify aliases
+4. **Import order issues** - polyfills needed to be imported in specific order
+
+## Root Causes
+
+### 1. Missing Polyfills
+The SDK requires several polyfills that were not documented:
+- `react-native-get-random-values` - for crypto.getRandomValues()
+- `react-native-url-polyfill` - for URL APIs
+- `buffer` - for Node.js Buffer support
+
+### 2. Missing Metro Configuration
+React Native's Metro bundler needed aliases for Node.js core modules:
+- `stream` → `stream-browserify`
+- `crypto` → `crypto-browserify`
+- `http` → `stream-http`
+- `https` → `https-browserify`
+- `url` → `url`
+- `zlib` → `browserify-zlib`
+- `path` → `path-browserify`
+
+### 3. Import Order Dependencies
+Polyfills must be imported before any other modules, including the DOP Wallet SDK.
+
+## Solutions Implemented
+
+### 1. Updated Integration Guide
+
+**File**: `DOP_WALLET_V6_REACT_NATIVE_INTEGRATION_GUIDE.md`
+
+#### Added Complete Dependencies Section
+- Comprehensive list of all required dependencies
+- Single command to install everything
+- Version specifications
+
+#### Added Metro Configuration
+- Complete `metro.config.js` template
+- Node.js core module aliases
+- Resolver configuration
+
+#### Added Critical Import Order Instructions
+- Step-by-step polyfill import guide
+- Warning about import order requirements
+- Global Buffer setup
+
+#### Enhanced Troubleshooting Section
+- Specific error messages and solutions
+- Setup verification scripts
+- Complete dependency checklist
+- Debug mode instructions
+
+### 2. Documentation Improvements
+
+#### Complete Example Updates
+- Proper App.js setup with correct import order
+- Full React Native component example
+- Service file structure
+
+#### Platform-Specific Setup
+- iOS Podfile requirements
+- Android build.gradle configuration
+- Pod install instructions
+
+#### Verification Tools
+- Setup verification script
+- Runtime checks for polyfills
+- Debug logging helpers
+
+## Before vs After
+
+### Before (Broken)
+```typescript
+// ❌ This would cause "Cannot read property 'call' of undefined"
+import { createDopWallet } from 'dop-wallet-v6';
+import 'react-native-get-random-values'; // Too late!
+
+// Missing Metro config would cause "Module not found" errors
+// Missing dependencies would cause runtime failures
+```
+
+### After (Working)
+```typescript
+// ✅ Correct order prevents all initialization errors
+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';
+```
+
+## Complete Dependency List
+
+### Runtime Dependencies
+```json
+{
+  "dop-wallet-v6": "^1.2.10",
+  "react-native-level-fs": "^3.0.1",
+  "@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",
+  "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"
+}
+```
+
+### Metro Configuration
+```javascript
+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'),
+  'zlib': require.resolve('browserify-zlib'),
+  'path': require.resolve('path-browserify'),
+  'fs': require.resolve('react-native-level-fs'),
+};
+```
+
+## Impact
+
+### For Users
+- ✅ **Eliminates setup errors** - No more "Cannot read property 'call' of undefined"
+- ✅ **Clear documentation** - Step-by-step setup instructions
+- ✅ **Verification tools** - Scripts to test setup before integration
+- ✅ **Comprehensive troubleshooting** - Solutions for common issues
+
+### For Developers
+- ✅ **Reduced support burden** - Fewer setup-related issues
+- ✅ **Better developer experience** - Clear integration path
+- ✅ **Future-proof setup** - Handles React Native polyfill requirements
+
+## Validation
+
+The updated integration guide includes:
+1. **Setup verification script** to test polyfill installation
+2. **Complete example** showing working integration
+3. **Troubleshooting guide** for common issues
+4. **Dependency checklist** for verification
+
+Users can now follow the guide step-by-step and have a working integration without encountering the previously reported errors.
+
+## Version Compatibility
+
+This fix documentation is for:
+- **DOP Wallet v6**: v1.2.10+
+- **React Native**: 0.65+
+- **Metro**: 0.76+
+- **Node.js**: 16+
+
+The solutions are forward-compatible and should work with future versions of these dependencies.

package/REACT_NATIVE_SETUP_QUICK_FIX.md

@@ -0,0 +1,189 @@
+# React Native Setup Guide for dop-wallet-v6
+
+This guide addresses the specific integration issues identified in React Native 0.81+ (new architecture) environments.
+
+## Quick Fix for Existing Issues
+
+If you're experiencing Metro bundling failures with errors like:
+- `Error: Unable to resolve module os from node_modules/ffjavascript/build/main.cjs`
+- `Invalid call at line 201: import(mod)` from web-worker
+- App hanging during wallet creation
+
+Follow these steps:
+
+### 1. Install Required Dependencies
+
+```bash
+npm install \
+  @react-native-async-storage/async-storage \
+  react-native-get-random-values \
+  crypto-browserify \
+  stream-browserify \
+  buffer \
+  events \
+  util \
+  assert \
+  process \
+  path-browserify \
+  url \
+  querystring-es3 \
+  stream-http \
+  https-browserify \
+  browserify-zlib
+
+# or with yarn
+yarn add \
+  @react-native-async-storage/async-storage \
+  react-native-get-random-values \
+  crypto-browserify \
+  stream-browserify \
+  buffer \
+  events \
+  util \
+  assert \
+  process \
+  path-browserify \
+  url \
+  querystring-es3 \
+  stream-http \
+  https-browserify \
+  browserify-zlib
+```
+
+### 2. Copy Node.js Polyfills
+
+Copy the `node-polyfills/` directory from this package to your React Native project root:
+
+```
+your-react-native-project/
+├── node-polyfills/
+│   ├── os-polyfill.js
+│   ├── web-worker-polyfill.js
+│   └── wasm-fallback.js
+├── metro.config.js
+└── ...
+```
+
+### 3. Update Metro Configuration
+
+Copy the `metro.config.react-native.example.js` as your `metro.config.js`:
+
+```javascript
+// metro.config.js - Copy from metro.config.react-native.example.js
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+
+const defaultConfig = getDefaultConfig(__dirname);
+
+const config = {
+  resolver: {
+    alias: {
+      'os': require.resolve('./node-polyfills/os-polyfill.js'),
+      'crypto': require.resolve('crypto-browserify'),
+      'stream': require.resolve('stream-browserify'),
+      'web-worker': require.resolve('./node-polyfills/web-worker-polyfill.js'),
+      // ... other aliases (see full example)
+    },
+    // ... other configuration
+  },
+};
+
+module.exports = mergeConfig(defaultConfig, config);
+```
+
+### 4. Initialize the SDK Properly
+
+In your app's entry point (typically `App.js` or `index.js`):
+
+```javascript
+// CRITICAL: Import shims FIRST, before any other dop-wallet-v6 imports
+import 'dop-wallet-v6/react-native-shims';
+
+// Then import the SDK
+import { 
+  startDopEngineReactNative, 
+  createDopWalletSafe,
+  testCircomlibjs 
+} from 'dop-wallet-v6';
+
+// Your app code...
+```
+
+### 5. Test the Integration
+
+Add this test to verify everything is working:
+
+```javascript
+import { testCircomlibjs } from 'dop-wallet-v6';
+
+const testDopWalletIntegration = async () => {
+  try {
+    console.log('Testing dop-wallet-v6 integration...');
+    
+    // This will throw an error if the integration has issues
+    await testCircomlibjs();
+    
+    console.log('✅ dop-wallet-v6 integration successful!');
+    return true;
+  } catch (error) {
+    console.error('❌ dop-wallet-v6 integration failed:', error);
+    return false;
+  }
+};
+
+// Call this in your app's startup
+testDopWalletIntegration();
+```
+
+## Common Error Solutions
+
+### Error: "Unable to resolve module os"
+- **Solution**: Ensure the Metro config includes the os-polyfill.js alias
+- **Root cause**: ffjavascript requires Node.js 'os' module
+
+### Error: "Invalid call import(mod)"
+- **Solution**: Ensure web-worker is aliased to web-worker-polyfill.js  
+- **Root cause**: web-worker package uses dynamic imports incompatible with Metro
+
+### App hangs during wallet creation
+- **Solution**: Ensure react-native-shims.js is imported FIRST
+- **Root cause**: circomlibjs trying to use Web Workers in React Native
+
+### Error: "Cannot read property 'call' of undefined"
+- **Solution**: Install all browserify polyfills (crypto, stream, buffer, etc.)
+- **Root cause**: Missing Node.js core module polyfills
+
+## Architecture Notes
+
+The integration works by:
+
+1. **Polyfill Layer**: Node.js polyfills provide React Native-compatible implementations
+2. **Metro Aliases**: Redirect problematic modules to safe alternatives  
+3. **React Native Shims**: Force circomlibjs into synchronous mode
+4. **Database Layer**: Use memdown + AsyncStorage for persistence
+
+This approach maintains full SDK functionality while being compatible with React Native's JavaScript runtime constraints.
+
+## Performance Considerations
+
+- **Synchronous Mode**: Crypto operations run synchronously, which may block the UI for complex operations
+- **No Web Workers**: All operations run on the main thread
+- **JavaScript Fallbacks**: Pure JS implementations instead of optimized WASM
+
+For better UX, consider showing loading indicators during wallet operations.
+
+## Troubleshooting
+
+If issues persist:
+
+1. Clear Metro cache: `npx react-native start --reset-cache`
+2. Clear node_modules: `rm -rf node_modules && npm install`
+3. Check that shims are imported first
+4. Verify all polyfill dependencies are installed
+5. Test with the `testCircomlibjs()` function
+
+## Support
+
+For additional issues, check the integration guide in the SDK documentation or file an issue with:
+- React Native version
+- Metro bundler output
+- Device/simulator information

package/REACT_NATIVE_WALLET_HANGING_FIX.md

@@ -0,0 +1,270 @@
+# 🚨 CRITICAL FIX: React Native Wallet Creation Hanging
+
+## Problem Summary
+
+**Issue**: `createDopWallet()` hangs indefinitely in React Native without any error messages.
+
+**Root Cause**: The `circomlibjs` cryptographic library attempts to use Web Workers and WebAssembly, which are not available in React Native, causing the key derivation process to hang during wallet creation.
+
+## ✅ IMMEDIATE SOLUTION
+
+### 1. Update Your App.js (Entry Point)
+
+Add these lines **at the very top** of your App.js, before any other imports:
+
+```javascript
+// CRITICAL: Add this 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;
+
+// CRITICAL FIX: Disable Web Workers and WebAssembly for circomlibjs
+global.Worker = undefined;
+global.WebAssembly = undefined;
+global.navigator = global.navigator || {};
+global.navigator.serviceWorker = undefined;
+
+// Import DOP Wallet shims (this includes additional circomlibjs fixes)
+import 'dop-wallet-v6/react-native-shims';
+
+// NOW safe to import your React components
+import React from 'react';
+import { AppRegistry } from 'react-native';
+import YourMainComponent from './YourMainComponent';
+
+const App = () => <YourMainComponent />;
+AppRegistry.registerComponent('YourAppName', () => App);
+```
+
+### 2. Use Safe Wallet Creation
+
+Replace your current wallet creation code with the new safe method:
+
+```typescript
+import { testCircomlibjs, createDopWalletSafe } from 'dop-wallet-v6';
+
+export const createWalletSafely = async () => {
+  try {
+    // Test circomlibjs first
+    console.log('Testing circomlibjs...');
+    await testCircomlibjs();
+    console.log('✅ CircomLibJS working correctly');
+    
+    // Create wallet with timeout protection
+    const encryptionKey = Buffer.from('your-32-byte-hex-key', 'hex');
+    const mnemonic = 'your twelve word mnemonic phrase here or leave undefined';
+    
+    const wallet = await createDopWalletSafe(
+      encryptionKey,
+      mnemonic,
+      undefined, // creationBlockNumbers
+      0, // derivationIndex
+      60000 // 60 second timeout
+    );
+    
+    console.log('✅ Wallet created successfully:', wallet.id);
+    return wallet;
+    
+  } catch (error) {
+    console.error('❌ Wallet creation failed:', error);
+    
+    if (error.message.includes('timed out')) {
+      Alert.alert(
+        'Wallet Creation Timeout',
+        'The wallet creation process timed out. This usually indicates compatibility issues. Please restart the app and try again.'
+      );
+    }
+    
+    throw error;
+  }
+};
+```
+
+### 3. Debug if Still Having Issues
+
+If the wallet creation still hangs, use this debug function to isolate the problem:
+
+```typescript
+import { testCircomlibjs } from 'dop-wallet-v6';
+
+export const debugCircomLibJS = async () => {
+  console.log('🔍 Starting CircomLibJS debug test...');
+  
+  try {
+    // Test with 30 second timeout
+    const timeoutPromise = new Promise((_, reject) => 
+      setTimeout(() => reject(new Error('CircomLibJS test timed out after 30 seconds')), 30000)
+    );
+    
+    const testPromise = testCircomlibjs();
+    
+    await Promise.race([testPromise, timeoutPromise]);
+    
+    console.log('✅ CircomLibJS debug test PASSED');
+    return true;
+    
+  } catch (error) {
+    console.error('❌ CircomLibJS debug test FAILED:', error);
+    
+    if (error.message.includes('timed out')) {
+      console.error(`
+⚠️  CIRCOMLIBJS IS HANGING!
+
+SOLUTIONS:
+1. Restart your React Native app completely
+2. Ensure you added the Worker/WebAssembly disabling code to App.js
+3. Clear Metro cache: npx react-native start --reset-cache
+4. Check that react-native-shims.js is being imported correctly
+      `);
+    }
+    
+    return false;
+  }
+};
+```
+
+## 🛠️ Additional Fixes
+
+### Metro Configuration
+
+Ensure your `metro.config.js` includes proper Node.js polyfills:
+
+```javascript
+const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.alias = {
+  'crypto': require.resolve('crypto-browserify'),
+  'stream': require.resolve('stream-browserify'),
+  'util': require.resolve('util'),
+};
+
+// Critical: Ensure circomlibjs uses browser fallbacks
+config.transformer.minifierConfig = {
+  mangle: {
+    keep_fnames: true, // Keep function names for circomlibjs
+  },
+};
+
+module.exports = config;
+```
+
+### Package.json Dependencies
+
+Ensure you have all required dependencies:
+
+```json
+{
+  "dependencies": {
+    "dop-wallet-v6": "^1.2.10",
+    "react-native-get-random-values": "^1.9.0",
+    "react-native-url-polyfill": "^2.0.0",
+    "buffer": "^6.0.3",
+    "crypto-browserify": "^3.12.0",
+    "stream-browserify": "^3.0.0",
+    "util": "^0.12.5"
+  }
+}
+```
+
+## 🧪 Testing Your Fix
+
+Use this simple test to verify everything is working:
+
+```typescript
+import { Alert } from 'react-native';
+import { testCircomlibjs, createDopWalletSafe } from 'dop-wallet-v6';
+
+export const testWalletIntegration = async () => {
+  try {
+    console.log('🧪 Starting wallet integration test...');
+    
+    // Step 1: Test circomlibjs
+    console.log('Step 1: Testing circomlibjs...');
+    await testCircomlibjs();
+    console.log('✅ Step 1 passed');
+    
+    // Step 2: Test engine initialization  
+    console.log('Step 2: Testing engine initialization...');
+    await initializeDopEngine();
+    console.log('✅ Step 2 passed');
+    
+    // Step 3: Test wallet creation
+    console.log('Step 3: Testing wallet creation...');
+    const encryptionKey = Buffer.from('4b22bfaa2cd4826c04efa1beb5c3debf8a534223200ce50ce3ca979af93911c1', 'hex');
+    const testWallet = await createDopWalletSafe(
+      encryptionKey,
+      'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
+      undefined,
+      0,
+      30000 // 30 second timeout for testing
+    );
+    console.log('✅ Step 3 passed - Wallet ID:', testWallet.id);
+    
+    Alert.alert('✅ Success', 'All wallet integration tests passed!');
+    return true;
+    
+  } catch (error) {
+    console.error('❌ Wallet integration test failed:', error);
+    Alert.alert('❌ Test Failed', `Error: ${error.message}`);
+    return false;
+  }
+};
+```
+
+## 📞 When to Contact Support
+
+Contact the DOP team if:
+
+1. ✅ You've implemented all the fixes above
+2. ✅ The `testCircomlibjs()` function passes
+3. ❌ But `createDopWalletSafe()` still hangs
+
+Include this debug information:
+
+```typescript
+// Run this and include the output when contacting support
+export const collectDebugInfo = async () => {
+  const debugInfo = {
+    platform: Platform.OS,
+    reactNativeVersion: require('react-native/package.json').version,
+    timestamp: new Date().toISOString(),
+    
+    // Test basic environment
+    hasBuffer: typeof Buffer !== 'undefined',
+    hasCrypto: typeof global.crypto !== 'undefined',
+    hasWorker: typeof global.Worker !== 'undefined',
+    hasWebAssembly: typeof global.WebAssembly !== 'undefined',
+    
+    // Test circomlibjs
+    circomlibsTest: null,
+  };
+  
+  try {
+    await testCircomlibjs();
+    debugInfo.circomlibsTest = 'PASSED';
+  } catch (error) {
+    debugInfo.circomlibsTest = `FAILED: ${error.message}`;
+  }
+  
+  console.log('Debug Info for Support:', JSON.stringify(debugInfo, null, 2));
+  return debugInfo;
+};
+```
+
+## Summary for React Native Developers
+
+**The main issue**: DOP Wallet uses advanced cryptography (`circomlibjs`) that doesn't work out-of-the-box in React Native.
+
+**The solution**: 
+1. Disable Web Workers/WebAssembly **before** importing DOP Wallet
+2. Use the new `createDopWalletSafe()` function with timeout protection
+3. Test with `testCircomlibjs()` to verify everything works
+
+**Most important**: Add the Worker/WebAssembly disabling code at the very top of your App.js file, before any other imports.
+
+This fix resolves the hanging wallet creation issue that was blocking React Native integration.

package/README.md

@@ -6,5 +6,18 @@ The DOP Wallet SDK is an open-source project developed by [DOP](https://www.dop.
 
 The Wallet SDK enables dApp and DeFi developers to provide privacy to users safely and conveniently on Ethereum, Polygon and BNB Chain.
 
-The repo is written in TypeScript, and compatible with node.js and modern web browsers.
+The repo is written in TypeScript, and compatible with **Node.js**, **modern web browsers**, and **React Native**.
+
+## 📱 React Native Support
+
+This SDK now has comprehensive React Native support with optimized polyfills and easy integration:
+
+```typescript
+import 'react-native-get-random-values';
+import { DopWallet } from 'dop-wallet-v6/react-native';
+```
+
+**📚 Quick Start:** See [REACT_NATIVE_INTEGRATION_GUIDE.md](./REACT_NATIVE_INTEGRATION_GUIDE.md) for complete setup instructions.
+
+**🔧 Verify Compatibility:** Run `npm run verify-rn-compatibility` to ensure your setup is correct.