mirror of https://github.com/jmcorgan/fips.git synced 2026-07-22 07:48:26 +00:00

Files

Johnathan Corgan 0a72317b59 Design documentation illustration pass and FLP→FMP rename

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

2026-02-21 22:05:44 +00:00

3.2 KiB

Raw Blame History

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-mesh-layer.md	FIPS Mesh Protocol (FMP): 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-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)

3.2 KiB Raw Blame History