hdwalletpy – Setup & Usage Guide

This project provides a Python-based HD Wallet tool with optional Docker-based build automation for fast, reproducible environments.

---

📦 Installation Options

Option 1: Standard Python Setup (Host Machine)

1. Clone the repository:

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

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt
   

---

Option 2: Fast Setup Using Docker + Makefile

This method avoids installing compilers on your host and speeds up dependency builds.

Step 1: Build Docker Image

make build-image

Creates a reusable image python-build-env:3.11 with build tools and python3-venv.

Step 2: Compile Wheels in Container

make wheels

Builds all dependency wheels into ./wheelhouse for fast installs.

Step 3: Create Host Virtual Environment

make venv-host
source .venv_host/bin/activate

Installs dependencies from wheelhouse (no compilation needed).

Optional: Work Inside a Warm Container

make up             # Start container
make shell          # Open shell inside container
make venv-container # Create container-only venv at /opt/venv

Cleanup

make clean # Remove host venv and wheelhouse
make down  # Stop/remove container

---

✅ Basic Usage

Run the tool with subcommands. For help, use -h (e.g., gen -h, recover -h).

Examples:

# Generate mnemonic (prints to stdout; for debug/test)
python ./src/pyhdwallet.py gen

# Generate and save AES-encrypted ZIP artifact into ./.wallet (password prompted)
python ./src/pyhdwallet.py gen --file

# Generate with PGP encryption + ZIP artifact (ZIP contains only encrypted .asc payload)
python ./src/pyhdwallet.py gen --pgp-pubkey-file pubkeys/mykey.asc --file

# Recover from mnemonic (prefer --interactive to avoid shell history)
python ./src/pyhdwallet.py recover --interactive

# Recover and save AES ZIP artifact
python ./src/pyhdwallet.py recover --interactive --file

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

# Run tests
python ./src/pyhdwallet.py test

---

🔐 Notes on --file, AES ZIP, and PGP

• --file writes only an AES-encrypted ZIP (no raw .json/.asc left on disk), using pyzipper.
• If --pgp-pubkey-file is set, the ZIP contains a single ASCII-armored PGP message (.asc) created with PGPy-style PGPMessage.new(...) then pubkey.encrypt(...).

---

⚠️ About --force

The tool includes a safety guard: if stdout is piped/redirected (non-TTY), it refuses to print sensitive output unless --force is set. Checking whether stdout is a terminal is commonly done via isatty().

Example:

python ./src/pyhdwallet.py gen > out.txt          # likely refused (non-TTY)
python ./src/pyhdwallet.py gen --force > out.txt # allowed

---

✅ Why Use Makefile?

• Speed: Avoid repeated apt-get installs; wheels cached locally.
• Reproducibility: Same Docker image for builds; no environment drift.
• Convenience: One-liner tasks (make wheels, make venv-host, make shell).
• Separation: Host venv vs container venv for clean workflows.

---

Common Makefile Targets

make build-image      # Build Docker image with build tools
make wheels           # Compile wheels into ./wheelhouse
make venv-host        # Host venv install from wheelhouse
make up               # Start warm container
make shell            # Shell into warm container
make venv-container   # Container venv at /opt/venv
make down             # Stop/remove container
make clean            # Remove .venv_host and wheelhouse