diff --git a/README.md b/README.md index 18fffc3..7ed068a 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,41 @@ The Hash of Wisdom server requires clients to solve computational puzzles (proof ### Prerequisites - Go 1.24.3+ - Docker (optional) +- [Task](https://taskfile.dev/) (optional, but recommended) ### Building ```bash # Build server go build -o hash-of-wisdom ./cmd/server -# Build client +# Build client go build -o client ./cmd/client ``` ### Running + +#### Using Task (Recommended) +```bash +# Most useful command - run all checks +task check + +# Start server +task server -- -config config.yaml + +# Connect client +task client -- --addr=localhost:8080 + +# Run tests +task test + +# See coverage +task test-coverage + +# See all available commands +task --list +``` + +#### Manual Commands ```bash # Start server (uses config.yaml by default) ./hash-of-wisdom @@ -31,6 +55,9 @@ go build -o client ./cmd/client # Connect with client ./client -addr localhost:8080 + +# Run tests +go test ./... ``` ### Using Docker @@ -59,29 +86,4 @@ docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom ## Algorithm Choice -The server uses **SHA-256 based proof-of-work** with leading zero bits difficulty: -- **Why SHA-256**: Cryptographically secure, well-tested, hardware-optimized -- **Leading Zero Bits**: Simple difficulty scaling, easy verification -- **HMAC Authentication**: Prevents challenge tampering and replay attacks -- **Configurable Difficulty**: Adaptive to different threat levels (4-30 bits) - -This approach provides strong DDoS protection while remaining computationally reasonable for legitimate clients. - -## Current Status - -✅ **Complete**: Core functionality, TCP server, client, metrics, containerization -🔄 **In Progress**: Documentation (Phase 9) -📋 **Planned**: See [Production Readiness Guide](docs/PRODUCTION_READINESS.md) for production deployment requirements - -## Testing - -```bash -# Run all tests -go test ./... - -# Run integration tests -go test ./test/integration/... - -# Benchmarks -go test -bench=. ./internal/pow/... -``` +See [Architecture Choices](docs/ARCHITECTURE.md) for detailed algorithm selection rationale and implementation decisions.