Nostr Agent Onboarding · start here · index · source: nostr-dev/docs/sources/hodlbod-book.md · snapshot 2026-10-10

Paths such as ~/Documents/…, ~/Production Environment/…, repos/… and services on localhost refer to the author's workstation and are not available to you — read them as worked examples of a setup you can recreate.

Hodlbod — "Building Nostr"

Source: https://github.com/coracle-social/building-nostr Author: Jonathan Staab (Hodlbod), creator of Coracle Status: Open-source book on GitHub. Cloned offline at ~/Documents/nostr-dev/repos/building-nostr/ for direct reading. The repo is gitignored from this workspace; use it as a read-only reference.

Why this book matters

Hodlbod is the most prolific writer of opinionated, post-protocol-draft design advice for Nostr. NIPs tell you the rules; Hodlbod tells you the trade-offs. The book is described in its own README as:

A book intended for developers who want to get familiar with nostr on a deeper level so that they can design decentralized applications and model data more effectively.

He also runs the Coracle client, which has been the leading testbed for the outbox model and per-relay context (per-note relay selection, governance via NIP-43/86, etc. — see the OpenSats summary).

How to read it

The full book (~1500 lines of markdown) is in a single file. Read locally:

$EDITOR  ~/Documents/nostr-dev/repos/building-nostr/content/book.md   # full text
$EDITOR  ~/Documents/nostr-dev/repos/building-nostr/summary.md         # ~3-page summary

The repo also has a build/ and export/ directory with rendered HTML/PDF; ignore those when reading.

Hodlbod's design lines that shaped the synthesis

• "Digital signatures decouple data storage from authentication." This is cited verbatim in §1 of design-synthesis.md. It's the philosophical core of the protocol.
• Per-event routing matters more than per-client routing. NIP-65 alone doesn't cover communities, DMs, or topical feeds. Don't pretend it does.
• Relays are services, not infrastructure. NIP-43 (membership lists) and NIP-86 (relay management API) — both Hodlbod-driven — formalize relays as things with policies, members, and intent. A relay should be allowed to say "I am a community for X" and a client should be allowed to honor that.
• Stronger relay controls + smoother synchronization. Coracle's recent releases focus on making the outbox model visible to users rather than hiding it.

Related Hodlbod artifacts

• Coracle — https://coracle.social — the client that ships his ideas first.
• Flotilla / Chachi — Hodlbod's group/community-relay tooling. See his long-form note "A Guide for Relay-Based Group Implementations" on njump: https://njump.me/naddr1qvzqqqr4gupzp978pfzrv6n9xhq5tvenl9e74pklmskh4xw6vxxyp3j8qkke3cezqqxnzde5xyersd33xscrwwfh5ekns6
• He posts notes on Nostr regularly. His npub: npub17plqkxhsv66g8quxxc9p5t9mlhsz9c5sjzs4dwlhq5zlfvprrlrq57jrt5 (search via nak req -k 1 -a 7c3f0b1ae0cd6907838c6c1434b2effdf02171489053856efb828bf4b023e7e3 -l 5 wss://relay.nostr.band).