# 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:

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

2. Create a virtual environment:

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

3. Install dependencies:

   ```bash
   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**

```bash
make build-image
```

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

#### **Step 2: Compile Wheels in Container**

```bash
make wheels
```

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

#### **Step 3: Create Host Virtual Environment**

```bash
make venv-host
source .venv_host/bin/activate
```

Installs dependencies from `wheelhouse` (no compilation needed).

#### **Optional: Work Inside a Warm Container**

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

#### **Cleanup**

```bash
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:

```bash
# 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:

```bash
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

```bash
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
```