diff --git a/README.md b/README.md new file mode 100644 index 0000000..18fffc3 --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# Hash of Wisdom + +A TCP server implementing the "Word of Wisdom" concept with proof-of-work challenges to protect against DDoS attacks. + +## Overview + +The Hash of Wisdom server requires clients to solve computational puzzles (proof-of-work) before receiving wise quotes. This approach prevents spam and DDoS attacks by requiring clients to invest CPU time for each request. + +## Quick Start + +### Prerequisites +- Go 1.24.3+ +- Docker (optional) + +### Building +```bash +# Build server +go build -o hash-of-wisdom ./cmd/server + +# Build client +go build -o client ./cmd/client +``` + +### Running +```bash +# Start server (uses config.yaml by default) +./hash-of-wisdom + +# Or with custom config +./hash-of-wisdom -config /path/to/config.yaml + +# Connect with client +./client -addr localhost:8080 +``` + +### Using Docker +```bash +# Build image +docker build -t hash-of-wisdom . + +# Run container +docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom +``` + +### Monitoring +- Metrics: http://localhost:8081/metrics (Prometheus format with Go runtime stats) +- Profiling: http://localhost:8081/debug/pprof/ + +## Documentation + +### Protocol & Implementation +- [Protocol Specification](docs/PROTOCOL.md) - Binary protocol definition +- [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/... +```