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

Files

Johnathan Corgan 00e26765bd Design documentation illustration and review pass

Wire format diagrams:
- Add 24 SVG diagrams covering every FMP and FSP wire format: common
  prefix, established frame headers, Noise IK handshake messages,
  handshake flow, TreeAnnounce, AncestryEntry, FilterAnnounce,
  LookupRequest/Response, SessionDatagram, Disconnect, SenderReport,
  ReceiverReport, FSP complete message, SessionSetup/Ack/Msg3,
  PathMtuNotification, CoordsRequired, PathBroken, and MtuExceeded
- Replace ASCII art in fips-wire-formats.md with SVG references
- Apply text edits to fips-mesh-layer.md, fips-mesh-operation.md,
  fips-transport-layer.md, and fips-ipv6-adapter.md

Spanning tree dynamics:
- Add 12 topology SVG diagrams: node join (overview + 3-panel steps),
  three-node convergence (4-panel), link addition with depth labels,
  link removal, partition formation, and 6 real-world example diagrams
  (office, mixed-link, two-site WAN topologies)
- Rewrite all code blocks to narrative prose with diagram references
- Add inline prior art attributions distinguishing Yggdrasil-derived
  concepts from FIPS-novel contributions
- Add 3 new references (De Couto ETX, IEEE 802.1D, RFC 2328 OSPF) and
  Prior Art summary
- Remove outdated sections: indirect partition note, integration test
  gaps, DHT-based lookup reference
- Change "must elect a new root" to "must rediscover its new root"

Spanning tree design review (fips-spanning-tree.md):
- Rename "Root Election" to "Root Discovery" across docs
- Add "What Is a Spanning Tree?" introductory section
- Add parent selection intro explaining self-organization role
- Fix tree distance example: 4 hops, not 2
- Clarify timestamp field as advisory only
- Remove unimplemented ROOT_TIMEOUT and TREE_ENTRY_TTL from timing
  parameters and implementation status tables

Bloom filter design review (fips-bloom-filters.md):
- Add "What Is a Bloom Filter?" intro section
- Rewrite Purpose section to frame filters as routing path identification
- Correct FPR analysis (old values were 3-50x overstated)
- Add Filter Occupancy Model based on network size and tree position
- Fix filter expiration to describe actual MMP-based cleanup
- Combine Scale Considerations with Size Classes after Wire Format
- Fix stale FPR values in src/bloom/mod.rs comments

Session layer review (fips-session-layer.md):
- Add inline prior art attributions: Noise Protocol Framework, WireGuard,
  DTLS (RFC 6347), IKEv2 (RFC 7296), RFC 1191 PMTUD, Yggdrasil, NIP-44
- Replace warmup state machine ASCII art with SVG diagram
- Convert CoordsWarmup wire format code block to prose
- Add External References section with full citations

Level 5 implementation doc cleanup:
- Delete fips-software-architecture.md (redundant with protocol layer docs)
- Delete fips-state-machines.md (Rust tutorial, not protocol design)
- Add fipsctl command reference to README.md
- Update cross-references in fips-intro.md, docs/design/README.md,
  fips-transport-layer.md, fips-configuration.md

Fixes:
- Correct fd::/8 to fd00::/8 in fips-session-layer.md,
  fips-identity-derivation.svg, and fips-node-architecture.svg
- Fix config example MTU: 1197 → 1472 in fips-configuration.md

File organization:
- Move all SVG diagrams into docs/design/diagrams/ subdirectory
- Update all diagram references to use new paths

2026-02-24 17:32:37 +00:00

3.0 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 discovery, parent selection, coordinates
fips-bloom-filters.md	Bloom filter math: FPR analysis, size classes, split-horizon

Implementation

Document	Description
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-        │
              │          operation          │
              ▼              │              │
   fips-mesh-layer ◄────────┤              │
              │              │              │
              ▼              ├──► fips-spanning-tree
   fips-session-layer        │         │
              │              └──► 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.0 KiB Raw Blame History