Skip to content

README.md

Latest commit

 

History

History
788 lines (601 loc) · 25.6 KB

README.md

File metadata and controls

788 lines (601 loc) · 25.6 KB

Smart Pywallet - Universal Bitcoin Wallet Recovery Tool

🎯 One Command for All Wallet Types

This improved version of pywallet features smart auto-detection - you only need to remember one command that automatically handles all wallet types and formats.

✨ Key Features

🧠 Smart Auto-Detection

  • Automatically detects wallet format (Berkeley DB, SQLite, damaged files)
  • Chooses optimal method (fast extraction vs recovery)
  • Seamless fallback when one method fails
  • Clear explanations of what's happening and why

⚡ Unified Command Interface

  • One command for all scenarios
  • No more confusion about which method to use
  • Client-friendly - works with preferred command syntax
  • Robust handling of edge cases

🔧 Full Python 3 Support & Stability

  • ✅ Fixed Python 3 compatibility - Resolved has_key() AttributeError
  • ✅ Enhanced error handling - Robust Berkeley DB corruption handling
  • ✅ Segmentation fault fixes - Safe binary search with bounds checking
  • ✅ Multiple fallback strategies - Advanced → Binary Search → Raw Recovery
  • ✅ Corrupted wallet support - Handles damaged database files gracefully

🏷️ Version Information & Branding

  • Version display at startup: Shows current version and website
  • Output file headers include version and attribution information
  • Clear attribution to original Jackjack's pywallet.py codebase
  • Professional branding for client confidence

📦 Installation

🐧 Ubuntu/Linux Compatibility

This version has been specifically tested and optimized for Ubuntu 24.04 and native Linux environments. Key improvements include:

  • ✅ Fixed PEP 668 compatibility - Works with Ubuntu's strict Python environment management
  • ✅ Proper virtual environment isolation - No more "externally-managed-environment" errors
  • ✅ All required dependencies - Pre-configured with bsddb3, ecdsa, pycryptodome
  • ✅ Cross-platform compatibility - Works on both WSL and native Ubuntu
  • ✅ Enhanced error handling - Better diagnostics for Ubuntu-specific issues

Quick Setup

# Make build script executable and run it
chmod +x install.sh
./install.sh

Manual Setup (Ubuntu 24.04+)

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install libdb-dev python3-dev build-essential python3-venv libssl-dev libffi-dev

# Create virtual environment (with proper isolation)
python3 -m venv pywallet_build_env --clear
source pywallet_build_env/bin/activate

# Install Python dependencies
pip install --upgrade pip
pip install bsddb3 ecdsa pycryptodome

# Test installation
python3 -c "import bsddb3; import ecdsa; import Crypto; print('✓ All dependencies working!')"

🔧 WSL vs Native Ubuntu Differences

Feature WSL Native Ubuntu 24.04
Python Environment More permissive PEP 668 enforced
Package Installation Allows global installs Requires proper venv
Virtual Environment Sometimes broken Needs explicit setup
Dependencies Often pre-installed Manual installation required
Performance Good Excellent

✅ This version works perfectly on both!

🚀 Usage - One Universal Command

The Only Command You Need to Remember:

./run_pywallet.sh --recover --recov_device=PATH_TO_WALLET --output_keys=output_file.txt

That's it! The system automatically:

  1. 🔍 Analyzes your wallet file or device
  2. 🎯 For .dat files: Tries targeted extraction first (fast method)
  3. ⚡ Smart fallback: Falls back to traditional recovery if needed
  4. 🔧 For devices/raw data: Uses traditional recovery method
  5. 📝 Explains what it's doing and why

🆕 NEW: True Universal Command

The --recover command now works with ANY wallet type:

  • Rwallet/wallet5.dat → Automatically uses targeted extraction
  • regular/wallet.dat → Tries targeted first, then traditional recovery
  • corrupted/wallet.dat → Graceful fallback to recovery mode
  • /dev/sda1 → Traditional device recovery
  • Any file or device → Automatically chooses the best method

Examples

Extract from any wallet file:

./run_pywallet.sh --recover --recov_device=wallet.dat --output_keys=my_keys.txt

Extract from Rwallet (targeted extraction):

