A Python tool for offline derivation of Bitcoin SV (BSV) wallet keys from either seed phrases (mnemonics) or master private keys (xprv). This tool supports both BIP39 and Electrum-style mnemonic formats and is designed for secure, offline key generation and management.

🚨 SECURITY WARNING:

• This tool is provided "AS IS" without any warranty
• We take NO RESPONSIBILITY for any loss of funds, damages, or issues arising from the use of this software
• Use at your own risk and always test with small amounts first
• Keep your seed phrases and private keys secure and never share them

🚨 EXAMPLE FILES WARNING:

• NEVER USE the example mnemonic or xprv provided in example_mnemonic.txt and example_xprv.txt
• These are PUBLIC examples and using them WILL result in loss of funds
• Always generate your own secure, random mnemonics for real use

• ✅ Dual Format Support: Works with both BIP39 and Electrum-style mnemonics
• ✅ Offline Operation: Completely offline key derivation for enhanced security
• ✅ Multiple Input Methods: Load from mnemonic seed phrase or master private key (xprv)
• ✅ Flexible Key Derivation: Support for custom BIP32 derivation paths
• ✅ Batch Generation: Generate multiple keys in ranges
• ✅ Multiple Export Formats: JSON, Simple CSV, and Detailed CSV export options
• ✅ 🔐 AES-256 Encryption: Password-protected encrypted export with PBKDF2 key derivation
• ✅ 🔓 File Decryption: Decrypt previously encrypted key files
• ✅ ElectrumSV Compatible: Compatible with ElectrumSV wallet format
• ✅ Interactive CLI: User-friendly command-line interface
• ✅ Professional Package Structure: Well-organized modular codebase
• ✅ Comprehensive Testing: 85+ unit tests with high code coverage
• ✅ Professional Development Setup: Complete linting, formatting, and testing workflow
• ✅ Console Command: Easy-to-use xprv-gen command after installation

xprv-gen/
├── xprv_gen/              # Main package
│   ├── __init__.py        # Package exports
│   ├── constants.py       # Constants and enums
│   ├── exceptions.py      # Custom exceptions
│   ├── wallet.py          # Core wallet functionality
│   ├── ui.py              # User interface components
│   └── cli.py             # CLI application logic
├── tests/                 # Test suite (85+ tests)
│   ├── test_constants.py  # Constants and enum tests
│   ├── test_wallet.py     # Wallet functionality tests
│   ├── test_ui.py         # UI component tests
│   └── test_cli.py        # CLI application tests
├── requirements.txt       # Runtime dependencies
├── requirements-dev.txt   # Development dependencies
├── pytest.ini            # Test configuration
├── pyproject.toml         # Tool configurations
├── Makefile               # Development automation
└── README.md              # This file

git clone <repository-url>
cd xprv-gen
make install

1. Clone the repository:

git clone <repository-url>
cd xprv-gen

2. Create virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # For development

3. Install the package in development mode:

pip install -e .

After installation, you can use the xprv-gen command directly:

# Interactive mode
xprv-gen

# Test mode with example data
xprv-gen --test

# Install dependencies and package
make install

# Run the CLI application
make run-cli

# Run comprehensive test suite
make test

# Run tests with coverage report
make coverage

# Format code (black + isort)
make format

# Run all linters (flake8, pylint, mypy)
make lint

# Clean up cache files
make clean

# View all available commands
make help

# Interactive mode
python -m xprv_gen.cli

# Test mode
python -m xprv_gen.cli --test

1. Load wallet from mnemonic seed phrase

   • Supports both BIP39 and Electrum-style mnemonics
   • Automatically detects the format
   • Enhanced validation with detailed error messages

2. Load wallet from master private key (xprv)

   • Import from extended private key string
   • Enhanced validation for proper xprv format

3. Generate new wallet

   • Create a new random wallet with optional entropy

4. Show master xpub

   • Display the master extended public key

5. Derive single key from path

   • Generate a specific key using BIP32 derivation path
   • Example: m/0/1234

6. Derive key range

   • Generate multiple keys in a range
   • Example: m/44'/0'/0' indices 0-10

7. Export keys 🆕

   • Export derived keys in multiple formats
   • Simple CSV: Basic address and key pairs
   • Detailed CSV: Includes derivation paths
   • JSON: Structured format with metadata
   • 🔐 Encrypted Export: Password-protected files

8. Decrypt file 🆕

   • Decrypt previously encrypted key files
   • Supports all encrypted formats
   • Secure password verification

• AES-256 Encryption: Industry-standard encryption algorithm
• PBKDF2 Key Derivation: 2048 iterations for password-based key derivation
• Password Protection: Double-entry password confirmation
• Multiple Formats: Encrypt JSON, Simple CSV, or Detailed CSV
• Secure File Extension: .enc extension for encrypted files

