NAT Traversal
+Most devices on the internet sit behind a NAT (Network Address Translator). Your router assigns your device a private address (like 192.168.1.100) and translates it to a public address when you connect outward. This works fine for browsing the web, but it creates a problem for P2P networks: two devices behind different NATs cannot directly connect to each other without help.
Tesseras solves this with a three-tier approach, trying the cheapest option first:
+-
+
- Direct connection — if both nodes have public IPs, they connect directly +
- UDP hole punching — a third node introduces the two peers so they can punch through their NATs +
- Relay — a public-IP node forwards packets between the two peers +
NAT type discovery
+When a node starts, it sends STUN (Session Traversal Utilities for NAT) requests to multiple public servers. By comparing the external addresses these servers report back, the node classifies its NAT:
+| NAT Type | What it means | Hole punching? |
|---|---|---|
| Public | No NAT — your device has a public IP | Not needed |
| Cone | NAT maps the same internal port to the same external port regardless of destination | Works well (~80%) |
| Symmetric | NAT assigns a different external port for each destination | Unreliable |
| Unknown | Could not reach STUN servers | Relay needed |
Your node advertises its NAT type in DHT Pong messages, so other nodes know whether hole punching is worth attempting.
+Hole punching
+When node A (behind a Cone NAT) wants to connect to node B (also behind a Cone NAT), neither can directly reach the other. The solution:
+-
+
-
+
A sends a PunchIntro message to node I (an introducer — any public-IP node they both know). The message includes A’s external address (from STUN) and an Ed25519 signature proving A’s identity.
+
+ -
+
I verifies the signature and forwards a PunchRequest to B, including A’s address and the original signature.
+
+ -
+
B verifies the signature (proving the request really came from A, not a spoofed source). B then sends a UDP packet to A’s external address — this opens a pinhole in B’s NAT. B also sends a PunchReady message back to A with B’s external address.
+
+ -
+
A sends a UDP packet to B’s external address. Both NATs now have pinholes, and the two nodes can communicate directly.
+
+
The entire process takes 2-5 seconds. The Ed25519 signatures prevent reflection attacks, where an attacker replays an old introduction to redirect traffic.
+Relay fallback
+When hole punching fails (Symmetric NAT, strict firewalls, or corporate networks), nodes fall back to relaying through a public-IP node:
+-
+
- A sends a RelayRequest to node R (a public-IP node with relay enabled). +
- R creates a session and sends a RelayOffer to both A and B, containing the relay address and a session token. +
- A and B send their packets to R, prefixed with the session token. R strips the token and forwards the payload to the other peer. +
Relay sessions have bandwidth limits:
+-
+
- 256 KB/s for peers with good reciprocity (they store fragments for others) +
- 64 KB/s for peers without reciprocity +
- Non-reciprocal sessions are limited to 10 minutes +
This encourages nodes to contribute storage — good network citizens get better relay service.
+Address migration
+When a mobile device switches networks (Wi-Fi to cellular), its IP address changes. Rather than tearing down and rebuilding relay sessions, the node sends a signed RelayMigrate message to update its address in the existing session. This avoids re-establishing connections from scratch.
+Configuration
+The [nat] section in the daemon config controls NAT traversal:
[nat]
+# STUN servers for NAT type detection
+stun_servers = ["stun.l.google.com:19302", "stun.cloudflare.com:3478"]
+
+# Enable relay (forward traffic for other NATed peers)
+relay_enabled = false
+
+# Maximum simultaneous relay sessions
+relay_max_sessions = 50
+
+# Bandwidth limit for reciprocal peers (KB/s)
+relay_reciprocal_kbps = 256
+
+# Bandwidth limit for non-reciprocal peers (KB/s)
+relay_bootstrap_kbps = 64
+
+# Relay session idle timeout (seconds)
+relay_idle_timeout_secs = 60
+To run a relay node, set relay_enabled = true. Your node must have a public IP (or a port-forwarded router) to serve as a relay.
Mobile reconnection
+When the Tesseras app detects a network change on a mobile device, it runs a three-phase reconnection sequence:
+-
+
- QUIC migration (0-2s) — QUIC supports connection migration natively. The app tries to migrate all active connections to the new address. +
- Re-STUN (2-5s) — discover the new external address and re-announce to the DHT. +
- Re-establish (5-10s) — reconnect peers that migration couldn’t save, in priority order: bootstrap nodes first, then nodes holding your fragments, then nodes whose fragments you hold. +
The app shows reconnection progress through the NetworkChanged event stream.
Monitoring
+NAT traversal exposes Prometheus metrics at /metrics:
-
+
tesseras_nat_type— current detected NAT type
+tesseras_stun_requests_total/tesseras_stun_failures_total— STUN reliability
+tesseras_punch_attempts_total{initiator_nat, target_nat}— punch success rate by NAT pair
+tesseras_relay_sessions_active— current relay load
+tesseras_relay_bytes_forwarded— total relay bandwidth
+tesseras_network_change_total— network change frequency on mobile
+