> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · 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](https://coracle.social)
**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:

```bash
$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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/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`).