# Professional Cryptocurrency Wallet

A production-ready, multi-chain cryptocurrency wallet built in Python with advanced security features, similar to Rabby Wallet. This wallet supports BIP39 seed phrases, multiple EVM networks, transaction simulation, and comprehensive security assessments.

![Wallet Screenshot](docs/images/wallet-main.png)

## 🚀 Features

### Core Functionality
- **BIP39 Seed Phrase Support**: Generate and import wallets using standard BIP39 mnemonic phrases
- **Multi-Chain Support**: Support for 15+ EVM networks including Ethereum, BSC, Polygon, Arbitrum, and more
- **HD Wallet Derivation**: Standard Ethereum derivation path (m/44'/60'/0'/0) with multiple account generation
- **Secure Storage**: Encrypted local storage with password protection
- **Transaction Management**: Send, receive, and track transactions across all supported networks

### Security Features (Rabby-like)
- **Transaction Simulation**: Preview transaction outcomes before signing
- **Risk Assessment**: Comprehensive security analysis for all transactions
- **Balance Change Preview**: See exactly what assets will be affected
- **Contract Verification**: Identify and warn about unverified contracts
- **Scam Detection**: Built-in database of known scam addresses and phishing sites
- **Approval Management**: Track and revoke token approvals
- **Whitelist/Blacklist**: Manage trusted and blocked addresses

### User Interface
- **Modern Dark Theme**: Professional, eye-friendly interface
- **Responsive Design**: Clean and intuitive user experience
- **Real-time Updates**: Live balance and transaction status updates
- **QR Code Generation**: Generate QR codes for addresses and payment requests
- **Multi-language Support**: Expandable localization system

### Advanced Features
- **Custom Networks**: Add and manage custom EVM networks
- **Gas Optimization**: Smart gas price estimation and optimization
- **Transaction History**: Complete transaction tracking with export capabilities
- **Backup & Restore**: Secure wallet backup and restoration
- **Hardware Wallet Support**: (Planned) Integration with hardware wallets

## 📋 Requirements

### System Requirements
- **Python**: 3.8 or higher
- **Operating System**: Windows, macOS, or Linux
- **RAM**: Minimum 512MB available
- **Storage**: 100MB free space
- **Internet**: Required for blockchain connectivity

### Python Dependencies
See [requirements.txt](requirements.txt) for complete list. Key dependencies:
- `web3` - Ethereum blockchain interaction
- `cryptography` - Encryption and security
- `tkinter` - GUI framework (built into Python)
- `qrcode` - QR code generation
- `Pillow` - Image processing

## 🛠️ Installation

### Option 1: Quick Start (Recommended)

```bash
# Clone the repository
git clone https://github.com/yourusername/crypto-wallet.git
cd crypto-wallet

# Create virtual environment
python -m venv wallet_env

# Activate virtual environment
# On Windows:
wallet_env\Scripts\activate
# On macOS/Linux:
source wallet_env/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the wallet
python crypto_wallet.py
```

### Option 2: Manual Installation

```bash
# Install core dependencies manually
pip install web3 eth-account cryptography ecdsa mnemonic requests qrcode[pil] Pillow

# Clone and run
git clone https://github.com/yourusername/crypto-wallet.git
cd crypto-wallet
python crypto_wallet.py
```

### Option 3: Development Setup

```bash
# For developers who want to contribute
git clone https://github.com/yourusername/crypto-wallet.git
cd crypto-wallet

# Create development environment
python -m venv dev_env
source dev_env/bin/activate  # or dev_env\Scripts\activate on Windows

# Install with development dependencies
pip install -r requirements.txt
pip install pytest black flake8

# Run tests
pytest tests/

# Format code
black .

# Lint code
flake8 .
```

## 🎯 Quick Start Guide

### Creating Your First Wallet

1. **Launch the Application**
   ```bash
   python crypto_wallet.py
   ```

2. **Create New Wallet**
   - Click "Create New Wallet" on the welcome screen
   - Choose a strong password (minimum 12 characters)
   - **IMPORTANT**: Write down your seed phrase and store it securely
   - Verify your seed phrase
   - Your wallet is ready!

3. **Import Existing Wallet**
   - Click "Import Wallet"
   - Enter your BIP39 seed phrase
   - Set a password for local encryption
   - Choose the number of accounts to import

### Basic Operations

#### Receiving Funds
1. Go to the "Receive" tab
2. Your address is displayed with a QR code
3. Share your address or QR code with the sender
4. Funds will appear in your balance once confirmed

#### Sending Funds
1. Go to the "Send" tab
2. Enter recipient address
3. Enter amount and select currency
4. Review gas settings
5. Click "Preview Transaction" to see details
6. Confirm and send

#### Managing Accounts
1. Go to the "Accounts" tab
2. View all your accounts and balances
3. Create new accounts with "Create Account"
4. Import accounts with private keys
5. Export account details as needed

## 🔧 Configuration

### Supported Networks

The wallet supports the following networks out of the box:

| Network | Chain ID | Symbol | Type |
|---------|----------|--------|------|
| Ethereum Mainnet | 1 | ETH | Mainnet |
| Binance Smart Chain | 56 | BNB | Mainnet |
| Polygon | 137 | POL | Mainnet |
| Arbitrum One | 42161 | ETH | L2 |
| Optimism | 10 | ETH | L2 |
| Avalanche C-Chain | 43114 | AVAX | Mainnet |
| Fantom Opera | 250 | FTM | Mainnet |
| Base | 8453 | ETH | L2 |
| Cronos | 25 | CRO | Mainnet |
| Celo | 42220 | CELO | Mainnet |

### Adding Custom Networks

1. Go to Settings → Network Settings
2. Click "Add Custom Network"
3. Fill in network details:
   - Network Name
   - Chain ID
   - Currency Symbol
   - RPC URLs
   - Block Explorer URL
4. Save and switch to your custom network

### Security Settings

#### Whitelist Management
- Add trusted addresses to whitelist
- Whitelisted addresses get reduced security warnings
- Manage in Settings → Security → Whitelist

#### Blacklist Management
- Block suspicious addresses
- Blacklisted addresses trigger security alerts
- Manage in Settings → Security → Blacklist

## 🏗️ Architecture

### Module Overview

```
crypto-wallet/
├── crypto_wallet.py          # Main application entry point
├── wallet_core.py             # BIP39 and key management
├── network_manager.py         # Multi-chain network handling
├── transaction_manager.py     # Transaction processing
├── security_manager.py        # Security and risk assessment
├── storage_manager.py         # Encrypted data storage
├── ui_components.py           # Modern UI components
├── qr_generator.py            # QR code generation
├── requirements.txt           # Python dependencies
└── README.md                  # This file
```

### Core Components

#### 1. Wallet Core (`wallet_core.py`)
- **BIP39 Implementation**: Full BIP39 mnemonic generation and validation
- **HD Wallet Derivation**: BIP32/BIP44 key derivation
- **Key Management**: Secure private key handling
- **Address Generation**: Ethereum address generation from private keys

#### 2. Network Manager (`network_manager.py`)
- **Multi-Chain Support**: 15+ pre-configured EVM networks
- **Custom Networks**: Add and manage custom networks
- **RPC Management**: Automatic RPC endpoint testing and failover
- **Network Switching**: Seamless network switching

#### 3. Transaction Manager (`transaction_manager.py`)
- **Transaction Building**: Construct and sign transactions
- **Gas Estimation**: Smart gas price calculation
- **Transaction Tracking**: Monitor transaction status
- **History Management**: Complete transaction history

#### 4. Security Manager (`security_manager.py`)
- **Risk Assessment**: Comprehensive transaction security analysis
- **Scam Detection**: Known scam address database
- **Contract Verification**: Smart contract safety checks
- **Approval Tracking**: Token approval management

#### 5. Storage Manager (`storage_manager.py`)
- **Encrypted Storage**: AES encryption for sensitive data
- **SQLite Database**: Local data persistence
- **Backup System**: Secure wallet backup and restore
- **Data Migration**: Version compatibility

#### 6. UI Components (`ui_components.py`)
- **Modern Theme**: Dark theme with accent colors
- **Responsive Layout**: Adaptive interface design
- **Custom Widgets**: Specialized crypto wallet UI elements
- **Accessibility**: Screen reader and keyboard navigation support

#### 7. QR Generator (`qr_generator.py`)
- **Address QR Codes**: Generate QR codes for wallet addresses
- **Payment Requests**: QR codes with amount and memo
- **Styling Options**: Multiple color schemes and logos
- **Export Options**: Save as PNG or convert to base64

## 🔐 Security

### Security Features

#### 1. Encryption
- **Local Storage**: All sensitive data encrypted with AES-256
- **Password-Based Encryption**: User password derives encryption keys
- **Salt Generation**: Unique salt for each wallet
- **Key Derivation**: PBKDF2 with 100,000 iterations

#### 2. Transaction Security
- **Simulation Before Signing**: Preview transaction outcomes
- **Risk Scoring**: 0-100 risk score for all transactions
- **Known Scam Detection**: Database of malicious addresses
- **Contract Analysis**: Verify contract safety before interaction

#### 3. Network Security
- **RPC Validation**: Verify RPC responses and chain IDs
- **HTTPS Only**: All network requests use HTTPS
- **Timeout Protection**: Network request timeouts
- **Error Handling**: Graceful handling of network errors

### Security Best Practices

#### For Users
1. **Strong Passwords**: Use passwords with 12+ characters
2. **Seed Phrase Security**: Store seed phrases offline and securely
3. **Regular Backups**: Backup wallet data regularly
4. **Network Verification**: Verify network details before adding custom networks
5. **Transaction Review**: Always review transaction details before signing

#### For Developers
1. **Code Review**: All code should be reviewed before deployment
2. **Dependency Updates**: Keep dependencies updated for security patches
3. **Input Validation**: Validate all user inputs
4. **Error Handling**: Proper error handling to prevent information leakage
5. **Testing**: Comprehensive testing including security testing

## 🧪 Testing

### Running Tests

```bash
# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test module
pytest tests/test_wallet_core.py

# Run with verbose output
pytest -v
```

### Test Coverage

The test suite covers:
- BIP39 mnemonic generation and validation
- Key derivation and address generation
- Transaction building and signing
- Network connectivity and switching
- Security risk assessment
- Storage encryption and decryption

### Manual Testing

1. **Wallet Creation**: Test wallet creation with various seed phrase lengths
2. **Account Management**: Create, import, and export accounts
3. **Network Switching**: Switch between different networks
4. **Transaction Flow**: Send and receive transactions
5. **Security Features**: Test risk assessment and warnings
6. **Backup/Restore**: Test wallet backup and restoration

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Workflow

1. **Fork the Repository**
2. **Create Feature Branch**: `git checkout -b feature/amazing-feature`
3. **Make Changes**: Implement your feature
4. **Add Tests**: Write tests for new functionality
5. **Run Tests**: Ensure all tests pass
6. **Format Code**: Run `black .` to format code
7. **Commit Changes**: `git commit -m 'Add amazing feature'`
8. **Push to Branch**: `git push origin feature/amazing-feature`
9. **Open Pull Request**: Create a PR with detailed description

### Code Standards

- **Python Style**: Follow PEP 8 with Black formatting
- **Documentation**: Document all public functions and classes
- **Type Hints**: Use type hints for better code clarity
- **Error Handling**: Proper exception handling
- **Security**: Follow security best practices

## 📚 API Reference

### WalletCore

```python
from wallet_core import WalletCore

# Initialize wallet core
wallet = WalletCore()

# Generate new mnemonic
mnemonic = wallet.generate_mnemonic(strength=128)

# Create accounts from mnemonic
accounts = wallet.create_wallet_from_mnemonic(
    mnemonic=mnemonic,
    passphrase="",
    account_count=5
)

# Validate mnemonic
is_valid = wallet.validate_mnemonic(mnemonic)
```

### NetworkManager

```python
from network_manager import NetworkManager

# Initialize network manager
networks = NetworkManager()

# Get available networks
all_networks = networks.get_networks()

# Switch network
success = networks.switch_network("Ethereum Mainnet")

# Add custom network
custom_network = NetworkConfig(
    name="Custom Network",
    chain_id=31337,
    symbol="ETH",
    decimals=18,
    rpc_urls=["http://localhost:8545"],
    block_explorer_url="http://localhost:4000"
)
networks.add_custom_network(custom_network)
```

### TransactionManager

```python
from transaction_manager import TransactionManager

# Initialize transaction manager
tx_manager = TransactionManager()

# Get balance
balance = tx_manager.get_balance(
    address="0x742d35Cc6639C0532fA5B3De4839C4C6cCE3c03D",
    network_config=network_config
)

# Build transaction
tx_data = tx_manager.build_transaction(
    from_address="0x...",
    to_address="0x...",
    amount="0.1",
    network_config=network_config,
    gas_settings=gas_settings
)
```

## 🐛 Troubleshooting

### Common Issues

#### Installation Issues

**Problem**: `pip install` fails with permission errors
**Solution**: Use virtual environment or `pip install --user`

**Problem**: Missing system dependencies
**Solution**: Install system packages:
```bash
# Ubuntu/Debian
sudo apt-get install python3-tk python3-dev

# macOS
brew install python-tk

# Windows: Usually included with Python
```

#### Runtime Issues

**Problem**: "Web3 connection failed"
**Solution**: 
1. Check internet connection
2. Try different RPC endpoint
3. Verify network configuration

**Problem**: "Failed to decrypt wallet"
**Solution**: 
1. Verify password is correct
2. Check if wallet file is corrupted
3. Restore from backup if available

**Problem**: Transaction fails with "insufficient gas"
**Solution**: 
1. Increase gas limit
2. Check account balance
3. Verify network is not congested

#### Performance Issues

**Problem**: Slow startup or UI lag
**Solution**: 
1. Close other applications
2. Restart the wallet
3. Check available system memory

### Getting Help

1. **Check Issues**: Look at [GitHub Issues](https://github.com/yourusername/crypto-wallet/issues)
2. **Documentation**: Read the full documentation
3. **Community**: Join our Discord/Telegram community
4. **Support**: Contact support@cryptowallet.com

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

**IMPORTANT SECURITY NOTICE**

This software is provided for educational and development purposes. While we have implemented security best practices, you should:

1. **Audit the Code**: Review all code before using with real funds
2. **Test Thoroughly**: Test with small amounts first
3. **Backup Everything**: Keep secure backups of your seed phrases
4. **Use at Your Own Risk**: The developers are not responsible for any loss of funds

**Never share your seed phrase or private keys with anyone.**

## 🙏 Acknowledgments

- **Rabby Wallet**: Inspiration for security features and user experience
- **MetaMask**: Reference for wallet functionality
- **BIP39 Standard**: For mnemonic phrase implementation
- **Ethereum Foundation**: For EVM standards and documentation
- **Python Community**: For excellent libraries and tools

## 📈 Roadmap

### Version 1.1 (Next Release)
- [ ] Hardware wallet integration (Ledger, Trezor)
- [ ] Enhanced transaction simulation
- [ ] Multi-signature wallet support
- [ ] Advanced gas optimization

### Version 1.2 (Future)
- [ ] DeFi protocol integration
- [ ] NFT support and management
- [ ] Staking functionality
- [ ] Cross-chain bridge integration

### Version 2.0 (Long-term)
- [ ] Mobile app versions
- [ ] Web-based interface
- [ ] Advanced trading features
- [ ] Portfolio analytics

---

**Made with ❤️ for the crypto community**

For questions, suggestions, or contributions, please visit our [GitHub repository](https://github.com/yourusername/crypto-wallet) or contact us at support@cryptowallet.com.