9 Layers. Zero Compromises.
Blackhole is a layered mesh OS — from XDP BPF at the NIC all the way up to AISP agent sessions. Each layer owns exactly one responsibility. Click any layer to expand its internals.
Inspired by: Lamport (1978), Fischer-Lynch-Paterson (1985), WireGuard whitepaper (Donenfeld, 2017), and XDP paper (Høiland-Jørgensen et al., 2018).
AISP agent sessions. Gatekeeper AI proxy. BMAP self-healing targets with 7 playbooks. JetStream provisioning is validated during assisted onboarding.
Zero Trust capability tokens with offline verification targets. Ed25519-signed, posture-gated, delegatable. ZK Schnorr proofs on P-256. ACLs, RBAC.
Assigns stable mesh IPs derived from Ed25519 public keys. Resolves *.bh hostnames without external DNS. IPv6 /32 (1T addresses) in progress.
WireGuard kernel-space tunnel management. Curve25519 key exchange. ChaCha20-Poly1305 AEAD. BLAKE2s for hashing. Birthday-paradox hole punching for symmetric NATs.
Multi-path peer discovery: mDNS for LAN, hub signaling for WAN. PeerRegistry is a CRDT — nodes join and leave without any coordinator. Instant reconnect from persistent cache.
Ed25519 keypair derivation. TLS certificate generation. Cap'n Proto binary wire format — schema-first encoding with benchmarked payload targets. First-boot provisioning.
Every Blackhole node IS a NATS server — no external broker dependency. The embedded NATS server boots inside the agent process. Nodes form a leaf-node cluster automatically.
The mesh OS kernel. Owns identity, lifecycle, and the event bus. Every subsystem registers here. Think of it as PID 1 for the mesh node.
The crown jewel. eBPF/XDP program loaded into the NIC driver — packets are processed before the Linux kernel ever sees them. Blackhole traffic is fast-pathed at wire speed.
Packet Flow: NIC to Application
A packet arriving at the NIC traverses all 9 layers in under 200µs on a modern server.
XDP fast path at L-1 saves ~20µs per packet vs Linux stack. WireGuard AEAD at L4 adds 32 bytes (Poly1305 MAC + ChaCha20 nonce). Policy evaluation at L6: ~200ns.
Why 9 Layers Beat TCP/IP's 4
TCP/IP conflates application, transport, and security. Blackhole adds a layer below the kernel (XDP) and splits application concerns into discrete, auditable layers.
TCP/IP Model (4 layers)
Problem: "Application" mixes security, routing, and business logic. No NIC-level hooks.
Blackhole Model (9 layers)
Each layer has one job. L-1 is below the OS — no other VPN has this.
Cap'n Proto Wire Format
All Blackhole wire messages use Cap'n Proto binary encoding — not JSON, not Protobuf.
Schema-first
Types defined in .capnp schemas. No runtime reflection. Compiler catches wire-format mismatches at build time.
Schema-aware decoding
Cap'n Proto keeps message layout explicit and benchmarkable so performance claims can be tied to reproducible payload evidence.
Compact binary target
Cap'n Proto payload size is benchmarked against the customer message shape before numerical reduction claims are promoted.
6 CRDT Types — No Coordinator Required
internal/crdt/ implements 6 conflict-free replicated data types. Nodes agree without Raft, without Paxos, without a leader.
| CRDT Type | Use Case in Blackhole |
|---|---|
GCounter | Rate limiting, token budgets, request counters |
LWW-Map | Peer metadata, config sync, key-value state |
OR-Set | PeerRegistry, capability revocation lists |
VectorClock | Event ordering, causality tracking across nodes |
PeerRegistry | Live mesh membership without coordinator |
FileSync | Agent file sync across mesh — conflict-free |
JetStream: 6 Streams + 5 KV Buckets
Auto-provisioned on first boot. No manual configuration. Every node can publish and consume.
BH_AUDIT
Tamper-evident audit trail for all requests
BH_EVENTS
Mesh lifecycle events (join, leave, reconnect)
BH_BENCH
Benchmark and performance telemetry
BH_LOGS
Structured log shipping from all nodes
BH_ALERTS
BMAP playbook alerts and remediation records
BH_SESSIONS
AISP session checkpoints and replay
BH_PEERS
Live peer endpoint and status cache
BH_CONFIG
Distributed configuration store
BH_CAPS
Capability token revocation cache
BH_HEALTH
Per-node BMAP health state
BH_OPS_FILES
Small ops config files (<64KB)
Academic Foundations
WireGuard: Next-Gen Kernel Tunneling
Donenfeld, J.A. (2017)
NDSS Symposium
ChaCha20-Poly1305 + Noise protocol formal proof
The eXpress Data Path (XDP)
Høiland-Jørgensen et al. (2018)
CoNEXT '18
BPF at the NIC driver — the basis for L-1
CRDTs: Consistency without Concurrency Control
Shapiro et al. (2011)
INRIA RR-7687
LWW-Map, OR-Set, GCounter mathematical foundations
Impossibility of Distributed Consensus (FLP)
Fischer, Lynch, Paterson (1985)
JACM 32(2)
Why Blackhole uses CRDTs instead of Raft/Paxos
Efficient Zero-Knowledge Proofs
Schnorr, C.P. (1991)
Journal of Cryptology
P-256 Schnorr proof target validated before publication
Time, Clocks, and Ordering of Events
Lamport, L. (1978)
CACM 21(7)
VectorClock CRDT and distributed event ordering
Explore the Source
Every layer described above has a corresponding Go package. The codebase is MIT-licensed.