dop-wallet-v6 1.2.15 → 1.2.17

package/DOP_WALLET_V6_WALLET_CREATION_GUIDE.md

@@ -1,305 +0,0 @@
-# DOP Wallet v6 - Wallet Creation Guide
-
-## Overview
-
-This guide explains the different ways to create wallets using the new-dop-wallet-v3 SDK, 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.
-
-```typescript
-import { createOrImportDopWallet } from 'dop-wallet-v6';
-
-// 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)
-- `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
-);
-```
-
-### 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
-// Examples of valid encryption keys
-const encryptionKey1 = crypto.randomBytes(32).toString('hex'); // string
-const encryptionKey2 = crypto.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 Integration
-
-For React Native apps, use these functions which include circomlibjs compatibility testing:
-
-```typescript
-import { createOrImportDopWallet, testCircomlibjs } from 'dop-wallet-v6';
-
-// Test compatibility first (optional but recommended)
-const isCompatible = await testCircomlibjs();
-if (!isCompatible) {
-  throw new Error('Cryptography not compatible with this environment');
-}
-
-// Create wallet
-const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
-  timeout: 90000 // Increase timeout for React Native
-});
-```
-
-## Error Handling
-
-```typescript
-try {
-  const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
-    mnemonic: userInputMnemonic,
-    timeout: 60000
-  });
-  
-  console.log('Wallet created:', walletInfo.id);
-  console.log('Address:', walletInfo.dopAddress);
-  
-  // IMPORTANT: Securely store the mnemonic
-  await secureStorage.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 {
-    // Handle other errors
-    console.error('Wallet creation failed:', error);
-  }
-}
-```
-
-## Complete Examples
-
-### Example 1: Create New Wallet (Auto-Generate Mnemonic)
-
-```typescript
-import { createOrImportDopWallet } from 'dop-wallet-v6';
-import { randomBytes } from 'crypto';
-
-const createNewWallet = async () => {
-  try {
-    // Generate encryption key
-    const encryptionKey = randomBytes(32);
-    
-    // Create wallet with auto-generated mnemonic
-    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey);
-    
-    console.log('✅ New wallet created!');
-    console.log('Wallet ID:', walletInfo.id);
-    console.log('Address:', walletInfo.dopAddress);
-    console.log('Mnemonic (SAVE THIS!):', mnemonic);
-    
-    // Store securely
-    await secureStorage.setItem('encryption_key', encryptionKey.toString('hex'));
-    await secureStorage.setItem('wallet_mnemonic', mnemonic);
-    
-    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';
-
-const importExistingWallet = async (userMnemonic: string) => {
-  try {
-    // Get stored encryption key or create new one
-    const encryptionKey = await getOrCreateEncryptionKey();
-    
-    // Import wallet from mnemonic
-    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
-      mnemonic: userMnemonic.trim().toLowerCase()
-    });
-    
-    console.log('✅ Wallet imported successfully!');
-    console.log('Wallet ID:', walletInfo.id);
-    console.log('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: React Native with AsyncStorage
-
-```typescript
-import { createOrImportDopWallet } from 'dop-wallet-v6';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-const createWalletRN = async () => {
-  try {
-    // Test compatibility first
-    await testCircomlibjs();
-    
-    // Generate encryption key
-    const encryptionKey = randomBytes(32);
-    
-    // Create wallet with longer timeout for React Native
-    const { walletInfo, mnemonic } = await createOrImportDopWallet(encryptionKey, {
-      mnemonicStrength: 256, // 24 words for maximum security
-      timeout: 90000 // 90 seconds timeout
-    });
-    
-    // Store in AsyncStorage
-    await AsyncStorage.multiSet([
-      ['encryption_key', encryptionKey.toString('hex')],
-      ['wallet_mnemonic', mnemonic],
-      ['wallet_id', walletInfo.id],
-      ['wallet_address', walletInfo.dopAddress]
-    ]);
-    
-    console.log('✅ Wallet created and stored in React Native!');
-    return walletInfo;
-    
-  } catch (error) {
-    console.error('React Native wallet creation failed:', error);
-    throw error;
-  }
-};
-```
-
-## Best Practices
-
-1. **Always validate user input mnemonics** before importing
-2. **Use secure storage** for encryption keys and mnemonics
-3. **Increase timeout** for React Native (90+ seconds)
-4. **Test circomlibjs compatibility** in React Native before wallet creation
-5. **Handle timeout errors** gracefully - suggest app restart
-6. **Use 24-word mnemonics** for maximum security when possible
-7. **Never log or store mnemonics in plain text** in production
-
-## Troubleshooting
-
-### "Invalid mnemonic phrase"
-- Ensure mnemonic has correct number of words (12, 18, or 24)
-- Check for typos or extra spaces
-- Verify words are from the BIP39 wordlist
-
-### "Wallet creation timed out"
-- Increase timeout value
-- Restart the React Native app
-- Check if circomlibjs shims are properly loaded
-
-### "Cryptography not compatible"
-- Ensure react-native-shims.js is imported before any wallet operations
-- Check Metro bundler configuration
-- Verify all polyfills are installed
-
-## 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
-});
-```
-
-The new API provides the mnemonic in the response, making it easier to handle both wallet creation and mnemonic storage in one step.

package/REACT_NATIVE_FIXES_COMPLETE.md

@@ -1,162 +0,0 @@
-# DOP Wallet v6 React Native Integration - Complete Fix Summary
-
-## 🚨 **Issues Identified by React Native Developer**
-
-1. **Legacy AsyncStorage References**: SDK dependencies still referenced legacy RN-core AsyncStorage
-2. **Missing Required Polyfills**: Required polyfills and Node.js shims not documented as mandatory
-3. **Level-FS Integration Broken**: The Level-FS integration described in docs doesn't work in React Native
-
-## ✅ **Comprehensive Fixes Applied**
-
-### **Fix #1: Legacy AsyncStorage - RESOLVED**
-
-**Problem**: GraphQL Mesh cache dependencies were trying to use legacy `require('react-native').AsyncStorage`
-
-**Solution**:
-- ✅ Disabled `@graphql-mesh/cache-localforage` in all GraphQL files
-- ✅ Added `@react-native-async-storage/async-storage` as direct dependency
-- ✅ Updated `react-native-shims.js` with compatibility notes
-
-**Code Changes**:
-```typescript
-// In all GraphQL files:
-// MODIFIED: Replaced MeshCache with undefined to disable caching for React Native compatibility
-// import MeshCache from "@graphql-mesh/cache-localforage";
-const cache = undefined; // Instead of: new MeshCache({...})
-```
-
-### **Fix #2: Required Polyfills - RESOLVED**
-
-**Problem**: Users didn't know which polyfills were mandatory, causing runtime errors
-
-**Solution**:
-- ✅ Added all required polyfills to `package.json` dependencies
-- ✅ Updated integration guide with mandatory polyfill documentation
-- ✅ Enhanced `react-native-shims.js` with automatic setup
-
-**Required Dependencies Now Bundled**:
-```json
-{
-  "dependencies": {
-    "@react-native-async-storage/async-storage": "^1.24.0",
-    "buffer": "^6.0.3", 
-    "crypto-browserify": "3.12.0",
-    "stream-browserify": "3.0.0",
-    "memdown": "^6.1.1"
-  }
-}
-```
-
-### **Fix #3: Level-FS Integration - COMPLETELY RESOLVED**
-
-**Problem**: `react-native-level-fs` returns filesystem interface, not LevelDB constructor
-
-**Solution**: 
-- ✅ Created `startDopEngineReactNative()` function that handles database internally
-- ✅ Implemented custom React Native LevelDB using `memdown` + AsyncStorage persistence
-- ✅ Removed all problematic level-fs dependencies
-- ✅ Updated integration guide with simplified approach
-
-**New React Native API**:
-```typescript
-// ✅ New simplified approach - no database management needed
-import { startDopEngineReactNative } from 'dop-wallet-v6';
-
-await startDopEngineReactNative(
-  walletSource,     // string
-  shouldDebug,      // boolean
-  artifactStore,    // ArtifactStore implementation
-  useNativeArtifacts,   // boolean (default: true)
-  skipMerkletreeScans,  // boolean (default: false) 
-  verboseScanLogging,   // boolean (default: false)
-  databaseName          // string (default: 'dop-wallet-db')
-);
-```
-
-### **Fix #4: Enhanced Database Implementation**
-
-**Problem**: Previous solution used in-memory only database (data lost on restart)
-
-**Solution**: 
-- ✅ Created custom `ReactNativeLevelDB` class
-- ✅ Implements full `AbstractLevelDOWN` interface
-- ✅ Uses `memdown` for fast in-memory operations  
-- ✅ Automatically persists to AsyncStorage for data retention
-- ✅ Gracefully handles AsyncStorage unavailability
-
-**Technical Implementation**:
-```typescript
-class ReactNativeLevelDB {
-  // Implements AbstractLevelDOWN interface
-  // Uses memdown for performance + AsyncStorage for persistence
-  // Automatically syncs data in background
-  // Compatible with all DOP Engine operations
-}
-```
-
-## 📋 **Updated Integration Process**
-
-### **1. Install Dependencies** (Simplified)
-```bash
-npm install dop-wallet-v6 @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill
-```
-
-### **2. Setup Polyfills** (Automatic)
-```typescript
-// App entry point
-import 'react-native-get-random-values';
-import 'react-native-url-polyfill/auto';
-import 'dop-wallet-v6/react-native-shims'; // Handles Buffer, crypto, etc.
-```
-
-### **3. Initialize Engine** (Simplified)
-```typescript
-import { startDopEngineReactNative } from 'dop-wallet-v6';
-
-await startDopEngineReactNative(
-  'myapp',
-  __DEV__,
-  artifactStore
-);
-```
-
-## 🎯 **Results for React Native Developer**
-
-### **Before (Broken)**:
-- ❌ AsyncStorage errors from GraphQL Mesh
-- ❌ "Cannot read property 'call' of undefined" from missing polyfills  
-- ❌ "level is not a function" from incorrect Level-FS usage
-- ❌ Complex database setup with multiple dependencies
-- ❌ Data loss on app restart
-
-### **After (Fixed)**:
-- ✅ No AsyncStorage conflicts - uses modern `@react-native-async-storage/async-storage`
-- ✅ All polyfills bundled and auto-configured
-- ✅ Single function call to initialize: `startDopEngineReactNative()`
-- ✅ Database persistence between app sessions
-- ✅ Zero manual database management required
-- ✅ Comprehensive error handling and fallbacks
-
-## 🔧 **Breaking Changes (v1.2.10)**
-
-**For React Native Users**:
-- **OLD**: `startDopEngine(walletSource, db, ...)`  
-- **NEW**: `startDopEngineReactNative(walletSource, shouldDebug, artifactStore, ...)`
-
-**Migration is Simple**:
-1. Replace `startDopEngine` import with `startDopEngineReactNative`
-2. Remove database creation code (`level`, `AsyncStorageDown`, etc.)
-3. Update function call to new signature
-4. Remove level-fs dependencies from package.json
-
-## ✅ **Verification**
-
-- ✅ SDK builds successfully
-- ✅ All TypeScript checks pass
-- ✅ Integration test updated to use new API
-- ✅ Documentation updated with correct examples
-- ✅ No more legacy AsyncStorage dependencies
-- ✅ Polyfills are automatically handled
-- ✅ Database persistence works in React Native
-
-**Bottom Line**: All React Native integration issues have been resolved. The SDK now provides a seamless, one-function initialization that handles all the complexity internally.

package/REACT_NATIVE_INTEGRATION_FIXES.md

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