dop-wallet-v6 1.2.15 → 1.2.16

package/REACT_NATIVE_SETUP_QUICK_FIX.md

@@ -1,189 +0,0 @@
-# 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

@@ -1,270 +0,0 @@
-# 🚨 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/SELECTIVE_TRANSPARENCY.md

@@ -1,207 +0,0 @@
-# Selective Transparency Feature
-
-The Selective Transparency feature allows DOP Wallet users to control the visibility of their assets, balances, NFTs, and profile information. Users can define privacy settings, manage whitelists, and generate cryptographic proofs for asset exposure.
-
-## Features
-
-### 1. User Profile Management
-- Create and manage user profiles with username, bio, profile picture, and social links
-- Profile customization with theme preferences and privacy alerts
-- Profile validation and search functionality
-
-### 2. Asset Visibility Control
-- Control visibility of token balances, NFTs, and transaction history
-- Granular control per token/NFT contract address
-- Global visibility settings with per-asset overrides
-
-### 3. Whitelist Management
-- Manage a list of trusted addresses that can view private information
-- Granular permissions for each whitelisted address
-- Support for viewing balances, NFTs, transactions, and profile data
-
-### 4. Viewing Requests & Proofs
-- Create and manage viewing requests from other users
-- Generate cryptographic proofs for authorized visibility
-- Proof verification and expiration management
-
-## Usage Examples
-
-### Profile Management
-
-```typescript
-import { ProfileManager } from 'dop-wallet-v3';
-
-const profileManager = new ProfileManager();
-
-// Create a user profile
-const profile = await profileManager.createProfile('wallet-id', {
-  username: 'alice',
-  bio: 'DeFi enthusiast',
-  profilePicture: 'https://example.com/avatar.jpg',
-  socialLinks: {
-    twitter: 'https://twitter.com/alice',
-    github: 'https://github.com/alice'
-  }
-});
-
-// Update profile
-await profileManager.updateProfile('wallet-id', {
-  bio: 'Privacy-focused DeFi user'
-});
-
-// Set profile customization
-await profileManager.setCustomization('wallet-id', {
-  theme: 'dark',
-  displayPreferences: {
-    currencyFormat: 'USD',
-    numberFormat: 'abbreviated',
-    dateFormat: 'MM/DD/YYYY',
-    timeFormat: '24h'
-  },
-  privacyAlerts: {
-    newViewingRequest: true,
-    profileUpdate: false,
-    assetVisibilityChange: true
-  }
-});
-```
-
-### Selective Transparency Settings
-
-```typescript
-import { SelectiveTransparencyManager } from 'dop-wallet-v3';
-
-const transparencyManager = new SelectiveTransparencyManager();
-
-// Create default privacy settings
-const settings = await transparencyManager.createDefaultSettings('wallet-id');
-
-// Update global visibility settings
-await transparencyManager.updateSettings('wallet-id', {
-  assetVisibility: {
-    showTokenBalances: false,  // Hide token balances by default
-    showNFTs: true,            // Show NFTs
-    showTransactionHistory: false, // Hide transaction history
-    showAddresses: false       // Hide addresses
-  }
-});
-
-// Set specific token visibility
-await transparencyManager.setTokenVisibility('wallet-id', '0x...tokenAddress', {
-  isVisible: true,
-  showBalance: true,
-  showTransactions: false
-});
-
-// Set NFT collection visibility
-await transparencyManager.setNFTVisibility('wallet-id', '0x...nftAddress', {
-  isVisible: true,
-  showCollection: true,
-  showTransactions: false
-});
-```
-
-### Whitelist Management
-
-```typescript
-// Add address to whitelist with specific permissions
-await transparencyManager.addToWhitelist('wallet-id', '0x...trustedAddress', {
-  viewBalances: true,
-  viewNFTs: true,
-  viewTransactions: false,
-  viewProfile: true
-});
-
-// Check if address has permission
-const canViewBalances = await transparencyManager.checkWhitelistPermission(
-  'wallet-id',
-  '0x...address',
-  'viewBalances'
-);
-
-// Remove from whitelist
-await transparencyManager.removeFromWhitelist('wallet-id', '0x...address');
-```
-
-### Viewing Requests & Proofs
-
-```typescript
-// Create a viewing request
-const request = await transparencyManager.createViewingRequest(
-  'requester-id',
-  'wallet-id',
-  'balance',
-  '0x...tokenAddress',
-  'Can I see your USDC balance?'
-);
-
-// Respond to viewing request
-await transparencyManager.respondToViewingRequest(request.id, 'approved');
-
-// Generate visibility proof (requires whitelist permission)
-const proof = await transparencyManager.generateVisibilityProof(
-  'wallet-id',
-  'requester-id',
-  'balance',
-  '0x...tokenAddress'
-);
-
-// Verify proof
-const isValid = await transparencyManager.verifyVisibilityProof(proof.id);
-```
-
-### Event Handling
-
-```typescript
-import { setSelectiveTransparencyCallback } from 'dop-wallet-v3';
-
-// Set up event listener
-setSelectiveTransparencyCallback((event) => {
-  switch (event.type) {
-    case 'profile_updated':
-      console.log('Profile updated for wallet:', event.data.walletId);
-      break;
-    case 'settings_changed':
-      console.log('Privacy settings changed for wallet:', event.data.walletId);
-      break;
-    case 'viewing_request':
-      console.log('New viewing request:', event.data);
-      break;
-    case 'proof_generated':
-      console.log('Visibility proof generated:', event.data);
-      break;
-  }
-});
-```
-
-## Security Features
-
-1. **Cryptographic Proofs**: All visibility proofs are cryptographically generated and time-limited
-2. **Whitelist-Only Proof Generation**: Only explicitly whitelisted addresses can generate visibility proofs
-3. **Granular Permissions**: Fine-grained control over what information each address can view
-4. **Expiration Management**: Viewing requests and proofs automatically expire
-5. **Validation**: All profile data and settings are validated before storage
-
-## Integration Notes
-
-- The feature is fully integrated into the main DOP Wallet SDK exports
-- All operations are asynchronous and return Promises
-- Profile and transparency managers maintain in-memory state (consider persisting to storage in production)
-- Event callbacks allow for real-time UI updates
-- All methods include proper error handling and sanitization
-
-## Testing
-
-The feature includes comprehensive unit tests covering:
-- Profile creation, updates, and validation
-- Privacy settings management
-- Token and NFT visibility controls
-- Whitelist management
-- Viewing request workflows
-- Visibility proof generation and verification
-- Error handling and edge cases
-
-Run tests with:
-```bash
-npm test -- --grep "ProfileManager|SelectiveTransparencyManager"
-```