mirror of https://github.com/jmcorgan/fips.git synced 2026-07-30 19:46:15 +00:00

Files

T

Johnathan Corgan d46dc874ef Restructure design docs around protocol layers

Reorganize FIPS design documentation from implementation-centric
structure (routing, gossip protocol, wire protocol, transports) to
protocol-layer organization with clear service boundaries.

New documents (8):
- fips-transport-layer.md — transport layer spec
- fips-link-layer.md — FLP spec (peer auth, link encryption, forwarding)
- fips-session-layer.md — FSP spec (end-to-end encryption, sessions)
- fips-ipv6-adapter.md — IPv6 adaptation (TUN, DNS, MTU enforcement)
- fips-mesh-operation.md — routing, discovery, error recovery
- fips-wire-formats.md — consolidated wire format reference
- fips-spanning-tree.md — tree algorithm reference
- fips-bloom-filters.md — bloom filter math reference

Rewritten (2):
- fips-intro.md — breadth-first intro with layer model diagrams
- fips-software-architecture.md — slimmed to stable decisions

Updated (3):
- spanning-tree-dynamics.md — removed stale root refresh, aligned terminology
- fips-configuration.md — fixed priority type (u16 → u8)
- fips-state-machines.md — synced code examples with codebase

Deleted (6): fips-transports.md, fips-wire-protocol.md,
fips-gossip-protocol.md, fips-session-protocol.md, fips-routing.md,
fips-tun-driver.md (content absorbed into new structure)

2026-02-17 04:50:04 +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-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)

3.2 KiB Raw Blame History