# 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/...
```