hash-of-wisdom/README.md

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

# Build server
go build -o hash-of-wisdom ./cmd/server

# Build client  
go build -o client ./cmd/client

Running

# 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

# 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 - Binary protocol definition
• Implementation Plan - Development phases and progress
• Package Structure - Code organization and package responsibilities
• Architecture Choices - Design decisions and patterns

Production Readiness

• Production Readiness Guide - 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 for production deployment requirements

Testing

# Run all tests
go test ./...

# Run integration tests
go test ./test/integration/...

# Benchmarks
go test -bench=. ./internal/pow/...