mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-22 07:48:26 +00:00
19efe06622
SessionAck previously only carried the responder's coordinates (src_coords). When the return path diverged from the forward path (e.g., after tree reconvergence), transit nodes on the return path lacked the initiator's coordinates and couldn't route the SessionAck back, causing handshake timeouts. Add dest_coords (initiator's coordinates) to the SessionAck wire format, mirroring SessionSetup's design. Transit nodes now cache both endpoints' coordinates when forwarding a SessionAck, making the return path self-sufficient regardless of path asymmetry. Root cause confirmed by churn-20 sim log analysis: the n04-n14 handshake failure was caused by n15 (return-path transit) lacking n04's coordinates, not by stale tree routes through a downed node.
FIPS Design Documents
Protocol design specifications for the Federated Interoperable Peering System — a self-organizing encrypted mesh network built on Nostr identities.
Reading Order
Start with the introduction, then follow the protocol stack from bottom to top. After the stack, the mesh operation document explains how all the pieces work together. Supporting references provide deeper dives into specific topics.
Protocol Stack
| Document | Description |
|---|---|
| fips-intro.md | Protocol introduction: goals, architecture, layer model |
| fips-transport-layer.md | Transport layer: datagram delivery over arbitrary media |
| fips-link-layer.md | FIPS Link Protocol (FLP): peer authentication, link encryption, forwarding |
| fips-session-layer.md | FIPS Session Protocol (FSP): end-to-end encryption, sessions |
| fips-ipv6-adapter.md | IPv6 adaptation: TUN interface, DNS, MTU enforcement |
Mesh Behavior
| Document | Description |
|---|---|
| fips-mesh-operation.md | How the mesh operates: routing, discovery, error recovery |
| fips-wire-formats.md | Wire format reference for all message types |
Supporting References
| Document | Description |
|---|---|
| fips-spanning-tree.md | Spanning tree algorithms: root election, parent selection, coordinates |
| fips-bloom-filters.md | Bloom filter math: FPR analysis, size classes, split-horizon |
Implementation
| Document | Description |
|---|---|
| fips-software-architecture.md | Stable architectural decisions guiding the codebase |
| fips-state-machines.md | Phase-based state machine pattern (Rust enum-of-structs) |
| fips-configuration.md | YAML configuration reference |
Supplemental
| Document | Description |
|---|---|
| spanning-tree-dynamics.md | Spanning tree walkthroughs: convergence scenarios, worked examples |
Document Relationships
fips-intro.md
│
┌──────────────┼──────────────┐
▼ ▼ ▼
fips-transport-layer fips-mesh- fips-software-
│ operation architecture
▼ │ │
fips-link-layer ◄────────┤ ▼
│ │ fips-state-machines
▼ │
fips-session-layer ├──► fips-spanning-tree
│ │ │
▼ └──► fips-bloom-filters
fips-ipv6-adapter
fips-wire-formats
(referenced by all layer docs)
fips-configuration
(standalone reference)
spanning-tree-dynamics
(pedagogical companion to fips-spanning-tree)