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.

+ +