diff --git a/docs/design/README.md b/docs/design/README.md index f4b44ab..38da2f2 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -2,7 +2,8 @@ Protocol design specifications and analysis. -| Document | Description | -|----------|-------------| -| [fips-design.md](fips-design.md) | Full protocol design specification | -| [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Spanning tree protocol dynamics study | +| Document | Description | +|--------------------------------------------------------|-------------------------------------------------| +| [fips-design.md](fips-design.md) | Full protocol design specification | +| [fips-links.md](fips-links.md) | Link protocol requirements and characteristics | +| [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Spanning tree protocol dynamics study | diff --git a/docs/design/fips-links.md b/docs/design/fips-links.md new file mode 100644 index 0000000..a6f9b7a --- /dev/null +++ b/docs/design/fips-links.md @@ -0,0 +1,133 @@ +# FIPS Link Protocols + +FIPS nodes peer with each other over a variety of link types. This document +explores the requirements and characteristics of different link protocols +that FIPS can operate over. + +## Design Principles + +FIPS is a Layer 3 (network) protocol. It exposes an IPv6 interface to local +applications, with an address deterministically derived from the node's npub. +This means existing UDP, TCP, and other IP-based applications work unmodified +over FIPS. + +However, this IPv6-over-links architecture requires care to avoid classic +encapsulation pitfalls. In particular, running TCP over a reliable link (like +TCP/IP overlay) creates "TCP-over-TCP" where retransmission and congestion +control mechanisms at both layers interact adversely. FIPS prefers unreliable +links for this reason. + +FIPS treats underlying connectivity as abstract links, regardless of whether +those links are: + +- True L2 protocols (Ethernet, Bluetooth) +- L4-over-L3 tunnels (UDP/IP) used as link substrate for NAT traversal +- Application-layer overlays (Tor, I2P) + +Each link driver presents a uniform interface to the FIPS routing layer: +send/receive datagrams to/from a link-layer peer address. + +## Link Protocol Characteristics + +### Overlay Links (L3/L4 Substrate) + +These links tunnel FIPS over an existing network layer, typically for internet +connectivity or anonymity. Overlay links are expected to be the majority in +early deployments, but all depend on existing IP/Internet infrastructure that +FIPS is ultimately designed to replace. + +| Link | Encapsulation | Addressing | MTU | Latency | Reliability | Bandwidth | Discovery | +|------|---------------|------------|-----|---------|-------------|-----------|-----------| +| UDP/IP | UDP datagram | IP:port | 1280-1472 | 1-500ms | Unreliable | High | DNS-SD, Nostr | +| TCP/IP | Framed stream | IP:port | Stream | 10-500ms | Reliable | High | DNS-SD, Nostr | +| WebSocket | WS frames | URL | Stream | 10-500ms | Reliable | High | Nostr | +| Tor | TCP stream | .onion | Stream | 500ms-5s | Reliable | Low-Med | Static, Nostr | +| I2P | I2P datagram | Destination | ~32K | 1-10s | Unreliable | Low | I2P directory | + +### Shared Medium Links + +These links operate over broadcast or multicast-capable media where multiple +endpoints share the same physical or logical channel. + +| Link | Encapsulation | Addressing | MTU | Latency | Reliability | Bandwidth | Discovery | +|------|---------------|------------|-----|---------|-------------|-----------|-----------| +| Ethernet | EtherType frame | MAC | 1500 | <1ms | Unreliable | High | Multicast | +| WiFi Direct | 802.11 frame | MAC | 1500 | 1-10ms | Unreliable | High | Service discovery | +| DOCSIS (Cable) | DOCSIS frame | MAC | 1500 | 10-50ms | Unreliable | 1M-1G | N/A (uses IP) | +| Bluetooth Classic | L2CAP | BD_ADDR | 672-64K | 10-100ms | Reliable | 2-3 Mbps | Inquiry + SDP | +| BLE | L2CAP CoC/GATT | BD_ADDR | 23-517 | 10-30ms | Reliable | 125K-2M | GATT advertising | +| Zigbee | 802.15.4 frame | 16/64-bit | ~100 | 15-30ms | Reliable | 250 kbps | Network scan | +| LoRa | Raw packet | Device addr | 51-222 | 100ms-10s | Unreliable | 0.3-50 kbps | Beacons | + +### Point-to-Point Links + +These links connect exactly two endpoints with no shared medium or addressing. + +| Link | Encapsulation | Addressing | MTU | Latency | Reliability | Bandwidth | Discovery | +|--------|-----------------|------------|----------|-----------|-------------|-----------|------------| +| Serial | SLIP/COBS frame | None (P2P) | 256-1500 | 1-100ms | Reliable | 9.6K-1M | Configured | +| Dialup | PPP frame | None (P2P) | 1500 | 100-200ms | Reliable | 33.6-56K | Configured | + +### Notes + +**MTU**: Minimum/maximum or typical range. FIPS must handle heterogeneous MTUs +across the mesh; the IPv6 minimum (1280) is a safe baseline for the FIPS +packet format. + +**Latency**: Typical range from best-case to worst-case. Affects spanning tree +convergence and keepalive timing. + +**Reliability**: Whether the link provides delivery guarantees. Unreliable +links may drop, reorder, or duplicate packets. FIPS must tolerate this at +the routing layer. + +**Bandwidth**: Order of magnitude. Affects flow control and congestion +decisions, but FIPS routing itself is low-bandwidth (control plane only). + +## UDP/IP as Primary Internet Link + +For internet-connected nodes, UDP/IP is the recommended link protocol: + +- **NAT traversal**: UDP hole punching enables peer connections through NAT +- **Firewall compatibility**: UDP outbound rarely blocked; stateful firewalls + pass return traffic +- **No connection state**: Matches FIPS datagram model +- **Low overhead**: 8-byte UDP header is negligible +- **Avoids TCP-over-TCP**: As noted in Design Principles, unreliable links + avoid adverse interactions with application-layer TCP + +Raw IP with a custom protocol number would be cleaner but is blocked by most +NAT devices and firewalls, limiting deployment to networks without NAT. + +## Link Driver Interface + +Each link driver implements: + +```rust +trait LinkDriver { + type PeerAddr: Clone + Eq + Hash; + + /// Send a FIPS packet to a peer + fn send(&self, peer: &Self::PeerAddr, data: &[u8]) -> Result<()>; + + /// Receive a FIPS packet (blocking) + fn recv(&self) -> Result<(Self::PeerAddr, Vec)>; + + /// Link MTU (maximum FIPS packet size) + fn mtu(&self) -> u16; + + /// Discover potential peers (link-specific mechanism) + fn discover(&self) -> Result>; +} +``` + +Link drivers handle any necessary framing, fragmentation, or encryption +at the link layer. The FIPS routing layer sees only FIPS packets. + +## Topics for Further Design + +- Framing protocols for stream-based links (TCP, WebSocket) +- Link-layer encryption requirements vs FIPS-layer encryption +- Congestion control and flow control per link type +- Multi-path: using multiple links to same peer +- Link quality metrics for parent selection