pyhdwallet – Secure HD Wallet Tool

A Python command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. Includes BIP85 deterministic child mnemonic derivation for creating multiple isolated wallets from a single master seed. Designed for offline operation with optional PGP encryption and AES-encrypted ZIP artifacts.

---

📦 Installation

Quick Start (macOS/Linux with Internet)

# Clone repository
git clone https://github.com/<your-username>/hdwalletpy.git
cd hdwalletpy

# Install using automated script
./install_offline.sh

The script automatically:

• Creates Python 3.12 virtual environment
• Installs from vendored wheels (offline-capable)
• Verifies installation with test suite
• Leaves you in activated venv

---

Air-Gapped Installation (No Internet)

This repository includes pre-built Python wheels for offline use.

Supported platforms:

• macOS ARM64 (M1/M2/M3/M4) - Python 3.12
• Linux x86_64 (Ubuntu/Tails) - Python 3.12

Steps:

1. On an online machine, clone and verify:

   git clone https://github.com/<your-username>/hdwalletpy.git
   cd hdwalletpy
   
   # Verify checksums
   cd vendor/linux-x86_64  # or macos-arm64
   sha256sum -c SHA256SUMS  # Linux
   shasum -a 256 -c SHA256SUMS  # macOS
   

2. Transfer entire repo to USB drive

3. On air-gapped machine:

   cd hdwalletpy
   ./install_offline.sh
   

4. Generate wallet:

   python src/pyhdwallet.py gen --off-screen --file
   

---

Developer Installation (with Docker)

For development or building wheels for other platforms:

# Build Docker image
make build-image

# Build wheels for all platforms
make vendor-all

# Install development environment
make install

# 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 --off-screen --file

# Generate with PGP encryption + ZIP
python src/pyhdwallet.py gen \
  --pgp-pubkey-file pubkeys/mykey.asc \
  --expected-fingerprint A27B96F2B169B5491013D2DA892B822C14A9AA18 \
  --off-screen \
  --file

# Derive BIP85 child mnemonic (12/15/18/21/24 words)
python src/pyhdwallet.py gen-child \
  --interactive \
  --words 12 \
  --index 0

# Derive BIP85 child with passphrase + encrypted output
python src/pyhdwallet.py gen-child \
  --mnemonic-stdin \
  --passphrase \
  --words 24 \
  --index 0 \
  --pgp-pubkey-file pubkeys/mykey.asc \
  --off-screen \
  --file

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

# Fetch PGP public key (requires internet)
python src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc

# Run tests
python src/pyhdwallet.py test
pytest -v tests/test_vectors.py

---

🔐 Security Features

• Offline-first: Network access blocked during key generation/recovery
• BIP85 deterministic entropy: Derive unlimited child mnemonics from master seed
• Test suite: Regression tests with frozen vectors ensure derivation logic integrity
• PGP fingerprint pinning: Prevents key substitution attacks
• TTY safety guard: Refuses to print secrets when stdout is piped/redirected
• AES-encrypted outputs: Wallet artifacts encrypted with pyzipper
• No shell history leaks: Use --interactive or --mnemonic-stdin for recovery
• Interoperable: BIP85 children compatible with Coldcard, Ian Coleman tool, etc.

---

🛠️ Makefile Targets

Vendoring (for air-gapped deployment):

make vendor-macos    # Build macOS ARM64 wheels
make vendor-linux    # Build Linux x86_64 wheels (Docker)
make vendor-all      # Build for both platforms
make verify-vendor   # Test offline installation

Development:

make install         # Create venv and install dependencies
make test            # Run test suite
make build-image     # Build Docker image
make shell           # Open shell in Docker container
make clean           # Remove venvs and build artifacts

---

📖 Full Documentation

• playbook.md - Complete command reference and operational guide
• tests/ - Regression test suite documentation

---

🔒 Recommended Air-Gapped Setup

For maximum security when generating production wallets:

1. Use fresh Ubuntu Live USB or Tails OS
2. Never connect to network after booting
3. Transfer this repository via separate USB
4. Run ./install_offline.sh
5. Generate wallet: python src/pyhdwallet.py gen --off-screen --file
6. Write mnemonic to paper/metal backup
7. Transfer encrypted ZIP to secure storage
8. Wipe USB drives securely

See playbook.md for detailed air-gapped procedures.

🖥️ Platform Compatibility

Makefile Targets

Target	macOS	Linux	Notes
make install	✅	✅	Create venv + install deps
make test	✅	✅	Run test suite
make vendor-macos	✅	❌	Requires native macOS ARM64
make vendor-linux	✅	✅	Uses Docker (any OS)
make vendor-all	✅	⚠️	Needs macOS for both platforms
make binary	✅	❌	Requires build_binary.sh
make binary-linux	✅	✅	Uses Docker (any OS)
make build-image	✅	✅	Docker required

Quick Commands by Platform

macOS:

make info                # Show platform info
make vendor-current      # Build for current platform only
make binary-current      # Build binary for current platform

Linux:*

make info                # Show platform info
make vendor-linux        # Build Linux wheels
make binary-linux        # Build Linux binary

Cross-platform (requires Docker):

make vendor-linux        # Works on any OS with Docker
make binary-linux        # Works on any OS with Docker

Quick Test

# Check platform detection
make info

# Build for your current platform
make vendor-current

# Or just the targets you need
make install  # Works everywhere
make test     # Works everywhere

📦 Binary Distribution

Pre-built standalone binaries are available for convenience (no Python required):

Download Binary

# macOS ARM64
curl -LO https://github.com/user/hdwalletpy/releases/download/v1.1.0/pyhdwallet-macos-arm64
chmod +x pyhdwallet-macos-arm64
./pyhdwallet-macos-arm64 test

# Linux x86_64
curl -LO https://github.com/user/hdwalletpy/releases/download/v1.1.0/pyhdwallet-linux
chmod +x pyhdwallet-linux
./pyhdwallet-linux test

---

🆕 What's New in v1.1.0

• BIP85 child mnemonic derivation via new gen-child command
• Derive 12/15/18/21/24-word child mnemonics from master seed
• Full interoperability with BIP85-compatible wallets (Coldcard, etc.)
• Optional master BIP39 passphrase support
• Verified against official BIP85 test vectors
• No new dependencies required (uses existing bip-utils + stdlib)

---