Phase 1: Nodes Find Each Other

2026-02-14

Tesseras is no longer a local-only tool. Phase 1 delivers the networking layer: nodes discover each other through a Kademlia DHT, communicate over QUIC, and publish tessera pointers that any peer on the network can find. A tessera created on node A is now findable from node C.

What was built

tesseras-core (updated) — New network domain types: TesseraPointer (lightweight reference to a tessera's holders and fragment locations), NodeIdentity (node ID + public key + proof-of-work nonce), NodeInfo (identity + address + capabilities), and Capabilities (bitflags for what a node supports: DHT, storage, relay, replication).

tesseras-net — The transport layer, built on QUIC via quinn. The Transport trait defines the port: send, recv, disconnect, local_addr. Two adapters implement it:

QuinnTransport — real QUIC with self-signed TLS, ALPN negotiation (tesseras/1), connection pooling via DashMap, and a background accept loop that handles incoming streams.
MemTransport + SimNetwork — in-memory channels for deterministic testing without network I/O. Every integration test in the DHT crate runs against this.

The wire protocol uses length-prefixed MessagePack: a 4-byte big-endian length header followed by an rmp-serde payload. WireMessage carries a version byte, request ID, and a body that can be a request, response, or protocol-level error. Maximum message size is 64 KiB.

tesseras-dht — A complete Kademlia implementation:

Routing table: 160 k-buckets with k=20. Least-recently-seen eviction, move-to-back on update, ping-check before replacing a full bucket's oldest entry.
XOR distance: 160-bit XOR metric with bucket indexing by highest differing bit.
Proof-of-work: nodes grind a nonce until BLAKE3(pubkey || nonce)[..20] has 8 leading zero bits (~256 hash attempts on average). Cheap enough for any device, expensive enough to make Sybil attacks impractical at scale.
Protocol messages: Ping/Pong, FindNode/FindNodeResponse, FindValue/FindValueResult, Store — all serialized with MessagePack via serde.
Pointer store: bounded in-memory store with configurable TTL (24 hours default) and max entries (10,000 default). When full, evicts pointers furthest from the local node ID, following Kademlia's distance-based responsibility model.
DhtEngine: the main orchestrator. Handles incoming RPCs, runs iterative lookups (alpha=3 parallelism), bootstrap, publish, and find. The run() method drives a tokio::select! loop with maintenance timers: routing table refresh every 60 seconds, pointer expiry every 5 minutes.

tesd — A full-node binary. Parses CLI args (bind address, bootstrap peers, data directory), generates a PoW-valid node identity, binds a QUIC endpoint, bootstraps into the network, and runs the DHT engine. Graceful shutdown on Ctrl+C via tokio signal handling.

Infrastructure — OpenTofu configuration for two Hetzner Cloud bootstrap nodes (cx22 instances in Falkenstein, Germany and Helsinki, Finland). Cloud-init provisioning script creates a dedicated tesseras user, writes a config file, and sets up a systemd service. Firewall rules open UDP 4433 (QUIC) and restrict metrics to internal access.

Testing — 139 tests across the workspace:

47 unit tests in tesseras-dht (routing table, distance, PoW, pointer store, message serialization, engine RPCs)
5 multi-node integration tests (3-node bootstrap, 10-node lookup convergence, publish-and-find, node departure detection, PoW rejection)
14 tests in tesseras-net (codec roundtrips, transport send/recv, backpressure, disconnect)
Docker Compose smoke tests with 3 containerized nodes communicating over real QUIC
Zero clippy warnings, clean formatting

Architecture decisions

Transport as a port: the Transport trait is the only interface between the DHT engine and the network. Swapping QUIC for any other protocol means implementing four methods. All DHT tests use the in-memory adapter, making them fast and deterministic.
One stream per RPC: each DHT request-response pair uses a fresh bidirectional QUIC stream. No multiplexing complexity, no head-of-line blocking between independent operations. QUIC handles the multiplexing at the connection level.
MessagePack over Protobuf: compact binary encoding without code generation or schema files. Serde integration means adding a field to a message is a one-line change. Trade-off: no built-in schema evolution guarantees, but at this stage velocity matters more.
PoW instead of stake or reputation: a node identity costs ~256 BLAKE3 hashes. This runs in under a second on any hardware, including a Raspberry Pi, but generating thousands of identities for a Sybil attack becomes expensive. No tokens, no blockchain, no external dependencies.
Iterative lookup with routing table updates: discovered nodes are added to the routing table as they're encountered during iterative lookups, following standard Kademlia behavior. This ensures the routing table improves organically as nodes interact.

What comes next

Phase 2: Replication — Reed-Solomon erasure coding over the network, fragment distribution, automatic repair loops, bilateral reciprocity ledger (no blockchain, no tokens)
Phase 3: API and Apps — Flutter mobile/desktop app via flutter_rust_bridge, GraphQL API (async-graphql), WASM browser node
Phase 4: Resilience and Scale — ML-DSA post-quantum signatures, advanced NAT traversal, Shamir's Secret Sharing for heirs, packaging for Alpine/Arch/Debian/FreeBSD/OpenBSD, CI on SourceHut
Phase 5: Exploration and Culture — public tessera browser, institutional curation, genealogy integration, physical media export

Nodes can find each other. Next, they learn to keep each other's memories alive.