A high-performance, production-ready Distributed Hash Table (DHT) implementation designed for Internet-scale deployment with security, privacy, and operability as first-class concerns.
IMPORTANT: Project in research and design phase. Drafts only.
Molia is a modern DHT built on Kademlia's XOR metric with significant enhancements for production use:
- Sub-second lookups at Internet scale (median ≤300ms, P95 ≤1s)
- Zero-allocation hot paths for predictable performance
- Shared-nothing architecture for maximum scalability
- WireGuard-based transport security with built-in Sybil resistance
- First-class NAT traversal and browser support
- Privacy-preserving lookups with query blinding
- Security: Ed25519 identity, WireGuard encryption, proof-of-work admission control
- Performance: Lock-free per-core sharding, zero-allocation design, batched I/O
- Reliability: Erasure coding, adaptive replication, graceful degradation
- Operability: Prometheus metrics, structured logging, rolling upgrades
- Privacy: Query blinding, two-hop relays, minimal metadata exposure
- Architecture Overview - Start here for the big picture
- Implementation Roadmap - 12-week development plan
- API Reference - Client library interface
- Kademlia Algorithm - DHT fundamentals, XOR metric, k-buckets, iterative lookups
- Shared-Nothing Architecture - Per-core sharding, message passing, isolation
- Zero-Allocation Design - Hot-path optimization, buffer pools, bounded containers
- I/O Design - Event loops, batch I/O, buffer management, peerstore persistence
- Transport & NAT Traversal - UDP stack, hole punching, relay strategies, WebRTC fallback
- Wire Protocol - RPC messages, encoding, versioning, negotiation
- WireGuard Integration - Per-shard crypto, session management, MTU handling
- Sybil Resistance - Proof-of-work, admission tokens, rate limiting, behavioral scoring
- Linux eBPF Optimization - SO_REUSEPORT with eBPF steering for WireGuard packet demux
- Security by Default: Silent before handshake, authenticated all traffic, proof-of-work gated
- Zero-Trust Networking: Every peer is untrusted; validate everything
- Fail Gracefully: Degrade performance under attack, never fail open
- Observable: Rich metrics, structured logs, distributed tracing
- Upgradeable: Rolling protocol upgrades, feature negotiation
- Privacy-Aware: Minimize metadata leakage, support query blinding
- Language: Rust (recommended)
- Crypto:
- Identity: Ed25519 (ed25519-dalek)
- Hashing: BLAKE3 (blake3)
- Transport: WireGuard (boringtun)
- Encoding: Protocol Buffers (prost)
- I/O: tokio (per-shard single-threaded runtimes)
- Storage: Per-shard WAL with periodic compaction
- Rust 1.70+ (recommended)
- Linux 5.3+ for eBPF features (optional)
- UDP connectivity (NAT traversal support included)
cargo build --releasecargo test
cargo test --features allocation-tracking # Verify zero-alloc paths./target/release/molia --bootstrap <seed-addrs>- Lookup Latency: P50 ≤300ms, P95 ≤1s, P99 ≤2s
- Throughput: 100K+ lookups/sec per 8-core node
- Hot Path: Zero allocations in steady state
- Per-Packet CPU: ≤5μs median at 3.5 GHz
- Churn Resilience: 95%+ success rate at 30% nodes joining/leaving per minute
- Churn Soak: 30% join/leave rate, maintain ≥95% lookup success
- Partition Heal: Regional isolation recovery
- Adversarial: 20% Sybils near target prefix
- NAT Matrix: Full-cone, symmetric, restricted NAT types
- Data Durability: Random node failures with erasure-coded recovery
- Zero-allocation tests with custom allocator tracking
- Fuzz testing of wire protocol and codecs
- Chaos engineering (network partitions, node crashes)
- Security audits of crypto and admission control
- Shard Count: Number of physical cores (default)
- Bucket Size (K): 20 peers per bucket
- Parallelism (α): 4 concurrent lookups
- TTL: 24h for mutable records, 5-30min for cached content
- Erasure Coding: 10:4 (data:parity) for blobs ≥1MB
- Prometheus metrics endpoint
- Structured JSON logs with privacy scrubbers
- Optional distributed tracing (opt-in per request)
- Grafana dashboards for SLOs and regional heatmaps
- Enable proof-of-work with adaptive difficulty
- Configure per-/24 and per-ASN rate limits
- Set relay budget caps (≤10% egress recommended)
- Enable query blinding for privacy-sensitive deployments
- Core types, crypto primitives, UDP server
- Routing table and iterative lookups
- Basic STORE/FIND_VALUE operations
- WireGuard integration per shard
- NAT traversal (rendezvous, hole punching)
- Provider records and erasure coding
- Mutable records with signatures
- Privacy features (query blinding, relays)
- Rate limiting and abuse scoring
- Observability stack (metrics, logs, dashboards)
- Chaos tests and partition scenarios
- Browser/WebRTC integration
- Relay budgeting and management
- Performance tuning and profiling
- Security audit and staged rollout
Contributions are welcome! Please see our contribution guidelines (coming soon).
- Protocol implementation and testing
- Security review and hardening
- Performance optimization
- Documentation improvements
- Platform support (Windows, mobile)
- Kademlia Paper: Maymounkov & Mazières. "Kademlia: A Peer-to-Peer Information System Based on the XOR Metric." IPTPS 2002.
- WireGuard: BoringTun userspace implementation
- BLAKE3: Fast cryptographic hashing
TBD - Specify license here
- Issues: GitHub Issues (link TBD)
- Discussions: GitHub Discussions (link TBD)
- Security: security@example.com (update with actual contact)
Built with a focus on security, performance, and operability for the modern Internet.