add Makefile Dockerfile README.md
This commit is contained in:
155
README.md
155
README.md
@@ -1,44 +1,97 @@
|
||||
# pyhdwallet v1.0.5
|
||||
Here’s an **extended README.md** that combines your original usage instructions with the **Makefile workflow** for clarity and ease of onboarding:
|
||||
|
||||
A secure, offline-first command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. It supports optional PGP-encrypted payloads (ASCII-armored `.asc`) and deterministic AES-encrypted ZIP wallet artifacts written under a local `.wallet/` folder.
|
||||
***
|
||||
|
||||
## Purpose
|
||||
## ✅ Extended `README.md`
|
||||
|
||||
pyhdwallet helps create new wallets or recover from existing mnemonics/seeds with offline operation, auditable derivation, and optional encryption for safer storage. PGP encryption produces an ASCII-armored PGP message suitable for saving as `.asc`.[3]
|
||||
````markdown
|
||||
# hdwalletpy – Setup & Usage Guide
|
||||
|
||||
## Repository layout
|
||||
This project provides a Python-based HD Wallet tool with optional Docker-based build automation for fast, reproducible environments.
|
||||
|
||||
- `src/pyhdwallet.py` — main CLI script
|
||||
- `.wallet/` — generated wallet artifacts (recommend adding to `.gitignore`)
|
||||
- `requirements.in`, `requirements.txt`
|
||||
- `README.md`, `playbook.md`, `LICENSE`
|
||||
---
|
||||
|
||||
## Installation
|
||||
## 📦 Installation Options
|
||||
|
||||
1. Ensure Python 3.11+ is installed.
|
||||
1. Clone/download the repo.
|
||||
1. Create and activate a virtual environment:
|
||||
### **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
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
make build-image
|
||||
```
|
||||
|
||||
1. Install dependencies:
|
||||
Creates a reusable image `python-build-env:3.11` with build tools and `python3-venv`.
|
||||
|
||||
#### **Step 2: Compile Wheels in Container**
|
||||
|
||||
```bash
|
||||
python -m pip install -r requirements.txt
|
||||
make wheels
|
||||
```
|
||||
|
||||
## Basic usage
|
||||
Builds all dependency wheels into `./wheelhouse` for fast installs.
|
||||
|
||||
Run the tool with a subcommand. For help, use `-h` (e.g., `gen -h`, `recover -h`).
|
||||
#### **Step 3: Create Host Virtual Environment**
|
||||
|
||||
```bash
|
||||
# Generate (prints mnemonic by default; intended for debug/test)
|
||||
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 an AES-encrypted ZIP artifact into ./.wallet (password prompted)
|
||||
# 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)
|
||||
@@ -57,12 +110,16 @@ python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.as
|
||||
python ./src/pyhdwallet.py test
|
||||
```
|
||||
|
||||
## Notes on `--file`, AES ZIP, and PGP
|
||||
***
|
||||
|
||||
- `--file` writes **only** an AES-encrypted ZIP (no raw `.json`/`.asc` is left on disk), using `pyzipper`.[4]
|
||||
- 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(...)`.[3]
|
||||
## 🔐 Notes on `--file`, AES ZIP, and PGP
|
||||
|
||||
## About `--force`
|
||||
* `--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()`.
|
||||
|
||||
@@ -70,12 +127,48 @@ Example:
|
||||
|
||||
```bash
|
||||
python ./src/pyhdwallet.py gen > out.txt # likely refused (non-TTY)
|
||||
python ./src/pyhdwallet.py gen --force > out.txt # forced (dangerous)
|
||||
python ./src/pyhdwallet.py gen --force > out.txt # allowed
|
||||
```
|
||||
|
||||
## Security
|
||||
***
|
||||
|
||||
## ✅ 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
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## License
|
||||
|
||||
Add your license info here.
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
✅ This README now **integrates your original usage instructions** with the **Makefile workflow**, so new users can choose between a standard Python setup or the optimized Docker-based approach.
|
||||
|
||||
---
|
||||
|
||||
👉 Do you want me to **also include the Makefile and Dockerfile snippets directly in the README** (so users don’t need to open separate files), or keep them as separate files for clarity?
|
||||
Or should I prepare a **GitHub-ready ZIP** with `README.md`, `Makefile`, `Dockerfile`, and `.gitignore` for you?
|
||||
```
|
||||
|
||||
- Designed to run offline; `gen`, `recover`, and `test` block network access in-process.
|
||||
- Use `--off-screen` to suppress printing sensitive data to stdout.
|
||||
- Prefer `--file` (AES ZIP) and optionally combine with `--pgp-pubkey-file` for stronger at-rest security.
|
||||
- For detailed examples and operational guidance, see `playbook.md`.
|
||||
|
||||
Reference in New Issue
Block a user