pyhdwallet – Secure HD Wallet Tool

Deterministic BIP32/BIP39/BIP44 HD wallet generator for Bitcoin, Ethereum, and other cryptocurrencies. Designed for air-gapped, offline use with multi-platform support.

📦 Installation

Quick Start (macOS/Linux with Internet)

# Clone repository
git clone https://github.com/yourusername/hdwalletpy.git
cd hdwalletpy

# Install using automated script
./install_offline.sh

Air-Gapped Installation (No Internet)

The project includes pre-built vendored wheels for offline installation on:

• macOS ARM64 (Apple Silicon)
• Linux x86_64 (Intel/AMD servers)
• Linux aarch64 (ARM64 servers, Raspberry Pi, Mac containers)

Steps:

1. On internet-connected machine:

   git clone https://github.com/yourusername/hdwalletpy.git
   cd hdwalletpy
   
   # Verify vendor checksums
   cd vendor/macos-arm64 && shasum -a 256 -c SHA256SUMS      # macOS
   cd vendor/linux-x86_64 && sha256sum -c SHA256SUMS         # Linux x86
   cd vendor/linux-aarch64 && sha256sum -c SHA256SUMS        # Linux ARM
   

2. Transfer to USB/CD:

   # Copy entire repository to USB drive
   cp -r hdwalletpy /Volumes/USB/
   

3. On air-gapped machine:

   cd /path/to/hdwalletpy
   
   # Ensure Python 3.12 is installed
   python3.12 --version
   
   # Run offline installer (auto-detects platform)
   ./install_offline.sh
   
   # Activate virtual environment
   source .venv/bin/activate
   
   # Generate wallet
   python src/pyhdwallet.py gen --help
   

Developer Installation (with Docker)

Build wheels and run tests across all platforms:

# Build Docker image
make build-image

# Build vendor wheels for all platforms
make vendor-all          # Runtime wheels only
make vendor-all-dev      # Runtime + dev wheels (pytest)

# Install development environment
make install-dev-offline

# Run tests
make test

✅ Basic Usage

# Generate wallet (prints mnemonic - debug mode)
python src/pyhdwallet.py gen

# Generate with off-screen mode + encrypted ZIP
python src/pyhdwallet.py gen --file --zip

# Generate with PGP encryption + ZIP
python src/pyhdwallet.py gen --file --zip --pgp recipient@example.com

# Recover wallet from mnemonic
python src/pyhdwallet.py recover

# Fetch PGP public key (requires internet)
python src/pyhdwallet.py fetchkey keyserver.ubuntu.com recipient@example.com

# Run tests
python src/pyhdwallet.py test

🔐 Security Features

• ✅ BIP39 24-word mnemonic generation
• ✅ BIP32 hierarchical deterministic wallet derivation
• ✅ BIP44 multi-currency account structure
• ✅ Air-gapped operation with vendored dependencies
• ✅ AES-256 encrypted ZIP artifacts with password protection
• ✅ PGP encryption support for at-rest storage
• ✅ Deterministic output for reproducible wallet generation
• ✅ Multi-platform offline support (macOS, Linux x86/ARM)
• ✅ Checksum verification for vendored wheels

🛠️ Makefile Targets

Vendoring (Air-Gapped Deployment)

make vendor-macos         # Build macOS ARM64 wheels
make vendor-macos-dev     # Build macOS dev wheels (pytest)
make vendor-linux         # Build Linux x86_64 wheels (Docker)
make vendor-linux-dev     # Build Linux x86_64 dev wheels
make vendor-linux-arm     # Build Linux ARM64 wheels (Docker)
make vendor-linux-arm-dev # Build Linux ARM64 dev wheels
make vendor-all           # Build runtime wheels for ALL platforms
make vendor-all-dev       # Build dev wheels for ALL platforms
make verify-vendor        # Test offline installation

Binary Distribution

make binary               # Build standalone binary for current platform
make binary-linux         # Build Linux binary via Docker
make binary-all           # Build binaries for all platforms

Development Workflow

make install              # Create venv and install dependencies
make install-offline      # Install from vendor/ (offline)
make install-dev-offline  # Install dev dependencies (offline)
make test                 # Run test suite
make clean                # Remove venv, cache, vendor/
make clean-vendor         # Remove vendor/ only

Release Management

make release              # Build complete release package
make release-test         # Test release binaries
make clean-release        # Remove release artifacts

📖 Full Documentation

See playbook.md for:

• Detailed air-gapped security setup
• Multi-platform installation guide
• PGP key management
• Operational security checklist
• Troubleshooting guide
• Testing and development workflows

🔒 Recommended Air-Gapped Setup

1. Build/verify on trusted internet machine
2. Transfer via USB/CD to air-gapped machine
3. Verify checksums before installation
4. Generate wallet offline with PGP encryption
5. Store encrypted artifacts on separate media
6. Test recovery process before real use

Threat model: Protects against network-based attacks, remote exploitation, and keyloggers. Physical security and operational discipline required.

📝 License

MIT License - See LICENSE for details.

🙏 Credits

Built with:

• bip-utils - BIP32/39/44 implementation
• PyInstaller - Binary packaging
• Python 3.12 and cryptography libraries