Pp2pbuilders

learn

The educational home of p2pbuilders — handbook, Holepunch walkthroughs, Field Manual, rooms tracks, ecosystem scars, build write-ups, and patterns. Same corpus as the in-app #/learn hub.

Open in board app → Field Manual edition

The P2P Engineer's Field Manual

Our 7-day crash course — DHTs and Kademlia to hand-written binary protocols, NAT traversal, Noise handshakes and profiler flame graphs. Every day ends in a runnable lab. · read the designed edition ↗

  1. Start here: the 7-day syllabus 3 min — What the Field Manual covers, how the seven days fit together, and how to work through it.
  2. Day 1: Distributed Hash Tables & Kademlia 10 min — The XOR metric that quietly organizes every modern swarm.
  3. Day 2: BitTorrent & Hypercore 10 min — Two ways to move data with no server: a static swarm and a signed, append-only log.
  4. Day 3: UDP, TCP/IP & NAT Traversal 10 min — How two machines behind home routers manage to talk directly — the hardest, most-tested topic on the list.
  5. Day 4: Binary Protocols & Serialization 10 min — Why every serious P2P system hand-rolls its bytes — framing, varints, and zero-copy formats.
  6. Day 5: Cryptographic Primitives 10 min — Signatures, key exchange, AEAD, and the Noise handshake that secures every Holepunch connection.
  7. Day 6: High-Performance JS Networking 10 min — The event loop, buffers, backpressure, and the allocation discipline that separates a toy from a relay.
  8. Day 7: Profiling, Optimization & Integration 10 min — Flame graphs that prove your optimization worked — then build the whole stack end to end.

P2P Foundations

The ideas underneath everything we build — keys, logs, discovery, availability, trust. Start here if you are new to P2P.

  1. Why peer-to-peer 5 min — What breaks when everything lives on a server, and what we get back when it does not.
  2. Identity is a keypair 6 min — No signup, no recovery, no registry — you are your public key. What that buys and what it costs.
  3. Everything is a signed log 7 min — Append-only logs are the atom of P2P data. State is a fold over everyone’s logs.
  4. How peers find each other 6 min — DHTs, topics, and gossip: getting from "I know a hash" to "I have live sockets to strangers".
  5. Staying online without servers 6 min — The laptop-lid problem, and how dumb always-on storage (relays) solves it without recreating servers.
  6. Trust without a boss 8 min — Spam, sybils and moderation when nobody owns the network: cost, time, and chosen curators.

Holepunch walkthroughs

Hands-on tours of the building blocks: Pear, Bare, Hypercore, Hyperbee, Hyperdrive, Hyperswarm, Corestore, Autobase.

  1. Pear: run, stage, release, seed 8 min — The P2P runtime — running apps from pear:// links and shipping your own without a server.
  2. Bare: the small JS runtime 6 min — Node-shaped JavaScript without Node — why P2P apps run on Bare, and how to write portable code.
  3. Hypercore: the signed append-only log 8 min — The atom of the stack — append, read, replicate, verify. With runnable code.
  4. Hyperbee: a database on a log 7 min — An ordered key/value store encoded as Hypercore blocks — sorted scans, prefixes as tables.
  5. Hyperdrive: a filesystem on two cores 7 min — P2P file trees — how drives really store bytes, and the operational trap that follows.
  6. Hyperswarm: find peers by topic 7 min — The DHT + holepunching layer — join a 32-byte topic, get encrypted sockets to strangers.
  7. Corestore: many cores, one storage 5 min — Namespaced core management — one primary key, deterministic derived cores, one replication stream.
  8. Autobase: many writers, one view 8 min — How multi-writer works on single-writer logs: input cores, causal ordering, deterministic views.

Storyteller & Pear Baby Rooms

Our beginner lesson tracks. Baby Rooms takes you from zero to your first live room; Storyteller builds a real app one chapter at a time.

  1. Pear Baby Rooms 1: your first room 10 min — From zero to two machines chatting P2P: one topic, one swarm, ~40 lines, no server.
  2. Pear Baby Rooms 2: who said that? 12 min — Keypairs and signatures in the room: prove authorship, keep your name across restarts.
  3. Pear Baby Rooms 3: a room that remembers 12 min — Swap loose messages for Hypercores: history, catch-up for latecomers, and offline peers.
  4. Storyteller 1: a story is a log 10 min — Designing an op schema — the storytelling app as a worked example of thinking in append-only.
  5. Storyteller 2: passing the pen 10 min — Multi-writer coordination without a server: fold-with-branching vs. Autobase, and choosing between them.

Lessons from our ecosystem

Hard-won lessons from running p2pbuilders, peerit and HiveRelay in the wild. Scars included.

  1. The transport carries no authority 6 min — The audit finding that reshaped our engine: trust signatures, never the pipe they arrived through.
  2. Orphan-proof your outbox 6 min — How rotating an identity key silently disappeared posts — and the re-merge that fixed it.
  3. Seed the blobs core, not just the metadata 6 min — The drive that looked alive but had no bytes: a Hyperdrive is two cores, and relays must pin both.
  4. PoW + reputation: honest limits 7 min — What our anti-spam stack actually withstands — published attack math, and why layers beat walls.

Build articles

Write-ups of things we actually shipped: the terminal HN, the browser port, the relay fleet.

  1. Building the terminal HN 8 min — How the p2pbuilders TUI is put together: one readline loop, a backend of ops, and scope cuts that shipped it.
  2. One engine, two apps: porting to the browser 8 min — The PearBrowser port: reusing peerit’s gossip engine verbatim, and the one hook it needed to stay generic.
  3. HiveRelay: dumb storage that keeps P2P online 7 min — The relay fleet behind our apps — pin-by-key, durability proofs, and why relays must stay dumb.

Patterns for P2P apps

A working catalog of shapes that keep showing up in peer-to-peer apps — steal these.

  1. Data patterns: logs, LWW, tombstones, sticky names 9 min — The recurring shapes for P2P state: single-writer logs, fold-to-view, last-write-wins, hide-don’t-delete, first-writer-wins.
  2. Network patterns: topics, gossip, validate-on-ingest 8 min — The connectivity shapes: derived topics, key gossip, admission control at the merge, and relay pinning.
  3. App patterns: local-first UI, optimistic writes, honest status 8 min — Product-layer shapes: render from the local view, mint-then-show, identity UX, and telling users the truth.