./run_pywallet.sh --recover --recov_device=RWT/wall.dat --output_keys=targeted_results.txt

Extract from any wallet directory:

./run_pywallet.sh --recover --recov_device=xtest/xtest1/wallet.dat --output_keys=recovered_keys.txt

Recover from damaged device:

./run_pywallet.sh --recover --recov_device=/dev/sda1 --recov_size=100MB --output_keys=recovered_keys.txt

🎉 All examples use the SAME command format! No more confusion about which method to use.

🧠 How Smart Detection Works

Step 1: Analysis

🔍 SMART RECOVERY - Analyzing target...
============================================================
🔍 SMART WALLET DETECTION
============================================================
You used --recover command on: wallet.dat
Auto-analyzing to choose the best extraction method...

Testing if wallet file is intact...

Step 2: Method Selection

✅ For Intact Wallets (Fast Path):

✅ Wallet integrity OK - Format: advanced
✅ WALLET IS INTACT - Using Advanced Extraction
============================================================
🎯 RECOMMENDATION: Your wallet file is complete and undamaged.
   Using FAST advanced extraction instead of slow recovery.
   This will get you ALL keys efficiently!

🔑 Enter the wallet password (or press Enter for default '1234'):
Password: [your_password]
⚡ Method: Advanced Extraction (FAST & COMPLETE)

🔧 For Damaged Wallets (Recovery Path):

❌ WALLET APPEARS DAMAGED - Using Recovery Method
============================================================
🔧 Your wallet file appears corrupted or damaged.
   Using traditional recovery method to scan for key fragments.
   This will be slower but may recover partial data.

🔄 Smart Fallback:

⚠️ Advanced extraction failed: [technical error]
🔄 Automatically falling back to traditional recovery method...
Using password from previous attempt: [password]
Starting recovery.

Step 3: Results

✅ SUCCESS! 202 unique keys recovered
📂 Keys saved to: recovered_keys.txt

🏷️ Version Information

Console Output

Every time you run the script, you'll see the version information:

Pywallet 2.3-gsc - https://pywallet.org
🔍 SMART RECOVERY - Analyzing target...

Output File Headers

All generated files include version attribution:

# Recovered private keys
# Data extracted by: Pywallet 2.3-gsc - https://pywallet.org
# Generated by pywallet recovery
# Format: private keys in both hex and WIF formats

🎯 What This Solves

Before (Confusing):

  • ❌ Multiple different commands for different wallet types
  • ❌ Users had to guess which command to use
  • ❌ Arguments about "correct" vs "wrong" commands
  • ❌ Manual fallback when methods failed

After (Simple):

  • ✅ One command for all wallet types
  • ✅ Automatic detection and method selection
  • ✅ Smart fallback when methods fail
  • ✅ Clear explanations of what's happening
  • ✅ Client satisfaction - they use their preferred command

📊 Supported Wallet Types

The smart detection automatically handles:

Wallet Type Format Detection Method Extraction Method
Bitcoin Core (old) Berkeley DB DB structure analysis Advanced extraction
Bitcoin Core (new) SQLite File signature detection Recovery parsing
Damaged/Corrupted Any Error fallback Recovery scanning
Disk Images Raw data Size/device analysis Recovery scanning
Backup Files Various Extension + content Auto-detected method

📁 Output Format

All recovered keys are saved in both HEX and WIF formats:

# Recovered private keys
# Generated by pywallet recovery
# Format: private keys in both hex and WIF formats

Key #1 (HEX): 3c9229289a6125f7fdf1885a77bb12c37a8d3b4962d936f7e3084dece32a3ca1
Key #1 (WIF): 5JA7QYoYKimso8jHZrUGDLLiqwEJa3uKyUQnpMcPyxP8jNG8acc

Key #2 (HEX): e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Key #2 (WIF): 5Jbm9rrusXMYL8HqtVJWANrKZWGNgMXTYqN9VVvV71TjdphjRPR
...

🔧 Command Options

Required Options:

  • --recover - Activates smart recovery mode
  • --recov_device=PATH - Path to wallet file or device
  • --output_keys=FILE - Output file for recovered keys

Optional Options:

  • --recov_size=SIZE - Limit recovery size (auto-detected for files)
    • Examples: 100MB, 2GB, 500MB
    • Not needed for wallet files (auto-detected)

