88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
|
# 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/...
|
||
|
|
```
|