diff --git a/README.md b/README.md index 18fffc3..36178e0 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 @@ -50,38 +77,10 @@ docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom ### Protocol & Implementation - [Protocol Specification](docs/PROTOCOL.md) - Binary protocol definition +- [PoW Algorithm Analysis](docs/POW_ANALYSIS.md) - Algorithm selection rationale and comparison - [Implementation Plan](docs/IMPLEMENTATION.md) - Development phases and progress - [Package Structure](docs/PACKAGES.md) - Code organization and package responsibilities - [Architecture Choices](docs/ARCHITECTURE.md) - Design decisions and patterns ### Production Readiness - [Production Readiness Guide](docs/PRODUCTION_READINESS.md) - Requirements for production deployment - -## 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/... -```