Size Format Support:

  • Modern: 100MB, 2GB, 500MB
  • Legacy: 100Mo, 2Gio (still supported)

🏆 Benefits

For Users:

  • ✅ Simple: Only one command to remember
  • ✅ Reliable: Automatic method selection
  • ✅ Transparent: Clear explanations of actions
  • ✅ Robust: Automatic fallback on failures

For Support:

  • ✅ No arguments about which commands to use
  • ✅ Self-documenting process with clear output
  • ✅ Handles edge cases automatically
  • ✅ Client satisfaction through preference accommodation

🎯 Real-World Recovery Scenarios

🔥 Scenario 1: Corrupted Bitcoin Core Wallet (Most Common)

Situation: Your wallet.dat file won't open in Bitcoin Core, shows corruption errors, or the application crashes when trying to load it.

Command:

# Standard Bitcoin Core location (Linux)
./run_pywallet.sh --recover --recov_device=~/.bitcoin/wallet.dat --output_keys=recovered_keys.txt

# Custom location
./run_pywallet.sh --recover --recov_device=/path/to/your/wallet.dat --output_keys=recovered_keys.txt

What to Expect:

❌ WALLET APPEARS DAMAGED - Using Recovery Method
🔧 Your wallet file appears corrupted or damaged.
   Using traditional recovery method to scan for key fragments.
🔑 Enter the wallet password: [enter your password]
✅ SUCCESS! 47 unique keys recovered

⚠️ Important: Always backup your original wallet.dat before recovery!

🔥 Scenario 2: Hard Drive Crash with Partial Wallet Data

Situation: Hard drive crashed, but you can still access some sectors. Wallet file may be partially readable.

Command:

# For damaged hard drive partition
./run_pywallet.sh --recover --recov_device=/dev/sda1 --recov_size=500MB --output_keys=recovered_keys.txt

# For damaged wallet file with known size issues
./run_pywallet.sh --recover --recov_device=/path/to/damaged/wallet.dat --output_keys=recovered_keys.txt

What to Expect:

🔍 SMART RECOVERY - Analyzing target...
⚠️ Advanced extraction failed: I/O error
🔄 Automatically falling back to traditional recovery method...
✅ Found 1 possible wallet
✅ Found 23 possible encrypted keys

🔥 Scenario 3: Old Bitcoin Core Wallet (Pre-2011)

Situation: Very old wallet from early Bitcoin days, different database format.

Command:

./run_pywallet.sh --recover --recov_device=/path/to/old/wallet.dat --output_keys=old_wallet_keys.txt

What to Expect:

✅ Detected Berkeley DB wallet format (traditional Bitcoin Core)
✅ WALLET IS INTACT - Using Advanced Extraction
⚡ Method: Advanced Extraction (FAST & COMPLETE)
✅ SUCCESS! 1,247 unique keys recovered

🔥 Scenario 4: Encrypted Wallet with Known Password

Situation: Wallet is encrypted but you know the password. File may or may not be corrupted.

Command:

./run_pywallet.sh --recover --recov_device=/path/to/encrypted/wallet.dat --output_keys=decrypted_keys.txt

What to Expect:

🔑 Enter the wallet password (or press Enter for default '1234'):
Password: [enter your actual password]
✅ Password accepted - decrypting keys...
✅ SUCCESS! 89 unique keys recovered (decrypted)

🔐 Security Note: Keys will be saved in unencrypted format in the output file!

🔥 Scenario 5: Multiple Wallet Files Recovery

Situation: You have several wallet files and want to recover from all of them.

Commands (run separately):

# Wallet 1
./run_pywallet.sh --recover --recov_device=wallet1.dat --output_keys=keys_wallet1.txt

# Wallet 2  
./run_pywallet.sh --recover --recov_device=wallet2.dat --output_keys=keys_wallet2.txt

# Wallet 3
./run_pywallet.sh --recover --recov_device=backup/old_wallet.dat --output_keys=keys_backup.txt

Combine Results:

# Merge all recovered keys (remove duplicates manually)
cat keys_wallet1.txt keys_wallet2.txt keys_backup.txt > all_recovered_keys.txt

🔥 Scenario 6: Wallet on External Drive/USB

