kccleoc/pyhdwallet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add Makefile Dockerfile README.md

Browse Source
This commit is contained in:
kccleoc
2026-01-07 21:03:00 +08:00
parent 129b09fcd9
commit a9af9d33af
3 changed files with 230 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
Dockerfile Normal file
View File

@@ -0,0 +1,16 @@
# Dockerfile
# Base build environment for hdwalletpy: Python 3.11 + build tools + venv support
FROM python:3.11-slim
# Install build tools, headers, and venv module
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential \
python3-dev \
libffi-dev \
python3-venv \
&& rm -rf /var/lib/apt/lists/*
# Set working directory for bind mounts
WORKDIR /app

90
Makefile Normal file
View File

@@ -0,0 +1,90 @@
# Makefile for hdwalletpy workflow
# - Build a reusable Docker image
# - Compile wheels in container (wheelhouse)
# - Create host venv and install from wheelhouse
# - Optionally run inside a warm container
# ---------- Config ----------
IMAGE := python-build-env:3.11
CONTAINER := hdwallet
WORKDIR := /app
VENV_HOST := .venv_host
VENV_CONTAINER := /opt/venv
WHEELHOUSE := wheelhouse
# ---------- Help ----------
.PHONY: help
help:
@echo "Targets:"
@echo " make build-image - Build Docker image with build tools and python3-venv"
@echo " make wheels - Build dependency wheels into ./$(WHEELHOUSE)"
@echo " make venv-host - Create host venv $(VENV_HOST) and install from wheelhouse"
@echo " make up - Start a warm container named $(CONTAINER)"
@echo " make shell - Open a shell in the warm container"
@echo " make venv-container - Create venv inside container at $(VENV_CONTAINER) and install requirements"
@echo " make down - Stop and remove the warm container"
@echo " make clean-venv - Remove host venv $(VENV_HOST)"
@echo " make clean-wheelhouse - Remove local wheel cache $(WHEELHOUSE)"
@echo " make clean - Clean venv and wheelhouse"
# ---------- Build reusable image ----------
.PHONY: build-image
build-image:
docker build -t $(IMAGE) .
# ---------- Build wheels in container ----------
.PHONY: wheels
wheels: requirements.txt
docker run --rm -it -v "$$PWD":$(WORKDIR) -w $(WORKDIR) $(IMAGE) bash -lc '\
python -m pip install --upgrade pip setuptools wheel && \
mkdir -p $(WHEELHOUSE) && \
python -m pip wheel -r requirements.txt -w $(WHEELHOUSE) \
'
# ---------- Host venv from wheelhouse ----------
.PHONY: venv-host
venv-host: requirements.txt
python3 -m venv $(VENV_HOST)
. $(VENV_HOST)/bin/activate && \
python -m pip install --upgrade pip setuptools wheel && \
python -m pip install --no-index --find-links=$(WHEELHOUSE) -r requirements.txt && \
python --version
# ---------- Warm container lifecycle ----------
.PHONY: up
up:
docker run -dit -v "$$PWD":$(WORKDIR) -w $(WORKDIR) --name $(CONTAINER) $(IMAGE) bash
.PHONY: shell
shell:
docker exec -it $(CONTAINER) bash
.PHONY: venv-container
venv-container: requirements.txt
docker exec -it $(CONTAINER) bash -lc '\
test -x $(VENV_CONTAINER)/bin/python || ( \
python -m venv $(VENV_CONTAINER) && \
. $(VENV_CONTAINER)/bin/activate && \
python -m pip install --upgrade pip setuptools wheel && \
python -m pip install -r requirements.txt \
) && \
. $(VENV_CONTAINER)/bin/activate && python --version \
'
.PHONY: down
down:
- docker rm -f $(CONTAINER)
# ---------- Cleanup ----------
.PHONY: clean-venv
clean-venv:
rm -rf $(VENV_HOST)
.PHONY: clean-wheelhouse
clean-wheelhouse:
rm -rf $(WHEELHOUSE)
.PHONY: clean
clean: clean-venv clean-wheelhouse

155
README.md
View File

@@ -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`.