mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-10 16:43:12 +00:00
Johnathan Corgan
0a72317b59
Rename FIPS Link Protocol (FLP) to FIPS Mesh Protocol (FMP)
The "Link Protocol" name understated the layer's scope — spanning tree
construction, bloom filter routing, greedy forwarding, and mesh-wide
coordination go well beyond link-level concerns. Rename fips-link-layer.md
to fips-mesh-layer.md, update FLP→FMP throughout docs and source code
(FLP_VERSION→FMP_VERSION, wire.rs, rx_loop.rs, spanning_tree.rs).
New SVG illustrations
- Protocol stack: color-coded layer diagram replacing ASCII art
- OSI mapping: side-by-side comparison with traditional networking layers
- Bloom filter propagation: 6-node tree with sender-colored filter boxes
showing split-horizon computation per link
- Routing decision flowchart: 5-step priority chain with candidate ranking
by tree distance and link performance
- Coordinate discovery: sequence diagram showing LookupRequest propagation,
response caching, and SessionSetup cache warming
Redesigned existing SVGs
- Architecture overview: uniform node layout, U-shaped encrypted link
connectors, separate end-to-end session line
- Node architecture: split Router Core into FSP and FMP layers, reorganize
transports into Overlay/Shared Medium/Point-to-Point categories
- Identity derivation: wider boxes, visible encode arrow, dashed npub line
fips-intro.md revisions
- Add inline references to prior work: Yggdrasil/Ironwood for coordinate
routing, Noise Protocol Framework for IK handshakes, WireGuard for
index-based session dispatch, Wikipedia for bloom filters, split-horizon,
and greedy embedding
- Add explanatory paragraphs after bloom filter diagram describing
split-horizon filter computation and candidate selection behavior
- Simplify transport abstraction language, remove I2P/LoRa references
- Fix LookupRequest wording ("propagates" not "floods"), note intermediate
node coordinate caching on lookup responses
- Rewrite architecture overview prose to match redesigned diagrams
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# 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](fips-intro.md) | Protocol introduction: goals, architecture, layer model |
|
|
| [fips-transport-layer.md](fips-transport-layer.md) | Transport layer: datagram delivery over arbitrary media |
|
|
| [fips-mesh-layer.md](fips-mesh-layer.md) | FIPS Mesh Protocol (FMP): peer authentication, link encryption, forwarding |
|
|
| [fips-session-layer.md](fips-session-layer.md) | FIPS Session Protocol (FSP): end-to-end encryption, sessions |
|
|
| [fips-ipv6-adapter.md](fips-ipv6-adapter.md) | IPv6 adaptation: TUN interface, DNS, MTU enforcement |
|
|
|
|
### Mesh Behavior
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-mesh-operation.md](fips-mesh-operation.md) | How the mesh operates: routing, discovery, error recovery |
|
|
| [fips-wire-formats.md](fips-wire-formats.md) | Wire format reference for all message types |
|
|
|
|
### Supporting References
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-spanning-tree.md](fips-spanning-tree.md) | Spanning tree algorithms: root election, parent selection, coordinates |
|
|
| [fips-bloom-filters.md](fips-bloom-filters.md) | Bloom filter math: FPR analysis, size classes, split-horizon |
|
|
|
|
### Implementation
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [fips-software-architecture.md](fips-software-architecture.md) | Stable architectural decisions guiding the codebase |
|
|
| [fips-state-machines.md](fips-state-machines.md) | Phase-based state machine pattern (Rust enum-of-structs) |
|
|
| [fips-configuration.md](fips-configuration.md) | YAML configuration reference |
|
|
|
|
### Supplemental
|
|
|
|
| Document | Description |
|
|
| -------- | ----------- |
|
|
| [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Spanning tree walkthroughs: convergence scenarios, worked examples |
|
|
|
|
## Document Relationships
|
|
|
|
```text
|
|
fips-intro.md
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
▼ ▼ ▼
|
|
fips-transport-layer fips-mesh- fips-software-
|
|
│ operation architecture
|
|
▼ │ │
|
|
fips-mesh-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)
|
|
```
|