Situation: Wallet file is on external storage that may have connection issues.

Command:

# First, copy wallet to local drive for stability
cp /media/usb/wallet.dat ./wallet_backup.dat

# Then recover from local copy
./run_pywallet.sh --recover --recov_device=./wallet_backup.dat --output_keys=usb_wallet_keys.txt

Why: Reduces risk of I/O errors during recovery process.

🔥 Scenario 7: Very Large Wallet Files (>100MB)

Situation: Wallet file is unusually large, recovery might take a long time.

Command:

# Standard recovery (may take hours)
./run_pywallet.sh --recover --recov_device=/path/to/large/wallet.dat --output_keys=large_wallet_keys.txt

What to Expect:

🔍 SMART RECOVERY - Analyzing target...
No size specified. Using full file size: 524288000 bytes (500.0 MB)
⚠️ Large file detected - this may take several hours
🔄 Processing... [progress indicators]

💡 Tip: Run in screen or tmux session for long recoveries:

screen -S wallet_recovery
./run_pywallet.sh --recover --recov_device=large_wallet.dat --output_keys=keys.txt
# Press Ctrl+A, then D to detach
# Later: screen -r wallet_recovery to reattach

🚨 Troubleshooting

"No size specified" Message

This is normal for wallet files:

No size specified. Using full file size: 933888 bytes (0.89 MB)

The system automatically detects the file size.

"Advanced extraction failed" Message

This triggers automatic fallback:

⚠️ Advanced extraction failed: [error details]
🔄 Automatically falling back to traditional recovery method...

This is expected behavior for certain wallet formats.

Berkeley DB Corruption Errors

The system now handles these gracefully with multiple recovery strategies:

DB open error: (22, 'Invalid argument -- BDB3037 file size not a multiple of the pagesize')
DB open error: (22, 'Invalid argument -- BDB2509 the log files from a database environment')

Solution: ✅ Automatic fallback to binary search and raw recovery methods

"Permission denied" Errors

# Make sure you have read access to the wallet file
chmod 644 /path/to/wallet.dat

# Or copy to a location you own
cp /path/to/wallet.dat ~/my_wallet_copy.dat
./run_pywallet.sh --recover --recov_device=~/my_wallet_copy.dat --output_keys=keys.txt

"File not found" Errors

# Check if file exists
ls -la /path/to/wallet.dat

# Find wallet files on system
find / -name "wallet.dat" 2>/dev/null
find ~ -name "*.dat" 2>/dev/null | grep -i wallet

Recovery Takes Too Long

# Check progress (in another terminal)
ps aux | grep pywallet
top -p $(pgrep -f pywallet)

# If stuck, try with smaller size limit
./run_pywallet.sh --recover --recov_device=wallet.dat --recov_size=50MB --output_keys=keys.txt

"No keys found" Result

Possible causes:

  1. Wrong password: Try without password or different passwords
  2. File is not a wallet: Verify it's actually a Bitcoin wallet file
  3. Completely corrupted: File may be beyond recovery
  4. Wrong file: Make sure you're using the right wallet.dat

Solutions:

# Try without password
./run_pywallet.sh --recover --recov_device=wallet.dat --output_keys=keys.txt
# (Press Enter when prompted for password)

# Try with different common passwords
# Run the command and try: password, 123456, bitcoin, etc.

# Verify file type
file wallet.dat
hexdump -C wallet.dat | head -20

Python 3 Compatibility Issues

Fixed: ✅ All AttributeError: 'dict' object has no attribute 'has_key' errors resolved

Segmentation Faults

Fixed: ✅ Added comprehensive safety checks to prevent crashes during binary search

"DB object has been closed" Error

This is handled automatically by the fallback system. The error is caught and recovery continues with an alternative method.

📊 Enhanced Diagnostic Reporting

🔍 Automatic Diagnostic Reports

Every wallet recovery operation now generates a comprehensive diagnostic report for troubleshooting and remote debugging assistance.

Report Generation:

📝 Creating detailed diagnostic report: pywallet_report_20250710_201505.log
   Diagnostic report saved to: pywallet_report_20250710_201505.log
   You can share this file for remote debugging assistance.

📁 Report Contents