• Password-based Decryption: Secure password verification
• Format Preservation: Maintains original export format
• Error Handling: Clear feedback for invalid passwords or corrupted files
• Flexible Output: Custom output filenames supported

1. Derive keys (options 5 or 6)
2. Choose Export Keys (option 7)
3. Select Encrypted Export (option 4)
4. Choose format (JSON, Simple CSV, or Detailed CSV)
5. Enter secure password (hidden input)
6. Confirm password
7. Keys saved as password-protected .enc file

The project includes a comprehensive test suite with 85+ unit tests:

• test_constants.py: Tests for constants and enums
• test_wallet.py: Core wallet functionality tests with mocking
• test_ui.py: User interface component tests
• test_cli.py: CLI application logic tests

# Run all tests
make test

# Run tests with coverage report
make coverage

# Run tests with detailed output
pytest -v

# Run specific test file
pytest tests/test_wallet.py

# Run tests with coverage and HTML report
pytest --cov=xprv_gen --cov-report=html

• Total Tests: 85+ comprehensive unit tests
• Mocking: Extensive use of pytest mocks for external dependencies
• Test Types: Unit tests, validation tests, error handling tests
• Coverage: High code coverage with professional testing standards

This project includes a complete professional development environment:

Configuration Files:

• pytest.ini - Test configuration and coverage settings
• pyproject.toml - Black, isort, and mypy configuration
• Makefile - Development automation
• requirements-dev.txt - Development dependencies

Code Quality Tools:

• Black: Code formatting
• isort: Import sorting
• flake8: Style guide enforcement
• pylint: Code quality analysis
• mypy: Static type checking
• pytest: Testing framework with coverage

1. Setup: make install
2. Development: Edit code
3. Format: make format
4. Lint: make lint
5. Test: make test
6. Coverage: make coverage

• Pylint Score: 10.00/10 (perfect)
• Line Length: ≤88 characters
• Type Hints: Full coverage with strict mypy
• Documentation: Comprehensive docstrings
• Testing: Comprehensive unit test coverage

• Standard 12-24 word seed phrases
• Includes built-in checksum validation
• Compatible with most hardware wallets

• Electrum's proprietary format
• Uses HMAC-SHA512 validation with "Seed version" key
• Compatible with ElectrumSV wallet

• Uses BIP32 hierarchical deterministic (HD) key derivation
• Supports both hardened and non-hardened derivation
• Compatible with standard derivation paths like m/44'/0'/0'

• BIP39: Uses PBKDF2 with "mnemonic" salt
• Electrum: Uses PBKDF2 with "electrum" salt
• Both use 2048 iterations for key stretching

• Algorithm: AES-256 in CBC mode
• Key Derivation: PBKDF2 with 2048 iterations
• Salt: Cryptographically secure random salt
• Padding: PKCS7 padding for block cipher
• Encoding: Base64 encoding for encrypted output

• Modular Design: Separated concerns into focused modules
• Single Responsibility: Each module has a clear purpose
• Exception Handling: Comprehensive custom exception hierarchy
• Type Safety: Comprehensive type hints and mypy validation
• Error Handling: Robust error handling with detailed messages
• Testing: Extensive test coverage with mocking

1. Offline Usage: Run this tool on an air-gapped computer
2. Secure Storage: Store seed phrases in secure, offline locations
3. Strong Passwords: Use strong, unique passwords for encrypted exports
4. Test First: Always test with small amounts before trusting large sums
5. Multiple Backups: Keep multiple secure backups of your seed phrases
6. Never Share: Never share your seed phrases or private keys
7. Verify Integrity: Always verify the integrity of encrypted files

Testing mnemonic: abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
Expected xprv: xprv9s21ZrQH143K...
✓ Valid BIP39 mnemonic
✓ Successfully loaded wallet from mnemonic
✓ Master xprv: xprv9s21ZrQH143K...
Match: True

=== Test Results ===
✓ All tests passed successfully!

• Python 3.13+ (tested)
• bsv-sdk>=1.0.0
• mnemonic>=0.19
• cryptography>=41.0.0 (for encryption features)

• pytest>=7.0.0 (testing framework)
• pytest-cov>=4.0.0 (coverage reporting)
• pytest-mock>=3.10.0 (mocking support)
• black>=23.0.0 (code formatting)
• isort>=5.12.0 (import sorting)
• flake8>=6.0.0 (style checking)
• pylint>=2.17.0 (code quality)
• mypy>=1.5.0 (type checking)

This project is licensed under the MIT License - see the LICENSE file for details.

Contributions are welcome! Please follow the development workflow:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run make format and make lint
5. Ensure all tests pass with make test
6. Maintain test coverage with make coverage
7. Submit a Pull Request

For issues and questions, please open an issue on the GitHub repository.

Remember: This tool handles sensitive cryptographic material. Always verify the integrity of the code and use it responsibly!