# Themes — Opinionated Read-Orders 7 thematic clusters with recommended read-orders. Each cluster: 3-7 file pointers, prioritized so an agent new to the topic gets the highest signal-per-token first. --- ## Theme 1 — QUIC-by-pubkey stack (Brief Rank 1 + 3) Build SPT on iroh's `Endpoint::connect(pubkey, alpn)` with mDNS LAN-first fallback. 1. `repos/iroh.md` — full workspace map; start with §Integration points for SPT and §Suggested SPT integration shape 2. `repos/quinn.md` — QUIC fundamentals (iroh wraps a forked quinn called `noq`); focus on §Hole-punching and §Connection migration 3. `docs/INDEX.md` Cluster A (Iroh prototype stack) — pre-curated reading list for the Brief §5 recipe 4. `rfcs-specs/INDEX.md` RFC 6762 + XEP-0174 — mDNS wire format + production service-type template 5. `papers/INDEX.md` arxiv-2408-01791 — why QUIC HP wins (latency + migration) 6. `papers/INDEX.md` arxiv-2510-27500 — realistic 70% success rate (set expectations) 7. `articles/INDEX.md` blog-ipfs-tech-...rust-libp2p-bootstrap — production scale signal for the underlying stack --- ## Theme 2 — Zero-credential pairing (no account ever) How two SPT users on different networks introduce themselves the first time. 1. `repos/magic-wormhole.md` — full SPAKE2 + mailbox + transit walkthrough; cheat sheet at bottom is copy-paste-ready 2. `articles/INDEX.md` vlaicu-io-posts-wormhole — conceptual explainer (PAKE, wordlist UX, comparison to WebRTC/SCP/Croc) 3. `rfcs-specs/INDEX.md` noise-protocol §7 — XX (mutual auth) and IK (pre-known responder) handshake selection 4. `forums-wikis-videos/INDEX.md` videos/34c3 Trevor Perrin — authoritative Noise talk; why XX or IK 5. `docs/INDEX.md` `docs-rs-snow.html` — Rust Noise crate API 6. `rfcs-specs/INDEX.md` syncthing-device-ids — what a finalized pubkey identity looks like (TOFU + display string) 7. `docs/INDEX.md` `briarproject-org.html` — QR-at-first-contact alternative UX --- ## Theme 3 — LAN-first hybrid (Brief Rank 3, the prototype recipe) The minimum-surprise architecture: try mDNS, fall back to WAN via iroh. 1. `rfcs-specs/INDEX.md` RFC 6762 — mDNS spec (§§3, 5, 6, 8, 11, 15, 18 + Appendix A) 2. `rfcs-specs/INDEX.md` XEP-0174 — most directly transferable template for `_spt._udp.local.` + TXT records 3. `docs/INDEX.md` `docs-rs-mdns-sd-latest.html` — `ServiceDaemon::new/browse/register`, threading model, port 5353 Defender note 4. `rfcs-specs/INDEX.md` syncthing-localdisco-v4 — fallback pure-broadcast UDP (works when mDNS is firewalled); magic `0x2EA7D90B` 5. `repos/iroh.md` lines 102-118 — `iroh-mdns-address-lookup` external crate (was `discovery-local-network` feature in 0.90) 6. `forums-wikis-videos/INDEX.md` forum-duplicacy (Tailscale vs ZT) — independent confirmation that "L2 + mDNS feels like it works" --- ## Theme 4 — Privacy via onion-relay (Veilid track, Brief Rank 4) For users who prefer anonymity over latency. Reserve as opt-in mode. 1. `repos/veilid.md` — full embed surface; §Embed veilid-core (no daemon) is the only viable mode for SPT 2. `articles/INDEX.md` theregister-...veilid — "Tor for apps" positioning + crypto suite 3. `docs/INDEX.md` `veilid-com-how-it-works-networking.html` — bootstrap, network class, ping validation 4. `docs/INDEX.md` `docs-rs-tor-hsservice-latest.html` — Arti `OnionService` API (alternate path) 5. `articles/INDEX.md` forum-torproject-arti — Arti 1.4.6 HS resilience release notes (Windows-native usability) 6. `forums-wikis-videos/INDEX.md` wiki/veilid — one-paragraph framing --- ## Theme 5 — Mesh-VPN coordinator anti-patterns What NOT to build, with concrete patterns worth borrowing selectively. 1. `repos/vpn-cluster.md` — 514-line deep dive on nebula + innernet + headscale; section §Cross-cluster patterns + §Relevance ranking lays out the borrow list 2. Brief §2.6 + §3 — disqualifications (Tailscale, ZeroTier, Headscale, Nebula, Innernet, Yggdrasil, WireGuard) 3. `articles/INDEX.md` dev-to-byteknight-yggdrasil — concrete friction (`sudo yggdrasilctl addPeer ...`) 4. `forums-wikis-videos/INDEX.md` forum-duplicacy + dietpi — community sentiment on Tailscale/ZT/WG 5. `repos/low-priority.md` cjdns + yggdrasil-go — SKIP rationale (daemon shape, wrong language) 6. Specifically borrow: headscale's `NodeStore` (copy-on-write atomic.Pointer Snapshot) + innernet's invitation-TOML + nebula's lighthouse-mediated 3-message punch signaling — see `repos/vpn-cluster.md` §Relevance ranking --- ## Theme 6 — DHT-as-rendezvous (Brief Rank 5, no operator at all) Mainline DHT as global yellow-pages; Magic Wormhole for first-contact trust. 1. `forums-wikis-videos/INDEX.md` wiki/mainline-dht — 16–28 M concurrent users, KRPC=bencode-over-UDP, 5-min token rotation 2. `docs/INDEX.md` `docs-rs-mainline.html` — `Dht::client/server`, `as_async()`, feature flags 3. `papers/INDEX.md` arxiv-2402-09993 — Kademlia scalability limits (NAT'd peers + TTL) — use DHT as yellow-pages only, not low-latency routing 4. `docs/INDEX.md` `libp2p-io-docs-kademlia-dht.html` — concept refresher 5. `repos/magic-wormhole.md` — pairing-only feature set for first-contact trust 6. `papers/INDEX.md` arxiv-2402-16201 — Honeybee Sybil resistance if random peer sampling becomes load-bearing --- ## Theme 7 — Binary-size discipline (cross-cutting; required for "single static binary") Every Rust crate in the stack contributes; this is the audit checklist. 1. `repos/low-priority.md` §min-sized-rust — canonical recipe checklist + nightly-knobs roadmap; SPT TODO list at bottom 2. `articles/INDEX.md` dev-to-ahaoboy-...bloaty-metafile — 11MB → 4.5MB worked example; rustls-tls swap is the biggest single win 3. `repos/iroh.md` §Binary size knobs — `tls-ring` vs `tls-aws-lc-rs`; default features to strip; mandatory transitive deps (hickory-resolver + reqwest = heaviest) 4. `repos/quinn.md` §Binary size knobs — `runtime-tokio` + `rustls-ring` minimum; drop `platform-verifier` and `bloom` 5. `repos/rust-libp2p.md` §Binary size knobs — per-protocol opt-in; `default-features = false` then enumerate 6. `repos/magic-wormhole.md` §Binary size knobs — pairing-only = `default-features = false` 7. `repos/veilid.md` §Binary size knobs — `geolocation` trap door (pulls reqwest); realistic floor >10 MB even minimal --- ## Theme 8 — Agent-protocol layering (MCP / A2A complementarity) Where SPT fits below MCP / A2A and why those don't solve the same problem. 1. `articles/INDEX.md` anthropic-com-news-mcp — MCP launch (local stdio/SSE) 2. `articles/INDEX.md` kdjingpai-com-...zhengshifaa — MCP 2025 roadmap (remote/registry/OAuth2/hierarchical) 3. `articles/INDEX.md` ibm-com-...agent2agent — A2A architecture (AgentCard, Task, Message) 4. `articles/INDEX.md` microsoft-...autogen — in-process orchestration (NOT transport) 5. Brief §2.7 (table) + §3 (MCP/A2A disqualification reasoning) --- ## If you read only 5 files in the whole corpus, read these 1. **`repos/iroh.md`** — Rank 1 candidate workspace; if iroh is the answer, this 324-line map is the integration spec. Surfaces the obsolete-vocab caveats (NodeId→EndpointId, discovery-local-network feature gone, noq fork required). 2. **`papers/INDEX.md` arxiv-2510-27500** (via the index entry; PDF on disk if you need full text) — 2025 production measurement of DCUtR overrides Brief's older numbers and tells SPT the realistic SLA (70% direct, plan for 30% needing relay, TCP ≈ QUIC, relay centralization risk). 3. **`repos/quinn.md`** — QUIC fundamentals that everything else assumes. Covers Windows specifics, hole-punching, connection migration, 0-RTT, all in 155 lines. 4. **`repos/magic-wormhole.md`** — pairing UX is non-optional and Magic Wormhole is the only mature Rust implementation. Cheat sheet at the bottom is the entire SPT pairing ceremony. 5. **`repos/vpn-cluster.md`** — 514-line cross-cluster review covering nebula + innernet + headscale. Reading this once tells you (a) which coordinator patterns are worth borrowing (headscale NodeStore, innernet invitations, nebula punch signaling), (b) which to avoid (all the daemon/CA stuff), and (c) why none of the existing mesh VPNs fit SPT's constraints. (Honorable mentions for slot 6: `rfcs-specs/INDEX.md` if you need wire-format magic constants, or `README.md` + `topics.md` in this directory to navigate the rest.)