Lesson 7

Putting It Together

You now know the individual parts: identity derivation, the protocol stack, transports, spanning tree routing, bloom filters, and the two encryption layers. This lesson walks through a concrete scenario that ties everything together: what happens when you ping npub1abc...def.fips from a cold-started node.

The scenario

Your node (call it Alice) has just started. It has one configured peer (Bob) reachable via UDP. You want to reach Zara, who is somewhere else in the mesh. You know her npub but have no idea where she is.

Step-by-step walkthrough

1

Transport connects to Bob

Alice's UDP transport opens a socket and sends a FIPS handshake to Bob's IP:port. At this point, Alice knows only the transport address, not Bob's FIPS identity.

2

FMP Noise IK handshake with Bob

Alice initiates a Noise IK handshake. She sends her npub encrypted under Bob's public key. Bob responds, proving he holds the corresponding private key. Both sides derive link encryption keys. The peer link is now authenticated and encrypted.

3

Spanning tree bootstrap

Alice and Bob exchange tree state: root node_addr, depth, and cost. If Bob already belongs to a tree, Alice evaluates Bob as a potential parent. If Alice's node_addr is smaller than the current root, she becomes the new root (and Bob may update his tree state too). Within a few exchanges, Alice has a tree coordinate.

4

DNS resolves the .fips name

The ping command triggers a DNS lookup for npub1abc...def.fips. The FIPS DNS resolver recognizes the .fips TLD and derives Zara's IPv6 address from her npub: hash the x-only public key to get node_addr, then prepend 0xfd. No external DNS server is contacted.

5

Coordinate lookup: where is Zara?

Alice knows Zara's node_addr but not her tree coordinates. She sends a LookupRequest, which propagates through the mesh via bloom-guided tree routing. When a node that knows Zara's coordinates receives this request, it replies with a LookupResponse containing the coordinates. Alice caches the result.

6

Session setup (Noise XK)

Alice initiates a Noise XK handshake with Zara. The SessionSetup messages travel through the mesh, and each transit node caches the source and destination coordinates it finds in the routing envelope. This "warms up" the coordinate caches along the path, speeding up future routing.

7

Data flows

The ICMP echo request from ping is encapsulated as an IPv6 packet, compressed by the IPv6 adapter (stripping the header and replacing it with a 4-byte port header), encrypted by FSP, wrapped in FMP link encryption, and sent toward Zara's coordinates. Each transit router decrypts the FMP layer, reads the destination, re-encrypts, and forwards. Zara strips both layers and replies. Ping succeeds.

8

Steady state

Subsequent packets to Zara skip steps 4-6: the coordinate and session are already cached. MMP periodically measures link quality. The spanning tree may re-converge if links change. Bloom filters are refreshed. But from Alice's application perspective, traffic flows like any IPv6 connection.

The lifecycle, summarized

Cold start
→ Transport connection (UDP socket to peer)
→ FMP handshake (Noise IK, link authenticated)
→ Spanning tree join (coordinate assigned)
First contact with unknown destination
→ DNS resolve (.fips → node_addr → IPv6)
→ Coordinate lookup (LookupRequest/Response)
→ Session setup (Noise XK, end-to-end encrypted)
Steady state
→ Data flow (IPv6 → FSP → FMP → Transport)
→ MMP keeps metrics fresh, tree adapts

Where to go from here

GitHub: jmcorgan/fips

The reference implementation. Rust codebase with the full protocol.

Protocol Specifications

The full design documents: wire formats, algorithms, security analysis.

fips.network

The official FIPS website.

Lifecycle

1. What triggers coordinate discovery in FIPS?

2. How does SessionSetup warm transit node caches?

3. What is the total per-packet overhead for IPv6 traffic through FIPS?