Each diagnostic report includes:

  • 🔧 System Information: OS, Python version, memory, disk space
  • 📊 Wallet File Analysis: File size, type, permissions, integrity checks
  • ⚡ Command Details: Exact command executed, parameters used
  • 🔍 Error Patterns: Detected issues, segmentation faults, database errors
  • 📈 Performance Metrics: Processing time, memory usage
  • 🛠️ Recovery Statistics: Keys found, encryption status, success rates

Sample Report Structure:

PYWALLET DIAGNOSTIC REPORT
========================
Timestamp: Thu Jul 10 08:15:05 PM MSK 2025
Command: ./run_pywallet.sh --recover --recov_device=wallet.dat --output_keys=keys.txt
Exit Code: 0

SYSTEM INFORMATION:
-------------------
OS: Linux ubuntu-desktop 6.11.0-29-generic
Python: Python 3.12.3
Memory: 16.0Gi total, 4.6Gi available
Disk Space: 47G available

WALLET FILE ANALYSIS:
--------------------
File: wallet0708/wallet.dat
Size: 11411456 bytes (10.88 MB)
Type: Berkeley DB (Btree, version 9, native byte-order)
Permissions: -rw-r--r--
Encryption: Encrypted (master key detected)

RECOVERY RESULTS:
-----------------
Keys Extracted: 1998 unique keys
WIF Keys Generated: 3996 total
Success Rate: 100%
Method Used: Binary recovery with master key decryption

🔧 Using Reports for Troubleshooting

  1. For Remote Support: Share the .log file with support team
  2. For Self-Diagnosis: Review error patterns and suggestions
  3. For Multiple Attempts: Compare different recovery runs
  4. For Performance Analysis: Monitor system resource usage

📁 Report File Management

# List all diagnostic reports
ls -la pywallet_report_*.log

# View latest report
cat $(ls -t pywallet_report_*.log | head -1)

# Clean old reports (keep last 5)
ls -t pywallet_report_*.log | tail -n +6 | xargs rm -f

🔒 Security Best Practices for Real Wallet Recovery

Before Recovery:

  1. 🔄 Backup Original: Always copy your wallet.dat before recovery

    cp wallet.dat wallet_backup_$(date +%Y%m%d).dat

  2. 🔌 Go Offline: Disconnect from internet during recovery for maximum security

  3. 🖥️ Clean Environment: Use a dedicated, clean computer if possible

During Recovery:

  1. 🔐 Secure Terminal: Make sure no one can see your screen when entering passwords
  2. 📝 No Screenshots: Never take screenshots of private keys
  3. 🚫 No Cloud Storage: Don't save recovery files to cloud services

After Recovery:

  1. 🔥 Secure Deletion: Securely delete recovery files after importing keys

    shred -vfz -n 3 recovered_keys.txt

  2. 🆕 New Wallet: Import keys into a new, secure wallet immediately

  3. 💸 Move Funds: Transfer funds to a new wallet with fresh keys

  4. 🧹 Clean Up: Clear terminal history and temporary files

Key Import Commands (for reference):

# Bitcoin Core
bitcoin-cli importprivkey "your_WIF_key_here" "label" false

# Electrum  
# Use: Wallet → Private Keys → Import

📈 System Requirements

  • Python: 3.6 or higher
  • OS: Linux, macOS, Windows (with WSL)
  • Memory: Minimum 1GB RAM (more for large recoveries)
  • Storage: Space for output files

🎉 Success Stories

Scenario 1: Intact Bitcoin Core Wallet

./run_pywallet.sh --recover --recov_device=wallets/wallet1.dat --output_keys=keys.txt

Result: ✅ Fast extraction, 2001 keys recovered in 30 seconds

Scenario 2: SQLite Wallet (newer Bitcoin Core)

./run_pywallet.sh --recover --recov_device=xtest/xtest1/wallet.dat --output_keys=keys.txt

Result: ✅ Auto-fallback to recovery, 202 keys recovered from SQLite format

Scenario 3: Damaged Hard Drive

./run_pywallet.sh --recover --recov_device=/dev/sda1 --recov_size=500MB --output_keys=keys.txt

Result: ✅ Deep scan recovery, partial key recovery from damaged sectors

🔧 Recent Fixes & Improvements (Latest Update)

✅ Critical Issues Resolved

1. Python 3 Compatibility Fixed

  • Issue: AttributeError: 'dict' object has no attribute 'has_key'
  • Solution: Replaced deprecated has_key() method with Python 3 compatible in operator
  • Impact: Tool now works properly with Python 3.x

2. Berkeley DB Corruption Handling Enhanced

  • Issues:
    • BDB3037 file size not a multiple of the pagesize
    • BDB2509 the log files from a database environment
    • BDB0210 metadata page checksum error
  • Solution: Multi-strategy database opening with graceful fallback
  • Impact: Corrupted wallets now process successfully instead of crashing

3. Segmentation Fault Prevention

  • Issue: Binary search causing crashes during key extraction
  • Solution: Comprehensive bounds checking and safe data parsing
  • Impact: Stable operation even with severely corrupted wallet data

4. Robust Fallback System

  • Enhancement: Three-tier recovery strategy
    1. Advanced Extraction (fastest, for intact wallets)
    2. Binary Search (medium speed, for corrupted DB files)
    3. Raw Recovery (slowest, for severely damaged files)
  • Impact: Maximum key recovery success rate

🎯 Real-World Test Results

Before Fixes:

❌ AttributeError: 'dict' object has no attribute 'has_key'
❌ DB open error: file size not a multiple of the pagesize
❌ Segmentation fault (core dumped)

After Fixes:

✅ Detected Berkeley DB wallet format (traditional Bitcoin Core)
✅ Advanced extraction failed, falling back to recovery method...
✅ Found 1 possible wallet
✅ Found 7 possible encrypted keys
✅ Recovery completed successfully

📊 Compatibility Status

Issue Type Status Solution
Python 3 Compatibility ✅ FIXED has_key() → in operator
Berkeley DB Corruption ✅ HANDLED Multi-strategy opening
Segmentation Faults ✅ PREVENTED Bounds checking
Fallback Mechanism ✅ ENHANCED 3-tier recovery
Error Messages ✅ IMPROVED Clear user feedback

⚡ Parameter Compatibility & Ubuntu Support

🔧 Fixed Parameter Issues

Common Parameter Confusion Resolved:

❌ Previous Issues ✅ Now Fixed
--output_keys=file.txt (didn't work) --output_keys=file.txt ✅ WORKS
--keys=file.txt (only option) Both --keys= and --output_keys= work
Confusing error messages Clear parameter validation

Both parameter formats now work:

# Either of these work identically:
./run_pywallet.sh --recover --recov_device=wallet.dat --output_keys=keys.txt
./run_pywallet.sh --recover --recov_device=wallet.dat --keys=keys.txt

🐧 Ubuntu 24.04 Native Support

Key Improvements for Ubuntu Users:

  • ✅ PEP 668 Compliance: Fixed "externally-managed-environment" errors
  • ✅ Proper Virtual Environment: Isolated Python environment that actually works
  • ✅ All Dependencies: bsddb3, ecdsa, pycryptodome properly installed
  • ✅ Cross-Platform: Works on both WSL and native Ubuntu
  • ✅ Performance: Better performance on native Ubuntu vs WSL

🔄 Migration from WSL to Ubuntu

If you're moving from WSL to Ubuntu:

  1. Old WSL setup (might have issues):

    # WSL was more permissive
pip install package  # worked globally

  2. New Ubuntu setup (properly isolated):

    # Ubuntu requires proper virtual environment
python3 -m venv pywallet_build_env --clear
source pywallet_build_env/bin/activate
pip install package  # works in venv

✅ This version handles both environments seamlessly!

📊 Environment Test Results

Environment Status Notes
WSL Ubuntu ✅ Working Backward compatible
Ubuntu 22.04 ✅ Working Tested
Ubuntu 24.04 ✅ Working Optimized
Debian 12 ✅ Working Compatible
Linux Mint ✅ Working Ubuntu-based

🎯 Bottom Line

One command. All wallet types. Smart detection. Automatic fallback. Rock-solid stability. Perfect Ubuntu compatibility.

That's the power of smart pywallet - eliminating complexity while maximizing results, now with enterprise-grade reliability for corrupted wallet recovery and seamless Ubuntu 24.04 support.