# Nostr Agent Onboarding — every document (llms-full.txt)

Snapshot 2026-10-10. Source site: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/ · index: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt
Each document below starts with a line `=== FILE: <url> ===`.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md ===

# Nostr Agent Onboarding — start here

> **You are an AI agent and someone pointed you at this site.** It is a
> curated knowledge base for building on, designing for, and reasoning about
> **Nostr**. Read this page first (≈5 minutes). It tells you what Nostr is, the
> rules you must not break, and which document to read for the task in front
> of you. Everything here is plain Markdown; every page has a `.md` twin.
>
> Snapshot: **2026-10-10** · 40 documents · served as an nsite (the
> site is itself a set of signed Nostr events — see §7).

## 0. How to read this site

| If you have… | Read |
|---|---|
| 5 minutes | This page. |
| ~30 minutes / ~120 kB of context | [`/llms-core.txt`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms-core.txt) — the five-part core synthesis + the design synthesis + the kind cheatsheet, concatenated. |
| A specific task | The **task router** in §3, then only the documents it names. |
| A large context window | [`/llms-full.txt`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms-full.txt) — every document, concatenated (~510 kB). |
| A crawler | [`/llms.txt`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) (index), [`/index.json`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/index.json) (machine-readable catalog), [`/sitemap.xml`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/sitemap.xml). |

Fetch the **`.md`** URLs, not the `.html` ones, whenever you can: they are the
canonical text, with no navigation chrome.

## 1. Nostr in one paragraph

Nostr is a description, not a system: **signed JSON events** plus **dumb,
plural, interchangeable relays**. A user mints a secp256k1 keypair, signs
events with it, and publishes them to any number of WebSocket servers
(relays); anyone can verify an event no matter where they got it from.
Signatures move authenticity into the data itself, which frees identity from
platforms and storage from trust. The price: there is **no global view, no
consistency, and no guarantees** — only routing heuristics, redundancy, and
webs of trust. Everything good about Nostr (credible exit, rug-pull
resistance, permissionless building) and everything hard about it (discovery,
spam, key loss, sync) follows from that one trade. To build on Nostr is to
accept the trade explicitly.

The whole wire protocol: client → relay `EVENT`, `REQ` (filters on `ids`,
`authors`, `kinds`, `since`/`until`, `limit`, `#<single-letter-tag>`),
`CLOSE`; relay → client `EVENT`, `OK`, `EOSE`, `CLOSED`, `NOTICE`, `AUTH`.
Event = `{id, pubkey, created_at, kind, tags, content, sig}`. Extensions are
**NIPs**, at <https://github.com/nostr-protocol/nips>.

## 2. Rules an agent must not break

These are the failures that recur when software (and especially
AI-written software) touches Nostr. Each links to where it is argued in full.

1. **Never ask for, handle, or store a user's secret key (`nsec`).** Sign
   through a signer: NIP-07 (browser extension), NIP-46 (remote "bunker"),
   NIP-55 (Android, e.g. Amber). A web client must never see an nsec.
   → [signer-login](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md),
   [how to develop §keys](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md)
2. **One purpose, one keypair.** A bot, service, or site gets its own freshly
   minted key. Never reuse a human's key for a service, and never publish
   kind 0 / 3 / 10002 (profile, follows, relay list) from an identity whose
   profile you don't own. Replaceable events overwrite: one wrong publish
   destroys someone's data.
3. **Default to regular events.** Use replaceable (0, 3, 10000–19999),
   addressable (30000–39999) or ephemeral (20000–29999) only when you can
   state in writing why discarding history is correct.
   → [kind cheatsheet](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md)
4. **Reuse before you invent.** Check the kind registry, `nak nip <n>`, and
   probe live relays (`nak req -k <kind> -l 5 <relay>`) before allocating a
   kind. Inventing a duplicate kind gets you fragmentation and zero readers.
   → [NIPs kind registry](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md)
5. **Tags are the data model; `content` is for humans.** Single-letter tags
   are relay-indexed and queryable. Don't put structured data as JSON in
   `content`.
6. **Never destroy data you didn't understand.** When updating a shared
   replaceable event (profile, follow list, mute list…), mutate the original —
   keep unknown tags and fields — instead of regenerating it from your model.
7. **Routing is correctness, not optimisation.** Read an author from their
   *outbox* relays (NIP-65 kind 10002 `write`), deliver mentions to recipients'
   *inbox* relays, DMs to their kind 10050 list. No hard-coded "big five"
   relay list in a general-purpose client.
   → [how it should work](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md)
8. **Every relay is unreliable and every claim is unverified.** Verify every
   signature (discard invalid ones), dedupe by id, distrust `created_at`,
   relay hints and single-relay answers. Sanitize all content.
9. **Signed public events are permanent.** Nostr is publicity technology —
   not private by default. Test against throwaway local relays (`nak serve`, a
   Khatru scaffold), not public ones; publish to the public network only what
   is meant to be public, forever.
   → [testing](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/testing.md)
10. **"Relay said OK" is not done.** Verify outcomes by reading back from the
    network (and, for sites, by fetching the gateway).
11. **Lean into the paradigm.** If you find yourself wrapping Nostr in a REST
    API with server-held state and usernames, stop. Auth, identity, storage
    and inter-process messaging come with the protocol.
12. **Hand off what you don't render.** Use NIP-89 handlers (kind 31990) for
    unknown kinds and add a NIP-31 `alt` tag to every exotic event you emit.

## 3. Task router

| Your task | Read, in this order |
|---|---|
| Understand Nostr from zero | [01 What Nostr is](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/01-what-nostr-is.md) → [02 How it should work](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) |
| Build a client / app | [03 How to develop](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md) → [signer-login](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) → [testing](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/testing.md) |
| Design events or a new kind | [04 How to design](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md) → [design synthesis](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) → [kind cheatsheet](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md) → [kind registry](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md) |
| Relay selection, outbox, spam | [02 How it should work](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) → [outbox model](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/outbox-model.md) → [fiatjaf's vision](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md) |
| Implement login / signing | [signer-login](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) (NIP-07 / NIP-46 / NIP-55, the three-keys model, known-bad library code) |
| Write Go | [Go baseline: `fiatjaf.com/nostr`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/go-client-baseline.md) — `nbd-wtf/go-nostr` is archived |
| Write JS/TS | [03 How to develop §tooling](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md) + [examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/) |
| Publish a static site (nsite) | [nsite publishing](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) → [known issues §7](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) |
| Store files / media | [Blossom](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md) |
| Ship an Android app | [Zapstore source](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/zapstore.md) → [Zapstore publishing](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md) |
| Git on Nostr (NIP-34 / GRASP) | [GRASP as structural layer](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/grasp-as-structural-layer.md) → [going public](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/going-public.md) |
| Provable time (OpenTimestamps) | [Merkle OTS extension](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/merkle-ots-extension.md) |
| Nostr keys as network identity | [FIPS](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fips.md) |
| Write tests | [testing](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/testing.md) |
| Know what's current / open | [05 Current frontier](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/05-current-frontier.md) |
| Understand the people & disagreements | [voices: fiatjaf](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md), [No Solutions podcast](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/README.md), [Constant](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/constant/README.md) |
| Read primary sources | [NIP-01 full text](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nip-01.md), [Hodlbod's *Building Nostr*](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/hodlbod-book.md), [nostrdesign.org](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nostr-design-principles.md) |

## 4. Live disagreements you should know about

Nostr has no authority, and its principal voices disagree. Don't flatten
these into one "correct" answer when advising a human — name the trade-off.

- **What the invention is:** keys/signatures (Hodlbod) vs. clients talking to
  many independent relays (fiatjaf) vs. the whole paradigm — keys *and*
  events *and* relays, taught explicitly (Constant).
- **Spam filtering:** relay-side, via filtered read relays (fiatjaf) vs.
  client-side web of trust (Martti Malmi).
- **Onboarding:** hide keys and relays to reduce friction (much of the client
  scene) vs. teach the paradigm — "relays and keys are not UX issues, they ARE
  the UX" (Constant).
- **The NIPs repo:** keep numbered specs (Hodlbod) vs. a bare kind registry
  plus competing prose guides (fiatjaf, "The end of NIPs").
- **DMs:** whether private messaging belongs on a publication protocol at all.

## 5. Caveats — read before trusting a detail

- **Dated knowledge.** Facts were verified on the dates stated inside each
  document (mostly August–September 2026). Library versions, relay policies
  and NIP texts change; re-check anything load-bearing against
  <https://github.com/nostr-protocol/nips> and the live network.
- **Workstation references.** Many documents were written for one
  developer's workstation and mention paths like `~/Documents/nostr-dev/…`,
  `~/Production Environment/…`, or local services on `localhost:8080/8081`.
  **Those do not exist for you.** Treat them as worked examples of a setup you
  can recreate (a local relay, a local Blossom server, `nak`), not as
  resources you can reach. Pages that contain such references carry a note.
- **Curated, opinionated.** The synthesis takes positions (see §4) and says
  so. The `voices/` section is the primary-source evidence behind them.

## 6. Tools worth knowing by name

- **`nak`** — the Nostr army knife (fiatjaf): keys, encode/decode, `req`,
  `event`, `serve` (throwaway relay), `bunker`, `blossom`, `nsite`, `nip <n>`.
  <https://github.com/fiatjaf/nak>
- **Libraries** — Go: `fiatjaf.com/nostr` (incl. the `khatru` relay
  framework). JS/TS: `nostr-tools`, NDK, Applesauce. Rust: `rust-nostr`.
  Android: Quartz (Amethyst).
- **References** — <https://nostrbook.dev>,
  <https://undocumented.nostrkinds.info>, <https://nostrapps.com>,
  <https://github.com/nostrability/nostrability>.

## 7. Provenance

Curated by **Constant** (Wouter Constant, techno-ethica.com,
`npub1t6jxfqz9hv0lygn9thwndekuahwyxkgvycyscjrtauuw73gd5k7sqvksrw`) from two
working knowledge bases: `nostr-dev` (the practitioner's layer — patterns,
measured gotchas, vendored sources) and `Nostr-exp` (the synthesis — what
Nostr is, how it should work, how to develop and design, the voices).
Compiled with AI assistance.

This site is an **nsite** (NIP-5A): a kind 15128 manifest signed by
`npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe`, listing every file by SHA-256, with the blobs on Blossom
servers. You can verify that what you fetched is what was published:

```bash
nak req -k 15128 -a 6f9f9da110d485c9d3f760269041a51e41bef47350249d02237a903213f561e0 --limit 1 wss://relay.nsite.lol \
  | jq -r '.tags[] | select(.[0]=="path") | "\(.[2]) \(.[1])"'
# then: sha256sum of any file you fetched must match its path tag
```

Text from upstream NIPs is MIT-licensed; quotations remain their authors'.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/00-overview.md ===

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

# Nostr-exp — a Nostr knowledge environment

A curated, opinionated description of **what Nostr is, how it should work,
how to develop for it, and how to design on it** — synthesized from the
primary voices of the protocol and kept honest about where they disagree.

Built 2026-08-31 from four research streams: fiatjaf's complete web essays
(21 annotated), fiatjaf's on-Nostr publications (24 articles + 425 notes
sampled from his relays), Constant's public Nostr corpus (721 notes, 19
long-form articles, plus web presence), and the No Solutions podcast (37
episodes, 8 analyzed from full transcripts) — layered on top of the
knowledge already codified in the sibling `~/Documents/nostr-dev` workspace
(Hodlbod's *Building Nostr* read in full, NIP-01, the NIPs registry, the
outbox literature, nostrdesign.org, the OpenSats report, Nostr Rising).

## Read this first: `core/`

The synthesis, in reading order:

| Doc | Question it answers |
|---|---|
| [`core/01-what-nostr-is.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/01-what-nostr-is.md) | What is Nostr? Events, kinds, relays, NIPs, what it is *not*, why not the alternatives. |
| [`core/02-how-it-should-work.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) | The intended architecture: the routing problem, outbox and its limits, hints, spam, no-global, the local relay, the failure model. |
| [`core/03-how-to-develop.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md) | The practitioner's layer: build pieces not platforms, the dev loop, keys and signing, fault tolerance, onboarding, anti-patterns, definition of done. |
| [`core/04-how-to-design.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md) | The design methodology: schema → class → routing → failure model, kind allocation, privacy, communities, value-for-value, trust, the arbitrating principles. |
| [`core/05-current-frontier.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/05-current-frontier.md) | Where the live edge is (late 2026): relay feeds, Blossom/nsites/Zapstore, signers, TEPP, FIPS, the AI convergence, open problems. |

## The voices: `voices/`

Primary-source research with distillations — including where the principals
*disagree*, which is the most instructive part:

- [`voices/fiatjaf/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md) — the creator. Relay-centric,
  anti-super-peer, "censorship-resistance is emergent client behavior."
  `essays.md` (web bibliography) + `on-nostr.md` (his relay publications).
- [`voices/constant/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/constant/README.md) — Constant (Wouter Constant,
  techno-ethica.com), owner of this workspace: teach the paradigm, relays
  for curation, identity ≠ key, TEPP, OpenTimestamps. `research.md` is the
  full corpus pass.
- [`voices/no-solutions/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/README.md) — Gigi & Pablo
  Fernandez's Sovereign Engineering podcast: no-global, rug-pull resistance,
  trade-offs out loud, the local relay, Nostr as AI substrate. `episodes.md`
  has the full episode table + transcript notes.

Key live disagreements to know about: keys-vs-relays as "the point"
(Hodlbod vs fiatjaf), spam filtering relay-side vs client-side (fiatjaf vs
Malmi), teach-the-paradigm vs hide-the-complexity (Constant vs much of the
client scene), whether the NIPs repo should exist (fiatjaf vs Hodlbod), and
whether DMs belong on Nostr at all (Constant/hzrd149 vs Malmi).

## Reference: `sources/`

Vendored and summarized source docs, seeded from `nostr-dev/docs/sources/`:
NIP-01 (full text), the NIPs kind registry, the outbox model, Blossom,
fiatjaf's "vision" essay, Hodlbod's book pointer, nostrdesign.org
principles, the OpenSats client report, Nostr Rising episodes, video
pointers. Machine-local paths inside these files (e.g.
`repos/building-nostr/`) refer to the `~/Documents/nostr-dev` workspace,
which also holds the tooling (nak, ngit, local relay/GRASP/Blossom stack)
for putting any of this into practice.

**`nostr-dev/docs/sources/` is canonical** — these are copies, last synced
2026-09-21, and it also carries sources this directory does not (`fips.md`,
`zapstore.md`). Refresh there, then copy across; the refresh recipe is in
`nostr-dev/docs/README.md`. Likewise, the *how* layer lives there: the
`patterns/` directory (signer login, nsite publishing, the Go baseline,
Zapstore publishing) and [`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) are where this synthesis turns
into working code.

## The one-paragraph version

Nostr is a description, not a system: signed JSON events plus dumb,
plural, interchangeable relays. Signatures move authenticity into the data
itself, which frees identity from platforms and storage from trust; the
price is that there is no global view, no consistency, and no guarantees —
only routing heuristics, redundancy, and webs of trust. Everything good
about it (credible exit, rug-pull resistance, permissionless building) and
everything hard about it (discovery, spam, key loss, sync) follows from
that one trade. To work on Nostr is to accept the trade explicitly: build
small interoperable pieces, route events deliberately, state your
trade-offs out loud, and keep the barrier to entry for the next client low
— because the number of independent clients, not the user count, is the
protocol's real health metric.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/01-what-nostr-is.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/core/01-what-nostr-is.md` · snapshot 2026-10-10

# What Nostr is

> Part 1 of the core synthesis. Read this first. Sources: NIP-01
> ([`../sources/nip-01.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nip-01.md)), Hodlbod's *Building Nostr* ([`../sources/hodlbod-book.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/hodlbod-book.md)),
> fiatjaf's essays ([`../voices/fiatjaf/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md)), and the NIPs registry
> ([`../sources/nips-readme-kinds.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md)).

## The one-sentence version

Nostr — *Notes and Other Stuff Transmitted by Relays* — is an open protocol in
which **users sign JSON events with their own cryptographic key and publish
them to any number of dumb, interchangeable servers called relays**. That is
the whole protocol. Everything else is convention layered on top.

## The load-bearing move: signatures decouple authentication from storage

On the legacy internet, knowing that "person X said Y" requires trusting the
server that stores Y. Data that is not cryptographically signed is tightly
coupled to custody: only the platform can attest to its authenticity, which is
exactly what makes the platform indispensable — and exactly what lets it
censor, surveil, and lock users in.

Nostr's single architectural move is to break that coupling. A Nostr event
carries its author's public key, a hash of its own contents (`id`), and a
Schnorr signature over that hash. Anyone can verify it; nobody can forge it;
and — crucially — **it does not matter where you got it from**. An event is
equally valid coming from a relay, an email attachment, a USB stick, or a
carrier pigeon. In Hodlbod's formulation: *digital signatures decouple data
storage from authentication.*

Three consequences fall out, and together they are the protocol's entire value
proposition:

1. **Identity is user-generated.** An identity is a secp256k1 keypair you mint
   yourself (`npub…`/`nsec…` in bech32 form). No registration, no issuer, no
   one who can revoke it.
2. **Relays are interchangeable mirrors, not authorities.** Any relay can drop
   you; none can silence you, because your followers can fetch the same signed
   events from any other relay — or from you directly.
3. **Clients are replaceable views.** Because data and identity live outside
   any application, users have *credible exit*: leave a client and you keep
   your identity, your data, and your whole social graph. Interoperability is
   not a feature of Nostr apps; it is the point of them.

Note a live difference in emphasis between the principals here. Hodlbod's
framing (above) is key-centric: signatures are the move, relays are downstream.
fiatjaf inverts it: keys on their own are "meaningless" — "having a key is
meaningless if you cannot publish messages to where the people you're trying
to reach can read them" — and the actual invention is **clients talking to
many independent, mutually-distrusting servers at once**. On his account the
keys exist to make that multi-relay architecture safe, not the other way
around. Both framings agree on every practical consequence; keep both in your
head, because each catches mistakes the other misses (key-worship without
reach; relay-craft without verifiable data). See [`../voices/fiatjaf/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md).

## The event: one data type for everything

Everything on Nostr is an event:

```jsonc
{
  "id":         "<sha256 of the serialized event>",
  "pubkey":     "<author's public key, hex>",
  "created_at": 1682377261,            // unix seconds, author-asserted
  "kind":       1,                     // 16-bit integer content type
  "tags":       [["p", "<pubkey>"], ["e", "<event-id>", "<relay-hint>"]],
  "content":    "usually human-readable text",
  "sig":        "<schnorr signature of id>"
}
```

Design decisions embedded in this shape, all deliberate:

- **Kinds are numbers, not names.** In a system built on signed, immutable
  data, names can never be renamed — and names smuggle in meaning that varies
  by reader. Integers are meaningless, so *usage* determines meaning, the way
  natural language works. The registry of kinds (see
  [`../sources/nips-readme-kinds.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md)) is a dictionary written after the fact,
  not a schema enforced up front.
- **Tags are the data model.** `content` is for humans; structured data goes
  in tags — a list of string-lists, ordered, with repeatable keys.
  Single-letter tags (`e`, `p`, `a`, `d`, `t`, …) are indexed by relays and
  therefore queryable; multi-letter tags are payload only.
- **Timestamps are author-asserted and second-granularity.** Nostr punts on
  distributed time on purpose: there is no ordering authority, and pretending
  otherwise (with millisecond precision, say) would be a lie. If you need
  provable time, anchor externally (NIP-03 / OpenTimestamps); otherwise the
  social layer — reputation — handles dishonest clocks.
- **The event id is a content hash**, which makes regular events referentially
  transparent: if you hold an id, the content can never change under you.

### Kind ranges: the storage contract

The kind number also selects the relay's storage behavior — the one place
where behavior and data got coupled (Hodlbod considers this a design wart, but
it is load-bearing today):

| Class | Range | Relay keeps | For |
|---|---|---|---|
| **Regular** | 1–2, 4–44, 1000–9999, 40000+ | everything | notes, replies, reactions — the default |
| **Replaceable** | 0, 3, 10000–19999 | latest per `(pubkey, kind)` | profile, follow list, relay list |
| **Ephemeral** | 20000–29999 | nothing | live signaling, auth, in-flight RPC |
| **Addressable** | 30000–39999 | latest per `(pubkey, kind, d-tag)` | articles, repos, lists — replaceable with cardinality |

Addressable events are referenced by *address* (`kind:pubkey:d-tag`, encoded
as `naddr…`) instead of by id, because their content is expected to change.
The trade-off is real: replaceability discards history and invites race
conditions when two clients update the same event concurrently. **Default to
regular** unless you can say in writing why throwing information away is
correct. (More in [`04-how-to-design.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md).)

## Relays: easy, dumb, and plural

A relay is a WebSocket server that stores events and answers queries. The full
protocol surface is a handful of verbs:

- Client → relay: `EVENT` (publish), `REQ` (subscribe with filters), `CLOSE`
- Relay → client: `EVENT` (deliver), `OK` (accept/reject), `EOSE` (end of
  stored events), `CLOSED`, `AUTH` (NIP-42 challenge)

A filter matches on `ids`, `authors`, `kinds`, `since`/`until`, `limit`, and
indexed tags (`#e`, `#p`, `#t`, …). That's the entire query language. Anything
fancier — full-text search (NIP-50), counting, analytics — is a per-relay
extension, not the protocol.

Relays are "easy," not "simple" (Rich Hickey's distinction): WebSockets over
HTTP over TCP is a boring, gate-kept stack — but it is *deployable by anyone
this afternoon*, and that is the property that matters. Because the interface
is minimal, there are hundreds of independent relay implementations and
thousands of running relays, and none of them is special.

What relays legitimately do beyond storage:

- **Curation and access control** (via NIP-42 `AUTH`): a relay may serve one
  community, one topic, paying members, or a single user. This makes relays
  *services with intent*, not commodity infrastructure — and that is a
  feature. A relay with no distinctive value proposition has no business
  model, and unfunded infrastructure re-centralizes.
- **Transport brokering**: because a relay is a publicly addressable
  mailbox, two programs can talk through one by exchanging (usually
  encrypted, often ephemeral) events. This is how remote signers (NIP-46),
  wallets (NIP-47), and data vending machines (NIP-90) work — services
  addressed by pubkey instead of IP address.

## NIPs: the protocol is descriptive, not prescriptive

Protocol extensions are documented in NIPs — "Nostr Implementation
Possibilities" — curated at <https://github.com/nostr-protocol/nips>. The
governing norms:

- **Implementation first.** A NIP documents what running code already does;
  the repo requires interoperating implementations before merging. Anyone can
  ship a new kind tomorrow without asking permission — adoption, not
  approval, decides what becomes "the protocol."
- **Specs are written for humans.** Brief, readable, hackable — the opposite
  of standards-body prose.
- **"There should be no more than one way of doing the same thing."** An
  ideal, not a law — but the burden of proof is on the person diverging.

This is what *Building Nostr* calls **radical openness**: the protocol is
defined by its implementations, standardization is discovery rather than
invention, and the messiness (overloaded tags, race-prone replaceables,
half-baked NIPs) is the accepted cost of a protocol no company can capture.
Nostr is the JavaScript of protocols: hacked together, full of warts, alive.

Even the NIP process itself is contested from within: fiatjaf's 2025 essay
"The end of NIPs" proposes dissolving the repository into a bare kind-number
registry plus competing prose guides, on the grounds that spec bureaucracy
confers unearned "officialness," lets dead ideas linger, and — worst — trains
developers to translate event schemas into UI while skipping the actually
hard part, relay choice. Whether or not the repo survives, take the diagnosis
seriously: the registry function (don't collide on kinds) is the essential
part; the prose is commentary.

## What Nostr is not

- **Not a blockchain.** No consensus, no global state, no token. Events are
  cheap, unordered, and duplicable. (Bitcoin appears only at the payments
  layer, as zaps — see [`04-how-to-design.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md) §value-for-value.)
- **Not peer-to-peer.** Deliberately client-server, because P2P fights the
  grain of the modern internet. P2P transports can be added as progressive
  enhancement; relays are the reliable baseline.
- **Not private by default.** Nostr is **publicity technology**. A signed
  public event is a permanent, attributable, analyzable record; signatures
  *remove deniability*. Privacy is opt-in per use case: NIP-44 encryption,
  NIP-59 gift wrap, NIP-17 DMs, closed relays. Constant's blunter version:
  "Nostr is a protocol for PUBLICations, it is right there in the word" — a
  structurally bad fit for DMs and "encrypted privacy" things in general.
  Design with this in mind and say it out loud in anything you build.
- **Not consistent.** In CAP terms Nostr chooses availability and partition
  tolerance, always. There is no "the network" to have a view of — only the
  relays you happened to ask. Any design that assumes a global view is
  fighting the protocol and will lose.

## Why not the alternatives

One paragraph each, from *Building Nostr*'s appendix; the pattern to notice is
that every alternative gives up one of the two essentials — user-held keys or
storage-independent data:

- **ActivityPub / Matrix (Mastodon et al.)**: federation of *home servers*
  that own identity and storage. Your admin can deplatform you and your data
  is unsigned, so there is no credible exit — the centralized model
  replicated at smaller scale, with less accountable admins.
- **Secure Scuttlebutt**: the spiritual ancestor — cryptographic identity,
  dumb pubs — but events form per-device hash chains, so you must sync a
  whole feed to validate one message, one key can't be used from two devices,
  and partial replication is impossible.
- **Pubky**: cryptographic identity + DHT-based discovery (genuinely better
  bootstrapping than Nostr's), but content lives unsigned on a single home
  server. Right identity, wrong storage.
- **Bluesky / atproto**: signed data and a sophisticated architecture, but
  the insistence on a global network view requires firehose relays and app
  views so expensive that only Bluesky-the-company runs them. Centralization
  by capital cost.

Nostr is the only design in this space with **both** user-held cryptographic
identity **and** decentralized, redundant, signed storage. It buys this with
inconsistency, jank, and unsolved problems (key rotation above all). That
trade is the protocol.

## Vocabulary quick reference

| Term | Meaning |
|---|---|
| event | signed JSON object; the universal data unit |
| kind | integer content type; selects semantics + storage class |
| relay | WebSocket event repository; interchangeable, plural |
| client | any app that signs/reads events on a user's behalf |
| NIP | a documented protocol convention |
| npub / nsec | bech32 public / secret key |
| nevent / naddr / nprofile | bech32 pointers (id / address / pubkey) with optional relay hints |
| d-tag | user-chosen identifier that keys an addressable event |
| outbox / inbox | relays a user writes to / accepts mentions & DMs at (NIP-65) — see [`02-how-it-should-work.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) |
| zap | Bitcoin micropayment bound to an event (NIP-57 lightning, NIP-61 ecash) |
| WoT | web of trust — follow-graph-derived reputation |


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/core/02-how-it-should-work.md` · snapshot 2026-10-10

# How Nostr should work

> Part 2 of the core synthesis: the *intended* network architecture — what
> keeps Nostr decentralized when it is used correctly, and what quietly
> re-centralizes it when it isn't. Sources: *Building Nostr* ch. 4, NIP-65,
> fiatjaf's "A vision for content discovery" ([`../sources/fiatjaf-vision.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md)),
> the Outbox literature ([`../sources/outbox-model.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/outbox-model.md)), OpenSats client report
> ([`../sources/opensats-advancements.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/opensats-advancements.md)).

## The routing problem is the real problem

Signatures make events valid anywhere; they do not make events *findable*
anywhere. Decentralization therefore stands or falls on the **routing
problem**:

1. Where should a given event be **sent**?
2. Where should a given query be **asked**?

Get this wrong in either of the two obvious ways and the network degrades:

- **Naïve replication** ("blast everything to every relay"): every relay must
  store everything, small relays become impossible, and the network collapses
  into a few mega-relays. That is redundant vertical scaling, not
  decentralization.
- **Fixed relay lists** ("just use these 5 popular relays"): the popular
  relays become de facto platforms. If they drop you, your followers cannot
  find you, and the censorship-resistance story is over.

This is not hypothetical. fiatjaf's 2024 experiment ("Nostr is not
decentralized nor censorship-resistant") published two identical notes — one
to three popular relays, one only to his own relay, announced exactly where
clients are supposed to look (his NIP-05 and NIP-65 lists). Engagement on the
second was a fraction of the first, which "shouldn't have happened at all" if
clients followed *people* rather than relays. His verdict: "Nostr today is
indeed centralized" — and the failure lives in clients that hardcode relay
sets, not in the protocol. Censorship-resistance is an **emergent property of
clients doing discovery properly**, or it does not exist. The same essay's
flip side ("Nostr is pro-censorship"): every relay is private property, free
to reject anything for any reason; the network resists censorship precisely
because censorship is everywhere permitted and nowhere decisive — *provided*
readers can look elsewhere, which is the client's job to make real.

The correct answer is **intelligent, per-event relay selection** — routing
*heuristics*, agreed on by convention so that writers and readers can predict
each other. Think of each heuristic as a database index: it connects a query
someone will plausibly run with the place matching events are stored.
Heuristics are additive — publish to every location a legitimate reader would
look, and *only* those (access control is precisely the deliberate omission of
a heuristic).

## The outbox model — the paradigm heuristic

NIP-65: each user publishes a **kind 10002 relay list** declaring where they
write. The two flags:

| Flag | Name | Meaning |
|---|---|---|
| `write` | **OUTBOX** | where this user publishes their public content |
| `read` | **INBOX** | where this user expects to receive mentions and DMs |

The rules that fall out:

- To read someone's posts → query 2–3 of their **outbox** relays.
- To publish your own post → your **outbox** + the **inbox** of everyone you
  `p`-tagged.
- To send a DM → recipient's **inbox** (NIP-17 uses a dedicated kind 10050
  DM inbox), plus your own for the record.
- Cold start / unknown user → indexer + general relays, then upgrade to their
  outbox once you've seen their 10002.

With outbox, each author is sovereign over their own distribution: routing is
declared by the *author*, not chosen by the platform. This is why the
literature is unanimous that **outbox is no longer optional for a serious
general-purpose client** (OpenSats report; Amethyst talks to ~1,000 relays
from a phone; the point is a flat traffic profile across many small relays
instead of ten hubs).

**Gossip** (Mike Dilger) is the superset in practice: outbox plus every other
discoverable hint — relay hints in `e`/`p`/`a` tags, `nprofile`/`nevent`
URIs, NIP-05 metadata, observed author presence. Use every signal you can get.
fiatjaf is emphatic that reducing discovery to NIP-65 alone is "too
restrictive," and that dropping per-event relay hints (as Coracle once
proposed) is "a catastrophic idea": hints are what keep community-relay
posts, conference relays, topical relays, archive relays, and even a
fully-banned "Alex Jones" — whose kind 10002 no indexer will carry —
reachable via nothing but an nprofile on a business card. Resilience comes
from *deliberately mixing many mechanisms*, manual user action included.

## Outbox is one heuristic, not the routing model

The most common architectural mistake after "ignore routing entirely" is
"pretend NIP-65 covers everything." It covers exactly one case:
author-addressed public social content. Other cases have their own
heuristics, and a NIP that defines a new kind **without defining its relay
selection is an incomplete spec**:

| Content | Route by | Mechanism |
|---|---|---|
| Public notes, articles, profiles | author | outbox (kind 10002) |
| Mentions, replies | mentioned users | inbox (kind 10002 / 10050) |
| DMs (NIP-17/44/59) | recipient | DM inbox only — *never* outbox |
| Community / group content (NIP-29, NIP-72) | the community | the group's declared relay(s) only; leaking to outbox violates the access model |
| Topical / curated feeds | topic | topic relays, relay-advertised interest (NIP-66 kind 30166 recommendations) |
| Search / aggregate | nobody | indexer relays, an explicit trade of centralization for capability |
| Zap receipts | zap *request* author | their outbox (the wallet acts on the sender's behalf) |
| Git / repo events (NIP-34) | the repo | repo's declared GRASP relays, then author outbox |
| Service RPC (NIP-46/47/90) | the service | the relay(s) the service advertises |

Publishing means applying **all** applicable heuristics for the readers you
intend, and none for the readers you don't.

## Bootstrapping, hints, and healing

**Bootstrapping.** Kind 10002 tells you where a user's content lives — but
where do the 10002s live? You have to start somewhere: hard-coded
indexer/default relays in the client (swappable, and honest about being a
compromise), purpose-built profile indexes, and eventually perhaps a DHT.
Bootstrapping is a *trust* problem as much as a network problem: relay
recommendations (NIP-66) are only as good as the web of trust you filter them
through.

**Relay hints.** Tags that reference events carry optional relay URLs (and
pubkey hints, which are more durable — a pubkey leads to an outbox even after
relays rot). Hints are the fallback when heuristics fail — and they have a
second, adversarial function: a hint baked into a signed event cannot be
stripped without breaking the signature, so even censorious relays end up
advertising where the censored content lives. Hints force federation and let
clients route around damage.

**Migration.** Relay selections change; signed data makes the fix trivial in
principle — copy the events — but somebody has to do it, and the rule for who
is: **the person who wants the event findable in a place is responsible for
putting it there.** Change your outbox → re-publish your content to the new
relay, or your 10002 becomes a lie ("Alice said her notes are on relay B;
they weren't"). Group moves relay → the admin syncs. New indexer →
its operator scrapes. Negentropy (NIP-77 set reconciliation) makes this cheap.
Most clients still don't do it; a complete client must.

**Proxies and the super-peer curse.** Read/write proxies that do relay
selection *for* the client break at the edges: NIP-42 AUTH deliberately
cannot be proxied, and the client-side context that drives selection (group
membership, user intent) never reaches the proxy. Multiplexers that carry
explicit client-side selections in a wrapper protocol are fine; opaque
"smart" proxies re-create the platform. fiatjaf generalizes this into the
**super-peer curse**: any trusted machine that hands clients "massaged,
sorted, filtered, ordered data" — Bluesky's app views, Farcaster hubs,
p2panda's Aquadoggo, and the aggregator/proxy experiments inside Nostr itself
— means the users behind it "will be controlled, censored, mislead and
tricked." If that architecture came to dominate Nostr he "would immediately
declare Nostr a failed experiment." The legitimate home for that power is the
relay layer itself — curation relays, WoT relays, search relays, AI-feed
relays — chosen by the user, never interposed between follower and followed.

## Relays are services, not infrastructure

The healthy end-state is not ten thousand identical relays; it is a market of
*differentiated* relays: community homes, paid indexes, curated topic feeds,
DM mailboxes, archives, algorithm relays that answer a query with a
recommendation feed. NIP-43/86 (membership lists, management API — the
Coracle line of work) formalize this: a relay may state who it serves and
what its policy is, and clients should honor that.

Constant's framing sharpens the point: "The point of Nostr was never to get
rid of servers; the point of Nostr is to be free again to leverage them for
what they are good for… It frees servers, just as much as it did the users."
Use relays for what servers are good at — **curation and ordering**: relay
feeds as a first-class client feature (fiatjaf pushes the same thing —
favorite a curated relay *as a feed*, don't add it to your read list),
NIP-29 rooms, curated topic relays. "Dumb relay" refers only to the
standardized query interface; within accept/store/serve, a relay is in full
control and free to be as smart as it likes.

Two corollaries:

- **Expose relays to users.** Per-note relay selection, visible relay
  provenance, user-editable selections. A client that hides relays "for UX"
  is quietly re-centralizing; making relays *legible* is what makes the user
  sovereign. (Coracle's per-note relay selection is the reference.)
- **Relays need business models.** A relay that is indistinguishable from its
  neighbors can only be a subsidized commodity, and subsidized commodity
  infrastructure is how we got the old internet. Distinct services can charge —
  and users choosing whom they do business with is the alignment mechanism.

## Spam is a routing problem too

fiatjaf's mature position ("The only solution to Nostr spam," 2025): spam is
solved at the **relay layer**, by construction, not by client-side cleverness.

- Main feeds have no spam problem: you read people you follow, from relays
  you chose.
- Inbox spam: query `#p` mentions **only from the user's declared read
  relays** — and choose read relays that actually filter (WoT-gated,
  NIP-05-gated, PoW, paid). Filtered public inbox relays should be client
  defaults so newcomers never see spam.
- Other people's threads: replies are fetched from *the author's* read
  relays; a spam-flooded thread "is their fault for not picking 'read'
  relays correctly" — hygiene is per-user, socially correctable, and the
  incentive lands on the right person.
- Why not client-side WoT/mutes as the primary defense: content must be
  downloaded before it can be filtered (at scale that's the bandwidth of all
  spam, and a 500-reply flood starves naive queries); mutes can't beat
  infinite fresh keys; and purely local filtering is a tragedy of the
  commons. Client-side trust scoring remains useful as a *secondary* layer —
  ranking, impersonation warnings, zap-feed dampening — not as the wall.

## No global view — and that's the design

There is no "the network." Nostr is partition-tolerant to its core: you can
fetch any subset of events from any subset of relays, and you will never know
whether you have "all" of anything. Every alternative that promises a global
view (Bluesky's firehose being the clearest case) pays for it with a
centralized chokepoint.

*Building Nostr* names the positive version of this **digital localism**: the
network topology is allowed to align with the social graph. Clusters overlap
relays; relays serve clusters; not all parts of the network need to be
connected for each part to be whole. Discovery bootstraps from "many
different hackish attempts" (fiatjaf) — replies you happen to see, hints,
NIP-05 addresses, invite links — and that friction is not a bug to engineer
away with a global index; it is what a captureless network feels like.

The No Solutions podcast crew states the same law from the builder's side:
global view counts, global usernames, guaranteed deletion, consistent group
state — "everything else is a lie… if you want a global view you need to
rebuild Bitcoin" (Gigi). Their predicted eternal-September failure mode:
newcomers "building REST APIs that give you global feeds." Don't be the
REST API.

## The local relay: partition tolerance as a feature

The strongest positive expression of no-global (No Solutions eps. 02/09/13):
**a relay is not an external dependency** — "a server truly is an external
dependency: one source of truth, power over you. A relay is not, because it
can literally be internal — on my phone, at home — completely exchangeable."
So put one on the device:

- **The flight-mode test**: an app backed by a local relay reads and writes
  offline, rebroadcasts in the background when connectivity returns, and its
  optimistic UI is *free* — the data is already signed; whether it has
  reached other relays yet is secondary.
- The local event cache doubles as the honest personalization layer: "what's
  been trending on my WoT relay in the last 48 hours" beats any global
  algorithm, computed from data the user already chose to hold.
- Marketing translation, for people who flinch at "censorship resistance":
  it's **100% uptime**.
- Missing-but-needed tooling around this: rebroadcast daemons that keep your
  events on your *current* relay set, and Blossom link-healing from the
  user's server list — signed data makes both trivial in principle; almost
  nobody ships them yet.

## The failure model you must build for

Concrete engineering consequences, non-negotiable for anything serious:

- Events arrive **duplicated** → dedup by id; ingest must be idempotent.
- Events arrive **late and out of order** → `created_at` is a claim, not an
  ordering; render defensively, use threads/references for causality.
- Events **don't arrive** → absence of evidence is nothing: "I asked 3 relays
  and got no result" never proves nonexistence.
- Relays **lie, throttle, vanish, and reject** → treat every relay response
  as best-effort; retry elsewhere; never let one relay's answer be final.
- Replaceable events **race** → last-write-wins per relay can differ across
  relays; fetch from several, take newest, and preserve fields you don't
  understand when re-publishing (see [`03-how-to-develop.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md) §fault tolerance).
- Any event may be **malformed or adversarial** → validate signatures always,
  sanitize content always, treat relay hints and media URLs as untrusted
  input.

Design for eventual, partial, best-effort consistency and Nostr is pleasant.
Design against it and every layer of your app fights you.

## The one-page summary

1. Routing heuristics, not replication, are what scale Nostr.
2. Outbox/inbox for social broadcast; every other kind needs its own declared
   heuristic; specs without routing are incomplete.
3. Whoever wants data findable somewhere is responsible for it being there —
   including after relay changes.
4. Relays are differentiated services with intent; make them visible to
   users and let them charge.
5. There is no global view. Build local-first, partition-tolerant, and
   paranoid about relay honesty.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/core/03-how-to-develop.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.

# How to develop for Nostr

> Part 3 of the core synthesis: the practitioner's layer — what to build, how
> to build it, and the responsibilities that come with shipping. Sources:
> *Building Nostr* chs. 2–5, nostrdesign.org, the NIPs repo norms, and the
> working practices proven in the sibling `nostr-dev` workspace.

## Build pieces, not platforms

The single most repeated piece of advice across fiatjaf, Hodlbod, and
nostrdesign.org: **build a small thing that does one thing well.** A client
that does everything is fighting three wars at once (routing, UX, moderation)
and will lose to the composability of the ecosystem around it. Because every
app shares the same identity and data layer, your single-purpose app gets the
whole network's users for free — a long-form reader, a group chat, a git
forge, a calendar, a marketplace, each speaking events other apps also speak.

Corollaries:

- You do not need permission, a token, a company, or a spec merge to ship.
  Sign events, publish them, document your kinds. Adoption is the approval
  process.
- You do not need to implement "Nostr" — only the NIPs your use case touches.
  Scope discipline is a feature: for kinds you don't handle, hand off via
  NIP-89 application handlers instead of rendering nothing (see below).
- Interoperability is your value proposition, not a compliance cost. The
  moment your events only make sense to your own client, you have rebuilt a
  silo with extra steps.
- **kind:1 maximalism** (fiatjaf): microblogging is "the central plaza of
  Nostr" and should stay deliberately dumb — announce your "other stuff"
  (articles, recipes, repos, events) with plain kind:1 notes that *link out*
  to your dedicated microapp, rather than expecting every feed client to
  render your kind. Superapp-ification raises the barrier to entry for new
  clients, and the barrier to entry for clients is the real decentralization
  metric. "It's ok if Nostr ends up having just 2 recipe-sharing clients,
  but it must have dozens of microblogging clients."

### If you're building a business on Nostr

fiatjaf's playbook ("How to do curation and businesses on Nostr"): resist the
tempting version — a closed platform that reuses Nostr identities, siphons
the open network, imprisons content behind an API, and runs a clever
algorithm on top. Even when it succeeds it enshrines you as a platform, with
a platform's ads, legal exposure, and capture dynamics. Instead: (1) ship an
interoperable, ideally open-source niche **client** with documented kinds;
(2) put the secret sauce — curation, validation, search, AI, moderation — in
a **relay you run and charge for**, and make it your client's default. Your
relay is your website; the social layer (follows, comments) still rides the
outbox model, so users keep portable identities and graphs that don't depend
on you — which is exactly why they can afford to trust you. "You don't own
the network, you're just competing against other websites on a leveled
playing field."

One sober caveat for web apps: a web client is chained to a domain and its
owner's server, so it "can't ever be trusted as an installed client can."
Until content-addressed app distribution matures, encourage users to keep a
second client configured — interchangeability is the mitigation.

## The development loop

1. **Model the events first.** Kind, class, tags, content shape — this is
   your schema and your API, and it outlives your app. Work through
   [`04-how-to-design.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md) before writing code.
2. **Check the registry and the wild.** Read the NIPs kind table; probe live
   relays for the kinds you're considering (`nak req -k <kind> -l 5 ...`) —
   plenty of kinds are occupied but undocumented. Reuse before inventing.
3. **Prototype against a local relay.** A throwaway relay (nostr-rs-relay,
   a Khatru scaffold, or a container) gives you deterministic tests without
   spamming the public network. Publish to public relays only what is meant
   to be public — signed events are forever.
4. **Then test against the real network,** because the real network has
   spam, malformed events, dead relays, and 30-second-old data — and your
   handling of those *is* the product. Two acceptance checks from the No
   Solutions school: the **flight-mode test** (does it work offline against
   a local relay, syncing later?) and the **paradigm test** — if you found
   yourself wrapping Nostr in a REST API with server-held state, stop:
   "you have to lean into the Nostr paradigm to get all this stuff for
   free… building REST APIs around Nostr is breaking the coolest part"
   (Pablo Fernandez). Nostr done right is *less* to build: authentication,
   storage, identity, and inter-process communication come with the
   protocol.
5. **Document your kinds in your repo** (kind, class, tag schema, content
   shape, routing heuristic, why). If you want interop, open a NIP PR once
   two implementations exist.

### Tooling that carries this loop

(Reference environment: the `~/Documents/nostr-dev` workspace, which has all
of this installed and a live local relay/GRASP/Blossom stack.)

- **`nak`** — the Nostr army knife: decode bech32, fetch/filter events, sign
  and publish, generate keys, read NIP texts (`nak nip 34`), run a throwaway
  relay (`nak serve`), act as a bunker (`nak bunker`), push blobs
  (`nak blossom`), publish a whole static site (`nak nsite`), sync two relays
  with negentropy (`nak sync`). The default instrument for one-shot inspection;
  learn it early.
- **Libraries** — JS/TS: `nostr-tools` (low-level primitives), NDK
  (high-level, outbox built in), Applesauce (reactive); Rust: `rust-nostr`;
  **Go: [`fiatjaf.com/nostr`](https://pkg.go.dev/fiatjaf.com/nostr)** — the
  protocol author's own library and the whole stack in one module (events,
  relays, pool, an outbox-aware `sdk`, the `khatru` relay framework,
  `eventstore` backends, Blossom, GRASP, and ~40 NIP packages). Note
  `github.com/nbd-wtf/go-nostr`, which most Go examples on the internet still
  import, **was archived 2026-01-24** and its README points here. Use a
  maintained library for serialization, signing, and relay pooling —
  hand-rolling NIP-01 serialization is how invalid ids happen.
- **Local relays** — nostr-rs-relay (turnkey, SQLite), Khatru (embeddable Go
  framework — the right base for policy experiments and specialty relays).
- **Reference sites** (links checked 2026-09-21) —
  [nostrbook.dev](https://nostrbook.dev) (protocol detail),
  [undocumented.nostrkinds.info](https://undocumented.nostrkinds.info) (kinds
  found in the wild), [nostrapps.com](https://nostrapps.com) (ecosystem),
  [github.com/nostrability/nostrability](https://github.com/nostrability/nostrability)
  (interop issue tracker — it is a GitHub repo, there is no `nostrability.com`;
  `nostrapp.link` no longer resolves either).

## Onboarding: teach the paradigm, don't hide it

The prevailing client instinct — hide keys, relays, and events behind
"accounts" and "services" to reduce friction — has a serious dissent, argued
hardest by Constant: **if Nostr fades into the background, you have rebuilt
the platform world.** "If you give users in your app an 'account' because
that is easier, they will end up making another 'account' in the next app…
we hardly differentiated from where we came from." The counter-program:

- Users need to know about **keys** (so they know they're free to use any
  app), **events** (so they know their posts outlive any server), and
  **relays** (so they can move freely) — and that the app is a tool, not a
  service. "Relays and keys are not ux issues, they ARE the ux."
- The paradigm is "not hard, it is just new." The aha-moment works like a
  riddle — you get it after the fact — and a dumbed-down, borked explanation
  destroys it. Nobody was taught TCP/IP, but everybody was taught what email
  *is*; teach what Nostr is.
- Practical touches: label sharing as "inside Nostr / outside Nostr"; treat
  key creation as a small ceremony, not a hidden implementation detail;
  progressive custody (local key → NIP-55/46 provider → bunker) rather than
  custodial "accounts."

This doesn't excuse hostile UX — it sets the target: *low-friction paths to
a correct mental model*, not low-friction paths around it.

## Keys and signing: never touch the nsec

The private key is the user's whole identity, unrotatable today. The bar:

- **Default to signers, not raw keys.** Integrate NIP-07 (browser
  extension), NIP-55 (Android intent / Amber), and above all **NIP-46 remote
  signers ("bunkers")** — Hodlbod's pick as the most promising, since they
  work from any device and keep the key in one guarded place. Support bunker
  URIs from day one. (Nuance from fiatjaf, 2026: for an *introductory native
  client*, generating and storing an nsec locally, then graduating the user
  to acting as a NIP-46/55 provider, is a reasonable onboarding flow — the
  real threats are web apps, malicious apps, and device compromise, and
  "Amber/NIP-55 defends against the first two." Web clients should be held
  to the strict never-see-the-nsec bar; they are structurally less
  trustworthy.)
  **Implementation:** don't improvise signer login. Follow
  [`~/Documents/nostr-dev/docs/patterns/signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md), and test with the Signer
  Login Tester nsite linked there.
- Every event you sign on a user's behalf is a permanent public record —
  sign exactly what the user intended, nothing else, and show them what
  they're signing where feasible.
- For services and bots: one purpose, one keypair, minted with
  `nak key generate`, stored outside the repo, documented (which npub, what
  it's for, where the secret lives). Never reuse a human's key for a
  service; never publish kinds 0/3/10002 from an identity you don't own the
  profile of.
- Onboarding without custody theater: password-encrypted key backup (NIP-49),
  2-of-2/multisig bunkers where real custody UX is needed.

## Fault tolerance: the reading and writing discipline

**Reading** (from *Building Nostr* ch. 2 — "a light touch"):

- Invalid signature → discard, no exceptions (NIP-59 unsigned rumors are the
  one structured exception).
- Malformed-but-honest events → degrade gracefully; assume incompetence
  before hostility. Show fallbacks, not crashes. Aggressive schema validation
  turns recoverable errors into broken UX and hurts interop.
- But **don't repair non-standard data into legitimacy** — tolerating a
  minority-broken format (bech32 where hex belongs, say) helps it hijack the
  kind. Fault tolerance is for readers; conventions are for writers.
- Adversarial content is normal: sanitize HTML, cap resource use, treat
  relay hints and media URLs as untrusted, apply user-configurable policy
  (WoT, PoW, domain lists) before auto-fetching anything.

**Writing — the prime directive: never destroy data you didn't understand.**
The classic Nostr bug family is one client clobbering another's data in a
shared replaceable event (relay hints in kind 3 content, muted words in kind
10000, encrypted fields dropped on update). The pattern that prevents it:
parse the event into your model *keeping the original event attached*, and on
save, mutate the original — preserving unknown tags and content — rather than
regenerating from your model:

```javascript
readProfile  = e => ({...decodeJson(e.content), e})
writeProfile = ({e, ...p}) => ({kind: 0, content: encodeJson(p), tags: e.tags})
```

**Routing** is part of correctness, not an optimization: implement the
heuristics from [`02-how-it-should-work.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) for every kind you emit, dedup by
id, treat every relay as unreliable, and re-publish user data when their
relay selections change.

## Ship the ecosystem, not just the app

- **NIP-89 handlers**: when you meet a kind you don't render, look up
  handler events (kind 31990, vetted through the user's WoT via 31989
  recommendations) and offer to open the content in an app that does. Publish
  handlers for *your* kinds so others can hand off to you. Walled gardens
  vertically integrate; Nostr apps recommend each other — and are stronger
  for it. Pablo's framing of why this beats an app store: "you see the
  people doing the thing… the people interacting with the tool *is* the
  distribution of the tool."
- **`alt` tags** (NIP-31) on every exotic event, so unknown-kind fallbacks
  at least say what the thing is.
- **`client` tags** where users consent — ecosystem legibility.
- **Open source it.** Reference implementations are how conventions actually
  propagate; undocumented-but-open beats documented-but-closed. On Nostr you
  can even host the repo itself on the protocol (NIP-34 / GRASP: git over
  relays, issues and patches as events).
- **Backwards compatibility is a UX duty, not a dogma.** Enhance existing
  formats when you can do so without overloading them; when you must break,
  mint a new kind and evangelize, don't mutate the old one under people. Be
  prepared to defend divergence — and to write code for *other* projects to
  get your change adopted; nothing persuades like a PR.

## Anti-patterns (each observed repeatedly in the wild)

- Inventing a kind that already exists because you dislike its NIP — you get
  fragmentation and zero readers.
- Fixed hard-coded relay list in a general-purpose client — re-centralization
  in a trench coat.
- JSON blobs in `content` for structured data that belongs in tags — opaque
  to relays and other clients.
- Overloading one kind (or one shared list event) for multiple purposes —
  the data-loss bug factory above.
- "Smart" relay proxies that select relays for the client — break AUTH,
  break groups, hide provenance.
- Trusting `created_at`, trusting a single relay's answer, trusting a hint —
  everything is a claim until verified or corroborated.
- Skipping the spam story — permissionless writing guarantees spam, so a
  client without one has a missing core feature, not missing polish. The
  primary mechanism is routing (filtered read relays — see
  [`02-how-it-should-work.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md) §spam); client-side WoT/PoW/mutes are the
  secondary layer.
- AI-generated apps that skip routing/handlers/WoT because they're invisible
  — they demo fine and quietly damage the network's decentralization
  (*Building Nostr*'s closing warning).

## Definition of done, Nostr edition

Your thing is done when:

1. Its event kinds are documented (schema + class + routing) somewhere public.
2. It signs via NIP-07/46/55 and has never seen an nsec.
3. It reads via the correct heuristics and survives dead/lying/slow relays.
4. It writes to the correct heuristics and preserves data it doesn't own.
5. Another client can consume its events from the spec alone — and at least
   one does, or could.
6. It hands unknown kinds off via NIP-89 instead of dead-ending.
7. Its users can leave it without losing anything. **Credible exit from your
   own app is the final acceptance test.**


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/04-how-to-design.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/core/04-how-to-design.md` · snapshot 2026-10-10

# How to design for Nostr

> Part 4 of the core synthesis: the design methodology — events, kinds, tags,
> communities, money, and trust, plus the principles that arbitrate every
> trade-off. Sources: *Building Nostr* chs. 2, 6, 7; the nostr-dev
> [`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) and kind cheatsheet; nostrdesign.org.

## Designing on Nostr = two artifacts

You are never designing "a system." The runtime is whatever relays exist.
You are designing:

1. **An event schema** — kind(s) + tag set + content shape, and
2. **A routing strategy** — which relays each kind goes to and is read from
   ([`02-how-it-should-work.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/02-how-it-should-work.md)).

Every other decision is downstream. Take them in this order:

### Decision 1 — the schema

- **Tags are your data model; content is for humans.** Structured data in
  tags (strings only, short, 2–3 positions); prose/markdown in content.
  JSON-in-content is legacy exception, not precedent.
- **Prefer more kinds over overloaded kinds.** "No more than one way to do
  the same thing" cuts both ways: reuse the existing kind when your thing
  *is* the same thing; mint a *separate* kind when it differs even modestly
  (NIP-52 splits date-based and time-based calendar events — that's the
  taste to copy). Overloading is the root of the cross-client data-loss bug
  family. Similarly, resist packing many concerns into one event: contention
  over a shared event (kind 0, the shared lists) is where sync conflicts
  live. Hodlbod: redesigning profiles today, he'd split every field into its
  own event.
- **Reuse tag conventions**: `e`/`p`/`a`/`d`/`t`/`r`/`alt`/`expiration`/
  `subject`/`client`… — if your data is "a reference plus an annotation,"
  it is an existing tag plus content, not a new kind. Know the three tag
  roles — data (display), filter (single-letter, relay-indexed), behavior
  (kind-independent semantics like `-`, `h`, `expiration`) — and when
  resolving overloaded tags let the kind's own spec win over generic
  meanings.
- **Positional tags rot.** If a tag wants 4+ positions, split it into
  associative companion tags instead.
- **The optional-becomes-mandatory test** (fiatjaf's razor — apply it to
  every extension you're tempted to ship): *if this became widespread, could
  a client ignore it and still show correct content?* If not, it is not
  optional, however innocent it looks — it will ratchet, via user pressure,
  into an obligation on every present and future client, raising the barrier
  to entry. That mechanism (his YAML-NIP-05 parable) is what killed NIP-26
  delegation as a general scheme and grounds his case against kind:1 edits: a
  client that doesn't fetch edits "will be displaying false information," so
  edits, once widespread, are mandatory — "a centralizing force… a slippery
  slope that should not be accepted." Extensions that pass the test: things a
  non-implementing client can simply not show (reactions, zaps, annotations
  with graceful fallback). Extensions that fail: anything that changes the
  meaning of already-published content out from under simple readers.

### Decision 2 — the event class

Default **regular**; regular events keep history, keep referential
transparency (id = content hash), and degrade gracefully. Escalate only with
a written justification of what you're discarding and why:

```
                one-current-value-per-user?
                   /                \
                 yes                 no
                  |                   |
       keyed by a d-tag?        instantaneous signal?
          /        \                /        \
        yes        no             yes         no
         |          |              |           |
  ADDRESSABLE  REPLACEABLE     EPHEMERAL    REGULAR ← default
  30000–39999  10000–19999    20000–29999
```

Smell tests: a settings event that accumulates → replaceable. A "current
location" stream → ephemeral. An edited blog post → addressable. An editable
*comment* → wrong, comments are accountable: regular + NIP-09 tombstone. A
draft → addressable. Remember what replaceability costs: history gone, race
conditions in, and only a social (not technical) resolution when two writes
collide.

### Decision 3 — routing per kind

For **every** kind you define: who reads this, with what query, and which
relays must therefore hold it? Write the heuristic into the spec. A kind
without a routing heuristic is an incomplete design (the geocache/topic-tag
lesson: events whose natural query has no relay-selection story end up on
hard-coded relays — centralization — or unfindable).

### Decision 4 — the failure and abuse model

Duplicates, gaps, reordering, lying relays, race-prone replaceables — plus:
who can spam this? impersonate in it? what leaks? An event schema is not done
until you can answer "what does a hostile pubkey do with this?" (spam →
WoT/PoW/paid relays; impersonation → WoT validation, *never* NIP-05 alone —
addresses locate users, they do not authenticate them) and "what does this
reveal?" (Nostr is publicity technology; metadata is data).

## Kind allocation, concretely

1. Search the NIPs registry table (vendored: [`../sources/nips-readme-kinds.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md)).
2. `nak nip <n>` for the relevant NIPs; read them.
3. **Probe the live network** — `nak req -k <kind> -l 5` against big relays;
   undocumented-but-occupied kinds are common, and colliding with one hurts
   both parties.
4. Fit an existing kind if you honestly can; match its schema exactly.
5. Else pick a free number in the correct class range, document it in-repo,
   ship, and NIP-PR it once a second implementation exists.

## Designing privacy: encryption vs. relay policy

Two mechanisms give confidentiality, with opposite trade-offs:

- **Encryption** (NIP-44 payloads, NIP-59 gift wrap, NIP-17 DMs, MLS for
  large groups): trustless — no relay can leak what it can't read — but
  policy is frozen into the protocol; every client must implement the same
  rules, and mistakes are catastrophic and unpatchable.
- **Relay-enforced access control** (NIP-42 AUTH + policy, the NIP-29
  model): flexible, cheap, admin-evolvable — any policy a script can express
  — but the relay is trusted; "forward secrecy" by policy is a promise, not
  a guarantee.

Choose by threat model, and be honest in your spec about which you chose.
Gift-wrapped events deliberately hide kind, author, and timestamp from
relays; remember that even then, *traffic* metadata (who talks to which
relay, when) still leaks — say so in your privacy story.

Two more honesty checks from the practitioners. Group encryption past
roughly twenty members is theater — "you'll either have a mole or an asshole
in there" (Gigi); don't pay heavy cryptography costs for an assurance the
social layer can't deliver, and consider Martti Malmi's alternative: use
Nostr as the *lookup substrate* (publish your Signal/SimpleX handles on your
profile) rather than forcing every private medium onto relays. And deletion
is make-believe everywhere, not just here: "computers are copying machines…
all deletions in a networked world are pinky-promise deletions." NIP-09/62
are courtesy requests; design as if nothing can be unpublished, because
nothing can.

## Designing communities

*Building Nostr* ch. 7's taxonomy — five community shapes, each wanting a
different architecture. Naming which one you're serving is half the design:

| Shape | Nature | Architecture fit |
|---|---|---|
| **Social cluster** | emergent, open, graph-defined | broadcast social + outbox; no membership machinery at all |
| **Group chat** | small, every-member-trusted, quadratic intimacy | encrypted (NIP-17 pairwise; MLS for scale); doesn't scale socially past trust, don't pretend it does |
| **Discussion forum** | open, topic-defined, needs moderation not gatekeeping | relay-based groups (NIP-29) or moderation-as-user-preference; forkable by design — same group on two relays merges in the client |
| **Owned community** | exists for/by a central figure (creator, company) | centralized control is a *feature*; NIP-29 relay owned by the owner; interop is the value-add |
| **Commons** | member-owned, politically self-organized | the hard one: roles, gradated membership, partitions by identity/topic/content-type; design *with* the community, not for it |

Lessons paid for in the wild: NIP-72's require-moderator-approval design
killed its forums (moderation must be *added under load*, not a precondition
for content to exist); moderation policy generally belongs to users and
relays, not frozen into the event spec; missing data is not a bug when the
user's own filters caused it — partition tolerance is also a social feature.
And know which value applies where — Constant on NIP-29: a group "is a
house, you are a guest, and the fact that you can be yeeted out is a
feature, not a bug. In this context, censorship resistance does not make
sense." Demanding broadcast-network values inside a community context is a
category error in both directions.

The generalization of all this is Constant's TEPP formula: Nostr is **"a
permissionless system for the creation of permissioned environments."**
Permission lists over the protocol's own primitives — people (npubs), places
(relays), things (kinds/events) — enforced redundantly at signer, client,
and relay, extensible through webs of trust. Child-safe internet (Kidstr) is
the flagship case, but the pattern covers any curated, bounded, or
supervised space you might need to design.

## Designing for value-for-value

Money is a first-class design material on Nostr, and its semantics are
patronage, not trade: digital content has ~zero marginal cost, so payment
buys *future production* plus identity/belonging — leaderboards, boosts with
messages, in-group signaling. Design for those dynamics, not for a store.

- **NIP-57 lightning zaps**: public receipts tie payment to event/recipient.
  Trust caveats: the receipt is only as honest as the receiver's wallet, and
  zap-driven feeds must be WoT-filtered or sybils farm them.
- **NIP-60/61 cashu nutzaps**: wallet lives in events (follows the user),
  pubkey-locked tokens verify without trusting the wallet; custodian risk
  moves to mints. "Uncle Jim" community mints/nodes mitigate.
- The underexplored direction: paying *infrastructure* — relays, DVMs,
  library authors — in-band and per-use, so the commons isn't ad-funded.
  If your design creates load on someone's server, design the payment path
  too.

## Trust and reputation as design material

There is no global truth on Nostr, so **reputation is always relative to a
starting point**. Design rules:

- Compute WoT from *this user's* follow graph outward; global scores
  (PageRank-style) are sybil bait. Garbage in, garbage out.
- Weight attestations by strength: a follow is weak-but-real interest;
  a reaction emoji is nearly nothing. Don't over-read weak signals.
- Explicit attestation schemes ("I trust X for Y") mostly fail — PGP proved
  incentives beat elegance; piggyback on actions users already take.
- Trust is domain-specific: good for spam/impersonation filtering, not a
  character reference.
- Supplements for cold-start: PoW (NIP-13), attestation services, payments —
  each gameable, useful in combination.
- **Identity ≠ key** (Constant): "an npub is a mere pointer to some
  identity… identity consists of expression and relation." Key rotation has
  no accepted formal solution — and Constant argues it shouldn't get one:
  rigid formal schemes "turn against you the moment an attacker penetrates
  them." Design instead for **social recovery**: WoT attestations of a new
  key, expiring musig2 "association events" whose silence signals compromise.
  fiatjaf lands nearby from the relaxed side: identity, unlike money, "can be
  recovered — slowly and painfully," so many optional schemes beat any
  mandatory one.
- **Timestamps as trust material**: `created_at` is a claim, but an
  OpenTimestamps proof (NIP-03; Constant's NIP-3B/3C fixes — stamp
  hash(id+sig), embed the proof) makes *backdating detectable*: "timestamps
  only give very weak indications of truth, but they are really good at
  catching certain lies." Post-compromise, a stamped history is what lets an
  identity prove which of its record predates the theft. Cheap to add, rarely
  regretted.

## The principles that arbitrate

When two design options tie, these break the tie (nostrdesign.org guiding
principles + the synthesis of everything above):

1. **User sovereignty over identity** — keys never leave the user; no design
   may require an intermediary that can impersonate.
2. **User sovereignty over relays** — never hard-code, never hide; relay
   selection is user-facing UI, not an implementation detail.
3. **Modularity over monoliths** — the smaller and sharper your piece, the
   more the ecosystem carries it.
4. **Filter, don't censor** — clients give users filtering tools (WoT, PoW,
   mute, relay choice) instead of deciding for them; moderation is relay-
   and user-policy, not client fiat.
5. **Interoperability over features** — a feature that breaks other clients'
   reading of shared data is a bug with good PR.
6. **Trust users, trust developers, keep specs simple** — write NIPs a
   human reads in five minutes; complexity is capture surface.
7. **Embrace compromise** — Nostr is "good enough" by design; perfect
   protocols with no users lose to messy protocols with them. Protocol work
   is politics in the Aristotelian sense: a community building the place it
   intends to inhabit. Participate accordingly.
8. **State your trade-offs out loud** — the No Solutions rule ("no
   solutions, only trade-offs"). Mints can rug you: that's the design, keep
   pocket change there. Zapstore dials decentralization down for credible
   exit, and says so. The characteristic newcomer failure is refusing to
   accept a trade-off — and thereby smuggling a central authority back in
   (Passkeys, home servers, global registries, "smart" proxies, DRM). A
   design document that names what it gives up is the mark of someone who
   understood the protocol.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/05-current-frontier.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/core/05-current-frontier.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.

# The current frontier (as of late 2026)

> Part 5 of the core synthesis: where the live edge of Nostr development
> actually is, drawn from the freshest material in this repo — fiatjaf's
> 2026 notes ([`../voices/fiatjaf/on-nostr.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/on-nostr.md)), the 2026 No Solutions
> episodes ([`../voices/no-solutions/episodes.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/episodes.md)), and Constant's active
> projects (`../voices/constant/research.md`). Everything here is moving;
> re-verify before building on it.

## What the principals are actually pushing right now

- **Relay feeds as a first-class client feature.** Both fiatjaf and Constant:
  a curated relay should be *favorited as a feed*, not added to your read
  list. Supported across a dozen clients (Jumble, Nostur, Yakihonne,
  Coracle, fiatjaf's own Hallway…). Relays with personality — communities,
  curation, algorithms — are the underused half of the protocol.
- **Boring sub-protocols being dogfooded to reliability**: NIP-17 DMs
  ("I just wanted proof that NIP-17 could work reliably, and now I got it"
  — fiatjaf), NIP-29 relay-based groups ("you only give partial authority
  to a server, you always keep your right to migrate"), NIP-34/GRASP git
  (working, still UX-rough — "will we ever get a 'merge' button?").
- **The NIPs process itself is in question**: fiatjaf now maintains a bare
  registry-of-kinds and argues for competing prose guides over numbered
  specs. Watch where documentation actually accrues.
- **Spam doctrine consolidating around filtered read-relays** (WoT-gated
  inbox relays like Pyramid's `/inbox`, NIP-05-gated, PoW, paid) with
  client-side WoT as a secondary layer — though Martti Malmi still runs WoT
  client-side on principle (trusting the relay operator is the cost he
  won't pay). Unresolved, productive disagreement.

## Media and app distribution

- **Blossom everywhere**: content-addressed blobs, user-declared server
  lists (kind 10063), the relay design pattern applied to media. Known gap:
  self-healing links — clients that repair a 404 from the user's server
  list — are still mostly unimplemented; the No Solutions podcast itself
  404'd when one Blossom server died.
- **nsites**: whole static sites as Nostr events + Blossom blobs
  (Constant's techno-ethica.com renders entirely from relays). Now specified
  as **NIP-5A**: one replaceable **kind 15128** manifest per pubkey listing
  every file by sha256, named sites at 35128, immutable snapshots at 5128, and
  a 2026 addition — an aggregate hash that makes two manifests provably the
  same site, plus `a`/`A` lineage tags so anyone can pin and republish
  someone else's site under their own key. Credible exit for a website.
  fiatjaf's "subjective apps" sketch goes further: a web client addressed by
  content hash, releases adopted voluntarily through the social graph — his
  answer to "web apps can't be true user agents."
  *(How to actually ship one, with the failure modes:
  [`~/Documents/nostr-dev/docs/patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md).)*
- **Zapstore**: permissionless app distribution with WoT instead of a
  blessed catalog; evolving from "user against the world" verification to
  **community catalogs** that do the trust heavy-lifting. The forcing
  function is real: OS-vendor sideloading crackdowns ("you're either a
  fully-KYC'd developer or you're a terrorist" — Franzap).
- **Composable clients**: napplets (sandboxed single-file mini-apps whose
  host runtime mediates signing, relays, uploads, permissions — "you should
  be able to compose your clients"), Soapbox Tiles, fiatjaf's revived
  nostr-apps idea. Direction: Nostr expertise concentrates in runtimes,
  relays, and libraries; app authors stop needing to know about keys at all.

## Identity, trust, and time

- **Signer maturity**: NIP-46 bunkers, Amber/NIP-55, FROST/musig2 threshold
  schemes ("pomegranate"); next frontier is signing *UX* — specialized
  signers, budgets, "the user must understand what they're signing within
  half a second, then you can auto-approve" (hzrd149).
- **Key rotation still unsolved, deliberately**: the field is converging on
  social recovery / attestation-based migration (Constant's expiring musig2
  association events; Malmi's keeper-device + per-device keys; Gigi/Pablo's
  "your friends tell people it's actually you") rather than any formal
  scheme. "You are not your npub. Your npub is a pointer."
- **Provable time**: OpenTimestamps integration (NIP-03 → Constant's
  NIP-3B/3C: stamp hash(id+sig), embed the proof) as the defense of history
  against key compromise and retrospective fabrication.
- **Permissioned environments from permissionless blocks**: Constant's TEPP
  / Kidstr (guardian-managed lists of people/places/things enforced at
  signer, client, and relay) as the freedom-tech answer to age-verification
  and digital-ID law — expect this whole area (child safety, SFW modes,
  supervised onboarding) to grow as regulation lands.

## Networking beyond the social layer

- **Nostr keys as network identity**: FIPS (mesh routing to a pubkey
  instead of an IP; peer discovery and NAT traversal over relays), Malmi's
  Nostr VPN (WireGuard negotiated over relays, peers addressed by npub,
  Cashu-incentivized exit nodes), Hashtree (content-addressed filesystem +
  git on Blossom, convergent encryption for host deniability). The pattern:
  Nostr as the *coordination and identity plane* for arbitrary protocols —
  "DNS and IP are the worst offenders" of internet centralization.
- **Money in-band**: Cashu/NIP-60 wallets as events (your ecash follows
  you), nutzaps as self-verifying payment receipts, HTTP-402/bearer-token
  flows replacing negotiation dances, DVMs as pay-per-use compute. The
  restaurant model of monetization: sell something actually scarce, no
  compliance department.

## The AI convergence

The loudest new thesis of 2025–26, and it cuts both ways:

- **Nostr as agent substrate**: "a neutral substrate that has money,
  identity, cryptography, and web-of-trust baked in" (Pablo). Agents mint
  their own npubs, hold NIP-60 wallets, discover tools via NIP-89/90, pay
  authors of signed knowledge that helped them. Signed provenance becomes
  existential as AI slop compounds — maintainer-signed docs and snippets
  outrank the model's own priors.
- **AI as adoption lever**: agent-assisted building collapses the cost of
  the micro-clients the philosophy always wanted (Malmi writes "basically
  zero" code by hand; Constant ships constantly as a self-described
  non-programmer; 80% of a SEC workshop shipped a working applet). Hodlbod's
  hope: AI-assisted hacking of open protocols "tears down walled gardens";
  his warning, seconded by everyone: AI-built apps that skip routing,
  handlers, and WoT are architecturally hollow and quietly re-centralize.
- **The training-data window**: "we have this window of opportunity to
  steer the LLMs and the future of technology into a freedom-tech
  direction" (Malmi) — publish your thinking where models will learn it, or
  the next generation of tools knows only Stripe, Cloudflare, and GitHub.
  Early evidence it works: agent workflows "were always trying to do
  client-server, REST, username-password… now Nostr is in the training
  data" (Sandwich).

## Open problems, honestly stated

1. Key rotation / compromise recovery — social schemes sketched, nothing
   deployed at scale.
2. Outbox-model completeness — most clients still don't fully implement
   discovery, migration, or re-broadcast; fiatjaf's two-notes experiment
   still indicts the ecosystem.
3. Blossom link-healing and content longevity (the "Nostr pacemaker"
   daemons) — obvious, unbuilt.
4. Bootstrapping trust for relay discovery (NIP-66 + WoT) — early.
5. Large-group private messaging — MLS (White Noise/marmot) vs
   double-ratchet trade-offs unresolved; group privacy at scale may be
   unachievable in principle.
6. Monetization for creators who need it today — "if you are starving,
   might as well come and starve here" (Constant). The honest pitch is
   pioneering, not parity.
7. The DM question — whether encrypted private communication belongs on
   Nostr at all (Constant: publications protocol; Malmi: no-network-effect
   privacy is exactly where Nostr *can* win; hzrd149: use Nostr as lookup,
   let Signal-class protocols carry the payload).


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/design-synthesis.md` · snapshot 2026-10-10

# Designing solutions on Nostr — synthesis

> Codification of the design principles for Nostr applications. Synthesized from
> Hodlbod's "Building Nostr" book (Coracle), fiatjaf's writing on fiatjaf.com,
> NIP-01, the NIPs kind registry, the OpenSats client report, the Nostr Rising
> podcast series, and the Gossip / Outbox literature.
>
> This is the first document any Claude session in this workspace should read
> before designing or building anything Nostr-shaped. It is the "why" layer.
> `CLAUDE.md` is the "what is installed" layer. [`docs/kind-cheatsheet.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md) is the
> "what to do when picking a kind" layer.

## 1. The single load-bearing idea

Nostr's whole shape falls out of one move: **signatures decouple authentication
from storage**. The signed event is the unit of truth. Relays are
interchangeable mirrors. The address space is keypairs. Everything else —
outbox routing, replaceable events, NIP-05, GRASP — is a downstream consequence.

When you design for Nostr, you are not designing a system. You are designing:

1. an event schema (kind + tags + content shape), and
2. a routing strategy (which relays this kind goes to / comes from).

The runtime is whatever relays happen to be around.

This is also the trap. People keep trying to reintroduce centralization — a
canonical relay, a global index, a "main" feed — because eventual-consistency-
across-anonymous-mirrors is genuinely uncomfortable. **Resist that.** Lean into
"many hackish attempts" (fiatjaf's phrase, see [`sources/fiatjaf-vision.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md)) as
a feature, not a bug.

### Worked example: same idea, applied to packet routing (FIPS)

The cleanest demonstration that this load-bearing idea generalizes outside
Nostr's own event/relay surface is **FIPS** (Free Internetworking Peering
System; [`sources/fips.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fips.md)). FIPS is a decentralized mesh routing protocol
whose nodes are identified by **the same secp256k1 keypairs as Nostr nodes**.
Peer discovery, endpoint advertisement, and NAT-traversal signaling all
happen over Nostr relays (kind 37195 addressable adverts; kind 21059
NIP-59-wrapped offers/answers). Where Nostr decouples authentication from
event storage, FIPS decouples it from packet routing — but the underlying
move is identical: signed thing + interchangeable mirrors. If you're
designing anything that wants "Nostr keypair as identity" but isn't itself a
Nostr application, FIPS is the most fully-developed reference architecture
available, and its 13 layered design specs in `repos/fips/docs/design/` are
worth reading on their own as a protocol-design exercise.

## 2. Routing: relay-feed vs outbox vs gossip

Three positions on the same axis, increasing sophistication. Pick deliberately;
don't drift.

### Relay-feed (fixed list)

The simplest model. The client connects to a curated set (typically 3–10
relays), publishes there, reads there. Easy to reason about; predictable.

Costs:
- **Centralization** — popular relays carry everything; the long tail dies.
- **Brittle to censorship** — if the relays in your fixed set drop you, you're
  gone, and your followers can't find you.
- **Doesn't scale** — you either over-fetch (connect to thousands of relays
  defensively) or under-fetch (miss the author's actual data).

Right choice when: the relay set is *intentional* and *bounded*. A community
relay, a private/team relay, a topical feed, a paid index. Not the right choice
for a general-purpose social client.

### Outbox (NIP-65, kind 10002)

Each user advertises their relays via a kind 10002 event. The two flags:

- `write` ≡ **OUTBOX** — where they publish.
- `read`  ≡ **INBOX**  — where DMs/mentions should be sent.

Routing rules that fall out of this:

| Action | Where to write | Where to read |
|---|---|---|
| Read someone's posts | — | their **OUTBOX** |
| Send a DM / mention | recipient's **INBOX** + your own INBOX (for record) | — |
| Publish your own post | your **OUTBOX** + tagged users' **INBOX** | — |
| Publish a profile / follow list / relay list | your **OUTBOX** | — |

The honest framing from the literature: outbox is **necessary but not
sufficient**. NIP-65 only solves "who-publishes-where for kind:1-style social."
Communities, DMs, topical feeds, search/indexing relays — none of those are
solved by NIP-65.

### Gossip (Mike Dilger's superset)

Outbox plus every other discoverable relay hint:

- `nprofile` URIs that include relay hints,
- NIP-05 metadata that names relays,
- relay hints in `e`/`p`/`a` tags on events that mention people,
- observed presence of authors in replies on relays you already speak to.

The Gossip client (mikedilger/gossip) is the canonical reference. NDK and
Coracle both implement gossip-flavored outbox. If you build a serious client,
you want gossip-flavored outbox. If you build a tool or pipeline (a bot, a
specialty relay, a single-purpose client), a fixed list is often fine — be
explicit about why.

### Per-kind routing — the real design surface

Once you accept "no single relay set fits all jobs," the design question
becomes **per-event routing**:

- Public broadcast (kind 1 notes, reposts, reactions) → outbox + tagged inboxes.
- DMs (NIP-17 / NIP-44 / NIP-59) → inbox-only of recipient.
- Community / group content (NIP-29, NIP-72) → community relay only.
- Topical / curated feeds → topic relay (paid, vetted, or invite-only).
- Search / indexing (kind 30000-range listings) → indexer relay
  (`purplepag.es`, `user.kindpag.es`, `search.nos.today`; `relay.nostr.band` was unreachable as of 2026-09).
- GRASP / nostr-git events (kind 30617/30618/1617/1621/1622) → repo's GRASP
  relay first, fall back to user's outbox.

A client that does all five well is hard. A client that does one of them
brilliantly is the Nostr way.

## 3. Event kinds — taxonomy and decision rule

NIP-01 defines four classes by kind number. The relay's storage contract is
*different for each class*. This is the key design choice; it is also where
most people make the wrong call.

| Class | Range | Relay contract | Use for |
|---|---|---|---|
| **Regular** | 1–2, 4–44, 1000–9999, 40000+ | Store everything; full history. | Notes, reactions, deletions, reposts. **Default.** |
| **Replaceable** | 0, 3, 10000–19999 | Latest per `(pubkey, kind)`. | Single-current-value-per-user state: profile (0), follow list (3), relay list (10002). |
| **Ephemeral** | 20000–29999 | Not stored. Live broadcast only. | Live signaling: typing, in-flight signing (NIP-46), presence. |
| **Addressable** | 30000–39999 | Latest per `(pubkey, kind, d-tag)`. | Multi-keyed state: long-form by slug (30023), git repos by name (30617), lists. |

### Default to regular

This is the consistent advice across Hodlbod, fiatjaf, and the Coracle book.

> Regular events have history, are auditable, and degrade gracefully. The
> other three classes are optimizations that throw information away — only
> reach for them when you can articulate *why* throwing it away is the right
> call.

### When to reach for each non-regular class

- **Replaceable** — there is exactly one current value per user, and history is
  noise, not signal. Your relay list, not "all the relay lists you've ever had."
  Your profile picture, not a timeline of profile pictures.

- **Addressable** — same as replaceable, but you have multiple distinct items
  keyed by an identifier *you* control: one article per slug, one repo per
  name, one list per d-tag. Replaceable + cardinality.

- **Ephemeral** — persistence would actively be wrong. A "user X is typing"
  event that lives forever is bizarre. A NIP-46 in-flight signing request that
  hangs around for months is dangerous. Ephemerals are the right call when the
  event has only an instantaneous meaning.

- **Regular** — everything else. Including: things you might be tempted to make
  replaceable for "efficiency." If you want history, accountability, threading,
  or "who said what when" — use regular.

### Common smells

- A "settings" event that's regular and accumulates → should be replaceable.
- A "current location" event that's regular → should probably be ephemeral.
- A "blog post" that's regular and edited → should be addressable.
- A "comment" that's addressable so it can be edited → almost certainly wrong;
  comments are accountable, use regular and tombstone with a NIP-09 deletion if
  needed.
- A "draft" that's regular → should be addressable (one current draft per
  user-defined identifier).

## 4. Picking a kind — concrete recipe

The instinct "check before you allocate" is the right one. The procedure:

1. **Read the canonical kind table** in
   [`nostr-protocol/nips/README.md`](https://github.com/nostr-protocol/nips/blob/master/README.md).
   This is the registry. (See vendored copy in [`docs/sources/nips-readme-kinds.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md)
   for offline reference.)

2. **Use NAK locally** — it ships with NIP descriptions:
   ```
   nak nip            # list all NIPs nak knows
   nak nip 34         # show NIP-34 (git stuff)
   nak nip open 34    # open NIP-34 in the browser
   ```
   On this machine NAK knows about 91 NIPs.

3. **Probe the live network** to see whether a kind is in use *even if
   undocumented*:
   ```
   nak req -k 39999 -l 1 wss://relay.damus.io wss://nos.lol
   ```
   This is the most underrated step. Plenty of clients ship private kinds that
   aren't in the registry but show up everywhere. We confirmed kind 39999 is
   occupied in the wild even though no NIP claims it.

4. **Reuse before you invent.** If your data fits an existing schema, use the
   existing kind. Inventing a new kind for "long-form content" because you
   don't like NIP-23 fragments the ecosystem and no one will read your events.
   This is the single biggest mistake new builders make.

5. **For new public kinds** — open a PR against
   [`nostr-protocol/nips`](https://github.com/nostr-protocol/nips). The community
   process is informal but real. For a private/in-house kind that only your
   client cares about, pick a high number in an unallocated band, document it
   in your repo, and accept that other clients will ignore it.

A practical 30-second cheatsheet lives in [`docs/kind-cheatsheet.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md).

## 5. Architectural philosophy — distilled

From Nostr Design's "Guiding Principles," fiatjaf's posts, Hodlbod's book, and
the OpenSats report:

- **User sovereignty above all.** Control of keys, choice of relays, no lock-in.
- **Signatures decouple data from storage.** Same event valid anywhere; relays
  are interchangeable mirrors, not authorities.
- **Build small things that do one thing well.** Modular clients > monolithic
  platforms. ("A client that does one thing really well.")
- **Embrace the messiness.** There is no global state. Discovery is "many
  hackish attempts." Eventual consistency is the norm.
- **Don't censor; expose filtering.** Give users tools, don't decide for them.
- **Per-relay context matters.** User-specific (outbox), public-feed
  (broadcast), topical/community (curated), DMs (inbox-only). One relay set
  doesn't fit all jobs.

## 6. What this means for building solutions on Nostr

The design surface is four decisions, taken in this order:

### 1. What's the event schema?

A kind, a tag set, a content shape. This is the only schema you get; **tags
are your data model.** Reuse existing kinds and tag conventions wherever you
can. Document any new ones in your repo.

### 2. Which class of event?

Default regular. Justify any other choice in writing — what are you optimizing,
what are you discarding?

### 3. What's the routing strategy per kind?

- Outbox for broadcast,
- inbox for delivery,
- topic relay for community,
- index relay for search.

Don't conflate.

### 4. What's the failure model?

Events arrive duplicated. Events don't arrive at all. Events arrive late, out
of order, or from a relay that's lying. **Build for that:**

- idempotent ingest,
- dedup by event id,
- treat relay responses as "best effort,"
- never assume "I queried 3 relays and got nothing, therefore it doesn't exist."

The recurring theme: **don't build platforms, build pieces.** A client that
does one thing well, against an event schema that other clients can also speak.
Censorship-resistance, identity portability, and the entire point of the
protocol fall out of that. Try to build a "Nostr Twitter" and you'll fight the
protocol; build a Nostr-native long-form reader, a code-collaboration tool, or
a feed algorithm, and the protocol carries you.

## 7. Local sources

Vendored where licensing allows; summaries + links otherwise. See
`docs/sources/`:

- `nip-01.md` — NIP-01 verbatim (MIT, the canonical event-kind classification)
- `nips-readme-kinds.md` — the NIPs README kind registry table
- `fiatjaf-vision.md` — summary + link to fiatjaf's "A vision for content discovery"
- `outbox-model.md` — summary + links to Nostrify, Why Nostr, gossip docs
- `hodlbod-book.md` — pointer to building-nostr (cloned into `repos/` for offline read)
- `nostr-rising.md` — episode list + summaries of the Nostr Rising series
- `nostr-design-principles.md` — Nostr Design "Guiding Principles" summary
- `opensats-advancements.md` — OpenSats "Advancements in Nostr Clients" summary
- `videos.md` — pointers to fiatjaf / Hodlbod / Pablo / Dilger talks on YouTube


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/kind-cheatsheet.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.

# Picking a Nostr event kind — 30-second cheatsheet

> Companion to [`docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §3–4. When you need to ship.

## Step 0 — Default

Use **regular** (kind in `1–2`, `4–44`, `1000–9999`, or `40000+`) unless you
have a written reason not to.

## Step 1 — Class

```
                  one-current-value-per-user?
                     /              \
                   yes               no
                    |                 |
        keyed by a d-tag?           ephemeral signal?
           /        \                   /        \
         yes        no                yes         no
          |          |                 |           |
   ADDRESSABLE  REPLACEABLE       EPHEMERAL    REGULAR  ← default
   30000-39999   10000-19999     20000-29999   1-9999, 40000+
```

## Step 2 — Existing kind? Use it.

Before allocating, do all four checks:

```bash
# 1. Search the canonical registry.
$EDITOR ~/Documents/nostr-dev/docs/sources/nips-readme-kinds.md
# or upstream: https://github.com/nostr-protocol/nips/blob/master/README.md

# 2. Ask NAK what NIPs it knows.
nak nip                  # list
nak nip 34               # show one
nak nip open 34          # open in browser

# 3. Probe the live network for events of that kind.
#    Even undocumented kinds may be in use by clients.
#    Real-world example: kind 37195 is FIPS overlay-discovery adverts (the
#    digits spell "FIPS" — 7=F, 1=I, 9=P, 5=S). Not in the canonical
#    NIPs registry, but live on relay.damus.io and nos.lol. Anyone who
#    allocated 37195 without probing would have collided with FIPS.
nak req -k <KIND> -l 3 wss://relay.damus.io wss://nos.lol wss://relay.primal.net

# 4. Probe with a tag filter to see realistic schemas.
nak req -k <KIND> -l 5 wss://relay.primal.net | jq -c '{kind,tags}'
```

If anyone is using it, your options are: (a) match their schema, (b) pick a
different number, (c) propose a NIP that consolidates.

## Step 3 — If you must invent

- Pick a number in a *gap* of the appropriate class. The README registry has
  many.
- Document it in your repo with: kind, class (regular/replaceable/ephemeral/
  addressable), tag schema, content shape, *why* you chose this class.
- For anything you want other clients to interoperate with, open a PR against
  [`nostr-protocol/nips`](https://github.com/nostr-protocol/nips). The community
  process is informal but real.

## Step 4 — Tag conventions matter as much as kinds

The kind says "what shape." The tags say "what data." Reuse before you invent:

| Tag | Meaning |
|---|---|
| `e` | reference to another event id |
| `p` | reference to a pubkey |
| `a` | reference to an addressable event (`<kind>:<pubkey>:<d-tag>`) |
| `d` | identifier for an addressable event |
| `t` | hashtag / topic |
| `r` | URL or relay reference |
| `k` | kind (used in NIP-22 comments to point at parent kind) |
| `client` | client name + version |
| `alt` | accessibility / fallback rendering |
| `expiration` | unix timestamp after which the event should be considered expired |
| `subject` | thread title (NIP-14) |

If your data is "a reference to a thing + an annotation," it's almost always
**existing tag + new content**, not new kind.

## Common smells (recap from the synthesis)

- A "settings" event that's *regular* and accumulates → should be **replaceable**.
- A "current location" event that's *regular* → should probably be **ephemeral**.
- A "blog post" that's *regular* and edited → should be **addressable**.
- A "comment" that's *addressable* so it can be edited → almost certainly wrong;
  comments are accountable, use **regular** and tombstone with NIP-09.
- A "draft" that's *regular* → should be **addressable** (one current draft per
  user-defined identifier).

## Quick reference — well-known kinds you'll meet

| Kind | What | Class | NIP |
|---|---|---|---|
| 0 | User metadata (profile) | replaceable | 1 |
| 1 | Short text note | regular | 1 |
| 3 | Follow list (contact list) | replaceable | 2 |
| 4 | Encrypted DM (legacy, deprecated for NIP-17) | regular | 4 |
| 5 | Event deletion request | regular | 9 |
| 6 | Repost | regular | 18 |
| 7 | Reaction | regular | 25 |
| 9 | Chat message | regular | 28 |
| 16 | Generic repost (non-kind-1) | regular | 18 |
| 1059 | Gift wrap (privacy envelope) | regular | 59 |
| 1063 | File metadata | regular | 94 |
| 5128 | **nsite manifest snapshot** | regular | 5A |
| 1311 | Live chat message | regular | 53 |
| 1617 | Patch (git) | regular | 34 |
| 1621 | Issue (git) | regular | 34 |
| 1622 | Reply (git issue / PR) | regular | 34 |
| 1630–1633 | Status (git, open/closed/merged/draft) | regular | 34 |
| 9734/9735 | Zap request / receipt | regular | 57 |
| 10000 | Mute list | replaceable | 51 |
| 10002 | **Relay list (outbox/inbox)** | replaceable | 65 |
| 10006 | Pinned events | replaceable | 51 |
| 10019 | **Nutzap mint list** | replaceable | 61 |
| 10063 | **Blossom server list** (user's media servers) | replaceable | BUD-03 |
| 15128 | **Root nsite manifest** (static site; MUST NOT carry `d`) | replaceable | 5A |
| 17375 | Cashu wallet | replaceable | 60 |
| 22242 | Auth (NIP-42 client auth challenge) | ephemeral | 42 |
| 24133 | NIP-46 connect (Nostr Connect / bunker) | ephemeral | 46 |
| 27235 | HTTP auth (NIP-98) | ephemeral | 98 |
| 30000 | Follow set | addressable | 51 |
| 30002 | Relay set | addressable | 51 |
| 30008 | Profile badge | addressable | 58 |
| 30009 | Badge definition | addressable | 58 |
| 30023 | Long-form article | addressable | 23 |
| 30024 | Long-form draft | addressable | 23 |
| 30311 | Live event | addressable | 53 |
| 30402 | Classified listing | addressable | 99 |
| 30617 | **Git repository announcement** | addressable | 34 |
| 30618 | Git repository state | addressable | 34 |
| 31922 | Date-based calendar event | addressable | 52 |
| 34128 | ~~Legacy nsite per-path event~~ — **deprecated, relays refuse it** | addressable | 5A |
| 35128 | **Named nsite manifest** (`d` = `^[a-z0-9-]{1,13}$`) | addressable | 5A |
| 31923 | Time-based calendar event | addressable | 52 |
| 32267 | **Software application** (Zapstore app metadata, `d` = package id) | addressable | 82 (PR) |
| 30063 | **Software release set** (Zapstore, `d` = `<package_id>@<version>`) | addressable | 82 (PR) |
| 3063 | **Software asset** (Zapstore per-binary file metadata; *not* NIP-94's 1063) | regular | 82 (PR) |
| 30509 | **Cryptographic identity link** (NIP-C1, `d` = cert SHA-256) — binds an APK signing key to a Nostr identity | addressable | C1 |
| 39000–39009 | Group metadata (NIP-29) | addressable | 29 |

For anything not on this list: do Step 2.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/known-issues.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.

# Known issues — local stack quirks

> Issues a sibling agent encountered while building `~/work/nostr-archive/`
> against this workspace's local stack. Documented here so future sessions
> don't re-discover them.

Each entry: what breaks, why, the workaround on this machine, and (if
applicable) the upstream fix to track.

## 1. ngit-relay nginx emits CORS headers twice

**Symptom.** A browser fetching anything from `http://localhost:8081`
fails with:

```
Access-Control-Allow-Origin: * (multiple)
The 'Access-Control-Allow-Origin' header contains multiple values...
```

The browser blocks the response. `curl -i` shows two
`Access-Control-Allow-Origin: *` headers in the response.

**Cause.** The container's `src/nginx.conf` adds CORS headers via
`add_header` inside `location @proxy { ... }`, *and* the upstream Khatru
server (proxied to `localhost:3334`) also emits the same headers. Nginx
passes both through — the response ends up with duplicate CORS headers,
which all major browsers reject per the CORS spec.

**Affects.** Any browser-based client hitting the local GRASP / Blossom
server. The TS examples in [`sdk/examples/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) don't trigger it because
they run in Node (no browser CORS check). It surfaces the moment you
serve a static page from one origin and hit `localhost:8081` from the
page's JS.

**Workaround (runtime, applied per container start).** Add five
`proxy_hide_header` lines inside `location @proxy` so nginx strips
Khatru's headers and keeps only its own:

```bash
docker exec ngit-relay-ngit-relay-1 sh -c '
  sed -i "/location @proxy {/a\\
        proxy_hide_header Access-Control-Allow-Origin;\\
        proxy_hide_header Access-Control-Allow-Methods;\\
        proxy_hide_header Access-Control-Allow-Headers;\\
        proxy_hide_header Access-Control-Expose-Headers;\\
        proxy_hide_header Access-Control-Max-Age;
  " /etc/nginx/http.d/default.conf && nginx -s reload
'
```

Verify with:

```bash
curl -sI -H 'Origin: http://localhost:9000' http://localhost:8081/list/0000000000000000000000000000000000000000000000000000000000000000 \
  | grep -i access-control-allow-origin
# expected: exactly one line
```

**Note.** This patch is **runtime only**. If you `sudo docker compose
down` and `up`, the patch is gone — re-apply. To make it persistent,
edit `repos/ngit-relay/src/nginx.conf` and `docker compose up -d
--build`. We deliberately don't patch the source in-place because
`repos/ngit-relay` is a clone of the upstream reference implementation
and we want it to track upstream cleanly.

**Discovered by.** The sibling agent building `~/work/nostr-archive/`'s
browser client. See `~/work/nostr-archive/client/README.md` § "Known
nginx CORS quirk in ngit-relay" for the original report.

**Upstream.** Worth filing on the ngit-relay project. The fix is one
config block; the regression is browser-only so the test matrix didn't
catch it.

## 2. Khatru evicts kind:30617 events by `(pubkey, kind)` ignoring `d`-tag

**Symptom.** Re-publishing a kind:30617 GRASP repo announcement under
one `d`-tag silently evicts a different repo's kind:30617 by the same
pubkey. Querying for the *previous* repo returns nothing, even though
the announcement was previously visible.

**Cause.** Per NIP-01, kinds 30000–39999 are *addressable*: relays must
keep the latest event per `(pubkey, kind, d-tag)`. The Khatru
implementation packaged in the local ngit-relay appears to evict on
`(pubkey, kind)` only — treating addressable events as if they were
plain replaceable.

**Affects.** Any pubkey publishing more than one GRASP repo to the local
relay. Single-repo workflows don't see this.

**Reproducer (informal).**

```
nak event --sec $NSEC -k 30617 -t d=alpha ws://localhost:8081
nak event --sec $NSEC -k 30617 -t d=beta  ws://localhost:8081
# both queryable
nak event --sec $NSEC -k 30617 -t d=alpha ws://localhost:8081
# 'beta' is now gone in the buggy version
```

**Workaround.** **Also publish each kind:30617 to a second relay that
handles addressable events correctly.** A standalone `nostr-rs-relay`
on `:8080` (already part of this workspace, see
`configs/local-services.json` → `available_on_demand.nostr_rs_relay`) is
a clean choice. Or use a public relay (`wss://relay.ngit.dev`,
`wss://relay.damus.io`).

The public relay you replicate to acts as the source of truth for
multi-repo announcements; the local relay still serves git pushes for
whatever repos *it* still has. If the bug is in your specific Khatru
build, mirroring is also the diagnostic — when the local query disagrees
with the public query, you've hit it.

**Upstream.** Track via the Khatru codebase
(`github.com/fiatjaf/khatru`) and the eventstore module the local
container uses (`fiatjaf/eventstore` — see
`relays/khatru-example/go.mod` for the version pinned in our example
relay). The eviction logic for addressable events lives in the
eventstore backend (`slicestore`, `lmdb`, etc.) — different backends
may have different behavior.

**Discovered by.** The sibling agent building `~/work/nostr-archive/`,
which publishes one kind:30617 per archive and one per archive's
GRASP-as-structural-layer (so two per archiver, same pubkey, same
kind, different d-tag).

## 3. `relay.zapstore.dev` whitelist verifier does not follow NIP-34 / GRASP repos

**Symptom.** Publishing kind 32267 / 30063 / 3063 events to
`wss://relay.zapstore.dev` is rejected with:

```
event pubkey is not allowed. Visit https://zapstore.dev/docs/publish for more information.
```

Committing a `zapstore.yaml` containing `pubkey: <publisher-npub>` at the
root of the linked source repo — the official path documented at
<https://zapstore.dev/docs/publish> — does **not** lift the rejection when
the source repo is a NIP-34 GRASP repo. The relay continues to refuse.
Kind 30509 (NIP-C1 cert link) and kind 0 (profile) under the same pubkey are
accepted; only the app-event trio is gated.

**Cause.** The relay's auto-whitelist verifier only resolves repository
references against a fixed set of forge hosts — confirmed against
[the publish docs](https://zapstore.dev/docs/publish):

> auto-whitelisting works for repositories hosted on GitHub, GitLab,
> Codeberg, and self-hosted Gitea/Forgejo instances.

Even though kind 32267's `repository` tag is a valid NIP-34 `naddr1…`, the
verifier does not (yet) resolve it to a kind 30617, follow the announced
`clone` URLs, and fetch `zapstore.yaml` from the resulting git tree.
GRASP-hosted projects therefore can never auto-whitelist via the
yaml-in-repo flow.

**Affects.** Any publisher whose canonical source repo is a GRASP repo —
i.e., the canonical configuration of *this* workspace. Three options
remain:

1. **Mirror to a supported forge.** Push the source to
   `github.com/<you>/<repo>` (or Codeberg, GitLab, Gitea, Forgejo) with the
   same `zapstore.yaml` at root. Re-issue the app events; the verifier
   reads the yaml from the forge, matches pubkey↔repo, and admits future
   publishes from that pubkey. Requires keeping the forge mirror in sync
   on every release.
2. **Vertex reputation.** Accumulate Nostr social activity under the
   publisher pubkey until their reputation system admits it. Passive;
   not directly actionable.
3. **Skip `relay.zapstore.dev`.** Three general-purpose relays
   (`relay.damus.io`, `nos.lol`, `relay.primal.net`) accept the same
   events with no whitelist gate. Any outbox-model-aware Zapstore client
   not pinned exclusively to the Zapstore relay will find the app from
   those.

**Discovered by.** This workspace, 2026-05-12, publishing OTSuite Mobile
v2.0.0 under `npub1zkd4h6zshlh2a3yuzaxqk2wgk2kv2za5trz76rd5upwy06fscjrq8mk5ta`.
The repo had its kind 30617 / 30618 on `relay.ngit.dev`, `zapstore.yaml`
with `pubkey: …` was committed (`6444c9d…`), and the public clone URL was
reachable — the relay still rejected. Cert-link (30509) and profile (0)
under the same pubkey were accepted.

**Upstream.** Worth filing on the `zapstore` org — implementing
naddr-aware verification would close the gap. Track at
<https://github.com/zapstore> (there is no dedicated relay repo public at
the time of writing; the `zsp` CLI is the closest published artifact).

## 4. `relay.ngit.dev` rejects events that don't carry an NIP-34 `a`-tag

**Symptom.** Pushing zapstore-style events (kind 30509, 30063, 3063, or
even kind 0) to `wss://relay.ngit.dev` under a pubkey that *is* the
maintainer of a stored GRASP repo returns:

```
Event event must reference an accepted repository or accepted event
```

Only kind 32267 lands, because `zsp` emits it with an `a`-tag containing
the kind 30617 coordinate of the linked repo.

**Cause.** `relay.ngit.dev` runs the same Khatru policy as the local
`ngit-relay` container (`ws://localhost:8081`): an event is only stored if
it explicitly references a stored repo by NIP-34 coordinate (`a`-tag
`30617:<pubkey>:<d>`) or by event id of an already-accepted event
(`e`-tag). Zapstore's release/asset/identity events reference the app by
`i`-tag (package id) instead, which the policy doesn't recognize. By design
— it's a *git repository* relay, not a general-purpose one — but the
selective acceptance is surprising on first contact.

**Affects.** Any flow that publishes non-NIP-34 events under a pubkey
whose primary identity is "GRASP repo maintainer." The most concrete case
is the zapstore publish documented in
[`patterns/zapstore-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md):
four of five event kinds bounce off `relay.ngit.dev` even though they're
all signed by the same npub that maintains the linked repo.

**Workaround.** Skip `relay.ngit.dev` for non-repo-tagged events; the
three general-purpose relays carry them fine. Hand-patching each event to
include an `a`-tag is possible but rewrites the event id (different
content → different sha256 → different signature), which then diverges
from the canonical event on every other relay — not worth it.

**Discovered by.** Same session as issue #3.

**Upstream.** Khatru policy in the `ngit-relay` reference implementation
(`repos/ngit-relay/`). Relaxing the rule to accept e.g. "any event from a
pubkey that maintains a stored repo, regardless of tag form" would close
this gap. Track via the `ngit-relay` project.

## 5. `nak event --sec ...` silently re-signed fully-formed events on stdin — RESOLVED in nak v0.19.2

**Resolved upstream.** nak commit
[`faac4d9`](https://github.com/fiatjaf/nak/commit/faac4d9440368fcad7f46c077089cc10fe37d81f)
(2026-03-17, "ensure an event is not resigned if it was already signed and
wasn't changed") first shipped in **v0.19.2**, tagged 2026-03-20. The `nak` on
`PATH` is v0.20.7 (§7.1), so it has the fix. The behaviour in §5.1 started in
v0.7.9 (commit `134d122`, 2024-10-29) and lasted **through v0.19.1**.

**The rule now.** A piped event that already carries a `sig` and that no flag
modifies is printed and published exactly as given. `--sec`,
`NOSTR_SECRET_KEY` and `--auth` do not count as modifications, and the key is
used only to answer NIP-42 AUTH. nak still re-signs when:

- a flag modifies the event: `-k`, `-c`, any tag flag (`-t`, `-e`, `-p`, `-d`,
  `-h`, `-a <naddr>`), `--ts`/`--created-at`, `--pow`, `--musig`;
- the input is incomplete (no `kind`, `created_at` or `sig`), so nak fills it
  in;
- **`--force-sign`** is given (new in v0.19.2).

A re-sign uses the `--sec` key, or nak's per-machine default key if there is
none. If that isn't the event's own key, `pubkey`, `id` and `sig` all change:
the old trap. The odd one out is `-a <pubkey>`: it overwrites `pubkey` but does
**not** re-sign, so the output is an invalid event.

**Gift wraps.** An unmodified NIP-59 wrap now goes through `nak event --auth
--sec <maintainer-key> <relay>` intact. Its `pubkey` stays the ephemeral key the
seal was encrypted to, so the recipient can decrypt it. `--force-sign`, or any
flag that modifies the event, still overwrites that ephemeral pubkey with the
`--sec` key and makes the wrap undecryptable (mechanism in §5.1). Never pass
either with a wrap.

**The reverse trap.** Anything that relied on `--sec` to re-sign now publishes
the input unchanged. That includes re-authoring an event under another key and
repairing a hand-edited signed JSON. nak checks only that a `sig` is *present*,
not that it verifies, so an edited event goes out with its stale `id` and `sig`
and relays reject it. Add `--force-sign`.

**Pre-flight.** What `nak event` prints is what it would publish. So before
publishing a pre-formed event, run the same command without relay URLs and
compare. Use `jq -cS .` on both sides, because nak re-serialises JSON that
another tool wrote:

```bash
diff <(jq -cS . wrap.json) <(nak event --auth --sec "$NSEC" < wrap.json | jq -cS .) \
  && echo "publishes as given"
```

For an older `nak`, the TypeScript helper in §5.1 remains the route.

**Verified 2026-09-26, offline.** Every command ran inside `bwrap
--unshare-net` (loopback only), with no relay argument, so nothing was
published. Throwaway keys: A signed the input, B is the other `--sec`, R is the
gift-wrap recipient. "Re-signed as B" means pubkey B with a new `id` and `sig`,
still valid. v0.18.3 is the parked `~/.local/bin/nak.v0.18.3.bak`.

| Piped input → `nak event …` | v0.18.3 | v0.20.7 |
|---|---|---|
| note signed by A → `--sec B` | re-signed as B | **byte-identical** |
| same → `NOSTR_SECRET_KEY=B`, no flag | re-signed as B | byte-identical |
| same → `--sec A` (its own key) | byte-identical | byte-identical |
| same → `--sec B --auth` | not run | byte-identical |
| same → `--sec B -t x=y` | not run | re-signed as B |
| same → `--sec B --force-sign` | (no such flag) | re-signed as B |
| same → `--sec B -a <pubkey B>` | not run | pubkey B, old `id`/`sig`: **invalid** |
| note signed by A, content then hand-edited → `--sec A` | re-signed, valid | passed through, **invalid** |
| gift wrap A→R → `--sec B` | pubkey B, **R cannot decrypt** | byte-identical (also with `--auth`), R decrypts |
| gift wrap A→R → `--sec B --force-sign` | (no such flag) | pubkey B, **R cannot decrypt** |

R's decryption was checked two ways: layer by layer with `nak decrypt`, and
with `nak gift unwrap`. A forced re-sign with the event's own key also comes out
byte-identical, because signing is deterministic.

**Not tested: a live AUTH publish.** From the source: with an event on stdin,
`publishFlow` takes its plain (non-TTY) path. On `auth-required:` it calls
`relay.Auth(ctx, kr.SignEvent)`, which signs only a kind 22242 AUTH event with
the `--sec` key, and then republishes the same, unchanged `evt`.

To re-check after a nak upgrade (no relay argument, so nothing is published):

```bash
A=$(nak key generate); B=$(nak key generate)
nak event -k 1 -c hi --sec "$A" </dev/null > /tmp/a.json
nak event --sec "$B" < /tmp/a.json | cmp - /tmp/a.json && echo unchanged   # fixed
nak event --sec "$B" --force-sign < /tmp/a.json | jq -r .pubkey            # → B's pubkey
```

### 5.1 History: the entry as logged 2026-05-12 (nak v0.7.9 – v0.19.1)

Kept as written, apart from the dated notes.

**Symptom.** You pipe a complete, signed event into `nak event` and pass
`--sec` so the relay's NIP-42 AUTH challenge can be answered. nak prints
"publishing... success" and the relay accepts the event — but the event
that lands on the relay has its `pubkey` rewritten to whatever pubkey
corresponds to `--sec`, with a new `id` and a new `sig`. The original
`pubkey` is lost.

For a NIP-59 gift wrap this is silently *catastrophic*: the encrypted
content (the kind 13 seal) was created with `ECDH(ephemeral_priv,
recipient_pub)`. The recipient decrypts by computing
`ECDH(recipient_priv, event.pubkey)`. When nak overwrites `event.pubkey`
with the maintainer's identity, `event.pubkey` no longer matches the key
the ciphertext was sealed for — NIP-44 v2 decryption fails and the message
appears as undecryptable garbage on the recipient's side.

**Cause.** `nak event` documents that a piped event "is rehashed and
resigned if modified, otherwise just returned as given." The
modification detector treats a `--sec` whose derived pubkey differs from
`event.pubkey` as a request to change `event.pubkey`, then dutifully
rehashes and re-signs. There is no warning, no `--no-rehash` flag, and
the printed output is the re-signed event (visible only with `--verbose`
during a publish).

*Correction, 2026-09-26: the source shows a wider trigger.* From `134d122`
through v0.19.1, `event.go` set `mustRehashAndResign` whenever `--sec` or
`--prompt-sec` was set at all, and `NOSTR_SECRET_KEY` in the environment
counted too. Nothing compared the key with `event.pubkey`. With the event's
own key the re-sign was invisible, because deterministic signing gives
byte-identical output. With any other key, `pubkey`, `id` and `sig` were
rewritten. The effect was as described above.

**Affects.** Any pipeline of the form

```bash
nak event --sec <nsec> <relay-with-auth> < some-event.json
```

where `some-event.json` was produced by another tool and its `pubkey` is
not the same as the one derived from `<nsec>`. NIP-59 gift wraps are the
canonical victim (ephemeral wrap key by design). Same trap applies to
NIP-46 bunker responses you proxy, decoupled-key flows, anything signed
by an ephemeral session key, or events you're republishing from a relay
on someone else's behalf.

*Note, 2026-09-26:* the same pipe with no `--sec` flag was hit too whenever
`NOSTR_SECRET_KEY` was exported (measured on v0.18.3).

**Reproducer.**

```bash
# Pre-formed event with one pubkey...
nak event -k 1 -c hi --sec <nsec-A> </dev/null > /tmp/a.json
jq -r .pubkey /tmp/a.json   # → pubkey of A

# ...piped through nak with a *different* --sec for AUTH only
nak --verbose event --sec <nsec-B> wss://relay-needing-auth < /tmp/a.json \
  | grep -m1 pubkey
# → pubkey of B (silently rewritten), id changed, content preserved
```

**Workaround.** Don't pass `--sec` to `nak event` when publishing a
pre-formed event. For relays that demand NIP-42 AUTH this means you have
to handle AUTH yourself — and this workspace ships exactly that helper:

```bash
# In sdk/examples/publish-wrap-with-auth.ts:
NOSTR_SECRET_KEY=<nsec> npx tsx examples/publish-wrap-with-auth.ts \
  /tmp/event.json wss://auth-required-relay [more-relays]
```

The helper opens a raw `ws://` connection per relay, waits ~500 ms for a
proactive `["AUTH", <challenge>]` from the relay (and also handles the
`["OK", <id>, false, "auth-required: …"]` follow-up form), signs a kind
22242 AUTH event with the supplied key, retries the EVENT once, and
publishes the event **byte-for-byte unchanged**. Reusable for any
pre-formed-event + AUTH-relay combo, not just gift wraps.

If you need to clean up after hitting this in production, a NIP-09 kind:5
deletion request signed by the *re-signed* event's `pubkey` (i.e. the
maintainer key, since that's what nak replaced into the event) referencing
the broken event's `id` is what compliant relays will honour.

**Discovered by.** This workspace, 2026-05-12, sending a NIP-17 / NIP-59
gift-wrapped DM from the OTSuite Mobile maintainer to the Zapstore admin
to request a manual whitelist. The first two attempts went through `nak
event --auth --sec ...` and produced an undecryptable wrap; the helper
above is the fix.

*Note, 2026-09-26:* by then the fix had been out for 53 days (v0.19.2,
2026-03-20). Per §7.1, though, the `nak` on `PATH` until 2026-09-21 was
v0.18.3. Before logging a nak bug, compare `go version -m $(command -v nak)`
against the latest release.

**Upstream.** Worth filing on `fiatjaf/nak`. Either an explicit
`--no-rehash` flag, or a default that refuses to silently mutate
`event.pubkey` when the input event was already validly signed, would
prevent recurrence.

*Note, 2026-09-26: already done.* v0.19.2 shipped the second option: signed,
unmodified input is no longer re-signed. It checks that a `sig` is present,
not that it is valid. `--force-sign` is the explicit opt-in. There is nothing
left to file for this issue. The `-a <pubkey>` case in the rule above is
unfiled.

## 6. Signer login (NIP-07 / NIP-46 / NIP-55): relay rot and known-bad code on this machine

**Read first:** [`patterns/signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) is the
implementation guide. This section holds only the *state of this machine*, as
audited 2026-09-19.

**Relays.**
- `wss://relay.nsec.app` and `wss://relay.nostr.band` were unreachable from
  here (TLS/WS connect times out). Both are still hard-coded as defaults in
  several projects and libraries.
- `auth.nostr1.com` demands NIP-42 AUTH before accepting a 24133.
- `relay.nos.social` blocks kind 24133.
- The local ngit-relay (`:8081`) and nostr-rs-relay (`:8080`) are unsuitable
  for NIP-46 tests.
- Working set: see guide §3.6.

**Code that looks like a reference but is still wrong. Do not copy it
without the fix.** Found by reading; none of it has been fixed.

| Where | Bug | Guide § |
|---|---|---|
| Every Go app on **stock** `fiatjaf.com/nostr` nip46/keyer (CFR, icdib, Starcraft Replaystr, nostrkit, Nostr-Music-Sampler V1–V3, In-Your-Face) | Waits for EOSE from all relays; drops NIP-04 replies; 30 s hard-coded sign timeout; broken `switch_relays`; waits for the relay OK before reading replies | 3.7 |
| `In-Your-Face-try2/internal/identity/nostrconnect.go:110`, `cmd/iyf-web/main.go:299`; `I can do it better/cmd/icdib/api.go:216`, `main.go:202` | Bunker session built on a context that is cancelled when login returns, so the next sign fails with "context canceled" | 3.7 (Go lifetime rule) |
| `nostrkit/identity/identity.go:131,159` (and CFR, icdib, Replaystr) | Raw login input wrapped with `%w`, so a mistyped nsec ends up in error text; `Redact` leaves `secret=` in bunker URIs | 2.6 |
| `OTSuite-mobile` `Navigation.kt:297`, `NostrSigner.kt:117` | NIP-55 rejection (`RESULT_OK`+`rejected`) treated as success with an empty signature; missing column crashes instead of falling back | 4.3–4.5 |
| `Idle StarFighter/web/shell.js:808` | NIP-55 web: rebuilds the event with a new `created_at` after the callback, so the signature is invalid | 5.3 |
| `Nostr-Agenda` `SessionManager.kt:206` | NIP-46 `PERMS` contains bare `sign_event`, which Amber drops (the test only passed against nak) | 2.3 |
| `Desktop/Archon-Web/src/bunker.js:313` | nostrconnect accepts a bare `"ack"` (spoofable) | 3.4.5 |
| MKStack / `@nostrify/react` 0.50.2 `NUser.fromBunkerLogin` (EarthTreeMedia) | Restores with the user pubkey as the signer pubkey | 1 |
| `work/nostr-archive-app` `Publish.tsx:279`, ETM `LoginDialog.tsx:173`, grimoire `LoginDialog.tsx:393` | NIP-07 availability decided at render time | 6.1 |
| `Sessions/GRASPCONTROL` `manager.go:312` | QR flow can record the signer pubkey as the user when `get_public_key` times out; cancel doesn't stop the listener | 1, 3.4 |
| `Facebook-Museum/app/third_party/nostr/nip46/client.go:28` (`ConnectPerms`, used at `:116`, `signer/nostrconnect.go:77`) | Bare `get_public_key,sign_event` perms (Amber strips them); client key kept in session memory only (D44), so a reload makes the client a stranger again | 2.3, 3.3.2 |
| `Testimony/internal/signer/nip07.go` `SignEvent`; `third_party/nostr/FORK.md` "Known divergence" | Returned pubkey not compared with the session; the FORK note is stale (`portable.go:202` does send perms) | 2.1 |
| Stock `fiatjaf.com/nostr` `wellknownnostrjson.go` | NIP-05 bunker lookup returns an unassigned named return, so login targets the zero pubkey and looks like "signer never answered" (fixed as Testimony Delta 10) | 3.7 |
| `Sessions/Musig2_main/Archon-Web_v2/src/lib/core/identity/bunker-signer.ts:252` | Random client key per instance; nip44-only decrypt | 3.3.2, 3.5 |
| `Sessions/bunker-android` `Bunker.kt:58` (signer side) | `connect` acks without checking the secret; incoming signatures aren't verified | — |

**Secret leak to clean up.** `EarthTreeMedia-Nostr` `rip/blossom-upload.log`,
`rip/media-map.json`, `compare/new-assets.log` and `compare/new-assets-map.json`
contain a full `bunker://…secret=` URI and the client-key hex. A timed-out
`nak` call echoed its command line into the logs. Scrub the files, and
consider revoking that client in Amber.

**Discovered by.** Cross-project signer audit, 2026-09-19.

## 7. nsite publishing: the trap set, measured

**Read first:** [`patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md)
is the implementation guide. This section holds the machine-state findings that
made five separate agents each rediscover the same things.

### 7.1 Two `nak` binaries, and the one on `PATH` had no `nsite` command — RESOLVED

`nak` has an `nsite` subcommand — `nak nsite upload|download`, a complete NIP-5A
deploy in one call. Until 2026-09-21 you could not reach it:

| Binary | Version | `nsite`? | On `PATH`? |
|---|---|---|---|
| `~/.local/bin/nak` | **v0.18.3** (Feb 2026) | **no** | **yes, won** |
| `~/go/bin/nak` | build from source | **yes** | shadowed |

So `nak nsite` looked like it did not exist, and four projects
(Idle StarFighter → Nostr Workshop Board → Signer Login Tester → Cerebrate)
each hand-rolled a ~130-line Python deploy script instead.

**Resolved.** `nak` is now **v0.20.7** at `~/go/bin/nak` and is the only one on
`PATH`; the old binary is parked at `~/.local/bin/nak.v0.18.3.bak`. Two traps
survive for whoever reinstalls it:

- **`nak --version` prints `nak version debug`** regardless of the version. The
  release ldflags are not set by `go install`, so the version string is a lie.
  The truth is `go version -m $(command -v nak) | grep fiatjaf/nak`.
- **The vanity import path is broken.** `go install fiatjaf.com/nak@latest`
  fails — `fiatjaf.com/nak?go-get=1` advertises `git@github.com:fiatjaf/nak.git`,
  an scp-style SSH URL the Go tool rejects ("first path segment in URL cannot
  contain colon"). Install it as **`go install github.com/fiatjaf/nak@latest`**.
  (`fiatjaf.com/nostr`, the library, resolves fine — only `nak` is misconfigured.)

### 7.2 `blossom.primal.net` rewrites every `text/*` blob to `text/plain`

The nsite gateway serves each file with the `Content-Type` the Blossom server
recorded **at upload, keyed by sha256** — so a wrong type is only fixable by
changing the file's bytes. Measured 2026-09-21, same three files, same
uploader, fresh key:

| Server | `.css` | `.js` | `.wasm` | GET |
|---|---|---|---|---|
| `https://nostr.download` | `text/css; charset=utf-8` | `text/javascript; charset=utf-8` | `application/wasm` | 200 |
| `https://blossom.primal.net` | **`text/plain`** | **`text/plain`** | `application/wasm` | 302 → 200 |
| `https://blossom.band` | upload **400** | upload **400** | upload **415** | 404 |
| `https://azzamo.media` | upload **415** | upload **415** | upload **415** | — |
| `http://localhost:8081` | `text/css; charset=utf-8` | `text/javascript; charset=utf-8` | `application/wasm` | 200 |

**This corrects the folklore.** `nak blossom upload` was never the problem — it
sends the correct type from the file extension (Go's `mime.TypeByExtension`),
and both the local server and `nostr.download` honour it. `blossom.primal.net`
is not "unreliable" and is not content-sniffing: it deterministically flattens
`text/*` to `text/plain` and passes `application/*` through. A browser refuses
a stylesheet served as `text/plain` and refuses to register a service worker
served as `text/plain` — the page renders, completely unstyled, looking fine.

`blossom.band` now rejects fresh-key uploads outright (400 on text, 415 on
wasm), not just `.wasm` as previously recorded. Don't list it.
`cdn.satellite.earth` is still 500 on everything. `inner.sebastix.social` is
reachable again (its API is at the **root** path; `…/blossom/` is an HTML
catch-all that 200s for anything and false-positives every dedup check).

**`azzamo.media` is media-only and cannot host an nsite.** It is the owner's
server (first in their kind 10063, published by Amethyst) and it accepts
uploads from *any* key — the Blossom side is not gated the way
`relay.azzamo.net` is (`payment_required` + `restricted_writes`). But it
refuses by MIME with HTTP 415: `text/html` and `text/javascript` "not allowed
for security reasons"; `text/css`, `text/plain` and `application/wasm` "not
supported". Only `image/*` and friends get in, faithfully typed. Right server
for media and for the side channel's file drops; never a `server` tag on a
15128. Canonical list: `configs/blossom.json`.

**Live defect in the owner's 10063**: its second entry is
`cdn.satellite.earth/`, which 500s. Their phone's media has a dead fallback.
Fix from Amethyst — never with `nsyte --publish-server-list`, which would
replace the whole list.

**Workaround.** `nostr.download` first in the `server` list and abort if it
fails; primal second, as an availability mirror only. Inlining CSS/JS remains
good belt-and-braces, but it is a mitigation for server #2, not for `nak`.

### 7.3 Four divergent copies of the same deploy script

Each project copied the last one and drifted. As of 2026-09-21:

| | Idle StarFighter | Workshop Board | Signer Login Tester | Cerebrate |
|---|---|---|---|---|
| description tag | `description` | `description` | `description` | **`summary`** (not a spec tag) |
| non-spec `relay` tags | yes | yes | yes | no |
| aggregate `x` tag | no | no | no | no |
| `/404.html` | no | no | no | no |
| SPA route aliases | no | no | no | no |
| gateway verification | no | no | no | no |
| abort rule | all servers failed | all servers failed | all servers failed | first server failed |

All four sites are live, because the bugs are latent: primal is listed second,
so the wrong MIME only bites when `nostr.download` misses a blob; and none of
the sites has deep links. **Fixed at source:** `bin/nsite-deploy.py` is now the
shared implementation and does all six columns correctly. Point new projects at
it instead of copying a fifth time. The four existing scripts were deliberately
left alone — retrofitting them means redeploying four live sites.

### 7.4 A root site event with a `d` tag reports partial success and 404s

`relay.nsite.lol` rejects it outright (`"Root site events must not include a
'd' tag"`); every other relay accepts it happily. So a broken deploy prints
"2/4 relays accepted" and looks survivable, while the gateway can never find
the site. A `d` tag belongs to kind 35128. Found 2026-09-21 publishing
Cerebrate.

More generally: **counting relay OKs is not a test.** `bin/nsite-deploy.py`
fetches the gateway and checks the served content types before it claims
success.

**Discovered by.** nsite cross-project audit, 2026-09-21.

## How to log a new issue here

Format: a section like the above with **Symptom / Cause / Affects /
Workaround / Discovered by / Upstream**. Workspace-relevant only —
issues that belong upstream and don't affect this stack go straight to
the upstream tracker, not here.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/signer-login.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.

# Pattern: signer login — NIP-07, NIP-46 (bunker / nostrconnect), NIP-55 (Amber)

> **Read this before writing any login code.** Every app built on this machine
> got signer login working only after several broken attempts (Facebook-Museum,
> Testimony, Kubo, In-Your-Face, GRASPCONTROL, Idle StarFighter, Nostr-Agenda,
> OTSuite …). The failures were almost always the same dozen mistakes. They are
> collected here with the fix, so the next app gets it right in one go.
>
> Verified against the NIP texts on `nostr-protocol/nips` master, Amber source,
> and the library sources on **2026-09-19**. Spec dates are in §9. If you are
> reading this much later, re-check §9 first — NIP-46 and NIP-55 both changed
> in 2026.
>
> **Test with the Signer Login Tester** (§8, <https://npub138kdqjl645xz6rvuw92m2v4us0shhpxezgqqz9zrrj2jdstakvus86qzyh.nsite.lol/>): a static page that exercises every
> method below and logs every wire message. If your signer works there and not
> in your app, the bug is in your app.

---

## 0. Which methods to offer

| Platform | Offer | Notes |
|---|---|---|
| Web app / nsite | **NIP-07** + **NIP-46 paste `bunker://`** + **NIP-46 QR `nostrconnect://`** | NIP-55-over-web is optional and fragile (§5). The NIP-55 spec itself says web apps should prefer NIP-46. |
| Android native | **NIP-55** (Amber etc.) + **NIP-46** | Use Quartz's `nip55AndroidSigner`, don't hand-roll (§4). |
| Go desktop / daemon / CLI | **NIP-46** | Use the patched library from Testimony, not stock `fiatjaf.com/nostr` (§3.7). |
| Go→wasm in the page | NIP-07 via a JS bridge + NIP-46 | Extensions don't inject `window.nostr` into workers — bridge from the page (Facebook-Museum `cmd/wasm/extsigner.go`). |

Web clients must never ask for an nsec (Nostr-exp [`core/03-how-to-develop.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/core/03-how-to-develop.md)).
Local-key onboarding is acceptable only in native introductory apps.

---

## 1. The three keys (the #1 conceptual bug)

NIP-46 has three keypairs. Mixing them up causes most "logged in as the wrong
person" and "can't reconnect" bugs:

| Key | Who holds it | Where you see it |
|---|---|---|
| **client key** | your app, generated once, **persisted** | host part of `nostrconnect://<client-pubkey>` |
| **remote-signer key** | the signer | host part of `bunker://<remote-signer-pubkey>`; author of every response |
| **user key** | the signer | only via `get_public_key` |

- The remote-signer key **may** equal the user key (Amber) but usually doesn't
  (nsec.app, nsecbunker, nak with separate keys). **Always call
  `get_public_key` after `connect`** and use its result as the session pubkey.
- Persist all three plus the relays. Example bug: nostrify 0.50.2
  `NUser.fromBunkerLogin` restores with the *user* pubkey as the signer
  pubkey. It works with Amber and times out with everything else.

---

## 2. Rules that apply to every method

1. **Verify every signed event you get back.** Check that `verifyEvent(ev)` is
   true, that `ev.pubkey === sessionPubkey`, and that `kind`, `content`, `tags`
   and `created_at` equal what you asked for. Recompute the id yourself.
   Extensions can switch accounts under you; bunkers can return anything.
2. **Every request has a timeout, and every timeout is visible in the UI.**
   Humans approve on phones, so use about 120 s for connect and QR pairing and
   about 60 s per sign. Libraries default to *no* timeout: nostr-tools
   `sendRequest`, NDK `signer.timeout`, and applesauce all wait forever.
3. **Kind-scoped permissions.** Request `sign_event:<kind>` for each kind you
   will sign. Amber silently discards bare `sign_event`
   (`removeIf { kind == null && type == "sign_event" }`), for both NIP-46 and
   NIP-55.
4. **Log the wire.** Keep a debug view of each request, response, relay OK and
   error. Every multi-day debugging session here ended once someone looked at
   the raw 24133 traffic.
5. **Say the Amber caveats in the UI:**
   - Amber drops *all* incoming NIP-46 requests when its Android
     notification permission is off (the Android 13+ default).
   - Since Amber 6.5.0 it silently rejects requests whose `created_at` is more
     than 5 minutes off its clock.
6. **Never print the secret.** `bunker://…&secret=` and client keys have
   leaked into logs and error strings here several times, for example
   EarthTreeMedia `rip/*.log` and nostrkit `Redact`. Redact `secret=` before
   logging a URI, and don't wrap raw user input into errors with `%w`.

---

## 3. NIP-46 — remote signing (bunker and nostrconnect)

### 3.1 Wire format (current)

- Kind **24133** (ephemeral). `content` = **NIP-44** ciphertext of JSON. Requests
  are p-tagged with the remote-signer pubkey; responses are p-tagged with the
  client pubkey.
- Request: `{"id": "<random>", "method": "<m>", "params": ["<string>", …]}`. All
  params are strings.
- Response: `{"id": "<same>", "result": "<string>", "error"?: "<string>"}`. If
  `error` is present, the request failed. `sign_event`'s result is a JSON
  *string*, not an object.

| method | params | result |
|---|---|---|
| `connect` | `[remote_signer_pubkey, secret_or_"", perms_or_"", client_metadata_json]` | `"ack"` or the secret |
| `get_public_key` | `[]` | user pubkey, hex |
| `sign_event` | `[json({kind, content, tags, created_at})]` | `json(signed event)` |
| `nip44_encrypt` / `nip44_decrypt` / `nip04_encrypt` / `nip04_decrypt` | `[third_party_pubkey, text]` | text |
| `ping` | `[]` | `"pong"` |
| `switch_relays` | `[]` | JSON string `["wss://…"]` or `null` |
| `logout` | `[]` | `"ack"` (courtesy; you must still delete the client key) |

- `client_metadata_json` is `{"name":…,"url":…,"image":…}`. It was added
  2026-06-23. To send metadata without perms, pass `""` in the perms slot.
- **auth challenge:** a response of `{"id", "result":"auth_url", "error":"<URL>"}`
  means "open this URL". Keep listening for a **second response with the same
  id**, which is the real result.

### 3.2 URIs

**bunker://** (the signer creates it; the user pastes it into your app):
```
bunker://<remote-signer-pubkey>?relay=wss://a&relay=wss://b&secret=<single-use>
```

**nostrconnect://** (your app creates it; shown as a QR, or as a link on the
same phone):
```
nostrconnect://<client-pubkey>?relay=wss%3A%2F%2Fa&relay=wss%3A%2F%2Fb&secret=<hex>&perms=sign_event%3A1%2Cnip44_encrypt&name=MyApp&url=https%3A%2F%2Fmyapp.example
```
- Both `relay` and `secret` are required.
- `metadata=<json>` is the **old** form (before 2024-11). Use `name`/`url`/`image`.
- **Amber URL-decodes the whole query and then splits on `&` and `=`.** Any
  value containing `&`, `=`, `+` or a space breaks even when percent-encoded.
  So keep `name` to one word, make `secret` hex, and leave out `image` unless
  its URL is simple.
- Use a hex secret from a CSPRNG (`crypto.getRandomValues`), never
  `Math.random`.

### 3.3 Checklist: the bunker:// flow (paste)

1. Parse the URI: signer pubkey plus relays plus secret. Tolerate a missing
   secret.
2. **Load the persisted client key, or create one and save it now,** before
   the first `connect`.
   - Amber auto-acks a repeat connect from a client it already knows.
   - A fresh key per attempt looks like a stranger reusing a consumed
     single-use secret, and **no prompt ever appears**. This is the #1 cause
     of "Amber doesn't work".
3. Connect to the relays and **drop the dead ones**. Relay health changes
   daily; see §3.6.
4. Open the reply subscription first:
   `{"kinds":[24133], "#p":[client_pubkey], "since": now-60}` with **no
   `limit`**.
   - Don't use `since: now`: Amber stamps replies about 5 s in the future.
   - Don't use `limit: 0` alone: that relies on relays live-streaming
     correctly.
   - Don't wait for EOSE from *all* relays before sending. One dead relay then
     hangs login forever; that is a stock `fiatjaf.com/nostr` and NDK bug. Wait
     at most about 2 s for the first EOSE, then send.
   - Don't send before the REQ is live either. Under wasm, the request beat the
     REQ on a shared socket and the ephemeral reply was never replayed.
5. **Always send `connect`**, even without a secret:
   `[signerPk, secret||"", perms||"", metadataJSON]`. Some signers refuse
   everything from a client that never connected.
6. Accept `"ack"` **or** the secret as a successful connect result.
7. Call `get_public_key`. That is the user.
8. Send `switch_relays`. If it returns a list, move the session to those
   relays (resubscribe first, then drop the old ones). This has been a spec
   SHOULD since 2026-01-26. Amber 6.3+ changed its default relays, so this
   matters.
9. Persist `{clientSecret, signerPubkey, userPubkey, relays}`. Reconnect later
   with `connect` without the secret (the secret was single-use).
10. On logout: send `logout` as a courtesy, then **delete the client key**.

### 3.4 Checklist: the nostrconnect:// flow (QR)

1. Create the client key and persist it. Create a hex secret.
2. Choose relays the signer is likely to use (§3.6). **Open and arm the
   subscription before showing the QR.** A fast phone replies within a second;
   if you're not listening yet, the reply is lost, because 24133 is ephemeral.
3. Show the QR, a copy button, and a plain `nostrconnect://` link. On the same
   phone, tapping the link opens Amber directly.
4. Accept **either** of these as the pairing reply:
   - a *response* whose `result === secret` (what current signers send), or
   - a legacy `connect` *request* whose `params[1] === secret`.
5. **Never accept a bare `"ack"` in this flow.** The client pubkey is printed
   in the QR, so anyone can reply `"ack"` and become "your signer". The spec
   says the client MUST validate the secret. nostr-tools enforces this since
   2026-08-19. applesauce, rust-nostr, nostr-login and Archon-Web still
   accept `"ack"`, so don't copy them.
6. The **author of the pairing reply is the remote-signer pubkey**. Then
   continue with §3.3 steps 7–10.

### 3.5 Encryption dialect

- **Send NIP-44 only.** The spec dropped NIP-04 for the 24133 envelope on
  2024-12-05.
- **Decrypt with NIP-44 first, then fall back to NIP-04** (the ciphertext
  contains `?iv=`). Old signers still reply in NIP-04, and Amber still accepts
  both.
- **Never dual-send** (the same request in both encryptions). Amber dedupes by
  event id and consumes the single-use secret on the first copy. The second
  copy then errors and **no prompt appears**.
- NIP-44 was extended on 2026-06-28 to allow plaintexts over 64 KiB, using a
  6-byte length prefix. Old decoders, including paulmillr's reference
  `nip44`, reject those. Large `sign_event` payloads can hit this.

### 3.6 Relays for NIP-46 (probed 2026-09-19, fresh keys, publish and receive)

| Relay | 24133 relayed? | Note |
|---|---|---|
| `wss://relay.nip46.com` | ✅ | dedicated NIP-46 relay; in Amber 6.6 defaults |
| `wss://bucket.coracle.social` | ✅ | in Amber 6.6 defaults |
| `wss://nrs.primal.net` | ✅ | in Amber 6.6 defaults |
| `wss://relay.damus.io` | ✅ | **removed** from Amber defaults in 6.3; intermittent 503s |
| `wss://relay.primal.net`, `wss://nostr.oxtr.dev` | ✅ | |
| `wss://auth.nostr1.com` | ⚠️ AUTH required | in Amber defaults; you must answer NIP-42 AUTH (sign kind 22242 with the **client key**) or publishes fail with `auth-required` |
| `wss://relay.nsec.app` | ❌ unreachable | still the default in many libraries and in apps on this machine; don't rely on it |
| `wss://relay.nos.social` | ❌ `blocked: kind not allowed` | |
| `wss://nos.lol` | ❌ timed out that day | |
| local ngit-relay `ws://localhost:8081`, nostr-rs-relay | ❌ / never OKs | don't use for NIP-46 tests; use a public relay or an in-process khatru |

- **Default for new apps:** `relay.nip46.com` + `bucket.coracle.social` +
  `nrs.primal.net` + `relay.damus.io`.
- Let the user edit the list, and probe it at login.
- Re-probe with the tester (§8) or with this, from a script file (nak stalls in
  inline compound shell):
  `nak req -k 24133 -p <pk> --stream wss://R` plus
  `nak event -k 24133 -p <pk> -c x --sec <fresh> wss://R`.
- **Don't gate on relay OK** for 24133. Some relays never OK ephemeral events.
  Start waiting for the reply immediately.

### 3.7 Library status (2026-09-19): what to use and what to patch

| Library | Verdict | Bugs you must work around |
|---|---|---|
| **nostr-tools** `BunkerSigner` (≥2.25) | best JS base | No per-request timeout (wrap it). A reply with an empty `result` never resolves. `switch_relays` compares a sorted list against an unsorted one. `queryBunkerProfile` reads the old NIP-05 `nip46` shape. Pass a persisted `clientSecretKey`. |
| **applesauce-signers** `NostrConnectSigner` | good (grimoire uses it) | Accepts bare `"ack"` in nostrconnect. `switchRelays` checks `Array.isArray` on a string, so it never switches. No timeout. `onAuth` defaults to `window.open` outside a click, which popup blockers stop. |
| **NDK** `NDKNip46Signer` (3.0.x) | avoid for NIP-46 | Sends `connect` with `[userPubkey??"", secret]` (the wrong first param). Only `"ack"` counts as success. Waits for EOSE before sending. Sticks to NIP-04 after seeing one NIP-04 reply. The nostrconnect URI has a single relay and a `Math.random` secret. No timeout by default. |
| **nostrify** (MKStack) | ok for NIP-07; bunker restore buggy | Bug in §1. No `auth_url` handling. |
| **fiatjaf.com/nostr** `nip46` (Go, stock) | **don't use stock** | Waits for EOSE from all relays (a dead relay hangs forever). Drops NIP-04 replies. 30 s hard-coded sign timeout (`BunkerSignTimeout` is ignored). One context bounds both the connect and the listener (the second sign fails with "context canceled"). Broken 1-in-10 pre-connect `switch_relays`. Waits for the relay OK before reading the reply. **Use the patched copy in `Production Environment/Testimony/third_party/nostr/` (see its `FORK.md`) plus `internal/signer/`.** |
| **rust-nostr** `nostr-connect` | ok | Accepts `"ack"` in nostrconnect. No `switch_relays`/`logout`. |
| **nostr-login** | unmaintained since 2025-03 | Don't adopt. |

**Go lifetime rule.** The bunker client's subscription lives as long as the
context you created it with. Build it with an **app-lifetime context** and use
per-request `context.WithTimeout` only around individual calls.
In-Your-Face-try2 and icdib both `defer cancel()` the login context, so the
session dies the moment login returns.

---

## 4. NIP-55 — Android native (Amber)

Use **Quartz** (`com.vitorpamplona.quartz`, `nip55AndroidSigner`), as
Nostr-Agenda does. It already does content-resolver-first with intent fallback,
id matching, rejection handling, signature verification and timeouts. If you
must hand-roll, implement all of this:

1. **Manifest `<queries>`**, or Android 11+ can't see the signer (neither the
   intent nor the ContentResolver):
   ```xml
   <queries><intent><action android:name="android.intent.action.VIEW"/>
     <category android:name="android.intent.category.BROWSABLE"/>
     <data android:scheme="nostrsigner"/></intent></queries>
   ```
   Detect with `queryIntentActivities(Intent(ACTION_VIEW, Uri.parse("nostrsigner:")))`.
   Show "Sign in with Amber" only if something is installed.
2. **Login = one `get_public_key` intent** with *no* package set, plus a
   `permissions` extra that lists every kind you'll sign:
   `[{"type":"sign_event","kind":31922},{"type":"nip44_decrypt"}]`.
   - Quartz's default covers only kind 22242, which means a prompt on every
     sign.
   - Store `result` (the pubkey) **and `package`**. Accept both npub and hex.
   - Don't call `get_public_key` again while logged in.
3. **Later requests:**
   - First try the ContentResolver:
     `content://<package>.SIGN_EVENT`, with
     `selectionArgs = [payload, pubkey_hex, current_user_hex]`.
   - A `null` cursor or empty row means manual approval is needed, so fall back
     to the intent with `setPackage(package)`.
   - A `rejected` column means the user chose "always reject". **Stop; don't
     fall back.**
   - Use `getColumnIndex` safely: a missing column must not crash.
4. **Read `result`**, not `signature`. Amber sets both; other signers may not.
   `event` is also returned for `sign_event`.
5. **Rejection is `RESULT_OK` + `rejected=true`** (spec rewrite 2026-06-03).
   `resultCode != RESULT_OK` means the signer failed. Code that only checks
   `resultCode` turns a rejection into "success with an empty signature" (the
   OTSuite bug).
6. Match results by `id`. Queue requests: one Amber prompt at a time
   (OTSuite `SignerIntentBridge` mutex). Deliver a cancel to the waiting
   caller; don't let it time out silently.
7. **Compose pitfall.** Activity results arrive while the screen is STARTED,
   not RESUMED, so navigating directly from the callback is silently dropped.
   Set a flag and navigate in a `LaunchedEffect`.

---

## 5. NIP-55 over the web (`nostrsigner:` URLs), optional and fragile

The spec recommends NIP-46 for web apps. If you still offer it (it's the only
no-relay option for a phone browser):

```
nostrsigner:<urlencoded payload>?compressionType=none&returnType=signature&type=<method>&callbackUrl=<url>
```

1. **Callback must be fragment-based**: `callbackUrl=https://host/path#nip55=`.
   - Amber splits the decoded data on `?`, so a `?x=` callback gets mangled
     (Idle StarFighter `d98801c`).
   - Amber opens `callbackUrl + Uri.encode(result)` in a new VIEW intent.
   - Listen for **`hashchange`** as well as page load, because a fragment-only
     navigation doesn't reload the page.
2. **Pending state in `localStorage`** with an expiry (not
   `sessionStorage`). The result often lands in a *new tab*.
3. **Request `returnType=signature`**. Rebuild the event from the **exact
   stored unsigned event**, including its `created_at`, recompute the id, then
   verify.
   - Rebuilding with a new `created_at` breaks the signature. This is the
     Idle StarFighter bug.
   - For `sign_event`, include `pubkey` in the unsigned JSON.
   - Encode the payload with `encodeURIComponent`. An unescaped `?` inside the
     JSON breaks Amber's parser.
4. **With no `callbackUrl`**, Amber copies the result to the clipboard and shows
   a toast. Offer a "paste result" box as the fallback.
5. **Chrome (reported, not independently confirmed).**
   - Since about August 2026, Chrome reportedly no longer sends
     `EXTRA_APPLICATION_ID`, so Amber treats a bare `nostrsigner:` link as an
     app intent and fails with "malformed nostrsigner request".
   - Amber's app-intent branch reads `type`, `callbackUrl`, `returnType`,
     `pubkey` and `id` from **extras** (verified in Amber source,
     `IntentUtils.getIntentDataFromIntent`). So an Android `intent:` URL
     works as a fallback:
     `intent:<payload>#Intent;scheme=nostrsigner;S.type=sign_event;S.returnType=signature;S.callbackUrl=<enc>;end`.
   - Offer both links.
6. A `nostrsigner:` link with no signer installed does nothing, and this can't
   be detected. Say so in the UI.
7. When an installed PWA opens the callback, it opens in a browser tab, not the
   PWA window.

---

## 6. NIP-07 — browser extension

```
await window.nostr.getPublicKey()            // hex
await window.nostr.signEvent({created_at, kind, tags, content})  // → full event
window.nostr.nip44?.encrypt/decrypt(pk, text) // optional — feature-detect
window.nostr.nip04?.encrypt/decrypt(pk, text) // deprecated
```

1. **Injection is late.** Extensions inject after your script runs (nos2x adds
   an async `<script>`). Don't decide "no extension" at render time. Poll
   `window.nostr` (truthy, not `'nostr' in window`) every 100 ms for about
   1–2 s, *and* re-check when the button is clicked. nostr-archive checks at
   click time and never had the bug; nostr-archive-app, ETM and grimoire check
   at render and show "install an extension" wrongly.
2. **Feature-detect `nip44`** before relying on it. NDK's check is buggy (an
   empty array is truthy).
3. **Serialize encrypt and decrypt calls.** Extensions throw
   "call already executing" on parallel prompts (NDK queues and retries).
4. **Verify** per §2.1. The user can switch accounts in the extension
   mid-session, so compare `signed.pubkey` with the session.
5. `getRelays()` was removed from the spec (2025-02). Don't depend on it.
6. **Workers and wasm workers don't get `window.nostr`.** Bridge the call from
   the page.
7. Some extensions reject an unsigned event whose `pubkey` is the zero key.
   Omit `pubkey` or set it to the real one.

---

## 7. Definition of done for a login feature

- [ ] Each offered method logs in, **signs a test event that you verify**
      (§2.1), and survives a page reload or app restart **without a new
      prompt** (session restored from persisted state).
- [ ] NIP-46 tested against **`nak bunker`** (fast, hermetic) *and* **real
      Amber**. nak speaks only NIP-44 and has no kind-scoped permissions, so
      a nak-only test proves neither the NIP-04 fallback nor the permissions
      (Nostr-Agenda's unscoped `sign_event` passed with nak).
- [ ] Both NIP-46 directions tested: pasted `bunker://` and scanned QR.
- [ ] Killing one relay in the list doesn't hang login.
- [ ] Rejecting on the phone shows "rejected", not a hang or fake success.
- [ ] Timeouts show a message that names the likely cause (Amber offline,
      notifications off, wrong relay).
- [ ] Logout deletes the client key; logging in again prompts again.
- [ ] No secret or nsec appears in any log, error, URL or analytics.

**nak recipes** (run from a script file; add `</dev/null` in loops):
```bash
# a bunker that signs for key K, on two relays, prints bunker:// URI (+ QR)
nak bunker --sec <hex-or-nsec> --qrcode wss://relay.nip46.com wss://bucket.coracle.social
# the other direction (app shows a nostrconnect:// QR): `connect` only hands the URI to
# an ALREADY RUNNING `nak bunker` over a unix socket — start the bunker first:
nak bunker --sec <hex> wss://relay.nip46.com &      # terminal 1
nak bunker connect 'nostrconnect://…'               # terminal 2 (fails "connection refused" if no bunker runs)
# drive a bunker as a client with a persisted client key
nak event -k 1 -c test --sec 'bunker://…' --connect-as <client-hex> wss://relay.damus.io
```

---

## 8. Reference implementations on this machine

| Need | Copy from | Why |
|---|---|---|
| **Test any signer** | **Signer Login Tester**, live at <https://npub138kdqjl645xz6rvuw92m2v4us0shhpxezgqqz9zrrj2jdstakvus86qzyh.nsite.lol/>; source at `~/Production Environment/Signer-Login-Tester/` (`tools/e2e.mjs` = 19 automated checks with `nak bunker`) | One static page. All methods, full wire log, written to this document. |
| NIP-46 in JS, hand-rolled | the tester's `src/nip46.js` + `src/relay.js` (about 250 lines total) | Implements §3 exactly, including NIP-42 AUTH for `auth.nostr1.com` |
| NIP-46 in JS, library | grimoire `src/components/nostr/LoginDialog.tsx` + applesauce | Opens the subscription before the QR, supports abort, persists accounts. Add timeouts and the secret-only check. |
| NIP-46 in Go | `~/Production Environment/Testimony/internal/signer/` + `third_party/nostr/` | Patched lib; verified against real Amber 2026-08-22. The reasoning is in `Facebook-Museum/app/third_party/nostr/FORK.md` Deltas 2–4. Don't copy Facebook-Museum's own `ConnectPerms`, which are bare (known-issues §6). |
| NIP-46 Go daemon lifetime | `Sessions/GRASPCONTROL/internal/identity/manager.go` | App-lifetime context, persisted `session.json` |
| NIP-55 Android | `~/Production Environment/Nostr-Agenda` (Quartz 1.11) | Verified with real Amber 6.2.2 |
| NIP-55 web | `Idle StarFighter/web/nip55.js` + `docs/NOSTR.md` §NIP-55 | Fragment callback, localStorage pending state. **But** fix its `created_at` rebuild bug (§5.3). |
| NIP-07 | NDK `NDKNip07Signer` pattern: poll, queue, check at click time | |
| Signer side (what Amber really does) | `Sessions/bunker-android/awareness/amber-upstream/` (`IntentUtils.kt`, `SignerProvider.kt`, `NostrConnectUtils.kt`) | Read the source when the spec and behaviour disagree |

Known-bad code on this machine (don't copy): see [`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) §6.

---

## 9. Spec changelog you must know (dates = commit on nips master)

| Date | Change |
|---|---|
| 2024-10-29 | NIP-46: remote-signer pubkey ≠ user pubkey |
| 2024-11-12 | NIP-46: `get_public_key` required after connect; nostrconnect `secret` required; NIP-05 login and `create_account` removed |
| 2024-11-22 | nostrconnect `metadata=` → `name`/`url`/`image`/`perms` params |
| 2024-12-05 | NIP-46 envelope NIP-44 only |
| 2025-02-14 | `get_relays` / `getRelays` removed from NIP-07/46/55 |
| 2025-10-13 | NIP-55: store the pubkey, don't re-call `get_public_key`; resolver arg = hex pubkey |
| 2025-12-18 | NIP-55: content-resolver `GET_PUBLIC_KEY` removed (intent only) |
| 2026-01-26 | NIP-46: `switch_relays` added (client SHOULD call after connect) |
| 2026-06-03 | NIP-55 rewritten: rejection = `RESULT_OK`+`rejected`; `selectionArgs` order `[payload, pubkey, current_user]` |
| 2026-06-14 | NIP-46: `logout` |
| 2026-06-23 | NIP-46: 4th `connect` param `optional_client_metadata` |
| 2026-06-28 | NIP-44: plaintexts > 64 KiB allowed (6-byte length prefix) |
| 2026-07-15 | NIP-46: unknown methods MUST get an error reply |
| Amber 6.3.0 | default relays drop relay.damus.io |
| Amber 6.5.0 (2026-08-14) | rejects 24133 older or newer than ±5 min; tracks consumed ids |

Primary sources: <https://github.com/nostr-protocol/nips/blob/master/07.md>,
[`46.md`](https://github.com/nostr-protocol/nips/blob/master/46.md),
[`55.md`](https://github.com/nostr-protocol/nips/blob/master/55.md),
<https://github.com/greenart7c3/Amber/releases>. Refresh this table when you
touch login code: `https://github.com/nostr-protocol/nips/commits/master/46.md.atom`.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/go-client-baseline.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/go-client-baseline.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.

# Pattern: the Go baseline — `fiatjaf.com/nostr`

> **Start every Go client, relay or tool on this machine from
> [`fiatjaf.com/nostr`](https://pkg.go.dev/fiatjaf.com/nostr).** It is the
> protocol author's own library and it covers the whole stack: events, relays,
> pooling, an outbox-aware client SDK, a relay framework, storage backends,
> Blossom, GRASP, and roughly forty NIP packages.
>
> Verified 2026-09-21 against the module cache and the live proxy.

---

## 1. Why this one

Three separate repos that most Go examples on the internet still import —
**`github.com/nbd-wtf/go-nostr`, `github.com/fiatjaf/khatru` and
`github.com/fiatjaf/eventstore` — were all archived by their owner on
2026-01-24** and are read-only. All three now live as packages inside this one
module. go-nostr's README says so:

> "This repository is in maintenance mode and adventurous programmers are
> encouraged to try `fiatjaf.com/nostr@master` instead."

`fiatjaf.com/nostr` is the successor to all of them, by the same author, with a
reworked API. It is already the de-facto standard here: about two dozen Go
modules across `~/Production Environment` import it, and
`relays/khatru-example/` was ported onto it on 2026-09-21.

| Archived repo | Now |
|---|---|
| `github.com/nbd-wtf/go-nostr` | `fiatjaf.com/nostr` |
| `github.com/fiatjaf/khatru` | `fiatjaf.com/nostr/khatru` |
| `github.com/fiatjaf/eventstore` | `fiatjaf.com/nostr/eventstore` |

The khatru port is the one with real API churn: hooks became single functions
instead of slices (`relay.StoreEvent = f`, not `append`), `QueryEvents` became
`QueryStored` returning an `iter.Seq`, ids are `nostr.ID`, and
`relay.UseEventstore(store, maxQueryLimit)` wires storage, replacement,
deletion, counting and the expiration manager in one line. Ready-made
acceptance policies live in `fiatjaf.com/nostr/khatru/policies`; worked
examples ship in the module at `khatru/examples/{basic-lmdb,blossom,grasp,exclusive}`.

## 2. Getting it

```bash
go get fiatjaf.com/nostr
```

Two things are unusual and worth knowing before you fight them:

**It has no tagged releases.** Only pseudo-versions. `@latest` resolves to
something like `v0.0.0-20260916040958-27e395a0f6e7`. So:

- **Pin the pseudo-version in `go.mod`** and bump it deliberately. The API is
  still moving; an unpinned bump can change event field types under you.
- If a bump is load-bearing for correctness — an id/signature golden test, a
  wire-format assertion — say so in a `go.mod` comment. CFR already does:
  `// pinned pre-stable; bumping re-runs NEW-1 (id/sig golden)`.

**The source is not on GitHub — it is Nostr-native.** The `go-import` meta at
`fiatjaf.com/nostr` points at a GRASP host:

```
https://basspistol.org/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6/nostrlib.git
```

Browsable at `viewsource.win/npub180cvv…/nostrlib`. Which is a nice thing to
know and also a dependency you should be aware of: `proxy.golang.org` caches
it, so `GOFLAGS=-mod=mod` builds keep working if that host blips, but a fresh
`go get` of a brand-new commit does not.

### 2.1 The Go toolchain trap

**The library's `go.mod` declares `go 1.25`. `/usr/bin/go` on this machine is
1.24.4.** It works anyway, silently, because `GOTOOLCHAIN=auto` downloads
go1.25.0 on demand — so a module that imports this library builds with 1.25
even though `go version` prints 1.24.4.

The trap: if you scaffold a new module with `go mod init` under the default
toolchain you get `go 1.24`, and the import then fails with a version error
that reads like a network problem. **Put `go 1.25` in a new `go.mod`** (every
Go project here that uses the library already does), and don't trust
`go version` at the shell — run it inside the module.

## 3. The package map

| Import | What |
|---|---|
| `fiatjaf.com/nostr` | `Event`, `Filter`, `Relay`, `Pool`, `Kind`, `Tags`, keys, envelopes, signing |
| `…/sdk` | the client SDK: `System` with caching, data loaders, **outbox relay management** |
| `…/keyer` | signing abstractions: plain key, bunker, read-only, `keyer.New()` from any input |
| `…/khatru` | the relay framework |
| `…/khatru/blossom` | Blossom server plugin for a khatru relay |
| `…/khatru/grasp` | GRASP (NIP-34 git) server plugin |
| `…/eventstore` | pluggable storage: Bleve, BoltDB, LMDB, in-memory, MMM |
| `…/nipb7/blossom` | Blossom *client* — upload/download/list, sets Content-Type from the extension |
| `…/nip5a` | **nsite manifests** — parse/build 15128 & 35128, base36 labels, path normalisation |
| `…/nip19` | bech32 entities |
| `…/nip44`, `…/nip17`, `…/nip59` | encryption, private DMs, gift wrap |
| `…/nip46` | remote signing (bunker) — **see §6 before using** |
| `…/nip34` | git / GRASP event types |
| `…/nip29` | relay-based groups |
| `…/nip65` | relay lists / outbox |
| `…/nip77` | negentropy sync |
| plus | nip04 05 06 10 11 13 14 22 23 27 31 40 42 45 49 52 53 54 57 60 61 70 73 86 92 94, nipad, schema |

Check the tree before you write a helper — a lot of what people hand-roll is
already in there. `nip5a` in particular: every nsite deploy script on this
machine predates anyone noticing it exists.

## 4. The API, and how it differs from go-nostr

The single biggest change: **identifiers are fixed-size byte arrays, not hex
strings.**

```go
type Event struct {
    ID        ID          // [32]byte, not string
    PubKey    PubKey      // [32]byte, not string
    CreatedAt Timestamp
    Kind      Kind        // a named type, not int
    Tags      Tags
    Content   string
    Sig       [64]byte    // not string
}
```

Most porting pain is this. `evt.PubKey == somehex` no longer compiles; use
`nostr.PubKeyFromHex`, `.Hex()`, `nostr.MustPubKeyFromHex`. It also means the
JSON marshalling is strict — **the library hard-errors on unknown top-level
event fields**, which is what forced the OTS sidecar fork (see
`~/Production Environment/Nostr-Go-Framework/docs/99-gotchas.md`). If you were
planning to smuggle an extra field into an event: don't; use a tag or a
companion event.

Other shape changes:

```go
sk  := nostr.Generate()                     // SecretKey
pk  := sk.Public()                          // PubKey

evt := nostr.Event{Kind: 1, CreatedAt: nostr.Now(), Content: "hello", Tags: nostr.Tags{}}
evt.Sign(sk)                                // sets ID and Sig
ok := evt.VerifySignature()

r, err := nostr.RelayConnect(ctx, "wss://relay.damus.io", nostr.RelayOptions{})
err = r.Publish(ctx, evt)

// Filter takes one filter, not a Filters slice; Tags is a TagMap
f := nostr.Filter{Kinds: []nostr.Kind{1}, Authors: []nostr.PubKey{pk}, Limit: 10}
sub, err := r.Subscribe(ctx, f, nostr.SubscriptionOptions{})

// Go 1.23 iterators
for evt := range r.QueryEvents(f) { _ = evt }

// Many relays at once
pool := nostr.NewPool()
for evt := range pool.FetchMany(ctx, relayURLs, f, nostr.SubscriptionOptions{}) { _ = evt }
for res := range pool.PublishMany(ctx, relayURLs, evt) { _ = res }
```

For anything that needs the outbox model, profile/relay-list caching or
loaders, **use `sdk.NewSystem()` rather than driving `Pool` by hand** — that is
what it is for, and hand-rolled outbox resolution is a recurring source of "why
can't it find this user's notes".

## 5. Picking the right layer

| Building | Start with |
|---|---|
| A CLI or one-shot tool | root package + `Pool` |
| A client that reads other people's data | `sdk.System` (outbox + caching + loaders) |
| A relay | `khatru` + an `eventstore` backend |
| A relay that also serves blobs | `khatru` + `khatru/blossom` |
| A git host | `khatru` + `khatru/grasp` |
| Uploading blobs | `nipb7/blossom` client |
| Publishing a static site | `nip5a` + `nipb7/blossom` — and read [`nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) |
| Signing as a user | `keyer` — and read [`signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) |

For Go/wasm clients (Testimony, Cerebrate, the Workshop Board, Idle StarFighter
are all this shape) the library works in the browser, with one standing patch:
**the wasm build needs the library dial patch** — see `project_testimony_app`
and Testimony's `third_party/nostr/FORK.md`.

## 6. The part you must not use as-is

**`fiatjaf.com/nostr/nip46` (remote signing) is known-broken for production
login.** Stock, it waits for EOSE from every relay (one dead relay hangs login
forever), drops NIP-04 replies, hard-codes a 30 s sign timeout that ignores
`BunkerSignTimeout`, has a broken pre-connect `switch_relays`, and waits for
the relay OK before reading the reply. `wellknownnostrjson.go` returns an
unassigned named return on NIP-05 bunker lookup, so login silently targets the
zero pubkey.

Every Go app on this machine that used it stock has the same bugs. **Use the
patched copy at `~/Production Environment/Testimony/third_party/nostr/` (see its
`FORK.md`) plus its `internal/signer/`.** Full detail:
[`signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) §3.7 and
[`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) §6.

This is the one place where "start from the library" does not apply. Everywhere
else, start from the library.

## 7. Conventions for this workspace

- Pin the pseudo-version; note *why* if the pin is load-bearing.
- `go 1.25` in new modules.
- Vendor a fork only under `third_party/nostr/` with a `replace` directive and a
  `FORK.md` stating every divergence. Four projects here do this correctly;
  copy that shape rather than editing the module cache.
- Don't reimplement a NIP that has a package. Check the tree first.
- New Go relay experiments go in `relays/<name>/` as separate modules, so each
  pins its own version.

## Related

- [`patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) — `nip5a` in anger
- [`patterns/signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) — the `nip46` situation in full
- [`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) §6 — known-bad code on this machine
- `~/Production Environment/Nostr-Go-Framework/` — the local Go doctrine, the
  gotcha ledger, and the `nostrkit` module built on this library


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/testing.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/testing.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.

# Pattern: testing a Nostr project

> **Read before writing the first test.** Nostr projects fail in ways ordinary
> test suites do not cover: an event id that changes between runs, a relay that
> silently truncates a query, a replaceable event that collapses differently on
> a real relay than in your fake, a signature you never actually verified.
>
> Tooling: `testing/`. Written 2026-09-21, distilled from the
> harnesses in TEPPv3, Facebook-Museum, Idle StarFighter, CFR and Merged Mechs.

---

## 0. Quickstart

**Any language** — a throwaway relay, seeded, for the duration of one command:

```bash
export PATH="$HOME/Documents/nostr-dev/testing/bin:$PATH"

nostr-testenv run --seed fixtures/social-basic.jsonl -- pytest      # or npm test, or anything
# your test reads $NOSTR_TEST_RELAY (ws://127.0.0.1:<random>) and $NOSTR_TEST_RELAY_HTTP
```

**Go** — the same relay, in-process:

```go
r := nostrtest.StartRelay(t, nostrtest.SeededFrom("testdata/world.jsonl"))
ev := nostrtest.Sign(t, "alice", 1, "hello", nil, nostrtest.At(0))
r.MustPublish(t, ev)
got := r.MustQuery(t, nostr.Filter{Kinds: []nostr.Kind{1}})
```

**Identities** are named and deterministic — `alice` is the same key on every
machine, forever:

```bash
nostr-testkeys alice --sec        # 6b4f9320…  always
eval "$(nostr-testkeys --env alice bob)"   # $ALICE_SEC, $ALICE_PUB, $ALICE_NPUB, …
```

---

## 1. Which relay — the house rule

This is the single most useful fact in this document, and it is not guessable.

| Relay | What it is | Use it for |
|---|---|---|
| **`nostr-testenv` / `nostrtest`** (random port) | in-memory, empty at start, gone at exit | **your tests.** Isolated, seedable, parallel-safe |
| `ws://localhost:8080` | the shared disposable `nostr-rs-relay`, persistent SQLite | cross-session work, manual poking. **~10 msg/s — pace writes at ~110 ms.** Contaminated by definition: it holds other people's runs |
| `ws://localhost:8081` | the **GRASP relay** — shared infrastructure | **read-only for tests.** It holds real kind 30617 repo announcements. It also *rejects most non-NIP-34 kinds* (`"event does not relate to a stored repository"`), which people spend an hour debugging as a bug in their own code |
| `ws://localhost:3334` | the khatru scaffold, on demand | experimenting with relay policy |
| public relays | real | the last mile only, and never in an automated suite |

`nostr-testenv` refuses port 8081 outright. If your test needs the GRASP relay,
it needs it for *reading*, and you should say so in a comment.

**Never point an automated suite at a public relay.** Signed events are
forever, most relays rate-limit, several reject fresh keys outright
(`nos.lol` and `nostr.mom` both refuse a first kind 1 from an unknown pubkey —
see `relays-reject-new-keys` in the workspace memory), and a green suite that
depends on someone else's uptime is not green.

---

## 2. The four altitudes

Pick the lowest one that can fail the way you care about.

**1. Pure unit.** Your event construction, parsing, validation. No relay, no
network. Fast, and where most of your assertions belong. Assert on *finding
classes and shapes*, never on error-message wording.

**2. In-process relay** — `nostrtest.StartRelay` / `nostr-testenv`. A real
khatru speaking the real protocol over a real websocket, in your test process.
This is the workhorse, and the altitude most projects skip straight past.
It catches: wrong filters, replaceable/addressable collapse, subscription
lifecycle, EOSE handling, reconnection, AUTH.

**3. A real standalone relay** — `ws://localhost:8080`, opt-in behind a flag
(`-local-relays`, `RUN_INTEGRATION=1`). Catches what an in-memory store does
not model: a server-side default `limit` silently truncating a REQ you issued
without one, real persistence, real rate limiting. TEPPv3's
`tests/integration/localrelay_test.go` is the reference for how to gate this.

**4. Browser.** Playwright, for anything with a UI or wasm. Assert **zero
console errors** and **zero unexpected network requests** — the second one is
how Facebook-Museum proves its "nothing leaves the machine" claim, and it is a
much stronger assertion than any unit test of the same code.

---

## 3. Determinism, and why it is not optional

Three things make a Nostr test non-reproducible. All three are avoidable.

**Keys.** A randomly generated key means: no golden file, no re-seeding a
relay idempotently (the same "event" gets a new id every run, so the relay
accumulates duplicates), and no reading a six-week-old failure log. Use named
identities:

```
sec = sha256("nostr-dev/testing/v1\n" + name)
```

`nostr-testkeys alice` and `nostrtest.Key("alice")` implement that same line,
and `nostrtest`'s own test suite asserts they agree — so a fixture built by the
shell tool is signed by the same alice your Go test asserts on.

**These keys are public.** The derivation is written down, so anyone can
compute every one of them. Never sign anything real with one. That an
adversary can forge them is the *point*: it is how you write the negative
cases.

The cast, and what each is conventionally for, so a stranger can read your
test: `alice` `bob` `carol` `dave` ordinary participants · `eve` passive
observer · **`mallory` the active adversary** · `trent` trusted third party ·
`victor` verifier · `relay-owner` · `guardian` / `subject` (TEPP roles) ·
`stranger` an unrelated pubkey.

**Time.** `nostr.Now()` in a test changes the event id every run. Pin it:
`BaseTime` is `1700000000`, and `At(60)` reads better than a literal. Fixtures
default each event to `base + index`, so ordering is defined and a replaceable
event has a defined winner.

**Ports.** Never hard-code one. Two tests on 7777 is a flake you will chase for
an afternoon. `StartRelay` and `nostr-testenv up` both take a free port and
tell you which.

---

## 4. Fixtures

A fixture is a JSONL file, one signed event per line — the same shape
`nak req` emits, so anything can consume it. Build them from a recipe that
names its authors instead of holding keys:

```json
{
  "base_time": 1700000000,
  "events": [
    {"as": "alice", "kind": 0, "content": {"name": "Alice"}},
    {"as": "bob",   "kind": 1, "content": "re: @{alice}", "tags": [["p", "@alice"]]},
    {"as": "alice", "kind": 30023, "d": "post-1", "content": "long form"}
  ]
}
```

```bash
nostr-fixture build world.recipe.json > world.jsonl
nostr-fixture inspect world.jsonl        # kinds, authors BY NAME, tags, content
```

In a **tag value**, `@alice` becomes her pubkey hex. In **content**, only the
explicit `@{alice}` expands — prose is full of @handles and must survive. Same
recipe, same bytes, every time.

Ready-made, in `testing/fixtures/`:

- **`social-basic`** — three people with profiles, relay lists, notes, a reply,
  follows, a long-form post, a reaction. The default "some events that look
  real".
- **`adversarial`** — mallory impersonating alice, p-tagging into her mentions,
  requesting deletion of someone else's event, squatting a `d` tag,
  far-future and ancient timestamps, the degenerate empty event. Every one is
  *validly signed* — which is exactly the class of attack signatures do not
  stop, and the class most clients forget to handle.

---

## 5. What to test that you would not think to test

Nostr-specific failure modes, each of which has bitten a project on this machine:

- **Event class collapse.** Replaceable (10000–19999, 0, 3) keeps one per
  pubkey; addressable (30000–39999) keeps one per `(pubkey, kind, d)`; regular
  keeps everything. Seed two of each and assert what survives. The local GRASP
  relay gets this *wrong* for kind 30617 ([`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) #2) — if your fake
  relay also gets it wrong, you will never find out.
- **Signature verification you never actually do.** Feed a tampered event.
  `nostrtest`'s `SeedFile` rejects one and names the line; make sure your code
  does too.
- **Relay disagreement.** Two relays, different subsets, one lying. Your client
  should converge, not crash or duplicate.
- **Silent truncation.** Issue a REQ without a `limit` against a real relay; a
  server-side default may cut it. An in-memory store will not reproduce this —
  altitude 3 exists for exactly this.
- **Reconnection.** Kill the relay mid-subscription and bring it back. Does the
  client resubscribe, and does it re-request from the right point?
- **Signer login.** Do not roll your own test — the
  [Signer Login Tester](https://npub138kdqjl645xz6rvuw92m2v4us0shhpxezgqqz9zrrj2jdstakvus86qzyh.nsite.lol/)
  exercises NIP-07, NIP-46 bunker and nostrconnect, and NIP-55, and logs every
  wire message. Read [`signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) first.
- **Timestamps you trusted.** `created_at` is author-controlled. The
  `adversarial` fixture has both ends.

---

## 6. Gotchas, with evidence

| Gotcha | Why |
|---|---|
| **`nak` reads stdin.** Every `subprocess.run([nak, …])` needs `stdin=DEVNULL` or it hangs until timeout | but you cannot pass both `stdin=` and `input=` — set it only when nothing is piped |
| **khatru's `UseEventstore` starts the NIP-40 expiration manager** | which deletes your past-dated fixture behind your back. `nostrtest` wires the same hooks without it; if you build your own relay, do the same |
| `ws://localhost:8080` caps at ~10 msg/s | pace seeding at ~110 ms, or seed the store directly |
| Headless Chromium returns `null` for a WebGL2 context | launch with `--enable-unsafe-swiftshader --use-gl=angle --use-angle=swiftshader --disable-gpu-sandbox` (Idle StarFighter's `tools/smoke.py`) |
| Headless Chromium dies with "Target crashed" | usually the 7.5 G tmpfs `/tmp` is full of agent scratch. `df -h /tmp` first |
| A repo path containing a space breaks unquoted `go` invocations | `R="/home/kabouter/Production Environment/Thing"; go -C "$R" test ./...` — quote everywhere |
| `go test -race` faulting inside `fiatjaf.com/nostr`'s JSON writer | TEPPv3 hit this on an older pin and used `-race -gcflags=all=-d=checkptr=0`. **Not reproduced** on the current library version — try plain `-race` first, and only reach for the flag if it faults |
| Seeding bypasses your relay's accept path | which is right for arranging a world and wrong for testing acceptance. `Seed` arranges; `MustPublish` goes over the wire |

---

## 7. Definition of done

- [ ] The suite passes twice in a row with **byte-identical event ids**
- [ ] It passes with **no network** (`nostr-testenv` only; nothing reaches a public relay)
- [ ] It passes **in parallel** (`go test -p 4`, or your runner's equivalent) — no fixed ports, no shared relay
- [ ] Nothing in it writes to `ws://localhost:8081`
- [ ] There is at least one **negative** case: a forged signature, an impersonation, or a malformed event
- [ ] Replaceable and addressable collapse is asserted, not assumed
- [ ] If there is a UI: a headless run asserting **zero console errors**
- [ ] The fixtures are committed with their **recipes**, so they can be rebuilt

## Related

- `testing/README.md` — the tool reference
- [`go-client-baseline.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/go-client-baseline.md) — `fiatjaf.com/nostr`, and `khatru` for building the relay under test
- [`signer-login.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/signer-login.md) — do not test login by hand
- [`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) — the local stack's quirks, several of which only show up under test
- `~/Production Environment/TEPPv3/TESTING.md` — the most thorough test charter on this machine; read it for how to run an adversarial campaign


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/nsite-publishing.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.

# Pattern: publishing a client as an nsite (NIP-5A)

> **Read this before writing a line of deploy code.** Five nsites have been
> published from this machine and every one of them cost a fresh round of
> rediscovery. The failures are always silent: the site returns HTTP 200 and
> looks broken, or returns 404 and looks un-deployed. Nothing tells you why.
>
> Verified against the live network **2026-09-21**. Spec read from
> `nostr-protocol/nips` `5A.md` at that date. Measurements in §4 were taken
> with throwaway keys against the real servers on that date.

---

## 0. The short version

```bash
# The workspace has a deploy script. Use it; don't write a fifth one.
~/Documents/nostr-dev/bin/nsite-deploy.py \
    --dir  dist \
    --keys ~/Documents/nostr-dev/secrets/<your-site>/keys.json \
    --title "Your Site" \
    --description "One sentence."
```

Six rules that cover ~every failure ever seen here:

1. **Kind 15128, no `d` tag.** 34128 is dead; a `d` tag on a root site gets the
   event rejected by the one relay that matters.
2. **The events must land on `wss://relay.nsite.lol`.** No gateway serves a
   site whose manifest it cannot find.
3. **Put `https://nostr.download` first in the `server` list.**
   `blossom.primal.net` serves every `text/*` asset as `text/plain` (§4),
   which silently kills stylesheets and service workers.
4. **Publish under a dedicated key, never the owner's.** 15128 is replaceable
   per pubkey — one deploy under the wrong key destroys whatever site that
   identity already served.
5. **Ship a `/404.html`.** The spec makes it the gateway's mandatory fallback;
   without it every deep link is a bare 404.
6. **Verify by fetching the gateway**, not by counting relay OKs. A deploy
   reports success and still 404s.

---

## 1. The event model, as the spec stands today

NIP-5A "Static Websites (nsites)", `draft` `optional`. Reference gateway:
[hzrd149/nsite-gateway](https://github.com/hzrd149/nsite-gateway), which is what
runs `nsite.lol`.

### 1.1 Kinds

| Kind | What | Class | Rule |
|---|---|---|---|
| **15128** | Root site | replaceable, one per pubkey | **MUST NOT** carry a `d` tag |
| **35128** | Named site ("subdomain") | addressable | **MUST** carry `d`, matching `^[a-z0-9-]{1,13}$`, not ending in `-` |
| **5128** | Manifest snapshot | regular, immutable | MUST carry exactly one aggregate `x` and one `a` |
| 34128 | *Legacy* per-path event | addressable | **dead.** `relay.nsite.lol` refuses it |
| 10002 | NIP-65 relay list | replaceable | how a gateway finds the manifest |
| 10063 | BUD-03 Blossom server list | replaceable | how a gateway finds the blobs |

The 13-character cap on a named site's `d` is not arbitrary: the canonical
DNS label is `<pubkeyB36><dTag>`, `pubkeyB36` eats 50 of the 63 characters a
label allows.

### 1.2 Manifest tags

| Tag | Form | Required |
|---|---|---|
| `path` | `["path", "/abs/path.ext", "<sha256-hex>"]` | **yes, one or more** |
| `x` | `["x", "<sha256-hex>", "aggregate"]` | optional, **recommended** (mandatory on 5128) |
| `d` | site identifier | 35128 only |
| `server` | `["server", "https://blossom…"]` | no — but see §4, it is load-bearing |
| `title` | human-readable title | no |
| `description` | **`description`, not `summary`** | no |
| `source` | `https://` or `nostr://` git URL | no |
| `app` | `["app", "<kind>:<pubkey>:<d>", "<relay>"]` | no (new — see §9) |
| `a` / `A` | copy lineage | copied sites only |

There is **no `relay` tag in the spec.** `nsyte` writes them and two of the
scripts on this machine copied that; it is harmless but it is not a spec tag,
and it is not how a gateway finds you — kind 10002 is.

`content` is empty in practice. The manifest is replaceable: **every deploy
republishes the complete file list.** There is no incremental update.

### 1.3 The aggregate hash

Deterministic identity for a site *version*, independent of tag order:

1. Take every `path` tag.
2. Emit one line per tag, exactly `<sha256hash> <absolute-path>\n`.
3. Sort the lines ascending lexicographically.
4. Concatenate as UTF-8, SHA-256 it, lowercase hex.

```bash
nak req -k 15128 -a <pubkey> --limit 1 wss://relay.nsite.lol \
  | jq -r '.tags[] | select(.[0] == "path") | "\(.[2]) \(.[1])"' | sort | sha256sum
```

Two manifests are "the same site" iff their aggregate hashes match — which is
what makes a copied or mirrored nsite verifiable. Emit it. `bin/nsite-deploy.py`
does; `nsyte 0.27` and `nak nsite` do not.

### 1.4 How a gateway resolves `<npub>.nsite.lol`

1. **Parse the left-most DNS label.** Valid `npub` → root site. `^v[0-9a-z]{50}$`
   → snapshot. `^[0-9a-z]{50}[a-z0-9-]{1,13}$` → named site. Else: not found.
2. **Find the manifest** on its own relays (`relay.nsite.lol`) *and* on the
   relays in the author's kind 10002, which it looks up via `LOOKUP_RELAYS`
   (default `wss://user.kindpag.es`, `wss://purplepag.es`).
3. **Match the path.** Exact `path`-tag match; a request not ending in a
   filename gets `index.html` appended (`/` → `/index.html`,
   `/blog/` → `/blog/index.html`). No match, or no manifest at all →
   **MUST fall back to `/404.html`**.
4. **Fetch the blob** by sha256: manifest `server` tags first, then the
   author's 10063, then the gateway's own fallbacks. Nothing anywhere → 404.
   The gateway SHOULD verify the blob's sha256 against the `path` tag.
5. **Serve it**, forwarding the Blossom server's `Content-Type` and
   `Content-Length`. **This forwarding is the whole ballgame — see §4.**

Two consequences worth internalising:

- The manifest does **not** have to be on `relay.nsite.lol` if your 10002 is
  discoverable on the lookup relays and points somewhere the gateway can read.
  Publishing to `relay.nsite.lol` is simply the path that has no moving parts.
- The gateway never executes anything. An nsite is static files talking to
  relays and Blossom from the browser. No server code, ever.

### 1.5 `relay.nsite.lol` policy (probed 2026-09-21)

> "This is a relay for nsite.lol, it only accepts kind 10002, 10063, 15128,
> 35128, and 5128 events."

strfry 1.1.0, `max_message_length: 131072` (128 KB ≈ 1,000+ `path` tags),
`max_limit: 5000`, no `restricted_writes`. It is public-write for those kinds
and those only — it will not hold your app's content events.

---

## 2. Four ways to deploy, and when to pick each

All four were run against the local rehearsal stack (§6) on the same four-file
directory, 2026-09-21. What each one actually puts in the kind 15128:

| | `bin/nsite-deploy.py` | `nak nsite` | `nsyte` | `ngit nsite` |
|---|---|---|---|---|
| `path` tags | ✅ | ✅ | ✅ | ✅ |
| `server` tags | ✅ | ✅ | ✅ | ✅ |
| `title` | ✅ | ❌ no flag | ✅ | ✅ |
| `description` | ✅ | ✅ | ✅ | ✅ |
| `source` | ✅ | ✅ | — | ✅ |
| aggregate `x` | ✅ | ❌ | ❌ | ? |
| `/404.html` fallback | ✅ | ❌ | ✅ `--fallback` | ✅ `--fallback` |
| SPA route aliases | ✅ `--route` | ❌ | ❌ | ❌ |
| kind 10002 + 10063 | ✅ | ❌ | flags exist but silently no-op in `--no-config -i` | via 10063 discovery |
| forbidden-key guard | ✅ | ❌ | ❌ | ❌ |
| verifies the gateway | ✅ | ❌ | ❌ | ❌ |
| per-server upload tolerance | ✅ | ❌ aborts on first failure | ✅ | ? |
| standalone directory | ✅ | ✅ | ✅ | ❌ **needs an ngit repo** |
| bunker signing | ❌ local key only | ✅ | ✅ `nbunksec` | ✅ `nbunksec`/`--signer` |



### 2.1 `bin/nsite-deploy.py` — the workspace default

`~/Documents/nostr-dev/bin/nsite-deploy.py`. Distilled from the four scripts
that Idle StarFighter, the Nostr Workshop Board, the Signer Login Tester and
Cerebrate each grew independently, plus everything in this document. It walks
a directory, uploads to Blossom with per-server tolerance, emits 15128 (with
the aggregate `x`) + 10063 + 10002, refuses forbidden pubkeys, aliases SPA
routes, and **verifies against the live gateway before it claims success.**

```bash
bin/nsite-deploy.py --dir dist --keys <keys.json> \
    --title "T" --description "D" \
    [--source nostr://npub…/repo] \
    [--route /about --route /help] \
    [--dry-run]
```

Use it. If it is missing something your site needs, fix it there — not in a
fifth copy.

### 2.2 `nak nsite` — built in, and nobody noticed

**`nak` has had an `nsite` subcommand this whole time.**

```bash
nak nsite upload --root -s https://nostr.download --sec <key> dist/ \
    wss://relay.nsite.lol wss://nos.lol wss://relay.damus.io
nak nsite download <npub> ./out
```

> **Why every agent missed it, and why that is fixed.** There used to be two
> `nak` binaries here, and the one that won on `PATH` (`~/.local/bin/nak`,
> v0.18.3, Feb 2026) had no `nsite` command — so `nak nsite` looked like it did
> not exist. Resolved 2026-09-21: `nak` is now v0.20.7 at `~/go/bin/nak`, it is
> the only one on `PATH`, and `nak nsite` works. The old binary is parked at
> `~/.local/bin/nak.v0.18.3.bak`. See [`known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) §7.1.

It is genuinely good: it signs Blossom auth properly, and it sets each blob's
`Content-Type` from the file extension via Go's `mime.TypeByExtension` (verified
— `.css`→`text/css`, `.js`→`text/javascript`, `.wasm`→`application/wasm`).

Its limits, read from the source:

- **It aborts the whole deploy on the first failed upload to any server.** With
  flaky public Blossom that is a mid-deploy abort. This is the main reason the
  hand-rolled scripts exist.
- No `--title` flag, so no `title` tag.
- No aggregate `x` tag.
- No 10002 / 10063 — publish those yourself with `nak event`.
- No forbidden-key guard. Nothing stops you replacing the owner's site.

Good for a throwaway or a local rehearsal, and the only one-liner that takes a
bunker. For a release, use §2.1.

### 2.3 `nsyte` — the third-party CLI

`~/.deno/bin/nsyte` (0.27.0 installed; **0.28.1 upstream as of 2026-09-08**).
Deno; `deno install -A -f -g -n nsyte jsr:@nsyte/cli`.

```bash
nsyte deploy dist -r wss://relay.nsite.lol,wss://nos.lol -s https://nostr.download \
    --sec <hex|nsec|bunker://…|nbunksec…> --fallback dist/404.html -i
nsyte debug <npub> --relays …      # the diagnostic when a site 404s
nsyte list -p <npub> -r wss://relay.nsite.lol
```

Worth knowing:

- `--dry-run` / `--dry-run-show-kinds` previews the exact events with no network.
- `--sec` auto-detects nsec / hex / `bunker://` / `nbunksec`; `nsyte bunker` and
  `nsyte ci` manage NIP-46 signers for CI.
- **`--publish-relay-list` / `--publish-server-list` publish nothing in
  `--no-config -i` mode** (observed). Publish 10002/10063 yourself.
- **Never use `--publish-relay-list` / `--publish-server-list` /
  `--publish-profile` with the owner's key** — they overwrite the owner's real
  10002, 10063 and kind 0, which their phone depends on.
- `nsyte run` cannot do a fully-local gateway rehearsal: its profile-relay
  lookup is hardcoded to `user.kindpag.es` / `purplepag.es`, so a local-only key
  resolves to nothing. It also injects a CSP with `connect-src 'self' wss: https:`,
  which blocks plain `ws://localhost` relays — don't debug that as an app bug.

### 2.4 `ngit nsite` — new in ngit 3

`ngit` 3.0.2 grew a full NIP-5A publisher:

```bash
ngit nsite publish dist --id blog --title "…" --description "…" \
    --source nostr://npub…/repo --fallback dist/404.html \
    --blossom-server https://nostr.download --relay wss://relay.nsite.lol \
    --nbunksec <…>            # or -n <nsec>, or --signer <npub|alias>
```

It is the most complete of the three third-party options: `--fallback` does the
`/404.html` mapping the spec requires, `--id` switches to a named 35128, it
reads nsyte-compatible `.nsite/config.json`, it discovers Blossom servers from
the author's kind 10063 when you don't override, and it signs via nsec, bunker
(`nbunksec`) or a configured signer.

**Its one constraint: it must run inside an ngit repository.** Outside one it
fails with `no nostr git remotes or git config "nostr.repo" value`. That is a
sensible design — the site belongs to the repo, and `--source` writes itself —
but it means it is not a drop-in for a standalone `dist/`. Reach for it when the
site *is* the front end of a GRASP repo; use §2.1 otherwise.

While you are here: ngit 3 also added `ngit release` (software applications,
releases and assets — the Zapstore side, see
[`zapstore-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md)), `ngit container` (OCI
images over Nostr + Blossom), `ngit ci`, and `ngit pr` replacing the old
`ngit list` / `ngit fetch`.

---

## 3. Identity: the rule that has no exceptions

**Kind 15128 is replaceable per pubkey.** Publishing a root site under an
identity that already has one *irreversibly replaces it*. There is no merge, no
warning, no undo.

The owner's key `5ea4648045bb1ff222655ddd36e6dceddc43590c26090c486bef38ef450da5bd`
(`npub1t6jxfqz9…sqvksrw`, "Constant") **already serves a live root nsite**
(Archon-Web, kind 15128). It also has a real kind 10002, a real
Amethyst-maintained 10063, and a real kind 0. All four are destroyable by a
careless deploy.

So, per the workspace identity convention (`CLAUDE.md` § "Persistent identities"):

```bash
mkdir -p ~/Documents/nostr-dev/secrets/<site> && chmod 700 ~/Documents/nostr-dev/secrets/<site>
nak key generate > ~/Documents/nostr-dev/secrets/<site>/keys.json
chmod 600 ~/Documents/nostr-dev/secrets/<site>/keys.json
# then a README.md beside it and configs/identities/<site>.json with the public half
```

and put a **hard abort on forbidden pubkeys in the deploy script** — the owner's
key always, plus any key that is public by design (the Workshop Board's embedded
workshop key is in its `FORBIDDEN` set for exactly this reason: if it could
publish the site, anyone holding the app could replace the site).

If the owner's own identity must sign, use a **named site (35128, `d` ≤ 13 chars)**
via their bunker, and never the `--publish-*` flags. A root site under the owner
key is forbidden.

---

## 4. Blossom Content-Type: the measurement that explains everything

The gateway forwards whatever `Content-Type` the Blossom server reports. The
server records that type **at upload, keyed by sha256** — so a wrong type can
only be fixed by changing the file's bytes. Re-uploading identical content
re-uses the existing blob and its existing wrong type.

Measured 2026-09-21, uploading the same three files from a fresh key via
`nak blossom upload`, then reading back what each server serves:

| Server | `.css` | `.js` | `.wasm` | GET |
|---|---|---|---|---|
| **`https://nostr.download`** | `text/css; charset=utf-8` ✅ | `text/javascript; charset=utf-8` ✅ | `application/wasm` ✅ | 200 direct |
| `https://blossom.primal.net` | **`text/plain`** ❌ | **`text/plain`** ❌ | `application/wasm` ✅ | 302 → 200 |
| `https://blossom.band` | upload **400** | upload **400** | upload **415** | 404 |
| `https://azzamo.media` | upload **415** | upload **415** | upload **415** | — |
| `http://localhost:8081` (ngit-relay) | `text/css; charset=utf-8` ✅ | `text/javascript; charset=utf-8` ✅ | `application/wasm` ✅ | 200 |

Read that carefully, because it corrects the folklore:

- **`nak blossom upload` was never the problem.** It sends the correct
  `Content-Type` from the file extension, and the local server and
  `nostr.download` both honour it.
- **`blossom.primal.net` rewrites every `text/*` type to `text/plain`.** It is
  not "unreliable" and it is not content-sniffing — it is deterministic:
  `text/*` is flattened, `application/*` passes through. A browser refuses a
  stylesheet served as `text/plain`, and refuses to register a service worker
  served as `text/plain`. The page renders, completely unstyled, looking like
  it loaded fine.
- **`blossom.band` now rejects fresh-key uploads outright** (400 for text, 415
  for wasm), not just `.wasm` as previously recorded. Do not list it.
- **`azzamo.media` (= `blossom.azzamo.media`) cannot host an nsite.** It is the
  owner's media server and first in their kind 10063, it accepts uploads from
  any key, and it preserves image types faithfully — but it refuses by MIME with
  HTTP 415: `text/html` and `text/javascript` "not allowed for security
  reasons", `text/css`, `text/plain` and `application/wasm` "not supported".
  Since an nsite is almost entirely those types, it must never appear in a
  `server` tag. Use it for media; see [`../sources/blossom.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md).
- `cdn.satellite.earth` returns 500 on both upload and GET (still down) — and
  it is the **second entry in the owner's live 10063**, so their Amethyst media
  has a dead fallback in it.
- `inner.sebastix.social` is reachable again (401 on `/upload`, 404 on unknown
  sha — i.e. a healthy BUD-01/02 server). Note its **root path** is the API;
  `…/blossom/` is an HTML catch-all that returns 200 for everything and would
  false-positive every dedup check. Its relay side is `restricted_writes: true`
  with `max_event_tags: 14`, so it cannot hold a manifest of more than ~11 files.

**What follows operationally:**

1. `SERVERS = ["https://nostr.download", "https://blossom.primal.net"]`, in that
   order, and **abort if the first one fails** for any file. Primal is a mirror
   for availability, never the type-of-record. The canonical list lives in
   `configs/blossom.json` → `web_assets`.
2. Inlining CSS and JS into `index.html` remains a good belt-and-braces move —
   it removes the failure mode entirely — but now you know *why*, and that it is
   only necessary because of server #2.
3. `.wasm` is safe everywhere that accepts it, including at 9 MB. Still ship the
   `fetch → arrayBuffer → WebAssembly.instantiate` fallback so a host with the
   wrong type can't break boot.
4. There are **no COOP/COEP headers** from nsite.lol ⇒ no `SharedArrayBuffer`,
   no wasm threads. Ever. Single-threaded Go/TinyGo/wasm-bindgen is fine.
5. No CSP from the gateway; CORS is `*` on gateway and blob GETs alike, so the
   app may fetch relays and blobs cross-origin without a proxy.

---

## 5. The failure table

| Symptom | Cause | Fix |
|---|---|---|
| `Site not found` / 404 at the root | Manifest never reached `relay.nsite.lol`, or reached it and was rejected | Publish 15128 there; check the OK message, not the relay count |
| Deploy reports "3/4 relays accepted", site still 404s | The one that refused was `relay.nsite.lol` — usually because the root event carried a `d` tag (`"Root site events must not include a 'd' tag"`) | Drop the `d`. It belongs to 35128 |
| Page loads completely unstyled, no console error | Stylesheet served `text/plain` by `blossom.primal.net` (§4) | Inline the CSS, or make sure `nostr.download` holds it and is listed first |
| Service worker silently never registers | Same, for the SW script | Same |
| Every deep link 404s | No `/404.html` path in the manifest | Add a `path` tag for `/404.html` pointing at index.html's sha; alias the known routes too |
| Deep link renders but returns HTTP 404 | You copied index.html to 404.html — that *renders* but the status is still 404 | Add extra `path` tags for the real routes, same sha, no extra upload → 200 |
| Redeploy doesn't show up | Gateway `cache-control: max-age=3600` | Hash-suffix asset filenames so only `/index.html` is a mutable path; hard-refresh; wait |
| Deploy hangs forever on a `nak` call | `nak` reads stdin | `stdin=subprocess.DEVNULL` on every call — but you cannot pass both `stdin=` and `input=`, so set it only when nothing is piped |
| Site was live, now 404 | Someone published a 15128 under the same pubkey | This is why §3 exists |
| `nsite.lol` returns 502 | Gateway outage; it is a real SPOF | Try another gateway (`<npub>.nsite-host.com`); the manifest is on relays, any implementation can serve it. A service worker precaching the bundle makes this survivable |
| Legacy site 404s | Published as 34128, or as 35128 with an empty `d` | Republish as a 15128 root |

---

## 6. Rehearsing locally

| Service | Endpoint | nsite behaviour |
|---|---|---|
| `nostr-rs-relay` | `ws://localhost:8080` | **accepts** 15128 / 10063 / 10002 — use this |
| khatru GRASP relay | `ws://localhost:8081` | **rejects** 15128 (`"event does not relate to a stored repository"`) — git-scoped, unusable here |
| Blossom (ngit-relay) | `http://localhost:8081` | BUD-01/02 work; **preserves the uploaded Content-Type**, wasm included |

**Level 1 — the app.** `python3 -m http.server 8088 -d dist` or
`nsyte serve -d dist`. Playwright + headless Chromium are installed.

**Level 2 — the pipeline.** Rehearse the whole publish against local infra with
a throwaway key:

```bash
nostr-rs-relay --config ~/Documents/nostr-dev/relays/nostr-rs-relay.config.toml &
KEY=$(nak key generate)
bin/nsite-deploy.py --dir dist --sec "$KEY" \
    --relay ws://localhost:8080 --server http://localhost:8081 --no-verify
nak req -k 15128 -a $(nak key public "$KEY") ws://localhost:8080 | jq '.tags|length'
```

This proves the walk, the hashing, the upload with MIME, the manifest shape and
the relay accept. Everything except the gateway.

**Level 3 — the gateway.** `nsyte run` cannot do this locally (§2.3). Either run
`hzrd149/nsite-gateway` yourself with `LOOKUP_RELAYS`/`NOSTR_RELAYS` pointed at
`ws://localhost:8080`, or accept Levels 1+2 and do the real check read-only on
nsite.lol at release time.

---

## 7. Definition of done

A deploy is not done when the relays said OK. It is done when:

- [ ] `curl -sI https://<npub>.nsite.lol/` → **200**, and the right `content-type`
- [ ] `curl -sI …/<your stylesheet or main js>` → the **correct** type, not `text/plain`
- [ ] `curl -so /dev/null -w '%{http_code}' …/<a deep route>` → **200**, not 404
- [ ] `curl -sI …/definitely-not-a-real-path` → serves your `/404.html`
- [ ] The page renders and does its job in a real browser (Playwright is installed)
- [ ] `nak req -k 15128 -a <pubkey> wss://relay.nsite.lol` returns the event
- [ ] The aggregate `x` in the event matches the one computed from its own `path` tags
- [ ] A `configs/identities/<site>.json` exists with the public half and the
      `secrets_location` pointer, and `git status` does not show the secret
- [ ] `nsite-manifest.json` is committed next to the source, so the next deploy
      is a diff rather than an archaeology exercise

---

## 8. Sites published from this machine

All five verified HTTP 200 on 2026-09-21.

| Site | npub | Source |
|---|---|---|
| Signer Login Tester | `npub138kdqjl645xz6rvuw92m2v4us0shhpxezgqqz9zrrj2jdstakvus86qzyh` | `~/Production Environment/Signer-Login-Tester/` |
| Nostr Workshop Board | `npub1jnrsdqxyyegg7xz8tl6u5zv5lccex393dz28uekzmdjjs9fjw4ysfch4a4` | `~/Production Environment/Nostr-Workshop-Leaderboard/` |
| Cerebrate | `npub1qldvgjekvjzur0vjjffe2m7k4y575k879ypr6ke08tfnxshrn33q0ghyac` | `~/Production Environment/Cerebrate/` |
| Idle StarFighter | `npub1kemgxdffeejmk0xf3ja7lhmxucp4cqzzx4jcvrv4l3ucua3j40gsfgteus` | `~/Production Environment/Idle StarFighter/` |
| Earthtree Media (demo) | `npub143ac528xxw9gtftammcf9dn7yhpcdy6k36824u85009wkwsx45cq57ev6h` | `~/Production Environment/EarthTreeMedia-Nostr/` |
| Nostr Agent Onboarding | `npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe` | `~/Production Environment/Nostr-Agent-Onboarding/` |

Plus the owner's own `npub1t6jxfqz9…` → Archon-Web. **Do not touch that key.**

The Earthtree site was recorded as 404 after the 34128→15128 transition; it was
republished with `nsyte` and is live. The note is stale.

---

## 9. What changed in the spec since the last local write-up

The previous in-depth pass on this machine was `Facebook-Museum/research/nsite-procedure.md`
(2026-07-07) — still the best long-form account of *how it was figured out*, and
the source of much of this document. NIP-5A has moved since:

- **`app` tags.** `["app", "<kind>:<pubkey>:<d>", "<relay>"]` links a manifest to
  an upstream app descriptor — deliberately generic so it can point at NIP-89
  (31990) *or* NIP-82/Zapstore (32267). This is the seam between an nsite and
  [`patterns/zapstore-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md): the same app can be a web nsite and a
  Zapstore listing, cross-referenced.
- **Copied nsites.** `a` (immediate parent) + `A` (lineage origin) let anyone pin
  someone else's site under their own namespace at a known state. Kind and `d`
  may change across a copy; `a`/`A` are the stable references. This is credible
  exit for a website.
- **Snapshots formalised.** 5128 now has MUSTs: copy the parent's `path` tags,
  exactly one matching aggregate `x`, exactly one `a`, and copy `A` if present.
- **The aggregate hash is specified**, with the exact line format and sort order,
  and is what makes two manifests provably the same site.
- **Canonical addressing moved to a single DNS label** (`<pubkeyB36><dTag>`,
  `v<snapshotIdB36>`) to dodge wildcard-certificate limits, and the spec's
  example host is now `nsite-host.com`.
- **Blob verification**: the host SHOULD check the served blob's sha256 against
  the `path` tag and treat a mismatch as not-found.
- `34128` is now listed in the NIPs registry explicitly as **deprecated**.

## Related

- `bin/nsite-deploy.py` — the shared implementation
- [`known-issues.md` §7](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) — the nak-binary split, the primal
  MIME rewrite, blossom.band's rejections
- [`patterns/going-public.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/going-public.md) — the wider "mirror local
  artifacts to public infrastructure" recipe; nsite is its step 4
- [`patterns/go-client-baseline.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/go-client-baseline.md) — if the client
  you are publishing is Go/wasm
- [`sources/blossom.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md) — BUD mechanics
- `~/Production Environment/Facebook-Museum/research/nsite-procedure.md` — the
  2026-07-07 primary research this distils


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/zapstore-publishing.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/zapstore-publishing.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.

# Pattern: Publishing an Android app to Zapstore (from this workspace)

> **Source:** the live OTSuite Mobile v2.0.0 publish documented in this
> workspace on 2026-05-12. Staging dir kept at
> `repos/otsuite-publish/`. Upstream protocol reference:
> [`docs/sources/zapstore.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/zapstore.md).

You have an Android app (your own or a third-party APK) and want to publish a
release to Zapstore. The local-first routing rule from `CLAUDE.md` applies:
**publish to the local sandbox first, mirror to public only when you're sure.**
This recipe walks the full loop from "fresh identity" to "events queryable on
the local relay" without touching `relay.zapstore.dev`.

For the protocol details (which kinds, which tags, why) read the source file
above first. This document is operational.

## The pieces

```
┌─────────────────────────┐    publishes      ┌──────────────────────────┐
│ zsp (Go CLI)            │ ─────────────────►│ kind 32267 + 30063 + 3063│
│ reads zapstore.yaml +   │                   │ on a Nostr relay         │
│ APK; signs with         │                   └──────────────────────────┘
│ SIGN_WITH=nsec…         │                                ▲
│                         │ ─── uploads ───► Blossom (the kind 3063 url)
└─────────────────────────┘
```

Three env-vars route the whole thing:

| Var | What it controls | Local-sandbox value |
|---|---|---|
| `SIGN_WITH` | The Nostr key the events are signed with | `nsec1…` (read from disk) |
| `BLOSSOM_URL` | Where the APK + icon + screenshots go | `http://localhost:8081` |
| `RELAY_URLS` | Where the events go | `ws://localhost:8080` |

Note: events go to `:8080` (the standalone `nostr-rs-relay`), **not** `:8081`
(the GRASP relay). See *Gotchas* below.

## Prerequisites

1. **`zsp` installed** — `go install github.com/zapstore/zsp@latest` lands a
   binary in `~/go/bin/zsp`. v0.4.10 is what this recipe is verified against.
2. **A signing identity (kind:0 profile)** — see next section.
3. **The local `nostr-rs-relay` running on `:8080`** —
   `nostr-rs-relay --config ~/Documents/nostr-dev/relays/nostr-rs-relay.config.toml &`.
   Verify with `ss -ltn | grep 8080`.
4. **The local Blossom (ngit-relay container) running on `:8081`** — already
   up by default. Verify with `curl -fsI http://localhost:8081/`.

## Step 1 — Publisher identity (kind:0)

Generate a keypair once. Persist it **outside `/dev/shm`** — `/dev/shm` is
tmpfs and wipes on reboot, which will silently orphan any profile you
published under the lost key.

```bash
mkdir -p ~/.config/nostr-dev/keys && chmod 700 ~/.config/nostr-dev/keys
nak key generate > ~/.config/nostr-dev/keys/<role>.nsec
chmod 600           ~/.config/nostr-dev/keys/<role>.nsec
# Optional fast-path mirror for the session:
mkdir -p /dev/shm/nostr-dev-session
cp ~/.config/nostr-dev/keys/<role>.nsec /dev/shm/nostr-dev-session/<role>.nsec
chmod 600           /dev/shm/nostr-dev-session/<role>.nsec
```

Publish the profile. The local rs-relay accepts any kind:0; the GRASP relay
on `:8081` will reject it:

```bash
NSEC=$(cat ~/.config/nostr-dev/keys/<role>.nsec)
nak event --sec "$NSEC" -k 0 \
  -c '{"name":"<Role>","display_name":"<Role>","about":"<one-liner>"}' \
  ws://localhost:8080/
```

Record the public reference (npub + pubhex, **no secret**) in
`configs/identities/<role>.json` so future sessions can find the identity
without re-deriving. Pattern:

```json
{
  "name": "<Role>",
  "purpose": "<one-line description>",
  "npub": "npub1…",
  "pubkey_hex": "…",
  "profile_published_to": ["ws://localhost:8080"],
  "nsec_storage": "~/.config/nostr-dev/keys/<role>.nsec",
  "created": "YYYY-MM-DD"
}
```

`configs/identities/ots-publisher.json` is the live example.

## Step 2 — Stage the publish

Make a staging directory under `repos/` (gitignored). `zsp` resolves paths
relative to the directory it's run from, so keep the yaml and any local
assets together:

```bash
mkdir -p ~/Documents/nostr-dev/repos/<app>-publish
cd       ~/Documents/nostr-dev/repos/<app>-publish
```

Write `zapstore.yaml`. Minimum useful form for an app whose source repo is a
local GRASP repo (kind:30617):

```yaml
# The repository field accepts a NIP-34 naddr (preferred when the source repo
# is itself a Nostr-native GRASP repo). It also accepts forge URLs
# (github.com/…, gitlab.com/…, codeberg.org/…, …).
repository: naddr1qq8x7arnw45hgefdd4hky6tvv5q3gamnwvaz7tmjv4kxz7fwdenkjapwv3jhvqgnwaen5te0d3hkxctvdphhxap68qcrsvgzyq2ekklg2zl7atkynst5czefeze2e3gtk3vvtmgdkns9c3lfxrzgvqcyqqq80xg0dw096

# Local APK path — also accepts URLs and F-Droid/GitHub release coordinates.
release_source: /home/you/Desktop/MyApp-v1.2.3.apk

name:    MyApp
summary: One-line description shown in app listings.
description: |
  Longer markdown-friendly description.

icon: /home/you/Desktop/MyApp-icon.png   # local path or URL
tags: [topic-a, topic-b]
```

Build the naddr from a kind:30617 if you don't have one already:

```bash
nak encode naddr \
  --kind 30617 \
  --pubkey <maintainer-pubkey-hex> \
  --identifier <d-tag> \
  --relay wss://relay.ngit.dev \
  --relay ws://localhost:8081
```

## Step 3 — Offline preview (always do this first)

`--offline` signs the three events but uploads nothing and publishes nothing.
Events go to stdout, the upload manifest to stderr — read both before
committing.

```bash
NSEC=$(cat /dev/shm/nostr-dev-session/<role>.nsec)
SIGN_WITH="$NSEC" \
BLOSSOM_URL=http://localhost:8081 \
RELAY_URLS=ws://localhost:8080 \
zsp publish --offline --quiet --skip-certificate-linking zapstore.yaml
```

Inspect:

- The kind 32267 `d`-tag is the package id you expected (no typo, no debug
  suffix you didn't intend — `com.example.app.debug` vs `com.example.app` is
  a different listing entirely).
- The kind 3063 `apk_certificate_hash` matches what you expect for the build
  variant. A debug build will have the well-known Android debug cert
  fingerprint; a release build will have your release keystore's.
- The upload manifest lists every blob (APK, icon, screenshots) with size +
  sha256.

`--skip-certificate-linking` is the right choice for a sandbox publish. See
*Cert linking* below for when to drop the flag.

## Step 4 — Cert linking (one-time, optional for sandbox)

If you have a release keystore, link its cert to your Nostr identity once.
This produces a **kind 30509** NIP-C1 proof event (`d`-tag = cert SHA-256,
plus a `signature` tag holding the RSA signature over the npub). Clients use
it to detect repo hijacks. Skip for debug keystores and sandbox-only
publishes (use `--skip-certificate-linking` in Step 5 in that case).

`zsp identity --link-key` accepts `.p12`/`.pfx`/`.pem`/`.crt`; **`.jks` needs
a one-line `keytool` conversion first**:

```bash
KS_JKS=~/Documents/nostr-dev/secrets/<app>/release-keystore.jks
KS_P12=~/Documents/nostr-dev/secrets/<app>/release-keystore.p12
PW=$(cat ~/Documents/nostr-dev/secrets/<app>/release-keystore-pw.txt)
ALIAS=<your-key-alias>

keytool -importkeystore -noprompt \
  -srckeystore "$KS_JKS" -srcstoretype JKS -srcstorepass "$PW" -alias "$ALIAS" \
  -destkeystore "$KS_P12" -deststoretype PKCS12 -deststorepass "$PW"
chmod 600 "$KS_P12"
```

Then sign + publish the link event. `--offline` lets us inspect the event
before sending; pipe to `nak` for the actual publish:

```bash
NSEC=$(cat ~/.config/nostr-dev/keys/<role>.nsec)
KEYSTORE_PASSWORD="$PW" SIGN_WITH="$NSEC" \
  zsp identity --link-key "$KS_P12" --offline \
  | nak event ws://localhost:8080/
```

The cert-link event is replaceable per `d`-tag (cert hash) and per-pubkey, so
re-running is a no-op until the cert rotates. Default expiry is 1 year —
override with `--link-key-expiry 2y` (or `6mo`, `30d`, …).

## Step 5 — Real publish

Same command as the offline preview without `--offline`. Drop
`--skip-certificate-linking` if you did Step 4:

```bash
NSEC=$(cat ~/.config/nostr-dev/keys/<role>.nsec)
SIGN_WITH="$NSEC" \
BLOSSOM_URL=http://localhost:8081 \
RELAY_URLS=ws://localhost:8080 \
zsp publish --quiet zapstore.yaml          # add --skip-certificate-linking for debug builds
```

Replaceable events (32267, 30063) make the publish idempotent — re-run as
often as you like and the relay keeps the latest per `(pubkey, kind, d)`.
The 3063 asset event is regular, so a content-addressed re-run produces an
identical event id and is also a no-op.

**`zsp` HEAD-checks Blossom before uploading.** If your blob is already at
the configured `BLOSSOM_URL` (same SHA-256), the upload is skipped. This is
how a publish can succeed against a *write-restricted* public Blossom: a
member uploads, and your unprivileged publisher key just references the
existing blob. (Confirmed against `inner.sebastix.social` — see Gotcha #7.)

## Step 6 — Verify

Three queries (one per kind) and one Blossom check:

```bash
PUBHEX=<your-publisher-pubkey-hex>

# App metadata
nak req -k 32267 -a "$PUBHEX" ws://localhost:8080/

# Release set (walk its `e` tag to the asset event clients will actually fetch)
nak req -k 30063 -a "$PUBHEX" ws://localhost:8080/

# Asset metadata (kind 3063 is *regular* — relay accumulates one per
# distinct content; URL changes mean a new event, the old one stays as dust)
nak req -k 3063 -a "$PUBHEX" ws://localhost:8080/

# Cert-link proof (if Step 4 was run)
nak req -k 30509 -a "$PUBHEX" ws://localhost:8080/

# APK actually on Blossom?
curl -fsI <kind-3063-url-tag> | head -1   # expect "HTTP/1.1 200 OK"

# Everything we uploaded under our pubkey (local Blossom only)
curl -fs "http://localhost:8081/list/$PUBHEX" | jq .
```

## Going public

Local-sandbox is enough for development and for handing a colleague an
`naddr` they can resolve against your relay. To make the app discoverable on
the open Zapstore takes three additional steps, each independent:

1. **Replicate events to public relays.** Either point `RELAY_URLS` at a
   public set on the next run, or follow
   [`patterns/going-public.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/going-public.md) for the
   pull-from-local-then-push-to-public idiom (kinder to public relays:
   you upload only the latest version of each replaceable event).

2. **Mirror Blossom blobs to a public Blossom.** Same: either
   `BLOSSOM_URL=https://cdn.zapstore.dev` on the publish, or upload the
   content-addressed blobs separately (`nak blossom upload --sec "$NSEC" -s
   https://cdn.zapstore.dev <file>`).

3. **Whitelist on `relay.zapstore.dev`** so the public relay accepts your
   pubkey. The documented path — commit a `zapstore.yaml` with
   `pubkey: <your-publisher-npub>` to the root of the linked source repo —
   **does not work when the source repo is a NIP-34 / GRASP repo**: the
   relay's verifier only resolves github / gitlab / codeberg / gitea /
   forgejo URLs. Full writeup in
   [`known-issues.md` §3](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md#3-relayzapstoredev-whitelist-verifier-does-not-follow-nip-34--grasp-repos).
   Practical options for GRASP-native projects:
   - **Mirror to a supported forge** (github / gitlab / codeberg / gitea /
     forgejo). The relay re-fetches the yaml from there and binds the
     pubkey automatically.
   - **Vertex reputation.** Passive; depends on social activity.
   - **DM the admin.** The relay's NIP-11 `contact` field is a real Nostr
     pubkey monitoring an inbox (typically a NIP-17 kind 10050 inbox; the
     Zapstore admin's inbox is `wss://auth.nostr1.com`, behind NIP-42
     AUTH). A polite NIP-17 gift-wrapped DM citing the publisher npub,
     repo coordinate, and current event ids has worked at least once
     from this workspace. Since nak v0.19.2, `nak event --auth --sec
     "$NSEC" <inbox-relay> < wrap.json` leaves an unmodified wrap intact,
     so nak can send it. Just add no flags that modify it (Gotcha #10).
     With an older nak, use
     [`sdk/examples/publish-wrap-with-auth.ts`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/publish-wrap-with-auth.md).
     Reference message: `repos/otsuite-publish/sent-dms/`.
   - **Accept partial reach.** The three big general-purpose relays
     (`damus.io`, `nos.lol`, `primal.net`) already carry the publish and
     provide outbox-model discovery. The Zapstore-client default relay is
     the only thing missing.
   Required only for the *Zapstore client's* default-relay set; your own
   relays don't care.

4. **NIP-C1 cert linking** is covered inline in Step 4. For the public
   Zapstore listing, that link event needs to be on the same public relays
   the kind 32267 lands on (`relay.zapstore.dev`, `relay.damus.io`, …) — the
   default `zsp identity` relay set is already `relay.primal.net,
   relay.damus.io, relay.zapstore.dev`. Override with `--relays` if you want
   a tighter set.

5. **(If publisher == repo maintainer) you self-serve the whitelist.** When
   the same npub signs the kind:30617 GRASP repo announcement *and* the
   kind:32267 app event, `relay.zapstore.dev`'s verifier can match the two
   directly. Otherwise the `zapstore.yaml`-in-repo flow above is the way.

## Gotchas

1. **Don't publish app events to `ws://localhost:8081`.** The GRASP relay
   policy rejects events that don't relate to a stored git repository
   (`blocked: event does not relate to a stored repository`). Publish to the
   standalone `nostr-rs-relay` on `:8080`. The kind:30617 repo announcement
   itself lives on the GRASP relay (that's where it gets published when you
   `ngit init`); the app events that *reference* it live elsewhere. The
   same policy applies on `wss://relay.ngit.dev` — only the kind 32267
   (which carries an `a`-tag) gets through there; 30509 / 30063 / 3063 / 0
   all bounce. See
   [`known-issues.md` §4](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md#4-relayngitdev-rejects-events-that-dont-carry-an-nip-34-a-tag)
   for the full writeup.

2. **`/dev/shm` is volatile.** Lost an nsec to a reboot once already; the
   orphan profile is fossilized in
   `configs/identities/ots-publisher.json _orphaned_predecessor`. Persist
   nsecs to `~/.config/nostr-dev/keys/` (outside the repo).

3. **Blossom `list/<pubkey>` reports `:3334` URLs.** The container-internal
   port leaks into the response body. Ignore it; the external port is
   whatever `BLOSSOM_URL` was on upload. (Same quirk noted in `CLAUDE.md` for
   the upload response.)

4. **Debug-signed APKs are bad NIP-C1 subjects.** The default Android debug
   keystore is identical across many developer machines. Linking that cert
   fingerprint to your npub effectively links *every other dev with the same
   debug keystore* to your identity too. Always use a release-signed APK
   when running the cert-linking step.

5. **Fat APKs publish under multiple `f` tags; single-arch APKs don't fan
   out.** `zsp` emits one kind 3063 per APK file. A fat APK gets multiple
   `f` arch tags on the same event; a release that ships separate
   per-arch APKs produces multiple kind 3063 events, one per file, all
   referenced from the same kind 30063 release set.

6. **`zsp publish --quiet` is genuinely quiet.** No output on success — only
   exit code 0. Pipe to `tee` if you want a record, or query the relay
   afterwards to confirm. (`--json` gives you JSONL on stdout if you want
   machine-readable.)

7. **Some public Blossoms (`inner.sebastix.social`, others) are
   member-write-only.** A non-member upload gets HTTP 403 with `only pyramid
   members can upload blobs`. The workaround is *content-addressing*: have
   the member upload the file, then have any publisher point `BLOSSOM_URL`
   at that server. `zsp` HEAD-checks before POSTing, finds the blob, skips
   the upload, and emits events whose `url` tag is the public URL anyway.
   The icon for the OTSuite v2 worked example was handled this way (`zsp`
   extracts the icon from the APK and stages it on the publisher's machine
   — hand it to the upstream member to push).

8. **Changing `BLOSSOM_URL` between publishes leaves orphan kind 3063
   events on the relay.** Kind 3063 is regular (not addressable). A
   different URL → different event content → different event id. The kind
   30063 release set's `e` tag follows the new asset, so client behaviour
   stays correct, but a `nak req -k 3063 -a $PUBHEX` returns every asset
   ever published. Tombstone the stale ones with NIP-09 kind:5 if it
   matters; otherwise leave as dust.

9. **`.jks` keystores need PKCS12 conversion before `zsp identity`.** Step 4
   has the one-line `keytool` command. `zsp` will tell you this if you try
   the JKS directly, but the error path costs a round-trip.

10. **Don't let `nak event` modify a gift wrap before publishing, or it
    arrives undecryptable.** Up to nak v0.19.1, any `--sec` made `nak event`
    re-sign a piped event. It overwrote the wrap's ephemeral pubkey with the
    `--sec` key's pubkey, rehashed and re-signed it, and published the rebuilt
    event. The ciphertext was still bound to the original ephemeral key, so
    NIP-44 v2 decryption failed on the recipient's side. That is how the
    DM-the-admin whitelist attempt in [Going public](#going-public) item 3
    failed twice. Fixed in nak **v0.19.2** (the one on `PATH` is v0.20.7):
    `nak event --auth --sec ...` now publishes a signed, unmodified wrap
    exactly as given. The overwrite still happens with **`--force-sign`**,
    or with any flag that modifies the event (`-t`, `-p`, `-c`, `--ts`,
    `--pow`, …), so pass neither with a wrap. Pre-flight the command
    without relay URLs and compare its output with the wrap (`jq -cS .` on
    both). On an older nak, use the
    [`publish-wrap-with-auth.ts`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/publish-wrap-with-auth.md)
    helper, which handles AUTH and publishes the event byte-for-byte
    unchanged. Full writeup and the 2026-09-26 offline verification in
    [`known-issues.md` §5](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md#5-nak-event---sec--silently-re-signed-fully-formed-events-on-stdin--resolved-in-nak-v0192).

## Reference — OTSuite Mobile v2.0.0 (release build)

What a worked, full-fat publish actually looks like — publisher npub matches
the GRASP repo maintainer, APK signed with a real 4096-bit RSA release
keystore, NIP-C1 cert-link in place, public Blossom hosting the binaries.

| Field | Value |
|---|---|
| Publisher npub (== repo maintainer) | `npub1zkd4h6zshlh2a3yuzaxqk2wgk2kv2za5trz76rd5upwy06fscjrq8mk5ta` |
| App package id (kind 32267 `d`) | `com.otsuite.lite` |
| Source repo (`a` tag) | `30617:159b5be8…c486:otsuite-mobile@wss://relay.ngit.dev` |
| Release cert SHA-256 | `de5c1e9c…0999`  (CN=OTSuite Mobile, RSA-4096) |
| APK | 201.99 MB, sha256 `6cf382b8…9c8d` — at `https://inner.sebastix.social/<sha256>` (member-uploaded) |
| Icon | 14.9 KB PNG, sha256 `6106cb33…94bb` — same Blossom |
| kind 32267 (app) | `4f7ec823…597c` |
| kind 30063 (release) | `cba23d18…e5b4` → `e:1fd90f9e…cab1` |
| kind 3063  (asset) | `1fd90f9e…cab1` |
| kind 30509 (NIP-C1) | `65776dc4…fe9a` (`d`=cert hash, expires 2027-05-12) |

`zapstore.yaml`: `repos/otsuite-publish/zapstore.yaml`.
Earlier debug-build config preserved at `zapstore.yaml.debug-build` for
comparison. Identity record:
`configs/identities/otsuite-mobile-publisher.json`.
Secrets: `secrets/otsuite-mobile/` (gitignored).

Replaying this publish end-to-end (from a clean shell, assuming services are
up and the APK is at the path):

```bash
APP=otsuite-mobile
cd ~/Documents/nostr-dev/repos/${APP%-publish}-publish 2>/dev/null || \
   cd ~/Documents/nostr-dev/repos/otsuite-publish

# One-time: cert link
KS_P12=~/Documents/nostr-dev/secrets/otsuite-mobile/release-keystore.p12
PW=$(cat ~/Documents/nostr-dev/secrets/otsuite-mobile/release-keystore-pw.txt)
NSEC=$(cat ~/Documents/nostr-dev/secrets/otsuite-mobile/session-nsec.txt)
KEYSTORE_PASSWORD="$PW" SIGN_WITH="$NSEC" \
  zsp identity --link-key "$KS_P12" --offline \
  | nak event ws://localhost:8080/

# Publish (idempotent)
SIGN_WITH="$NSEC" \
BLOSSOM_URL=https://inner.sebastix.social \
RELAY_URLS=ws://localhost:8080 \
zsp publish --quiet --overwrite-release zapstore.yaml
```


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/grasp-as-structural-layer.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/grasp-as-structural-layer.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.

# Pattern: GRASP repo as the structural layer for non-code content

> **Source:** developed and proven in `~/work/nostr-archive/` (sibling agent's
> work). See `~/work/nostr-archive/docs/archive-grasp-repo.md` for the full
> `archive-grasp/v1` schema. This doc generalizes the pattern beyond
> archives.

NIP-34 GRASP repos are typically used for source code. They generalize: a
GRASP repository is a useful **structural layer for any content
collection** whose organizing tree changes over time and whose authorship
matters.

## When this pattern applies

If your problem looks like:

- "I have a curated set of items that lives somewhere else (Blossom blobs,
  third-party URLs, IPFS, local files)."
- "The set evolves: items added, renamed, moved, federated from other
  curators."
- "Each curatorial change should be **attributed** and **history-preserving**."
- "The set has a *folder hierarchy* or graph structure that's
  organizer-controlled."

…then a GRASP repo is probably a better structural layer than a Nostr
addressable event (kind 30000-range) holding a JSON tree.

## Why a GRASP repo beats a JSON-blob TOC

| Concern | JSON blob in Blossom + addressable event | GRASP repo |
|---|---|---|
| Atomic updates | Re-upload blob, re-publish event, hope the two land together | One commit |
| History | None (replaceable event evicts older versions) | `git log` is the history |
| Author attribution | Only on the wrapper event | On every commit |
| Federation | Custom: include other archivers' addresses in your blob | Native: Git submodule pointing at their repo |
| Concurrent maintainers | Hard | NIP-34's `maintainers` tag + signed pushes |
| Tooling | None standard | Every git client, every IDE, web UI (gitworkshop.dev) |

## Minimal schema sketch

The archive project chose this layout, which is reusable verbatim for
anything similar:

```
<repo-root>/
├── <root-metadata>.json     # schema version + collection-level metadata
├── README.md                # human-readable description
├── <folder>/
│   └── folder.json          # per-folder metadata + references to content
│       (hierarchy is the on-disk directory tree — no `children` field)
└── ...
```

Two rules that fall out of "use Git's tree as the structure":

1. **Don't duplicate the tree in JSON.** No `children`, no `path`-as-string.
   If the file is at `podcasts/bitcoin-and/folder.json`, that's its path.
2. **References to content go in `folder.json`** by Nostr coordinate
   (`["nevent", "<id>"]`, `["naddr", "<addr>"]`) or sha256
   (`["x", "<sha256>"]`) or external URL (`["r", "<url>"]`). The
   structural layer references; it doesn't embed.

## Federation via Git submodules

The cleanest part of this pattern. A folder that's "really another
archiver's collection mirrored here" is a Git submodule:

```
<my-repo>/
├── archive.json
└── partners/
    └── alice/                # submodule → alice's GRASP repo at commit X
        └── archive.json      # alice's signed root, mounted under partners/alice/
```

Walking the consumer's side:

1. Clone the parent repo from its GRASP server.
2. On entering `partners/alice/`, the submodule's `.gitmodules` entry
   says where alice's repo lives. Use `git-remote-nostr` to clone it
   (alice's URL is a `nostr://` URL or a GRASP HTTP URL).
3. The pinned commit hash in the parent's tree object is alice's
   *signed* tree at that moment — the parent attests "I have seen this
   exact tree of alice's and chosen to include it here."

No new schema needed. Submodules already mean exactly this.

## Storage layer remains independent

The structural repo references content; it doesn't host it. Content goes
to:

- **Blossom** — when the items are arbitrary binary blobs you need to
  pin (audio, video, PDFs). Reference by sha256.
- **Nostr** — when the items are short-form, addressable, or already on
  Nostr (kind:1 notes, long-form articles, etc.). Reference by
  `nevent` / `naddr`.
- **External URLs** — when the items are web resources you don't own.
  Reference by `r` tag. Consider also pinning a Blossom snapshot.

## Local mechanics on this machine

The local GRASP server (`http://localhost:8081`, see
`configs/local-services.json`) accepts arbitrary repos under
`/<npub>/<repo>.git`. Same workflow as for code:

```bash
cd <repo-working-tree>

# init nostr identity for the repo (publishes kind:30617)
NSEC=$(jq -r .nsec /dev/shm/nostr-dev-session/keys.json)
ngit init -d --name "<name>" --identifier "<d-tag>" \
        -g ws://localhost:8081 --repo-relay-only -n "$NSEC"

# routine commits, atomic per change
git commit -m "add: podcasts/<name>"
git push origin main      # via the nostr:// remote

# release the credential
ngit account logout
```

The pre-receive hook on ngit-relay validates pushes against the on-relay
kind:30617 announcement, so the same identity model that protects code
repos protects the structural layer.

## Trade-offs / when *not* to use this

- **Single-document state.** If your structure is one settings JSON and
  it has no history value, kind 10000-range replaceable is simpler.
- **High write velocity.** A commit per change is cheap, but if you're
  appending O(thousand) tiny changes per day, you're better off with a
  log of regular events and a periodic compaction. GRASP repos shine
  for human-paced curation, not high-frequency state.
- **No federation requirement.** If you're a single archiver and never
  expect a second one, the submodule story is unused; the simpler
  approach is also fine.

## Related concepts in this workspace

- [`docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §3 — event-kind taxonomy and *why* defaulting
  to regular events composes with this pattern (curatorial changes are
  themselves regular kind:1115/1116-style events that the structural
  layer references).
- [`docs/sources/blossom.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md) — content layer that pairs with this
  structural layer.
- [`docs/known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) — Khatru's `kind:30617` eviction quirk that
  affects multi-repo archivers.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/going-public.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/going-public.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.

# Pattern: Going public — exposing local Nostr-native artifacts on the open internet

> **Source:** the runbook `~/work/nostr-archive/docs/going-public.md` (sibling
> agent's work). That document covers an archive specifically; this one
> generalizes the recipe so any artifact built on this workspace's local
> stack can be made publicly reachable without exposing this machine to
> inbound traffic.

You built something against the local GRASP / relay / Blossom
(`http://localhost:8081`). It works in this environment. Now you want
anyone with a browser to be able to use it, ideally without poking holes
in your firewall, NAT, or DNS.

The pattern is **publish to public infrastructure**. Local stays
canonical for development; public is a mirror. The visitor's browser
only ever talks to public services. Bytes are content-addressed, events
are signed — replicating to public losses no provenance.

## Three things to mirror

1. **Events** (kind:1, kind:30617, anything addressable) → public Nostr
   relays.
2. **Blobs** (Blossom) → public Blossom servers.
3. **Git repos** (GRASP `nostr://` URLs) → a public GRASP host.

If your artifact is a static web client, there's a fourth piece:

4. **The static site itself** → publish as an **nsite** (NIP-5A, kind 15128;
   the old per-file kind 34128 is dead). An nsite gateway (`<npub>.nsite.lol`)
   serves it from public Blossom. Full recipe:
   [`nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md).

## The recipe

Adapted, generalized, and condensed from `~/work/nostr-archive/docs/going-public.md`.
Every step is idempotent — re-running won't hurt.

### 1. Mirror events to public relays

Pick the kinds your artifact uses, pull from local relays, push to public:

```bash
PUBHEX=$(jq -r .pub_hex /dev/shm/nostr-dev-session/keys.json)
PUBLIC=("wss://relay.ngit.dev" "wss://nos.lol" "wss://relay.damus.io")

# Replace 30617 with whatever kinds your artifact uses
{ for k in 30617 30618 1; do
    nak req -k "$k" -a "$PUBHEX" ws://localhost:8081 2>/dev/null
  done
} | jq -c 'select(.id != null)' | sort -u > /tmp/events.jsonl

while IFS= read -r ev; do
  echo "$ev" | nak event "${PUBLIC[@]}" >/dev/null 2>&1
done < /tmp/events.jsonl
```

Expect 2-of-3 success on any given event. Public relays sometimes
rate-limit, content-policy, or blip. As long as one accepts each event,
discovery still works.

### 2. Mirror Blossom blobs to a public server

```bash
NSEC=$(jq -r .nsec /dev/shm/nostr-dev-session/keys.json)

# Collect every sha256 your events reference (`x` tags, `primary`, `ots`,
# whatever your kinds use):
SHAS=$(jq -r 'select(.kind==<your-kind>) | .tags[] | select(.[0]=="x") | .[1]' \
        /tmp/events.jsonl | sort -u)

for sha in $SHAS; do
  curl -sLf -o /tmp/blob "http://localhost:8081/$sha"
  nak blossom --sec "$NSEC" -s https://blossom.primal.net upload /tmp/blob >/dev/null
done
rm /tmp/blob
unset NSEC
```

Recommended public Blossom servers as of writing:
- `https://blossom.primal.net` — large, reliable, no auth quirks
- `https://blossom.band` — index-friendly
- Run `blossom-audit` against a server before relying on it: `npx blossom-audit audit https://server bitcoin --sec <ephemeral nsec>`

### 3. Push the GRASP repo to a public host

`relay.ngit.dev` runs the same `ngit-relay` software as the local stack
and accepts pushes from any pubkey, validated against on-relay
`kind:30617` events. So the same `ngit init` workflow you used locally
also works against the public GRASP — just point it there:

```bash
cd <repo-working-tree>
NSEC=$(jq -r .nsec /dev/shm/nostr-dev-session/keys.json)
ngit init -d \
    --name "<repo-name>" \
    --identifier "<d-tag>" \
    --description "Public mirror." \
    -g wss://relay.ngit.dev \
    -g ws://localhost:8081 \
    -n "$NSEC"
unset NSEC
```

After this, the kind:30617 announcement on relay.ngit.dev lists *both*
clone URLs — public first, local as fallback. A browser visiting the
public URL clones from relay.ngit.dev. A consumer on this machine can
still use localhost.

### 4. (If applicable) Publish the client as an nsite

For a static-site artifact (HTML/CSS/JS/wasm), this step has its own pattern
doc and its own script — **[`nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md)** and
`bin/nsite-deploy.py`. Don't hand-roll it; five
people already did and each hit the same three traps.

```bash
~/Documents/nostr-dev/bin/nsite-deploy.py --dir dist \
    --keys ~/Documents/nostr-dev/secrets/<site>/keys.json \
    --title "…" --description "…"
```

Result: anyone visits `https://<your-npub>.nsite.lol/` and the gateway
fetches `kind:15128`, resolves each path's blob from public Blossom, and
serves it.

The three traps, in one line each: publish under a **dedicated key** (15128 is
replaceable per pubkey, so the wrong key destroys an existing site); the events
**must** reach `wss://relay.nsite.lol`; and `https://nostr.download` goes
**first** in the server list because `blossom.primal.net` serves every `text/*`
asset as `text/plain`, which silently kills stylesheets and service workers.

### 5. Update the client's defaults to point at public infrastructure

If your client has hardcoded `ws://localhost:8081`, switch to
`wss://relay.ngit.dev` (or whichever public relays apply) before
publishing. Keep the localhost URL as a *fallback in the user's UI*, not
the default.

## What still requires this machine

- **None of the above for visitors.** Once mirrored, the artifact is
  publicly reachable.
- **Producing new content.** Whatever pipeline writes to the local
  Blossom + signs events still runs here. Add `NAP_BLOSSOM_MIRRORS` (or
  your equivalent env var) so each new blob auto-mirrors to public on
  the way out.

## Failure modes to expect

| Symptom | Cause | Mitigation |
|---|---|---|
| Public Blossom 404 on a blob you uploaded yesterday | GC; some servers expire un-pinned blobs | Re-upload (idempotent — same sha256). Use a Blossom server that doesn't GC. |
| Public relay drops a kind:1 you sent | Rate limit or content policy | Mirror to ≥3 public relays. |
| `relay.ngit.dev` is down | Service outage | The kind:30617's `clone` tag lists local fallback (only useful from this network). For real production, mirror the repo to a second public GRASP. |
| `nsite.lol` is down | Gateway outage | Try `<npub>.nsite-host.com` or any other nsite gateway. The kind:15128 lives on relays; any gateway implementation can serve it. |
| Browser CORS error against the local GRASP | The local container's nginx + Khatru both emit CORS headers | See [`docs/known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) § "ngit-relay double CORS headers" |

## What this pattern doesn't solve

- **Inbound producer access.** If you want others to push *to* your
  machine, you need a tunnel or a real public IP. This pattern is
  specifically about making locally-produced artifacts *consumable*
  publicly.
- **DMs and inbox-routed content.** NIP-65 inbox semantics still mean
  you have to publish to the recipient's INBOX, not your own outbox.
  Going public for outbox-routed content is what this pattern handles.
- **Bandwidth costs at scale.** If the public Blossom server you mirror
  to charges for bandwidth, viral content is your problem. Mirror to
  multiple servers; if one buckles the others stay up.

## Related

- `configs/local-services.json` — where the local services live
- [`docs/sources/blossom.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md) — Blossom mechanics (the blob mirror step)
- [`docs/sources/outbox-model.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/outbox-model.md) — relay routing semantics (the event
  mirror step)
- [`docs/known-issues.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/known-issues.md) — the CORS quirk, Khatru kind:30617 eviction, and
  §7 the nsite trap set; all relevant when going public
- [`patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) — step 4 in full


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/merkle-ots-extension.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/patterns/merkle-ots-extension.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.

# Pattern: OpenTimestamps Merkle-extends-downward

> **Source:** designed and verified end-to-end in
> `~/work/nostr-archive/docs/ots-proofs.md`. **The test harness that used to sit
> at `~/work/nostr-archive/tests/ots-extension/` is gone as of 2026-09-21** — the
> algorithm below is still correct, but the reference implementation is not on
> this machine any more; `pipeline/nap/ots.py` and `client/js/ots.js` in that
> repo are the surviving code. Verified against both
> `python-opentimestamps` and `github.com/fiatjaf/ots` for leaf-set sizes
> {1, 2, 3, 5, 8}. Property holds.
>
> This document generalizes the primitive away from archives. It applies
> to anything that needs *shared* Bitcoin time-attestation across a set of
> related digests.

## The primitive

You have N sha256 digests (files, blob hashes, signed-event ids,
arbitrary content) that you want Bitcoin-anchored timestamps on. Naïve
approach: stamp each with OpenTimestamps individually, get N `.ots`
files. Cost: N rounds of calendar-server interaction, eventually N
Bitcoin block confirmations to pay attention to.

Better approach: **stamp once over a Merkle root of all N**, and derive
per-leaf `.ots` proofs that verify with stock OpenTimestamps tooling.

Cost: 1 calendar interaction, 1 Bitcoin block, and a small piece of
client-side surgery to extend the proof down to a chosen leaf.

## Why the construction works

The OpenTimestamps "virtual machine" expresses each Merkle step as two
ops: `OpAppend(sibling)` (or `OpPrepend(sibling)`) followed by `OpSHA256`.
These are exactly the operations a calendar's *own* aggregation tree
uses. So a bundle's Merkle layer is **just an extra aggregation level
below the calendar's** — indistinguishable in form. Concatenating your
bundle's Merkle path to the front of an OTS file's operation chain
yields a single uninterrupted operation sequence from leaf to Bitcoin
block header.

The only design constraints that matter:

1. Internal node = `sha256(left || right)`. **No length prefix, no
   leaf-tag byte, no domain separation.**
2. Tree shape: bottom-up, with **odd nodes carried up unchanged** (not
   duplicated as in Bitcoin's coinbase tree). An odd carry-up is a
   no-op at that level; the node is paired one level higher. This is
   the calendar's convention.
3. For `n = 1`, the root is the leaf itself with no SHA-256 applied.

If you do those three things, an OTS proof over the root extends to any
leaf with stock-format output. If you violate any of them, the
extension still composes mathematically but the resulting `.ots` file
is non-standard and stock `ots verify` won't accept it.

## When to use this

This is a generic primitive. Some places it earns its keep:

- **Federated content stores.** A bundle of N blobs gets one `.ots`. Per-
  blob proofs are derivable on demand. Re-archivers can carry the
  derived proofs forward without re-stamping. (This is the archive
  project's case.)
- **Audit logs.** A daily/hourly batch of N log lines gets one stamp.
  Per-line proofs are extracted only when a dispute requires one.
- **Document sets.** A signed envelope over N attachments. A recipient
  who only needs one attachment can verify time-attestation for
  *just that file* without seeing the others.
- **Code release manifests.** N artifact hashes (binaries, source
  tarballs, container images) under a single release stamp.
- **Anything with "share one anchor, derive many proofs."**

## Sketch in pseudocode

Tree build (deterministic; lex-sort by hex digest):

```python
def build_root(leaves: list[bytes32]) -> bytes32:
    assert len(leaves) >= 1
    level = sorted(set(leaves))
    while len(level) > 1:
        next_level = []
        for i in range(0, len(level) - 1, 2):
            next_level.append(sha256(level[i] + level[i+1]))
        if len(level) % 2 == 1:
            next_level.append(level[-1])     # odd carries up unchanged
        level = next_level
    return level[0]
```

Per-leaf proof extraction:

```python
def extract_leaf_proof(leaves, target, bundle_ots_bytes) -> bytes:
    # Walk from `target` up to root, recording (sibling_digest, side)
    # at each pairing step. Concatenate the resulting ops in front of
    # the existing OTS operation chain. The output deserializes as a
    # standard .ots file.
    ...
```

Reference impls of the OTS surgery exist in `python-opentimestamps`
(`Timestamp.merge`, direct op-list manipulation) and in `ots-rs`
(operation-chain access). The archive project has a working Python
implementation, formerly at `~/work/nostr-archive/tests/ots-extension/extend.py` (removed; see the note at the top).

## Verification (any consumer)

The leaf and a derived `.ots` proof are sufficient input:

```bash
ots verify --digest <leaf-hex> leaf.ots
# or, if you have the bytes:
ots verify leaf.ots --file leaf-content.bin
```

The verifier walks: leaf → (your appended Merkle ops) → bundle root →
(calendar's aggregation ops) → Bitcoin block header → block height +
timestamp. Stock client; no special tooling.

## "Earliest timestamp wins" for federated content

If the same digest appears in multiple bundles by different curators,
you can have multiple valid OTS proofs for it. The canonical time is
the **earliest** Bitcoin block height across all valid proofs.
Verifiers MUST take the minimum, not the most recent or most
accessible.

This composes naturally because:

- The digest is content-addressed (sha256 doesn't change when copied).
- Each curator's bundle has its own root and its own `.ots`, and
  per-leaf extension produces independent proofs.
- All proofs refer to the same digest; only the path through the
  Merkle tree and the calendar's aggregation differs.

The corollary: a re-archiver MAY carry forward an earlier curator's
per-leaf proof rather than re-stamping. The original timestamp survives
the re-curation, so provenance is preserved.

## Tooling on this machine

- **Stamp the root**: `~/go/bin/ots stamp <root-bytes-or-file>` →
  `<file>.ots` with pending calendar attestations.
- **Wait** ~hours for the calendar's commitment to be confirmed in
  Bitcoin.
- **Upgrade**: `~/go/bin/ots upgrade <file>.ots` → file now contains
  Bitcoin attestation.
- **Verify**: `~/go/bin/ots verify <file>.ots` (Go) or `ots verify`
  from the Python client (in a project venv).
- **Per-leaf extension**: no first-class CLI yet; use
  `python-opentimestamps` in a venv plus an extension script (see
  `~/work/nostr-archive/pipeline/nap/ots.py` for a working
  reference).

## What the OTS proof does NOT prove

- **It attests the bytes.** If a leaf's content matches the digest, the
  digest is in the bundle root, and the bundle root is in a Bitcoin
  block header, then those bytes existed by that block's timestamp.
- **It does not attest signatures.** A Nostr event's signature is
  produced separately and could be re-signed later over the same
  Merkle root. If you need to time-bind a signature, stamp the
  signed event's canonical serialization separately.
- **It does not attest intent or framing.** The OTS proof says the
  bytes existed, not that any descriptive metadata about them is true.

## Related concepts in this workspace

- [`docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) — for the *why* of decoupling content from
  storage; this primitive extends the same idea to time-attestation.
- [`docs/sources/blossom.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md) — natural pairing for content layer (sha256-
  addressed blobs).
- [`docs/sources/nips-readme-kinds.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md) → kind 1040 (NIP-03,
  OpenTimestamps Attestations for Events) — the kind that exists for
  attaching an OTS proof to a Nostr event id; useful as the publication
  channel once you've derived per-leaf proofs.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nip-01.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/nip-01.md` · snapshot 2026-10-10

NIP-01
======

Basic protocol flow description
-------------------------------

`draft` `mandatory` `relay`

This NIP defines the basic protocol that should be implemented by everybody. New NIPs may add new optional (or mandatory) fields and messages and features to the structures and flows described here.

## Events and signatures

Each user has a keypair. Signatures, public key, and encodings are done according to the [Schnorr signatures standard for the curve `secp256k1`](https://bips.xyz/340).

The only object type that exists is the `event`, which has the following format on the wire:

```yaml
{
  "id": <32-bytes lowercase hex-encoded sha256 of the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <unix timestamp in seconds>,
  "kind": <integer between 0 and 65535>,
  "tags": [
    [<arbitrary string>...],
    // ...
  ],
  "content": <arbitrary string>,
  "sig": <64-bytes lowercase hex of the signature of the sha256 hash of the serialized event data, which is the same as the "id" field>
}
```

To obtain the `event.id`, we `sha256` the serialized event. The serialization is done over the UTF-8 JSON-serialized string (which is described below) of the following structure:

```
[
  0,
  <pubkey, as a lowercase hex string>,
  <created_at, as a number>,
  <kind, as a number>,
  <tags, as an array of arrays of non-null strings>,
  <content, as a string>
]
```

To prevent implementation differences from creating a different event ID for the same event, the following rules MUST be followed while serializing:
- UTF-8 should be used for encoding.
- Whitespace, line breaks or other unnecessary formatting should not be included in the output JSON.
- The following characters in the content field must be escaped as shown, and all other characters must be included verbatim:
  - A line break (`0x0A`), use `\n`
  - A double quote (`0x22`), use `\"`
  - A backslash (`0x5C`), use `\\`
  - A carriage return (`0x0D`), use `\r`
  - A tab character (`0x09`), use `\t`
  - A backspace, (`0x08`), use `\b`
  - A form feed, (`0x0C`), use `\f`

### Tags

Each tag is an array of one or more strings, with some conventions around them. Take a look at the example below:

```yaml
{
  "tags": [
    ["e", "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36", "wss://nostr.example.com"],
    ["p", "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca"],
    ["a", "30023:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:abcd", "wss://nostr.example.com"],
    ["alt", "reply"],
    // ...
  ],
  // ...
}
```

The first element of the tag array is referred to as the tag _name_ or _key_ and the second as the tag _value_. So we can safely say that the event above has an `e` tag set to `"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"`, an `alt` tag set to `"reply"` and so on. All elements after the second do not have a conventional name.

This NIP defines 3 standard tags that can be used across all event kinds with the same meaning. They are as follows:

- The `e` tag, used to refer to an event: `["e", <32-bytes lowercase hex of the id of another event>, <recommended relay URL, optional>, <32-bytes lowercase hex of the author's pubkey, optional>]`
- The `p` tag, used to refer to another user: `["p", <32-bytes lowercase hex of a pubkey>, <recommended relay URL, optional>]`
- The `a` tag, used to refer to an addressable or replaceable event
    - for an addressable event: `["a", "<kind integer>:<32-bytes lowercase hex of a pubkey>:<d tag value>", <recommended relay URL, optional>]`
    - for a normal replaceable event: `["a", "<kind integer>:<32-bytes lowercase hex of a pubkey>:", <recommended relay URL, optional>]` (note: include the trailing colon)

As a convention, all single-letter (only english alphabet letters: a-z, A-Z) key tags are expected to be indexed by relays, such that it is possible, for example, to query or subscribe to events that reference the event `"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"` by using the `{"#e": ["5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"]}` filter. Only the first value in any given tag is indexed.

### Kinds

Kinds specify how clients should interpret the meaning of each event and the other fields of each event (e.g. an `"r"` tag may have a meaning in an event of kind 1 and an entirely different meaning in an event of kind 10002). Each NIP may define the meaning of a set of kinds that weren't defined elsewhere. NIP-10, for instance, specifies the `kind:1` text note for social media applications.

This NIP defines one basic kind:

- `0`: **user metadata**: the `content` is set to a stringified JSON object `{name: <nickname or full name>, about: <short bio>, picture: <url of the image>}` describing the user who created the event. Extra metadata fields may be set. A relay may delete older events once it gets a new one for the same pubkey.

And also a convention for kind ranges that allow for easier experimentation and flexibility of relay implementation:

- for kind `n` such that `1000 <= n < 10000 || 4 <= n < 45 || n == 1 || n == 2`, events are **regular**, which means they're all expected to be stored by relays.
- for kind `n` such that `10000 <= n < 20000 || n == 0 || n == 3`, events are **replaceable**, which means that, for each combination of `pubkey` and `kind`, only the latest event MUST be stored by relays, older versions MAY be discarded.
- for kind `n` such that `20000 <= n < 30000`, events are **ephemeral**, which means they are not expected to be stored by relays.
- for kind `n` such that `30000 <= n < 40000`, events are **addressable** by their `kind`, `pubkey` and `d` tag value -- which means that, for each combination of `kind`, `pubkey` and the `d` tag value, only the latest event MUST be stored by relays, older versions MAY be discarded.

In case of replaceable events with the same timestamp, the event with the lowest id (first in lexical order) should be retained, and the other discarded.

When answering to `REQ` messages for replaceable events such as `{"kinds":[0],"authors":[<hex-key>]}`, even if the relay has more than one version stored, it SHOULD return just the latest one.

These are just conventions and relay implementations may differ.

## Communication between clients and relays

Relays expose a websocket endpoint to which clients can connect. Clients SHOULD open a single websocket connection to each relay and use it for all their subscriptions. Relays MAY limit number of connections from specific IP/client/etc.

Relays MUST only accept connections to a single endpoint when additional path segments do not influence its behavior.

### From client to relay: sending events and creating subscriptions

Clients can send 3 types of messages, which must be JSON arrays, according to the following patterns:

  * `["EVENT", <event JSON as defined above>]`, used to publish events.
  * `["REQ", <subscription_id>, <filters1>, <filters2>, ...]`, used to request events and subscribe to new updates.
  * `["CLOSE", <subscription_id>]`, used to stop previous subscriptions.

`<subscription_id>` is an arbitrary, non-empty string of max length 64 chars. It represents a subscription per connection. Relays MUST manage `<subscription_id>`s independently for each WebSocket connection. `<subscription_id>`s are not guaranteed to be globally unique.

`<filtersX>` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes:

```yaml
{
  "ids": <a list of event ids>,
  "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>,
  "kinds": <a list of a kind numbers>,
  "#<single-letter (a-zA-Z)>": <a list of tag values, for #e — a list of event ids, for #p — a list of pubkeys, etc.>,
  "since": <an integer unix timestamp in seconds. Events must have a created_at >= to this to pass>,
  "until": <an integer unix timestamp in seconds. Events must have a created_at <= to this to pass>,
  "limit": <maximum number of events relays SHOULD return in the initial query>
}
```

Upon receiving a `REQ` message, the relay SHOULD return events that match the filter. Any new events it receives SHOULD be sent to that same websocket until the connection is closed, a `CLOSE` event is received with the same `<subscription_id>`, or a new `REQ` is sent using the same `<subscription_id>` (in which case a new subscription is created, replacing the old one).

Filter attributes containing lists (`ids`, `authors`, `kinds` and tag filters like `#e`) are JSON arrays with one or more values. At least one of the arrays' values must match the relevant field in an event for the condition to be considered a match. For scalar event attributes such as `authors` and `kind`, the attribute from the event must be contained in the filter list. In the case of tag attributes such as `#e`, for which an event may have multiple values, the event and filter condition values must have at least one item in common.

The `ids`, `authors`, `#e` and `#p` filter lists MUST contain exact 64-character lowercase hex values.

The `since` and `until` properties can be used to specify the time range of events returned in the subscription. If a filter includes the `since` property, events with `created_at` greater than or equal to `since` are considered to match the filter. The `until` property is similar except that `created_at` must be less than or equal to `until`. In short, an event matches a filter if `since <= created_at <= until` holds.

All conditions of a filter that are specified must match for an event for it to pass the filter, i.e., multiple conditions are interpreted as `&&` conditions.

A `REQ` message may contain multiple filters. In this case, events that match any of the filters are to be returned, i.e., multiple filters are to be interpreted as `||` conditions.

The `limit` property of a filter is only valid for the initial query and MUST be ignored afterwards. When `limit: n` is present it is assumed that the events returned in the initial query will be the last `n` events ordered by the `created_at`. Newer events should appear first, and in the case of ties the event with the lowest id (first in lexical order) should be first. Relays SHOULD use the `limit` value to guide how many events are returned in the initial response. Returning fewer events is acceptable, but returning (much) more should be avoided to prevent overwhelming clients.

When `limit` is zero, the relay MUST NOT return stored events for that filter. After the initial queries for all filters are complete, the relay MUST send `EOSE` and MUST keep the subscription active for newly received matching events.

### From relay to client: sending events and notices

Relays can send 5 types of messages, which must also be JSON arrays, according to the following patterns:

  * `["EVENT", <subscription_id>, <event JSON as defined above>]`, used to send events requested by clients.
  * `["OK", <event_id>, <true|false>, <message>]`, used to indicate acceptance or denial of an `EVENT` message.
  * `["EOSE", <subscription_id>]`, used to indicate the _end of stored events_ and the beginning of events newly received in real-time.
  * `["CLOSED", <subscription_id>, <message>]`, used to indicate that a subscription was ended on the server side.
  * `["NOTICE", <message>]`, used to send human-readable error messages or other things to clients.

This NIP defines no rules for how `NOTICE` messages should be sent or treated.

- `EVENT` messages MUST be sent only with a subscription ID related to a subscription previously initiated by the client (using the `REQ` message above).
- `OK` messages MUST be sent in response to `EVENT` messages received from clients, they must have the 3rd parameter set to `true` when an event has been accepted by the relay, `false` otherwise. The 4th parameter MUST always be present, but MAY be an empty string when the 3rd is `true`, otherwise it MUST be a string formed by a machine-readable single-word prefix followed by a `:` and then a human-readable message. Some examples:
  * `["OK", "b1a649ebe8...", true, ""]`
  * `["OK", "b1a649ebe8...", true, "pow: difficulty 25>=24"]`
  * `["OK", "b1a649ebe8...", true, "duplicate: already have this event"]`
  * `["OK", "b1a649ebe8...", false, "blocked: you are banned from posting here"]`
  * `["OK", "b1a649ebe8...", false, "blocked: please register your pubkey at https://my-expensive-relay.example.com"]`
  * `["OK", "b1a649ebe8...", false, "rate-limited: slow down there chief"]`
  * `["OK", "b1a649ebe8...", false, "invalid: event creation date is too far off from the current time"]`
  * `["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"]`
  * `["OK", "b1a649ebe8...", false, "restricted: not allowed to write."]`
  * `["OK", "b1a649ebe8...", false, "error: could not connect to the database"]`
  * `["OK", "b1a649ebe8...", false, "mute: no one was listening to your ephemeral event and it wasn't handled in any way, it was ignored"]`
- `CLOSED` messages MUST be sent in response to a `REQ` when the relay refuses to fulfill it. It can also be sent when a relay decides to kill a subscription on its side before a client has disconnected or sent a `CLOSE`. This message uses the same pattern of `OK` messages with the machine-readable prefix and human-readable message. Some examples:
  * `["CLOSED", "sub1", "unsupported: filter contains unknown elements"]`
  * `["CLOSED", "sub1", "error: could not connect to the database"]`
  * `["CLOSED", "sub1", "error: shutting down idle subscription"]`
- The standardized machine-readable prefixes for `OK` and `CLOSED` are: `duplicate`, `pow`, `blocked`, `rate-limited`, `invalid`, `restricted`, `mute` and `error` for when none of that fits.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nips-readme-kinds.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/nips-readme-kinds.md` · snapshot 2026-10-10

# NIPs registry — kind table and message types

> Vendored verbatim from <https://github.com/nostr-protocol/nips/blob/master/README.md>
> at the time of 2026-09-21T14:26:31+02:00. Refresh with the snippet in docs/README.md.
> Upstream dropped its 'Standardized Tags' table; the common-tag list now lives in
> docs/kind-cheatsheet.md §4.

## Event Kinds

This table is not exhaustive. For a machine-readable registry of all known event kinds prefer <https://github.com/nostr-protocol/registry-of-kinds> (or alternative registries following the same YAML schema).

| kind          | description                     | NIP                                    |
| ------------- | ------------------------------- | -------------------------------------- |
| `0`           | User Metadata                   | 01                            |
| `1`           | Short Text Note                 | 10                            |
| `3`           | Follows                         | 02                            |
| `4`           | Encrypted Direct Messages       | 04                            |
| `5`           | Event Deletion Request          | 09                            |
| `6`           | Repost                          | 18                            |
| `7`           | Reaction                        | 25                            |
| `8`           | Badge Award                     | 58                            |
| `9`           | Chat Message                    | C7                            |
| `11`          | Thread                          | 7D                            |
| `13`          | Seal                            | 59                            |
| `14`          | Direct Message                  | 17                            |
| `15`          | File Message                    | 17                            |
| `16`          | Generic Repost                  | 18                            |
| `17`          | Reaction to a website           | 25                            |
| `20`          | Picture                         | 68                            |
| `21`          | Video Event                     | 71                            |
| `22`          | Short-form Portrait Video Event | 71                            |
| `24`          | Public Message                  | A4                            |
| `30`          | internal reference              | [NKBIP-03]                             |
| `31`          | external web reference          | [NKBIP-03]                             |
| `32`          | hardcopy reference              | [NKBIP-03]                             |
| `33`          | prompt reference                | [NKBIP-03]                             |
| `40`          | Channel Creation                | 28                            |
| `41`          | Channel Metadata                | 28                            |
| `42`          | Channel Message                 | 28                            |
| `43`          | Channel Hide Message            | 28                            |
| `44`          | Channel Mute User               | 28                            |
| `54`          | Podcast Episode                 | F4                            |
| `62`          | Request to Vanish               | 62                            |
| `64`          | Chess (PGN)                     | 64                            |
| `78`          | Application-specific Data       | 78                            |
| `443`         | KeyPackage                      | [Marmot][marmot]                       |
| `444`         | Welcome Message                 | [Marmot][marmot]                       |
| `445`         | Group Event                     | [Marmot][marmot]                       |
| `818`         | Merge Requests                  | 54                            |
| `1018`        | Poll Response                   | 88                            |
| `1021`        | Bid                             | 15                            |
| `1022`        | Bid confirmation                | 15                            |
| `1234`        | Draft Checkpoint                | 37                            |
| `1040`        | OpenTimestamps                  | 03                            |
| `1059`        | Gift Wrap                       | 59                            |
| `1063`        | File Metadata                   | 94                            |
| `1068`        | Poll                            | 88                            |
| `1111`        | Comment                         | 22                            |
| `1222`        | Voice Message                   | A0                            |
| `1244`        | Voice Message Comment           | A0                            |
| `1311`        | Live Chat Message               | 53                            |
| `1337`        | Code Snippet                    | C0                            |
| `1617`        | Patches                         | 34                            |
| `1618`        | Pull Requests                   | 34                            |
| `1619`        | Pull Request Updates            | 34                            |
| `1621`        | Issues                          | 34                            |
| `1622`        | Git Replies (deprecated)        | 34                            |
| `1630`-`1633` | Status                          | 34                            |
| `1971`        | Problem Tracker                 | [nostrocket][nostrocket]               |
| `1984`        | Reporting                       | 56                            |
| `1985`        | Label                           | 32                            |
| `1987`        | AI Embeddings / Vector lists    | [NKBIP-02]                             |
| `2003`        | Torrent                         | 35                            |
| `2004`        | Torrent Comment                 | 35                            |
| `2022`        | Coinjoin Pool                   | [joinstr][joinstr]                     |
| `4550`        | Community Post Approval         | 72                            |
| `7374`        | Reserved Cashu Wallet Tokens    | 60                            |
| `7375`        | Cashu Wallet Tokens             | 60                            |
| `7376`        | Cashu Wallet History            | 60                            |
| `7516`        | Geocache log                    | CC                            |
| `7517`        | Geocache proof of find          | CC                            |
| `8000`        | Add User                        | 43                            |
| `8001`        | Remove User                     | 43                            |
| `9000`-`9030` | Group Control Events            | 29                            |
| `9041`        | Zap Goal                        | 75                            |
| `9321`        | Nutzap                          | 61                            |
| `9734`        | Zap Request                     | 57                            |
| `9735`        | Zap                             | 57                            |
| `9802`        | Highlights                      | 84                            |
| `10000`       | Mute list                       | 51                            |
| `10001`       | Pin list                        | 51                            |
| `10002`       | Relay List Metadata             | 65, 51               |
| `10003`       | Bookmark list                   | 51                            |
| `10004`       | Communities list                | 51                            |
| `10005`       | Public chats list               | 51                            |
| `10006`       | Blocked relays list             | 51                            |
| `10007`       | Search relays list              | 51                            |
| `10008`       | Profile Badges                  | 51, 58               |
| `10009`       | User groups                     | 51, 29               |
| `10011`       | External Identities             | 39                            |
| `10012`       | Favorite relays list            | 51                            |
| `10013`       | Private event relay list        | 37                            |
| `10015`       | Interests list                  | 51                            |
| `10019`       | Nutzap Mint Recommendation      | 61                            |
| `10020`       | Media follows                   | 51                            |
| `10030`       | User emoji list                 | 51                            |
| `10050`       | Relay list to receive DMs       | 51, 17               |
| `10051`       | KeyPackage Relays List          | [Marmot][marmot]                       |
| `10054`       | Favorite podcasts list          | 51                            |
| `10063`       | User server list                | B7                            |
| `10064`       | Authored podcasts list          | 51                            |
| `10096`       | File storage server list        | 96 (deprecated)               |
| `10133`       | Payment Targets                 | A3                            |
| `10154`       | Podcast Metadata                | F4                            |
| `10166`       | Relay Monitor Announcement      | 66                            |
| `10312`       | Room Presence                   | 53                            |
| `13194`       | Wallet Info                     | 47                            |
| `13534`       | Membership Lists                | 43                            |
| `5128`        | nsite manifest snapshot         | 5A                            |
| `15128`       | Root nsite manifest             | 5A                            |
| `17375`       | Cashu Wallet Event              | 60                            |
| `22242`       | Client Authentication           | 42                            |
| `23194`       | Wallet Request                  | 47                            |
| `23195`       | Wallet Response                 | 47                            |
| `24133`       | Nostr Connect                   | 46                            |
| `24242`       | Blobs stored on mediaservers    | B7                            |
| `27235`       | HTTP Auth                       | 98                            |
| `28934`       | Join Request                    | 43                            |
| `28935`       | Invite Request                  | 43                            |
| `28936`       | Leave Request                   | 43                            |
| `30000`       | Follow sets                     | 51                            |
| `30002`       | Relay sets                      | 51                            |
| `30003`       | Bookmark sets                   | 51                            |
| `30004`       | Curation sets                   | 51                            |
| `30005`       | Video sets                      | 51                            |
| `30006`       | Picture sets                    | 51                            |
| `30007`       | Kind mute sets                  | 51                            |
| `30008`       | Badge sets                      | 51, 58               |
| `30009`       | Badge Definition                | 58                            |
| `30015`       | Interest sets                   | 51                            |
| `30017`       | Create or update a stall        | 15                            |
| `30018`       | Create or update a product      | 15                            |
| `30019`       | Marketplace UI/UX               | 15                            |
| `30020`       | Product sold as an auction      | 15                            |
| `30023`       | Long-form Content               | 23                            |
| `30024`       | Draft Long-form Content         | 23                            |
| `30030`       | Emoji sets                      | 51                            |
| `30040`       | Curated Publication Index       | [NKBIP-01]                             |
| `30041`       | Curated Publication Content     | [NKBIP-01]                             |
| `30063`       | Release artifact sets           | 51                            |
| `30078`       | Application-specific Data       | 78                            |
| `30166`       | Relay Discovery                 | 66                            |
| `30267`       | App curation sets               | 51                            |
| `30311`       | Live Event                      | 53                            |
| `30312`       | Interactive Room                | 53                            |
| `30313`       | Conference Event                | 53                            |
| `30315`       | User Statuses                   | 38                            |
| `30382`       | User Trusted Assertion          | 85                            |
| `30383`       | Event Trusted Assertion         | 85                            |
| `30384`       | Addressable Trusted Assertion   | 85                            |
| `30402`       | Classified Listing              | 99                            |
| `30403`       | Draft Classified Listing        | 99                            |
| `30617`       | Repository announcements        | 34                            |
| `30618`       | Repository state announcements  | 34                            |
| `30818`       | Wiki article                    | 54                            |
| `30819`       | Redirects                       | 54                            |
| `31234`       | Draft Event                     | 37                            |
| `31922`       | Date-Based Calendar Event       | 52                            |
| `31923`       | Time-Based Calendar Event       | 52                            |
| `31924`       | Calendar                        | 52                            |
| `31925`       | Calendar Event RSVP             | 52                            |
| `31989`       | Handler recommendation          | 89                            |
| `31990`       | Handler information             | 89                            |
| `32267`       | Software Application            |                                        |
| `34235`       | Addressable Video Event         | 71                            |
| `34236`       | Addressable Short Video Event   | 71                            |
| `34550`       | Community Definition            | 72                            |
| `34128`       | Legacy nsite manifest           | 5A (deprecated)               |
| `35128`       | Named nsite manifest            | 5A                            |
| `38172`       | Cashu Mint Announcement         | 87                            |
| `38173`       | Fedimint Announcement           | 87                            |
| `37516`       | Geocache Listing                | CC                            |
| `37517`       | Geocache Curation List          | CC                            |
| `38383`       | Peer-to-peer Order events       | 69                            |
| `39000-9`     | Group metadata events           | 29                            |
| `39089`       | Starter packs                   | 51                            |
| `39092`       | Media starter packs             | 51                            |
| `39701`       | Web bookmarks                   | B0                            |

[nostrocket]: https://github.com/nostrocket/NIPS/blob/main/Problems.md
[joinstr]: https://gitlab.com/1440000bytes/joinstr/-/blob/main/NIP.md
[NKBIP-01]: https://wikistr.com/nkbip-01*fd208ee8c8f283780a9552896e4823cc9dc6bfd442063889577106940fd927c1
[NKBIP-02]: https://wikistr.com/nkbip-02*fd208ee8c8f283780a9552896e4823cc9dc6bfd442063889577106940fd927c1
[NKBIP-03]: https://wikistr.com/nkbip-03*fd208ee8c8f283780a9552896e4823cc9dc6bfd442063889577106940fd927c1
[marmot]: https://github.com/marmot-protocol/marmot


## Message types

### Client to Relay

| type    | description                                         | NIP         |
| ------- | --------------------------------------------------- | ----------- |
| `EVENT` | used to publish events                              | 01 |
| `REQ`   | used to request events and subscribe to new updates | 01 |
| `CLOSE` | used to stop previous subscriptions                 | 01 |
| `AUTH`  | used to send authentication events                  | 42 |
| `COUNT` | used to request event counts                        | 45 |

### Relay to Client

| type     | description                                             | NIP         |
| -------- | ------------------------------------------------------- | ----------- |
| `EOSE`   | used to notify clients all stored events have been sent | 01 |
| `EVENT`  | used to send events requested to clients                | 01 |
| `NOTICE` | used to send human-readable messages to clients         | 01 |
| `OK`     | used to notify clients if an EVENT was successful       | 01 |
| `CLOSED` | used to notify clients that a REQ was ended and why     | 01 |
| `AUTH`   | used to send authentication challenges                  | 42 |
| `COUNT`  | used to send requested event counts to clients          | 45 |



=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/outbox-model.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/outbox-model.md` · snapshot 2026-10-10

# Outbox model — references and condensed rules

> Vendored summary + canonical links. The mechanics are simple enough to
> codify here directly.

## Canonical sources

- **NIP-65** — Relay List Metadata (kind 10002):
  <https://github.com/nostr-protocol/nips/blob/master/65.md>
- **Nostrify** — "The Outbox Model": <https://nostrify.dev/relay/outbox>
- **whynostr.org** — "What is the Outbox Model?":
  <https://www.whynostr.org/post/8yjqxm4sky-tauwjoflxs/>
- **Mike Dilger's gossip client** — original implementation:
  <https://github.com/mikedilger/gossip>
- **NDK outbox docs** — <https://github.com/nostr-dev-kit/ndk> (the JS library
  in this workspace's `sdk/` already implements outbox under the hood)

## The mechanics — condensed

A **kind 10002** event from a user contains `r` tags. Each `r` tag has either
no second value (relay used for both reading and writing), or one of `read` /
`write`:

```json
{
  "kind": 10002,
  "tags": [
    ["r", "wss://relay.damus.io"],
    ["r", "wss://nos.lol", "write"],
    ["r", "wss://relay.nostr.band", "read"]
  ],
  "content": ""
}
```

Terminology, post NIP-65 finalization:

| Tag flag | Modern name | Use |
|---|---|---|
| `write` (or unflagged) | **OUTBOX** | where this user *publishes* their events |
| `read` (or unflagged) | **INBOX** | where this user *expects to receive* DMs and mentions |

## Routing rules that fall out

- **Reading someone's posts** → query their **OUTBOX** relays (typically pick
  2–3 of them, not all).
- **Sending a DM (NIP-17 / NIP-44 / NIP-59)** → publish to the recipient's
  **INBOX** only. Also publish to your own INBOX so you have a record.
- **Posting your own content publicly** → publish to **all** of your OUTBOX
  relays + the INBOX relays of every user you `p`-tagged or mentioned.
- **Querying a user's profile / follow list / relay list** → their OUTBOX.
- **Anonymous browsing / cold start** → general-purpose relays
  (`wss://relay.damus.io`, `wss://nos.lol`) + index relays
  (`wss://purplepag.es`, `wss://user.kindpag.es`; `relay.nostr.band` was
  unreachable as of 2026-09).

## Why outbox > fixed-list (for general social)

A fixed-list client publishes to N popular relays and reads from the same N.
Result: those N relays become de facto centralization points; if they drop
you, your followers can't see you. With outbox, *each user is sovereign over
their own distribution*. Censorship-resistance comes from the routing being
declared by the author, not the platform.

## What outbox does NOT solve (be explicit in your design)

- **Communities, group chats, topical feeds** — those want a community/topic
  relay, not the user's outbox. NIP-29, NIP-72.
- **DMs** — go to inbox, not outbox.
- **Search / full-text indexing** — needs a search relay
  (`search.nos.today`; NIP-50. `relay.nostr.band` was unreachable as of 2026-09).
- **Discovery of users you don't follow yet** — outbox is read-side only.
  You need gossip-flavored hints (relay hints in `e`/`p`/`a` tags, NIP-05,
  `nprofile`).
- **Per-event routing for non-broadcast kinds** — anything that is not a
  general-purpose social broadcast probably wants a deliberate routing choice.

## Practical implementation hints

- Maintain a routing table: `pubkey → [outbox relays]`. NDK calls this an
  "outbox database." Update lazily as you encounter new authors.
- Cap outbox per author at 2–4 relays per query. More is wasteful; fewer is
  fragile.
- Treat kind 10002 as **replaceable** — only the latest matters.
- A user with no kind 10002 → fall back to general-purpose relays + any relay
  hints you have for them.

## Gossip — the superset

Gossip = outbox + every other discoverable hint:

- relay hints in `e` tags (`["e", "<id>", "<relay-url>"]`),
- relay hints in `p` tags (`["p", "<pubkey>", "<relay-url>"]`),
- relay hints in `a` tags for addressable references,
- `nprofile` / `nevent` URIs that bake in relays,
- NIP-05 metadata that names relays,
- observed presence of the author in replies on relays you already speak to.

The Gossip client is the canonical reference; NDK and Coracle implement
gossip-flavored outbox by default.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/blossom.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/blossom.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.

# Blossom — binary blob storage for Nostr

**Spec home:** <https://github.com/hzrd149/blossom>
**Status:** running locally as part of the ngit-relay container at
`http://localhost:8081`. See `configs/local-services.json` → `always_on.ngit_relay_container.services.blossom`
for the full descriptor.

## What Blossom is

Blossom = "Blobs Stored Simply on Mediaservers." A protocol for storing and
serving arbitrary binary blobs, addressed by their **sha256**, with **Nostr
keys for authentication**. Specs are called BUDs ("Blossom Upgrade Documents").

The blob — not the URL — is the identity. The same blob is the same on every
server, and any server can serve it. Mirroring is a sha256 copy, no rewriting
of references.

## Why it pairs with Nostr

Nostr events carry `e`, `p`, `a` references — pointers into the event graph.
Blossom plays the same role for **content-addressed binary data**: an image,
a video, an audio file, a tarball, anything. A Nostr event with a
`url` / `imeta` tag pointing at `https://<host>/<sha256>` is a Blossom
reference.

The clean division of labor:
- **Relays** store events (signed JSON, small, structured).
- **Blossom servers** store blobs (binary, large, unstructured), keyed by hash.
- **Pubkeys** authenticate writes to both.

## BUD-01 — server requirements (the surface area)

| Method | Path | Purpose | Auth |
|---|---|---|---|
| `GET`    | `/<sha256>`                | fetch blob bytes               | none |
| `HEAD`   | `/<sha256>`                | check existence + size         | none |
| `PUT`    | `/upload`                  | upload a blob                  | kind:24242 event in `Authorization: Nostr <base64>` header |
| `GET`    | `/list/<pubkey-hex>`       | list blobs uploaded by pubkey  | none |
| `DELETE` | `/<sha256>`                | delete a blob                  | kind:24242 event |

The auth event (kind 24242) carries:
- `t` tag = the action (`upload`, `delete`, `list`, etc.)
- `x` tag = the sha256 of the blob being acted on (for upload/delete)
- `expiration` tag = unix timestamp after which the auth is no longer valid

Spec: <https://github.com/hzrd149/blossom/blob/master/buds/01.md>

## The BUDs you will actually meet

| BUD | What |
|---|---|
| **01** | Server requirements + blob retrieval (`GET`/`HEAD /<sha256>`) |
| **02** | Upload and management (`PUT /upload`, `GET /list/<pubkey>`, `DELETE /<sha256>`). `/list` returns `{ url, sha256, size, type, uploaded }` per blob. |
| **03** | **User Server List** — the user's kind **10063**, `["server", "https://…"]` tags. This is how a client (or an nsite gateway) discovers where someone's blobs live. |
| **04** | **Mirroring** — `PUT /mirror`; ask one server to pull a blob from another by URL. Cheap redundancy, same sha256. |
| **05** | Media optimisation (`PUT /media`) — server-side transcode; returns a *different* sha256. |
| **06** | Upload requirements (`HEAD /upload`) — ask before you send, so a server can refuse on size/type without the body. |
| **09** | Blob report |

Note BUD-03 is the *server list*, not mirroring — a common mix-up, and it
matters because 10063 is what the nsite gateway reads.

## How to use the local Blossom server

### From a shell with `nak`

```bash
NSEC=$(jq -r .nsec /dev/shm/nostr-dev-session/keys.json)   # ephemeral key

# upload
nak blossom --sec "$NSEC" -s http://localhost:8081 upload ./some-file.png

# list our blobs
nak blossom --sec "$NSEC" -s http://localhost:8081 list

# fetch (no auth needed)
curl -s http://localhost:8081/<sha256> -o some-file.png

# delete
nak blossom --sec "$NSEC" -s http://localhost:8081 delete <sha256>
```

### From TypeScript

Working example: `sdk/examples/blossom-upload.ts`. Run with:

```bash
cd ~/Documents/nostr-dev/sdk
NOSTR_SECRET_KEY=$(jq -r .nsec /dev/shm/nostr-dev-session/keys.json) \
  npm run blossom-upload -- ./some-file.png
```

It computes the sha256, builds and signs a kind:24242 auth event, PUTs the
blob, then verifies via HEAD + GET + list.

## Public servers: what each one actually does

**Blossom servers are not interchangeable.** They differ on which MIME types
they accept and — critically — on whether they preserve the `Content-Type` you
uploaded with. That type is recorded at upload, keyed by sha256, and is what an
nsite gateway forwards to the browser, so a server that rewrites it silently
breaks stylesheets and service workers.

Measured 2026-09-21 by uploading the same probe files from a throwaway key and
reading back what each server serves.

| Server | Accepts | Content-Type fidelity | Notes |
|---|---|---|---|
| **`https://nostr.download`** | everything probed | **faithful** — `text/css`, `text/javascript`, `application/wasm` all preserved | **The default first server for anything web.** Serves 200 direct. |
| `https://blossom.primal.net` | everything probed | **rewrites `text/*` → `text/plain`**; `application/*` passes through | Fine as an availability mirror, never as the type-of-record. 302-redirects blob GETs. |
| **`https://azzamo.media`** (= `https://blossom.azzamo.media`) | **media only** | **faithful** (`image/png` preserved) | See below. |
| `https://blossom.band` | — | — | Rejects fresh-key uploads outright: 400 on text, 415 on wasm. |
| `https://cdn.satellite.earth` | — | — | **500 on upload and GET.** Dead. |
| `https://inner.sebastix.social` | (invite) | faithful | API is at the **root** path; `…/blossom/` is an HTML catch-all that 200s for everything and false-positives every dedup check. |
| `http://localhost:8081` (ngit-relay) | everything probed | **faithful** | The local server. 100 MB/file, 50 GB total. |

### `azzamo.media` — the owner's media server

`azzamo.media` and `blossom.azzamo.media` are the same host. It self-describes
as *Azzamo Blossom 1.0.0*, BUD-01/02/04/05/06/09, `upload`/`media`/`mirror`
enabled, `discovery` off. It is **first in the owner's kind 10063**
(`npub1t6jxfqz9…`, published by Amethyst), which is what their phone uploads
through.

Two things to know before reaching for it:

1. **Uploads are open to any key**, not just the owner's — a throwaway key was
   accepted. (Contrast `relay.azzamo.net`, which *is* `payment_required` +
   `restricted_writes`. The Blossom side is not gated the same way.) So
   "available via the Constant keypair" is true, and it is also available via
   any other key you sign with.
2. **It is a media server and refuses everything else**, by MIME, with HTTP 415:

   | Probe | Result |
   |---|---|
   | `.png` | **accepted**, served as `image/png` |
   | `.html` | 415 — "MIME type text/html is not allowed for security reasons" |
   | `.js` | 415 — "MIME type text/javascript is not allowed for security reasons" |
   | `.css` | 415 — "MIME type text/css is not supported" |
   | `.txt` | 415 — "MIME type text/plain is not supported" |
   | `.wasm` | 415 — "MIME type application/wasm is not supported" |

**So: use `azzamo.media` for owner-signed media** — images, video, audio, the
things kind 10063 exists for, and the side-channel's file drops. **Never list
it as an nsite `server`**: an nsite is mostly HTML/CSS/JS/wasm and every one of
those uploads will 415. For nsites the list stays
`nostr.download` first, `blossom.primal.net` second — see
[`../patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) §4.

> **Stale entry in the owner's live 10063.** It lists
> `blossom.azzamo.media/`, then `cdn.satellite.earth/`, then
> `blossom.primal.net`. The middle one returns 500 on everything — a dead
> fallback in a live media list. Worth republishing that 10063 from Amethyst
> without it. (Do **not** rewrite it with tooling — `nsyte --publish-server-list`
> and friends would clobber it; see [`../patterns/nsite-publishing.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/nsite-publishing.md) §3.)

## Quirk to know

The upload response from the local Blossom server returns
`"url":"http://localhost:3334/<sha256>"` — that's the **internal khatru port**
inside the container, not the external nginx port. Don't follow that URL;
use your configured base URL (`http://localhost:8081`) for subsequent
GET/HEAD/DELETE. The TS example handles this correctly by computing the
sha256 client-side and using the configured server URL.

## Limits (configured in `repos/ngit-relay/.env`)

```
NGIT_BLOSSOM_MAX_FILE_SIZE_MB=100
NGIT_BLOSSOM_MAX_CAPACITY_GB=50
```

`NGIT_OWNER_NPUB` in the same file is treated as the privileged owner whose
limits don't apply. By default it's set to a placeholder npub
(`npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr`). If you
want the workspace's ephemeral session key to be the owner, edit `.env` and
restart with `sudo docker compose up -d`. Don't bother — for local dev the
default 100MB / 50GB caps are plenty.

## When to use Blossom (vs alternatives)

- **Use Blossom when**: you need to attach binary content (images, video,
  files, archives, blobs) to Nostr events and want the references to be
  content-addressed and mirrorable across servers without breaking links.
- **Use a CDN / object store when**: the binary content has nothing to do
  with Nostr identity (you're just hosting static assets for a web app).
- **Use IPFS when**: you specifically want a global content-addressed
  network with active replication and existing tooling. Blossom is
  intentionally simpler — sha256 + HTTP, no DHT.

## Related work and clients

- **hzrd149's `blossom-server`** (TypeScript reference impl): <https://github.com/hzrd149/blossom-server>
- **`blossom-audit`** — audit a server's BUD compliance:
  `npx blossom-audit audit http://localhost:8081 bitcoin --sec <nsec>`
- **`bloss`** (Go), **`blossom-server-rs`** (Rust) — alternative implementations
- Most modern Nostr clients (Amethyst, Damus, Coracle) already speak Blossom
  for image/video uploads.

## How this informs design

When designing a Nostr feature that involves binary content:

1. **Don't store binary data inside events.** Events are gossiped, indexed,
   replicated — fat events are expensive everywhere.
2. **Store the binary in Blossom; reference it by sha256 in the event.**
3. **Publish to multiple Blossom servers** for redundancy; the sha256 stays
   the same so consumers can fall back from one server to another.
4. **Consider mirroring** (BUD-04) if you operate a relay — it's cheap to
   serve a blob you already have, and it improves the network's resilience.
5. **Pick the server for the content type.** Media → `azzamo.media` (the
   owner's) or `blossom.primal.net`. Anything a browser has to interpret —
   HTML, CSS, JS, wasm → `nostr.download` first, because it is the only public
   server measured to preserve those types faithfully.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/zapstore.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/zapstore.md` · snapshot 2026-10-10

# Source: Zapstore + NIP-82 (Software Applications)

> Reference layer for the protocol Zapstore implements. Primary implementation:
> [`github.com/zapstore`](https://github.com/zapstore). The spec is being
> codified as NIP-82 ([PR nostr-protocol/nips#1336](https://github.com/nostr-protocol/nips/pull/1336),
> in flight at the time of writing — 2026-05-12). Always cross-check the
> live `zsp` source if a tag or field disagrees with this summary.

## The model

Zapstore is **not a server**. It's a convention over three things every Nostr
client already has: addressable events, file blobs, and outbox-style relay
routing. A "published app" is:

- a **kind 32267** event (app metadata, replaceable by package id) signed by
  the publisher,
- one or more **kind 30063** events (one per release version, replaceable per
  `package_id@version`), each pointing at…
- one or more **kind 3063** events (per-binary metadata: hash, URL, size,
  cert), whose `url` tags resolve to **Blossom** blobs.

Discovery is just an `nostr+REQ` for `kind: 32267` with a tag filter. The
Zapstore app and `zapstore.dev` are *one client* over that data; anyone can
build another.

## Event kinds

### kind 32267 — Software Application (addressable, `d` = package id)

Required tags: `d` (package id, e.g. `com.example.app`), `name`, `icon` (URL).
Common tags emitted by `zsp` v0.4.10:

| Tag | Meaning |
|---|---|
| `d` | package id (e.g. `com.otsuite.lite.debug`) |
| `name`, `summary`, `icon` | display fields |
| `t` | topic/category (repeatable) |
| `repository` | URL or NIP-34 `naddr` to the source repo |
| `a` | full NIP-34 coordinate `30617:<pubkey>:<d>` for the repo announcement |
| `f` | platform/arch filter (`android-arm64-v8a`, `android-x86_64`, …) |
| `h` | platform-grouped hash (used by clients to detect changes across releases) |

`content` is the long description (markdown OK).

### kind 30063 — Software Release (addressable, `d` = `package_id@version`)

A *set* event in the NIP-51 sense. Links one or more kind-3063 assets that
together make up a release.

| Tag | Meaning |
|---|---|
| `d` | `<package_id>@<version>` |
| `i` | package id (so clients can filter releases for a given app) |
| `version` | semver string |
| `c` | channel (`main`, `beta`, `nightly`, `dev`) |
| `f` | arch filter (repeated per arch the release supports) |
| `e` | event id of each kind-3063 asset (with relay hint) |

### kind 30509 — NIP-C1 Cryptographic Identity Link (addressable, `d` = cert SHA-256)

Used by `zsp identity --link-key` to bind an APK signing certificate to a
Nostr identity. Clients that walk the kind 32267 → 30063 → 3063 chain compare
the 3063's `apk_certificate_hash` to the latest 30509 `d`-tag under the same
publisher pubkey — a mismatch signals a possible repo hijack.

| Tag | Meaning |
|---|---|
| `d` | SHA-256 of the certificate (DER form) |
| `signature` | RSA (or ECDSA, depending on the key) signature over the publisher's npub, signed by the APK signing key. The cryptographic proof of co-control. |
| `expiry` | Unix timestamp after which the proof is no longer considered valid. Default 1 year; tunable via `zsp identity --link-key-expiry`. |

### kind 3063 — Software Asset (regular, one per binary)

This is the **file-metadata** event. It is `zsp`'s own kind — *not* NIP-94's
kind 1063. The NIP-82 PR draft discussed 1063; the shipped `zsp` v0.4.10 uses
3063. If you only have the spec PR open, you'll be misled — check the wire.

| Tag | Meaning |
|---|---|
| `i` | package id |
| `x` | SHA-256 of the asset bytes (the Blossom address) |
| `url` | Blossom URL (`<server>/<sha256>`) |
| `m` | MIME (e.g. `application/vnd.android.package-archive`) |
| `size` | bytes |
| `f` | arch filter (one tag per arch in the binary; fat APKs get multiple) |
| `min_platform_version` / `target_platform_version` | Android min/target SDK |
| `filename`, `version_code`, `version` | display + ordering metadata |
| `apk_certificate_hash` | SHA-256 of the APK signing cert (used by NIP-C1) |

## Blossom usage

- Default upload target: `https://cdn.zapstore.dev`.
- Override: `BLOSSOM_URL=<server-base-url>` env var.
- The CLI uploads icons, screenshots, and the APK itself — anything the events
  reference by `url`. Blobs are content-addressed, so re-uploading an
  unchanged asset is a no-op.

## Relay usage

- Default publication target: `wss://relay.zapstore.dev`.
- Override: `RELAY_URLS=<comma-separated-list>` env var.
- `relay.zapstore.dev` enforces a **whitelist** on first-time publisher
  pubkeys. Either (a) commit a `zapstore.yaml` with the publisher pubkey at
  the root of the linked source repo so the relay can verify pubkey↔repo, or
  (b) accumulate prior reputation via their Vertex system.

## Signing

`zsp` reads the signer from `SIGN_WITH`. Supported forms:

| Value | Meaning |
|---|---|
| `nsec1…` | Raw nsec |
| `<hex>` | Raw hex private key |
| `bunker://<pubkey>?relay=…&secret=…` | NIP-46 remote signer |
| `browser` | NIP-07 (opens a localhost preview page that signs via your browser extension) |
| `npub1…` | Use the given identity for *preview only*; pairs with `--offline` |

## Cert linking — NIP-C1

`zsp identity --link-key key.p12` (or the interactive prompt on first
publish) produces a NIP-C1 proof that ties the **APK signing certificate** to
the **Nostr identity**. Clients use it to detect repository hijacks: a new
release signed by a different cert under the same npub flags as suspicious.

Skip with `--skip-certificate-linking` when:
- The cert is a debug keystore (the default Android debug cert is shared
  across many machines and effectively meaningless as a proof).
- You're producing a sandbox publish that won't be consumed by clients
  checking provenance.

For any release you intend to ship to the public Zapstore, **do** the linking
with the actual release keystore.

**Format note.** `zsp identity --link-key` accepts `.p12`/`.pfx`/`.pem`/`.crt`
directly. **`.jks` (Java KeyStore) needs a one-shot conversion first** —
`zsp` will error with a `keytool -importkeystore` command if you point it at
a JKS. Sample:

```bash
keytool -importkeystore -noprompt \
  -srckeystore release.jks   -srcstoretype JKS    -srcstorepass "$PW" -alias <key-alias> \
  -destkeystore release.p12  -deststoretype PKCS12 -deststorepass "$PW"
```

## CLI: `zsp`

```bash
go install github.com/zapstore/zsp@latest      # binary lands in ~/go/bin/
```

Modes:

| Invocation | Use |
|---|---|
| `zsp publish --wizard` | Interactive setup. Writes a `zapstore.yaml` for you. |
| `zsp publish zapstore.yaml` | Config-driven. The form to script against. |
| `zsp publish app.apk -r github.com/u/r` | Local APK + forge URL. `-r` does not accept `naddr`; use the yaml. |
| `zsp publish ... --offline` | Sign events without uploading or publishing. Events to stdout, upload manifest to stderr. **The standard dry-run.** |
| `zsp utils extract-apk app.apk` | Read-only: dump package id / version / cert / icon. |
| `zsp utils check-releases <src>` | Detect whether upstream has a newer version than what's published. |

## Links

- [`zapstore/zsp` README](https://github.com/zapstore/zsp) — canonical CLI
- [Zapstore publishing docs](https://zapstore.dev/docs/publish)
- [Zapstore FAQ](https://zapstore.dev/docs/faq)
- [NIP-82 PR (nostr-protocol/nips#1336)](https://github.com/nostr-protocol/nips/pull/1336)


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fips.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/fips.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.

# FIPS — Free Internetworking Peering System

**Spec home:** <https://fips.network>
**Source:** <https://github.com/jmcorgan/fips> (Rust, MIT)
**Local clone:** `~/Documents/nostr-dev/repos/fips/` (offline reference, gitignored from this repo)
**Local build:** binaries in `~/Documents/nostr-dev/repos/fips/target/release/` and copied to `~/.cargo/bin/{fips,fipsctl,fipstop,fips-gateway}` after `cargo install`.

## Why it lives in the workspace docs

FIPS is the cleanest worked example of the workspace's central design idea
(see [`docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §1) applied **outside** Nostr's own
event/relay surface. Where Nostr decouples authentication from event
storage, FIPS decouples it from **packet routing** — it uses the same
secp256k1 keypair, the same npub identity space, and the same Nostr-relay
infrastructure for peer discovery, then runs an encrypted mesh on top of
arbitrary transports.

If you're designing anything that wants "Nostr keypair as identity" but
isn't itself a Nostr application, FIPS is the most fully-developed
reference architecture available. The 13 design specs in
`repos/fips/docs/design/` are worth reading on their own as a layered
protocol design exercise.

## What FIPS is, in one paragraph

A distributed mesh-routing protocol where each node is identified by a
Nostr secp256k1 keypair. Nodes self-organize into a spanning tree across
**arbitrary transports** (UDP, TCP, Ethernet, Bluetooth, Tor, serial),
forwarding packets hop-by-hop with bloom-filter-aided routing. Every
packet gets dual encryption: hop-by-hop (Noise IK) at the link layer
and end-to-end (Noise XK) at the session layer. An IPv6 adapter maps
npubs to `fd00::/8` ULA addresses and serves a `.fips` DNS namespace, so
unmodified IP applications (curl, ssh, a Nostr relay, anything) work
over the mesh without modification.

## Layered design

| Layer | Protocol | Job |
|---|---|---|
| **Transport** | platform-specific (UDP / TCP / Ethernet / BLE / Tor / serial) | Uniform datagram interface over heterogeneous media |
| **Mesh (FMP)** | Noise IK + spanning tree | Peer authentication, hop-by-hop link encryption, forwarding |
| **Session (FSP)** | Noise XK | End-to-end encryption between any two nodes, session lifecycle |
| **IPv6 adapter** | TUN + DNS resolver | Maps npubs ↔ `fd00::/8` addresses; `.fips` DNS for app interop |

Each layer's spec is one markdown file in `repos/fips/docs/design/`.

## The Nostr integration — kinds and tags

FIPS uses three Nostr kinds in production. **All three are interesting examples for [`docs/kind-cheatsheet.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md)** because two of them are in the wild but not (yet) in the canonical NIPs registry.

### Kind 37195 — overlay advert (addressable)

> The digits visually spell "FIPS" — 7=F, 1=I, 9=P, 5=S. (Cute.)

A node publishes its currently-reachable transport endpoints as a kind 37195 event signed by its FIPS identity key (= its Nostr identity key). Peers that know the npub fetch the advert from the node's configured relays and append the advertised endpoints to their dial list.

- **Class:** addressable (range 30000–39999). Latest event per `(pubkey, kind, d-tag)` is what matters.
- **`d` tag:** application namespace, default `fips-overlay-v1`. Lets multiple FIPS deployments coexist on the same relays without crosstalk.
- **Tag content:** transport endpoints (`udp:host:port`, `tcp:host:port`, `tor:onion:port`, the special `udp:nat` rendezvous token), TTLs, capabilities.
- **Unpublication:** standard NIP-9 kind:5 delete, addressed at the kind 37195 event id.

This is a textbook case of "addressable kind in the wild, not in the registry." Per the kind-cheatsheet's Step 2, anyone considering kind 37195 for their own use should `nak req -k 37195 -l 3 wss://relay.damus.io wss://nos.lol` and discover that someone is already there. Coordinate via the FIPS project rather than collide.

### Kind 21059 — encrypted offer/answer (ephemeral, gift-wrapped)

For NAT hole-punching. When two nodes are both behind UDP NAT, they exchange STUN-derived candidate pairs through Nostr using NIP-59 gift-wrap. The outer wrap is kind 1059 (NIP-59 standard); the inner sealed event is kind 21059 (FIPS-specific, ephemeral 20000–29999 range).

- **Class:** ephemeral. The event has no value once the punch attempt completes.
- **Routing:** to the recipient's NIP-65 inbox relays (with fallback to `dm_relays` from the FIPS YAML config).

Another good real-world example — ephemeral kinds are uncommon outside NIP-46 / NIP-42 / NIP-98 (the core auth-flow kinds), so seeing one for application-specific live signaling is instructive.

### Kind 10002 — relay list (replaceable, NIP-65)

FIPS reuses NIP-65 unmodified for "where do my offer/answer messages get delivered." A FIPS node looking up a peer for hole-punch first fetches the peer's kind 10002 event, then publishes the kind 21059 gift-wrap to those inbox relays.

This is the right move — invent kinds only when an existing one doesn't fit.

## Binaries

| Binary | What |
|---|---|
| `fips` | Main daemon: TUN adapter, transports, mesh + session protocols. Needs root for TUN. |
| `fipsctl` | CLI: query node status, peers, links, sessions, metrics. Doesn't need root. |
| `fipstop` | TUI dashboard, like `htop` for a FIPS node. |
| `fips-gateway` | Optional daemon: lets unmodified LAN hosts reach mesh destinations via DNS-allocated virtual IPs and kernel NAT. |

In this workspace they're built at `repos/fips/target/release/` and installed to `~/.cargo/bin/`. The agent has them on PATH but no daemon is running.

## Why no `fips` daemon is running on this machine

By design choice — same posture as the other "potentially-internet-facing service" decisions in this workspace:

- `fips` requires **root** to load the TUN driver. Different threat model than localhost-bound containers.
- A FIPS node's value depends on a **persistent identity** (npub), since its routing state is anchored to that key. The workspace's `/dev/shm` ephemeral key would invalidate adverts on every reboot — pointless for a real mesh node.
- Running a node binds **UDP 2121** and **TCP 8443** outbound by default and joins a live mesh. Operationally meaningful; not appropriate as a default.
- The `nostr-discovery` feature is **off by default** in stock configs; an operator opts in deliberately. We respect that default.

If you want to run one, `repos/fips/packaging/` has Debian, AUR, OpenWrt, macOS, and Windows packagers. The minimal operator-facing flow:

```bash
# Install the .deb (or use the cargo-built binaries)
sudo cp ~/Documents/nostr-dev/repos/fips/target/release/fips /usr/local/bin/
sudo mkdir -p /etc/fips && sudo cp <your-config>.yaml /etc/fips/fips.yaml
# (config needs a persistent identity — generate or supply an nsec)
sudo /usr/local/bin/fips
# In another terminal:
fipsctl show status
fipstop
```

Don't do this with the workspace's ephemeral session key.

## Spec docs (offline at `repos/fips/docs/design/`)

| File | Topic |
|---|---|
| `fips-intro.md` | Goals, layered architecture, problem statement |
| `fips-transport-layer.md` | Datagram interface over arbitrary media |
| `fips-mesh-layer.md` | FMP — peer auth, link encryption, forwarding |
| `fips-session-layer.md` | FSP — end-to-end encryption, session lifecycle |
| `fips-ipv6-adapter.md` | TUN + DNS adapter mapping npubs ↔ `fd00::/8` |
| `fips-mesh-operation.md` | Routing, discovery, error recovery |
| `fips-wire-formats.md` | Message wire formats |
| `fips-nostr-discovery.md` | **The Nostr integration** — read this if you only read one |
| `fips-spanning-tree.md` | Root discovery, parent selection, coordinates |
| `fips-bloom-filters.md` | FPR analysis, size classes, split-horizon |
| `fips-configuration.md` | YAML configuration reference |
| `fips-gateway.md` | LAN gateway adapter |
| `spanning-tree-dynamics.md` | Walkthroughs of convergence scenarios |

## How this informs the workspace's design knowledge

- **§1 of [`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md)** (the "single load-bearing idea") — FIPS is the worked example showing that "signatures decouple authentication from storage" generalizes beyond event databases to **packet routing**.
- **[`kind-cheatsheet.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/kind-cheatsheet.md)** — kind 37195 is a real-world reminder to probe `nak req -k <N> ... wss://relay.damus.io wss://nos.lol` before allocating any kind, because the registry is incomplete.
- **[`patterns/grasp-as-structural-layer.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/patterns/grasp-as-structural-layer.md)** — different pattern but same underlying lesson: Nostr identity is the anchor; the structural layer is the part you choose. FIPS chose "decentralized routing"; the archive project chose "Git tree."


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/fiatjaf-vision.md` · snapshot 2026-10-10

# fiatjaf — "A vision for content discovery and relay usage for basic social-networking in Nostr"

**Source:** <https://fiatjaf.com/3f106d31.html>
**Author:** fiatjaf (creator of the Nostr protocol)
**Status:** third-party content — link only, with summary. Full text is on the
canonical site under fiatjaf's authorship; not re-hosted here.

## Why this essay matters

This is one of the earliest written design rationales from the protocol's
creator. It frames Nostr's discovery problem as *intentionally* unsolved at the
protocol level and pushes the responsibility onto clients to bootstrap from
many small signals. The "many hackish attempts" phrasing in [`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md)
comes from this essay.

## Core architectural prescription

- Three core social-app views: **home feed** (following-only), **profile view**
  (single user), and **replies view** (threaded).
- Discovery bootstraps from many sources: direct observation in replies,
  `nprofile` URIs, NIP-05 addresses, bare pubkeys.
- Relays are pragmatically classified — *spammy*, *safe*, *closed*. Different
  classes get different trust treatment depending on the query.
- Per-author queries can hit any relay because the events are signed; but
  *replies* and *global feeds* should be filtered to the safer relay set to
  prevent spam injection.

## Direct quote (the load-bearing claim)

> Nostr is just a very loose set of servers with basically no connection
> between them … the process of keeping connected to others and finding
> content must be addressed through many different hackish attempts.

This frames the design philosophy: **decentralized friction is a feature, not
a bug**. Don't try to engineer it away.

## How this informed the synthesis

- §1 of [`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) ("the single load-bearing idea") — directly cites
  this framing.
- §2 ("relay-feed vs outbox vs gossip") — fiatjaf's "any relay for user-specific
  content, safe relays for global feeds" distinction is an early form of
  per-event routing; the modern outbox/gossip model formalizes it.
- §5 ("don't censor; expose filtering") — flows from the same "trust the user
  to filter" stance.

## Related fiatjaf writing

- The fiatjaf.com index page lists his Nostr essays under the `nostr.html`
  hub: <https://fiatjaf.com/nostr.html>.
- He often writes terse, opinionated posts; treat them as primary sources for
  *why* a NIP exists, not *what* it specifies (which is in the NIP itself).


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/hodlbod-book.md ===

> **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`).


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nostr-design-principles.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/nostr-design-principles.md` · snapshot 2026-10-10

# Nostr Design — Guiding Principles

**Source:** <https://nostrdesign.org/docs/guiding-principles/>
**Adjacent reading:** <https://nostrdesign.org/docs/design-principles/starting-from-scratch/>
**Status:** community design guide. Summary + direct quotes below.

## The five principles (paraphrased)

1. **User sovereignty over identity.** "Users must retain control over their
   private keys. No client or company should lock users into their platforms."
2. **User sovereignty over relays.** "Users can always choose which relays to
   join or leave"; clients "should not force users to use a specific relay or
   a specific set of relays."
3. **Modularity over monoliths.** Build clients "that do one thing really
   well" rather than attempting all-inclusive applications.
4. **No platform censorship.** "Clients should avoid censoring anything they
   disagree with. Instead, they should give users the option to filter out
   content they do not wish to see." Filtering UX, not gatekeeping.
5. **Interoperability.** Different clients implementing the same NIPs should
   produce compatible events. Don't break the open ecosystem to ship a feature.

## How this informed the synthesis

[`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §5 ("architectural philosophy — distilled") is largely a
restatement of these principles. The framing "build pieces, not platforms" in §6
is a direct riff on principle 3.

## Companion: "Starting from Scratch"

The companion essay walks through what to think about when designing a new
Nostr-native client. Worth reading before starting any greenfield client
work. URL: <https://nostrdesign.org/docs/design-principles/starting-from-scratch/>


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/opensats-advancements.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/opensats-advancements.md` · snapshot 2026-10-10

# OpenSats — "Advancements in Nostr Clients"

**Source:** <https://opensats.org/blog/advancements-in-nostr-clients>
**Status:** OpenSats grant-program report. Public blog post; summary + direct
quotes below.

## What this report tracks

OpenSats funds a large fraction of core Nostr work (Coracle, Damus, Amethyst,
NDK, Hodlbod, fiatjaf, etc.). This report aggregates *what those projects
shipped* over a window — so it's a useful proxy for "what the actual
practitioners think the next move is."

## Lines that matter for design

### On the outbox shift

> Migration from manual relay lists to dynamic outbox models. Instead of
> users manually selecting which relays to read from, clients now automatically
> compile effective relay sets based on actual follows and content
> distribution.

This is the codification of: *outbox is no longer optional for a serious client.*

### On relay scale

> Enables clients like Amethyst to connect to ~1,000 relays simultaneously
> over mobile.

Concrete data: real clients in production talk to **thousands** of relays at
once. Plan for that scale; don't assume "a handful."

### On distributing load

> Distributes network traffic across many smaller relays rather than
> concentrating activity on 10-20 major hubs.

Outbox + gossip is what keeps the network's traffic profile flat. If your
client centralizes its reads on the popular relays "for performance," you are
contributing to centralization.

### On Coracle's contributions (Hodlbod)

> Coracle introduced governance standards through NIP-43 and NIP-86,
> formalizing relay membership lists and access controls. This enables relays
> to explicitly state who they serve and what content policies they
> maintain — transforming relays from invisible infrastructure into transparent
> services with defined purposes.

This is the "relays are services" line restated. NIP-43 (membership) and
NIP-86 (relay management API) are the mechanism.

### On per-note relay selection

> Coracle's 0.6.x releases added per-note relay selection, letting authors
> directly control where posts distribute rather than defaulting to major
> relays. This makes the outbox model tangible for everyday users.

This is the leading edge: *user-visible* per-event routing. Not just a default
the client computes — a control surface the user sees.

### On encrypted DMs

> NIP-17 (private messages) and NIP-59 (gift wrap) ensure encrypted
> communication works seamlessly across different clients while maintaining
> metadata privacy.

If you're building anything DM-shaped, NIP-17 + NIP-59 is the modern stack;
NIP-04 is deprecated.

## How this informed the synthesis

§2 (outbox/gossip), §3 (per-kind routing), §5 (relays as services), and §6
(failure model: clients talk to thousands of relays) all draw on this report's
data points.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/nostr-rising.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/nostr-rising.md` · snapshot 2026-10-10

# Nostr Rising — podcast series (bitcoin.review)

**Hosts:** NVK (bitcoin.review) + rotating guests from the Nostr core dev community.
**Status:** publicly available podcast; transcripts not freely re-hostable. Episode
list with summaries below; play directly from the linked URLs.

The series is the single best public conversation record of *why* design
decisions in Nostr were made. When the synthesis cites "the literature," this
is a meaningful chunk of it.

## Episodes

| # | Title | Guests | Topic | Link |
|---|---|---|---|---|
| 01 | Permissionless Algos | JB55, Hodlbod, Miljan | Why algorithmic feeds belong to users; relay-side vs client-side curation | <https://bitcoin.review/podcast/episode-78/> |
| 02 | Communities | Rabble, Alex Gleason, Hodlbod, Pablo | Communities = relays; NIP-72 / NIP-29 trade-offs | <https://bitcoin.review/podcast/episode-79/> |
| 03 | Relays & Scaling | Fiatjaf, Mike Dilger, Pablo | The outbox/gossip model; what scale means without a global topology | <https://bitcoin.review/podcast/episode-80/> |
| 04 | DMs and Groupchats | Fiatjaf, Hodlbod, Jeff G | NIP-17, NIP-44, NIP-59 gift wrap; MLS for groups | <https://bitcoin.review/podcast/episode-81/> |
| 05 | Podcasting 2.0 | Kieran, Odell, Hodlbod, Oscar Merry | Long-form audio + value4value over Nostr | <https://bitcoin.review/podcast/episode-82/> |
| 07 | Long Form Content | DK, Miljan | NIP-23, content distribution, why long-form pulls from a different relay set than kind:1 | <https://bitcoin.review/podcast/episode-84/> |
| 08 | Nostr Funding | Lyn Alden, Max, Odell | Sustainability of relays + open source | <https://bitcoin.review/podcast/episode-85/> |

(Episode 06 was published but is not surfaced in current listings.)

## Themes that recur across the series

- **Relays are not commodity infrastructure.** They have policies, costs, and
  audiences. Treat them like services.
- **The outbox/gossip model is a *consequence* of relay diversity, not a
  preference.** If all relays were equivalent and uncensored, you wouldn't
  need it. They aren't, so you do.
- **Per-domain routing.** DMs ≠ public broadcast ≠ communities ≠ long-form ≠
  podcast feeds. Each has its own routing pattern. Don't conflate.
- **Permissionless algorithms.** Anyone can publish a kind-30000-range
  filter/feed and let others subscribe to it. Algorithmic feeds become
  user-portable.
- **Sustainability is a design concern.** Funding for relays, NIPs, and core
  clients (Coracle, Damus, Amethyst) is part of why the protocol stays open.

## How this informed the synthesis

Episode 03 (Relays & Scaling) and Episode 02 (Communities) are the most
load-bearing for [`design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) §2 (per-kind routing) and the
"relays are services" framing.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/videos.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `nostr-dev/docs/sources/videos.md` · snapshot 2026-10-10

# Talks and videos — fiatjaf, Hodlbod, Pablo, Dilger

**Status:** pointers only. Videos can't be archived offline meaningfully here;
the URLs are what's useful. If you want to grab transcripts, run them through
yt-dlp + whisper, but that's outside this workspace's scope.

## Recommended viewing — design-relevant

| Title | Speakers | Why watch | URL |
|---|---|---|---|
| **CD122: Nostr Development with Fiatjaf, Hodlbod, Pablo, Dilger** | All four core dev voices in one room | Design rationale across the stack; this is *the* tape if you only watch one | <https://www.youtube.com/watch?v=F57UDu3YPYM> |
| **BR049: Nostr Filters & Censorship Panel** | Fiatjaf, Hodlbod, Vitor Pamplona | Why client-side filters > relay-side moderation; relevant to "don't censor; expose filtering" | <https://www.youtube.com/watch?v=2MnyII8BPks> |
| **S15 E21: Fiatjaf on Nostr, Drivechains & Why Lightning Sucks** | Fiatjaf | Background on the protocol's *origin* mindset | <https://www.youtube.com/watch?v=gLV8i8KtkfI> |
| **Nostr Rising 03 (audio)** | Fiatjaf, Mike Dilger, Pablo | Outbox/gossip and scaling; audio version of bitcoin.review BR080 | <https://substack.bitcoin.review/p/br080-nostr-rising-03-relays-and> |
| **Nostrovia podcast — Fiatjaf and Pablo** | Fiatjaf, Pablo | NDK design and what apps the protocol enables | <https://creators.spotify.com/pod/profile/nostrovia/episodes/Fiatjaf-and-Pablof7z-e2d2d8k> |
| **Nostrovia podcast — Coracle (Hodlbod)** | Hodlbod | Coracle's design choices, outbox, communities | <https://creators.spotify.com/pod/profile/nostrovia/episodes/Coracle-e1ugcbh> |

## fiatjaf's YouTube presence

He is not a heavy YouTube poster; the design content is mostly in interviews
and panels (above) plus his blog ([`docs/sources/fiatjaf-vision.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/sources/fiatjaf-vision.md)). Don't
expect a polished channel — expect references on interviews + scattered talks.

## Lifting transcripts (optional)

If you want grep-able transcripts on disk:

```bash
# in a sandbox, not in this repo
yt-dlp --write-auto-sub --skip-download --sub-format vtt 'https://www.youtube.com/watch?v=F57UDu3YPYM'
# convert to plain text:
sed 's/<[^>]*>//g; s/^[0-9].*-->.*$//' *.vtt | awk 'NF' > cd122.txt
```

Don't commit transcripts here — they're fair-use research artifacts, not part
of the workspace definition.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/fiatjaf/README.md` · snapshot 2026-10-10

# fiatjaf — the protocol's creator

fiatjaf created Nostr with the November 2020 manifesto
(<https://fiatjaf.com/nostr.html>) and remains its most consequential — and
most contrarian — voice. His writing is terse, ironic, and deliberately
scandalous in its titles; read it as primary source for *why* the protocol is
shaped the way it is, not for what any NIP specifies.

- npub: `npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z`
- Site: <https://fiatjaf.com> — Nostr essays: <https://fiatjaf.com/-/tags/nostr>
- In this folder: [`essays.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/essays.md) — annotated bibliography of all
  21 substantive Nostr essays (summaries + verbatim quotes);
  [`on-nostr.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/on-nostr.md) — what he publishes on Nostr itself.

## The five positions that define his thinking

**1. Nostr is a description, not a thing.** Not a website, an app, a set of
servers, or a community — only a message format and a server interface. Every
property of any particular relay (free? public? permanent? moderated?) is a
private decision of "the program running on the relay server," never a
property of Nostr. The founding trilemma: *"It doesn't rely on any trusted
central server, hence it is resilient; it is based on cryptographic keys and
signatures, so it is tamperproof; it does not rely on P2P techniques,
therefore it works."*

**2. The client–multi-relay split is the whole invention.** The one novel
idea, in his own words: *clients talk to multiple servers.* Everything he
attacks — DHTs, IPFS, global content pools, and the "super-peer curse"
(Bluesky's app views, Farcaster hubs, p2panda's Aquadoggo, Nostr's own
proxy/aggregator experiments) — is an architecture that re-inserts a trusted
machine between follower and followed. Anti-dote: power belongs *in the relay
layer* (curation relays, WoT relays, paid relays, AI-feed relays), never
interposed in front of it.

**3. Censorship-resistance is emergent client behavior, not a protocol
property.** His most important self-critiques: *"Nostr today is indeed
centralized"* (2024 — because clients hardcode relay lists and reach dies
when the big three ban you) and *"Nostr is pro-censorship"* (2025 — every
relay is private property, free to reject anything; the network resists
censorship precisely because censorship is everywhere permitted and nowhere
decisive). The obligation this puts on developers: real relay discovery —
NIP-65 outbox *plus* relay hints in tags, NIP-05 hints, nprofile hints, and
manual user action, "a mix of multiple approaches." Reducing discovery to
NIP-65 alone he calls catastrophic; dropping relay hints destroys the
graceful degradation that lets even a fully-banned user stay readable.
Corollary, against the key-worshippers: *"Keys are meaningless"* — "having a
key is meaningless if you cannot publish messages to where the people you're
trying to reach can read them." Relays, not keys, are the thing.

**4. The centralizing force is anything optional that becomes mandatory.**
His recurring test for protocol extensions, told as the YAML-NIP-05 parable
and deployed against NIP-26 delegation, kind:1 edits, and superapp rendering
of every kind: if widespread adoption would force *every* client to implement
it or display false/broken content, it is not optional, and it raises the
barrier to entry for new clients — which is his real decentralization metric.
Hence "the case against edits" (a non-implementing client would show false
information) and "kind:1 maximalism" (kind:1 is "the central plaza," to be
kept deliberately dumb and served by dozens of tiny clients; other stuff
lives in dedicated kinds + microapps, *linked* from the plaza, not rendered
into it). By 2025 the same instinct turns on his own creation: "The end of
NIPs" proposes replacing the NIPs repo with a bare kind-number registry plus
competing prose guides, because spec bureaucracy bred developers who
"translate event schemas into UI" while ignoring the hard part — relay
choice.

**5. Spam and business both resolve at the relay layer.** Spam: main feeds
are spam-free by construction; inboxes are fixed by querying `#p` mentions
only from filtered read-relays (WoT, NIP-05-gated, PoW, paid); client-side
filtering fails because content must be downloaded before it can be filtered,
and a dirty thread "is their fault for not picking 'read' relays correctly."
Business: don't build a platform that imprisons Nostr content behind an API —
ship an interoperable niche client, put the secret sauce in a relay you run
and charge for, compete "on a leveled playing field": "You don't own the
network… so you're not responsible for it." Worked example: git over Nostr
(NIP-34/GRASP) — find the network-effect chokepoint (GitHub), replace its
coordination layer with signed events on competing relays.

## Where he differs from the other voices

- vs. **Hodlbod**: Hodlbod's framing is key-centric (signatures decouple
  storage from authentication); fiatjaf's is relay-centric (keys are a burden
  that exists to enable relays). Both agree on the conclusion — outbox
  discipline, small clients, no super-peers — but weight it differently.
- vs. **the NIPs process**: he created it and now wants it dissolved into a
  kind registry; Hodlbod defends curated NIPs as the least-bad communication
  venue. Live debate, unresolved.
- On **key management**: relaxed where others are alarmed — identity, unlike
  money, "can be recovered — slowly and painfully"; many optional schemes
  coexisting beat any mandatory one.

Treat these tensions as content, not noise: the disagreements between the
principals are the most instructive part of the literature.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/essays.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/fiatjaf/essays.md` · snapshot 2026-10-10

# fiatjaf on Nostr: annotated bibliography of his web essays

Research pass over https://fiatjaf.com (essay hub: https://fiatjaf.com/nostr.html, full
Nostr tag index: https://fiatjaf.com/-/tags/nostr). All 24 Nostr-tagged essays were
fetched and read in full on 2026-08-31; the 21 most substantive are annotated below,
grouped by theme. Dates are the ones printed on each page.

## Synthesis: fiatjaf's philosophy of Nostr

Across these essays, fiatjaf's Nostr is not a network, a platform, or even a set of
servers — it is a *description*: a minimal message format (signed events) plus a minimal
server interface (relays), and nothing else. Everything he values follows from that
minimalism. The founding manifesto's one-liner still governs everything he writes: no
trusted central server (resilient), cryptographic signatures (tamperproof), and — the
deliberately contrarian third leg — *no P2P techniques, therefore it works*. He is openly
hostile to DHTs, global content pools, blockchains-for-social, and "super-peer"
architectures (Bluesky/ATProto, Farcaster, p2panda, IPFS), all of which he sees as either
physically unworkable or as re-smuggling a trusted server in through the back door. The
alternative he insists on is the multi-relay client: a genuinely independent "user agent"
that talks to many dumb, private, mutually-independent servers, assumes any of them may
be evil, and does the hard work of figuring out *where* to read and write. Censorship
resistance, in his telling, is not a property of the protocol at all — it is an emergent
property of clients doing relay discovery properly (relay hints, NIP-05 hints, NIP-65
outbox lists, manual action, "a mix of multiple approaches"). Hence his most striking
self-criticisms: "Nostr is not decentralized nor censorship-resistant" (today, because
clients hardcode relay lists) and "Nostr is pro-censorship" (every relay is private
property free to reject anything; freedom lives in the reader's ability to look
elsewhere). Even keys, the thing newcomers worship, he calls "meaningless" — an
unnecessary burden that exists only to enable relays.

His design guidance for developers is a consistent ethic of *keeping it simple to write a
client*, because the barrier to entry for clients is, to him, the real decentralization
metric. Anything that starts optional but becomes de-facto mandatory once widespread —
NIP-26 delegation, note edits, YAML variants of NIP-05, superapp rendering of every event
kind inside kind:1 feeds — is a "centralizing force" to be resisted, however innocent it
looks. He wants kind:1 microblogging kept as a deliberately dumb, neutral "central plaza"
served by dozens of small clients, with "other stuff" (recipes, music, git, calendar
events) living in dedicated kinds, dedicated microapps, and topical or curated relays,
linked from the plaza rather than absorbed into it. Businesses should not build platforms
that imprison Nostr content behind an API; they should ship an interoperable client and
run a value-adding relay that competes "on a leveled playing field" — the magic sauce
goes in the relay, the network stays owned by no one. By 2025 this anti-ossification
instinct extends to the standards process itself: "The end of NIPs" proposes abandoning
the NIPs repository for a bare kind-number registry plus competing prose guides, because
spec bureaucracy was producing developers who translate event schemas into UI while
ignoring the actually-hard part, relay choice.

The temperamental throughline is an embrace of chaos and markets over guarantees and
committees. Nostr "can't ever promise perfect reachability, no protocol can"; relays are
houses, and if someone's thread is full of spam "that is their fault" for choosing bad
read-relays; users who lose keys can painfully rebuild, unlike money, so key management
needs no mandatory scheme. He is ironic, self-deprecating ("I hope you got my point and
agreed because this article is ended"), and dismissive of slogans — including
Nostr-community slogans like "not your keys, not your notes" and "self-sovereign
identity". But the irony sits on top of a rigid core conviction: the client–multi-relay
split is the only social-network architecture that has ever aligned incentives with
censorship-resistance, and nearly every proposed "improvement" is an attempt to
reintroduce the platform.

---

## Theme 1 — Foundational vision: what Nostr is (and is not)

### nostr - Notes and Other Stuff Transmitted by Relays
- URL: https://fiatjaf.com/nostr.html
- Date: Nov 20 2020

The founding manifesto, written before any implementation existed. It defines Nostr as
clients and relays only: users sign posts with their keys and send them to multiple
relays; readers query multiple relays; relays are "very simple and dumb," never talk to
each other, and are never trusted (signatures are verified client-side). The bulk of the
document is a demolition of the alternatives: Twitter (ads, addiction techniques, bans,
shadowbans); Mastodon (identities attached to third-party domain names, server despotism,
lost followers on migration, no incentive to run servers, painful server-to-server
pushing); SSB (great idea, but over-complicated protocol quirks like ECMA-262 JSON
signing and a mandatory per-user chain of updates); and everyone-runs-their-own-server
schemes (people won't, and domains get censored). It then argues Nostr solves banning
(identity is a key, not an account; move relays and followers follow via relay
recommendations), censorship (paid relays: "there will always be some Russian server
willing to take your money"), spam (relays can charge or authenticate), and heavy content
(relays can reject or charge for it). A prescient FAQ already concedes the discovery
problem: if you share no relay with someone you cannot see them, hints can help, and
"we can't ever promise perfect reachability, no protocol can." The famous answer on why
nobody built this before: companies want money, P2P activists want zero servers, and
"they both fail to see the specific mix of both worlds that Nostr uses."

> "The simplest open protocol that is able to create a censorship-resistant global 'social' network once and for all."
> — https://fiatjaf.com/nostr.html

> "It doesn't rely on any trusted central server, hence it is resilient; it is based on cryptographic keys and signatures, so it is tamperproof; it does not rely on P2P techniques, therefore it works."
> — https://fiatjaf.com/nostr.html

### Nostr: a quick introduction, attempt #1
- URL: https://fiatjaf.com/d0b15ac7.html
- Date: Jan 28 2024

The first of three attempts at explaining Nostr to normal people, each with a different
emphasis. Here Nostr "doesn't have a material existence, it is not a website or an app" —
it is a description of messages computers can exchange, which lets different apps connect
to different servers automatically with no contracts or behind-the-scenes coordination.
He compares it to the internet itself: millions of websites, anyone can run one, but with
one shared "language" that makes switching relays clean — so a ban just moves the author,
and conversely no relay has to "uphold a moral ground of 'absolute free speech'": relays
may delete or ban for no reason and nobody is entitled to complain. He is candid about the
costs: no guarantee any relay has the notes you want, users may see different reply sets
and be confused, and malicious relays could edit notes — which is the actual reason for
signatures, whose price is the dreaded nsec the user must guard. The signature "fix is
perfect" except for that key burden, which at least yields portable identity and
third-party-free login.

> "To conclude: Nostr is like the internet (or the internet of some decades ago): a little chaotic, but very open."
> — https://fiatjaf.com/d0b15ac7.html

### Nostr: a quick introduction, attempt #2
- URL: https://fiatjaf.com/ded75cbc.html
- Date: Sep 6 2024

The shortest and most political framing. Nostr explicitly does *not* subscribe to "free
speech" ideals, which he says belong to politics and presuppose a powerful government
enforcing a common rule. Instead, Nostr says servers are private property and provides "a
generalized framework for people to connect to all these servers, creating a true free
market" — Nostr is the public road, relays are the private stores along it. Concretely it
is just data-format definitions over WebSocket with signatures, a base on which
sub-protocols (microblogging, group chat, "recipe sharing and feedback") get layered.
This essay is the cleanest statement of his market-libertarian reading of the
architecture, later expanded in "Nostr is pro-censorship."

> "Nostr instead is much simpler, it simply says that servers are private property and establishes a generalized framework for people to connect to all these servers, creating a true free market in the process."
> — https://fiatjaf.com/ded75cbc.html

### Nostr: a quick introduction, attempt #3
- URL: https://fiatjaf.com/0601c1ca.html
- Date: Nov 3 2025

Aimed squarely at a misconception he keeps meeting: people who hear "relays" and imagine
a set of free public servers, then ask "who will run these relays?" or "how is this
censorship-resistant if you can take down the relays?" His answer: "Don't be one of these
people." Nostr is only the interface description — a relay understands `["REQ", "z",
{"limit":10}]` and nothing else. Whether a relay is free, whether it stores your event,
whether it deletes it after a while or keeps 32 redundant copies, whether it serves
everyone or only some people — every one of those is a private decision of "the program
running on the relay server." The essay is a drumbeat repetition of that clause,
hammering home that no property of any particular relay is a property of Nostr.

> "Nostr is not any specific set of relays, and relays are not meant to be public or free."
> — https://fiatjaf.com/0601c1ca.html

### Visual depiction of the architecture of 3 different decentralized social networking protocols
- URL: https://fiatjaf.com/52a0d652.html
- Date: Oct 3 2025

A short comparative piece (with diagrams on the page) contrasting the Fediverse, Nostr,
and ATProto. The Fediverse ("Mastodon is the de facto controller of the protocol";
ActivityPub proper he calls a broader spec "conceived by the minds of unreasonable
academics, unimplementable in nature" and only partly adopted) is clients talking to a
single server that talks to other servers. ATProto/Bluesky's core idea is decomposing the
social server into three kinds of servers in a pipeline. Nostr's single core novelty is
stated in one clause — clients talk to multiple servers — and he owns the consequence
proudly: the result is chaos, and the chaos is the point. Useful as the most compact
statement of what he thinks is architecturally distinctive about Nostr versus its two
main competitors.

> "its core new idea is that clients can talk to multiple servers, which gives us a very chaotic ecosystem of signed messages."
> — https://fiatjaf.com/52a0d652.html

---

## Theme 2 — Relays, discovery, and what censorship-resistance actually requires

### A vision for content discovery and relay usage for basic social-networking in Nostr
- URL: https://fiatjaf.com/3f106d31.html
- Date: Jan 12 2023

His canonical design document for how a Twitter-like client should actually use relays —
the essay the later "not decentralized" polemic points back to. He models three app views
(home feed, profile, replies; optionally global) and classifies relays subjectively as
spammy, safe (fee/registration barriers but fundamentally open), or closed (friend
groups, communities). The heart is the follow flow: to follow someone you must learn
*some* relay where they publish, bootstrapped from wherever you met them — relay URLs
embedded in `e`/`p` tags, nprofile URIs, NIP-05 relay lists, or (worst case) a bare npub
requiring prompts or searching your known relays. Clients must then continuously mine
relay hints from every event seen anywhere to keep a local profile→relay database fresh
as people migrate. Rendering follows from this: home and profile feeds can safely query
even spammy relays (the author filter protects you), but reply views and global feeds
must query only safe/closed relays or spam gets injected. He closes by admitting the many
corner cases (resolving a referenced note via its hint, the mentioner's relays, the relay
you saw the mention on...) and that all of it "may fail and then it is probably not a big
deal."

> "Nostr is just a very loose set of servers with basically no connection between them, there are no guarantees of anything, and the process of keeping connected to others and finding content must be addressed through many different hackish attempts."
> — https://fiatjaf.com/3f106d31.html

> "To write Nostr applications and to use Nostr one must embrace the inherent chaos."
> — https://fiatjaf.com/3f106d31.html

### Nostr is not decentralized nor censorship-resistant
- URL: https://fiatjaf.com/87a208d9.html
- Date: Mar 19 2024

A remarkable self-critique conceding (charitably) Peter Todd's long-standing accusation.
His experiment: two identical notes published simultaneously, one to three popular relays
(nostr.wine, nos.lol, pyramid.fiatjaf.com), one only to his own relay — which he
announces in his NIP-05 and NIP-65 relay list, i.e. exactly where clients are supposed to
look. The first got vastly more engagement, which "shouldn't have happened at all" if
clients actually followed people rather than followed relays. He draws the political
consequence: a figure banned by the three biggest public relays would instantly drop to
~10% reach — the same fate as personalities deplatformed from corporate social media —
"in that sense Nostr today is similar to what we had before." The crucial distinction he
insists on: Todd is right about the present, wrong about the design — the failure lives
in clients that subscribe to a static relay set, not in the protocol, and it is fixable
by driving clients toward real relay discovery.

> "Nostr today is indeed centralized."
> — https://fiatjaf.com/87a208d9.html

> "Peter Todd is wrong that Nostr is inherently centralized or that it needs a protocol change to become what it has always purported to be."
> — https://fiatjaf.com/87a208d9.html

### Censorship-resistant relay discovery in Nostr
- URL: https://fiatjaf.com/bc63c348b.html
- Date: Mar 19 2024

The constructive companion piece, published the same day. It gives the history of the
discovery problem: the idea was always that clients would follow people "in the relays
they decided to publish to, even if it was a single-user relay hosted in an island in the
middle of the Pacific ocean," but nothing ever enforced this (nothing could), and his own
first client Branle shipped with "a stupid static list of relays" anyway. Mike Dilger's
Gossip was the first client to do censorship-resistant discovery for real — NIP-05 hints,
relay hints, kind:3 relay lists — and NIP-65 then crystallized it into what got
popularized as the "gossip model"/"outbox model," adopted by Coracle and Snort. His
warning: reducing the outbox model to just NIP-65 is "too restrictive" — NIP-05 hints,
nprofile/nevent hints, and event-tag hints all still matter and should be used together.
He ends by arguing the space is not finished: manual user action is "underrated" (if not
designed "by people that think users are dumb animals"), and resilience will come from
deliberately mixing many mechanisms rather than standardizing one.

> "Reliance on third-parties, hardcoded values, social graph, and specially a mix of multiple approaches, is what Nostr needs to be censorship-resistant and what I hope to see in the future."
> — https://fiatjaf.com/bc63c348b.html

### Why relay hints are important
- URL: https://fiatjaf.com/8ce7df34.html
- Date: Jun 13 2024

A rebuttal to Coracle's removal of support for relay hints in event references in favor
of pubkey hints plus kind:10002 (NIP-65) alone. He piles up concrete cases the pure
outbox model cannot handle: posts inside NIP-29/NIP-87 communities whose relays are in
nobody's outbox list; a conference-only relay whose events could never be referenced from
outside; a user whose big outbox relay periodically nukes old events while their archive
lives on cellar.nostr.wine; topical relays (cooking recipes) that users publish to
exclusively; one keypair running two personas with two different kind:10002 lists on
different indexers; relays that reject certain kinds; and finally the fully-banned user —
an "Alex Jones" who cannot even get his kind:10002 onto index relays could still live "a
normal Nostr life" via nprofile business cards and per-event relay hints, but without
hints he is simply unreadable. The essay is the strongest statement of his view that
hints woven through events, not any single published relay list, are what make Nostr's
reachability degrade gracefully under adversarial conditions.

> "That is a catastrophic idea that destroys much of Nostr's flexibility for no gain at all."
> — https://fiatjaf.com/8ce7df34.html

### The only solution to Nostr spam
- URL: https://fiatjaf.com/6fcc40bf.html
- Date: Nov 17 2025

His mature position: spam is solved at the relay layer, not the client layer. Main feeds
have no spam problem by construction (you read people you follow, from relays you chose).
Inbox spam (mentions/replies in notifications) is fixed by clients querying `#p` mentions
only from the user's NIP-65 "read" relays — and by users choosing read-relays that
actually filter: relay.mostr.pub's NIP-05 requirement, his pyramid inbox's 2-level
web-of-trust filter, PoW or paid relays as fallbacks; he calls for public filtered inbox
relays to become client defaults so newcomers never see spam. The hardest case is other
people's threads: you fetch replies from *their* read relays, and if those are garbage,
"that is their fault" — an incentive structure where clean threads are each user's
responsibility, socially correctable, like not visiting a house that is always dirty.
The final section rebuts the do-it-all-client-side camp: mutes don't stop bots with
infinite keys; client-side WoT fails because "content must first be downloaded before it
can be filtered" (at scale, gigabytes of spam daily, and a 500-reply flood already
starves naive queries); client-side filtering is monolithic where relay choice is
composable; and purely local filtering is a tragedy of the commons, since it leaves every
visitor to your threads fending for themselves.

> "If the practices outlined above become widespread, it will also become evident that, if you're seeing spam at someone else's thread that is their fault. It's their fault for not picking 'read' relays correctly."
> — https://fiatjaf.com/6fcc40bf.html

### Nostr is pro-censorship
- URL: https://fiatjaf.com/3a914800.html
- Date: May 28 2025

Deliberately titled to scandalize, this is his deepest statement of why the relay
architecture works where "anti-censorship" platforms failed. The core of Nostr is not
keys but the fact that a client can reach a huge number of independent servers, "from a
modest server at his basement to a big cloud relay," without trusting any. Platforms and
protocols built on "a big common 'global' pool of messages" all eventually broke on the
same rock: someone must host the content, hosting has costs and moral and legal
implications, "and there will never be a global agreement between all the peoples of the
Earth about whom or what should be allowed" — even rate-limits and IP blocking are a form
of censorship. Nostr dissolves the problem by definition: no global pool exists, every
relay is independent, and it is the *reader's* job to figure out where to read — so every
relay is free to censor as much as it likes, and the network as a whole becomes
censorship-proof precisely because censorship is everywhere permitted and nowhere
decisive. The closing caveat carries the whole weight: all of this "breaks down if apps
relinquish their obligation to figure out what relays to read from and decide to read
from a static list of relays."

> "no relay has any obligations to please all the peoples of the Earth and is free to impose any limits or policies it wants."
> — https://fiatjaf.com/3a914800.html

### Keys are meaningless
- URL: https://fiatjaf.com/cb4ca47a.html
- Date: May 28 2025

The short, sharp companion to "Nostr is pro-censorship," attacking key-worship among
technologists. Secret keys are "just numbers"; a script can mint a bazillion of them with
zero effect on the world. He rejects the slogans "not your keys, not your notes" and
"self-sovereign identity" as meaningless — "people are not keys," and by key-worshipper
logic a person locked in a cage is "free" because only they can move their own body.
Sovereignty ("what an unfortunate word") means nothing without means of action in the
world; for Nostr the means of action is publishing to places where your audience actually
reads. Keys are, in his phrase from the sister essay, an unnecessary burden that exists
to enable the thing that matters: relays.

> "having a key is meaningless if you cannot publish messages to where the people you're trying to reach can read them."
> — https://fiatjaf.com/cb4ca47a.html

---

## Theme 3 — Protocol design discipline: what NOT to do

### How being "flexible" can bloat a protocol
- URL: https://fiatjaf.com/27598e6f.html
- Date: Feb 10 2023

A parable ("a somewhat absurd example, but you'll get the idea") about how optional
niceties become mandatory burdens. One client charitably supports NIP-05 files in YAML at
`/.well-known/nostr.yaml` alongside JSON — harmless, surely. A user's YAML file works
there, so when other clients "break," the user complains to *their* developers, who,
fearing an incomplete client, add YAML support too; the cycle repeats until YAML is
extra-officially part of the spec and every future client forever does double the work.
The mechanism — user-facing pressure ratcheting one client's kindness into everyone's
obligation — is the same one he later invokes against NIP-26, against edits, and against
superapp kind-rendering. It is his most compact statement of why "why not?" is never a
sufficient argument for a protocol extension.

> "The end result of this is that now nip05 extra-officially requires support for both JSON and YAML files. ... A lot of work was wasted for nothing."
> — https://fiatjaf.com/27598e6f.html

### Why I don't like NIP-26 as a solution for key management
- URL: https://fiatjaf.com/4c79fd7b.html
- Date: Apr 4 2023

The essay that effectively killed NIP-26 (delegated event signing) as a general
mechanism. He recounts its origin in the needs of Minds.com — letting a custodial
platform key be statelessly associated with a user's self-owned key via a delegation tag
— and stresses that its whole appeal to him was that it was "fully optional": clients
ignoring it would just see two identities, both with faces and histories, no harm done.
Then the community started treating NIP-26 as *the* key-management story: a cold master
key on a hardware device signing monthly delegation tags for per-app throwaway keys.
That flips the property that made it acceptable: now the active keys are "faceless
entities," and a client that doesn't implement NIP-26 sees only "a constant stream of
random keys" — unable to follow or interact with anyone. So NIP-26 becomes de facto
mandatory for every client, breaking the simplicity of the protocol for a solution he
considers partial and inelegant anyway. If a mandatory delegation scheme is ever truly
needed, he argues, it should be designed fresh rather than rushed — but key management
can instead be solved by many optional approaches coexisting.

> "So now every client must implement NIP-26 to become usable at all, it is not optional anymore."
> — https://fiatjaf.com/4c79fd7b.html

### Thoughts on Nostr key management
- URL: https://fiatjaf.com/72f5d1e4.html
- Date: Apr 4 2023

The constructive sequel to the NIP-26 essay, listing techniques that "work in tandem":
NIP-41 stateless key invalidation, NIP-46 Nostr Connect, NIP-07 browser signers, hardware
signing devices, musig/FROST threshold keys with semi-trusted servers, dedicated mobile
signers. More interesting than the list are his stated premises for why he doesn't worry
much: Nostr keys are not as valuable a target as Bitcoin keys; identity, unlike money,
can be recovered "slowly and painfully" after total loss; and for most people losing keys
and starting fresh "isn't a big deal" — people delete social accounts and lose phone
numbers all the time and just tell their friends. He sketches social recovery as an
example: friends publish events attesting to Alice's new key, and Carol's client
trust-weights Bob's attestation. His favorite property of NIP-41-style and
social-recovery schemes: they need no support in ordinary clients at all — they can live
in "standalone single-purpose microapps" users visit occasionally, which then update
follow lists automatically.

> "Even when you lose everything, identity can be recovered -- slowly and painfully, but still --, unlike money"
> — https://fiatjaf.com/72f5d1e4.html

### The case against edits
- URL: https://fiatjaf.com/ad84e3b3.html
- Date: Nov 7 2024

A structured polemic (in objection-and-reply format) against editable kind:1 notes. Edits
are fine in specialized kinds, but kind:1 "is the public square of Nostr," where
decentralization is paramount. His core argument is about the barrier to entry: if edits
spread, every client — including the tiny embedded ones he hopes for, "Nostr notes being
referenced from and injected in unrelated webpages, unrelated apps, hardware devices,
comment sections" — must implement complicated edit-fetching on top of already-complex
outbox querying. To "but likes and zaps are optional extras too" he answers: those don't
change the content of the post; edits do, so a non-implementing client shows *false
information* — meaning edits, once widespread, are mandatory, and clients without them
die, which is exactly what a centralizing force looks like. He punctures the "every
platform has edits" myth (Bluesky, Instagram comments, TikTok, YouTube videos, email, and
15 years of Twitter say otherwise) and turns "the market will decide" around: "The market
has decided for Facebook, Instagram, Twitter and TikTok. If we were to follow what the
market had decided we wouldn't be here." Alternatives he offers: the annotations spec
(graceful fallback to replies), human-readable diffs as annotations, and the old email
trick of a delayed-send window for fixing typos.

> "Direct edits are a centralizing force on Nostr, a slippery slope that should not be accepted."
> — https://fiatjaf.com/ad84e3b3.html

> "No, they are not optional. If edits become widespread they necessarily become mandatory. Any client that doesn't implement edits will be displaying false information to its users and their experience will be completely broken."
> — https://fiatjaf.com/ad84e3b3.html

### `kind:1` maximalism and the future of other stuff and Nostr decentralization
- URL: https://fiatjaf.com/cd8ce2b7.html
- Date: Oct 26 2024

His architecture for how "other stuff" (long-form, podcasts, calendar events,
livestreams) should relate to microblogging. Three options for discoverability: (a)
publish everything as kind:1 ("obviously very bad"); (b) different kinds, but
microblogging clients fetch and render them all (via NIP-31/NIP-89); (c) different kinds,
announced by plain kind:1 notes that link out to dedicated clients. He confesses he long
favored (b) — as do, tacitly, the clients rendering ever more kinds in feeds — but has
switched to (c): superapp-ification "pushes clients to become bigger and bigger, raising
the barrier to entry into the kind:1 realm," and he personally hated seeing his long-form
articles dumped into feeds as if they were tweets. Solution (c) maximizes publisher
flexibility, keeps a crisp boundary for simple clients, and preserves the reason for
microapps to exist (if every client renders recipes perfectly, dedicated recipe apps
die). The conclusion inverts the essay's title: kind:1 is *not* just another kind — it is
"the central plaza of Nostr," and its neutrality demands dozens of small, diverse clients
even if every niche vertical has only two.

> "It's ok if Nostr ends up having just 2 recipe-sharing clients, but it must have dozens of microblogging clients"
> — https://fiatjaf.com/cd8ce2b7.html

### The end of NIPs
- URL: https://fiatjaf.com/311b999e.html
- Date: Aug 15 2025

A late, radical proposal from the person who created the NIP process: "We stop using the
NIPs repository completely." Replace it with a minimal, uncontentious registry that only
reserves kind numbers with one-line descriptions, and let anyone interested in a kind (or
kind-group) write their own guide to how it works — multiple competing explanations
rather than one official text. His bill of grievances: most NIPs are just event-schema
tables not worth the increasingly bureaucratic numbering process; NIP texts are too short
to teach real usage — "specially the part about choosing what relays to use at each
step," whose neglect produced developers "writing 'clients' that only connected to a
hardcoded set of relays"; GitHub is getting worse and Nostr should dogfood its own
discussion tools; the NIP number confers an unearned "officialness aura" while good
uncodified practices have none; and dead NIPs should be able to actually die instead of
polluting every newcomer's reading list. The closing reflection: he copied the
numbered-documents style from his own LNURL spec work, but that described one main flow
with optional features — Nostr is not one flow and "clearly isn't like a
single-implementation programming-language-spec with a dictator and his committee," so
the format was a category error.

> "We stop using the NIPs repository completely."
> — https://fiatjaf.com/311b999e.html

> "...many developers ... just focus[ed] on translating between event schemas as described in the NIP text and UI elements and disregarded the hard subtleties of relay choice, writing 'clients' that only connected to a hardcoded set of relays"
> — https://fiatjaf.com/311b999e.html

### P2Panda and the super-peer curse
- URL: https://fiatjaf.com/c45ce07b.html
- Date: Feb 22 2025

Prompted by someone suggesting p2panda could replace Nostr, this becomes his general
taxonomy of the "super-peer" failure mode. p2panda's Aquadoggo node is not a relay but an
"app server": a trusted machine that abstracts away all protocol work and hands "massaged,
sorted, filtered, ordered data" to a dumb client — meaning underlings behind it "will be
controlled, censored, mislead and tricked." He identifies the same design as fundamental
to Bluesky, Farcaster, and Pubky, creeping into RSS (aggregators) and IRC (bouncers), and
experimented with inside Nostr itself — ZBD Social (his own project), Primal, Ditto,
Satlantis, Bostr — while noting SSB and Mastodon were never corrupted by it. If this
architecture were destined to dominate Nostr, he "would immediately declare Nostr a
failed experiment." What super-peers buy is the reliability pure p2p can't deliver, plus
filtering and discovery; Nostr's answer must be to lean harder on its own weirdness:
whitelisted community relays, rule-enforcing relays, search relays, AI-feed relays,
spam-filtering relays, curation relays — power in the relay layer, never interposed
between a follower and the followed.

> "The basic Nostr feature of being able to follow anyone you want and not giving a super-peer the power to break that link between follower and followed, i.e. the outbox model, is still the most basic function of relays."
> — https://fiatjaf.com/c45ce07b.html

### Why IPFS cannot work, again
- URL: https://fiatjaf.com/b8e2f959.html
- Date: May 13 2021

(Not Nostr-tagged, but the sharpest single statement of the anti-DHT conviction baked
into Nostr's "no P2P techniques, therefore it works" — his site has a whole
"How IPFS is broken" series at https://fiatjaf.com/d5031e5b.html.) The argument is a
reduction: storing all data on all computers can't work (too much data — "if you think
this can work then you're a BSV enthusiast"); sharding by pubkey still can't work (still
too much data, incentives misaligned); and IPFS's actual move — storing only *pointers*
to where data lives — just relocates the problem. Now every available file must be
continuously advertised, flooding the network, and every retrieval floods it again with
peer-to-peer request forwarding; push more storage onto peers and nodes become
unbearable, push less and flooding grows and retrieval slows. There are no incentives
anywhere in the loop. The punchline is the one he redeploys against every "decentralized"
storage scheme.

> "But if everybody just saves everything to Infura or Cloudflare then it works, magic decentralized technology."
> — https://fiatjaf.com/b8e2f959.html

### About Nostr, email and subscriptions
- URL: https://fiatjaf.com/8af0e043.html
- Date: May 24 2024

A short piece against transplanting legacy communication assumptions onto Nostr. Some
services were sending Nostr DMs containing articles as a "subscription" mechanism —
which he calls senseless: pulling DMs from relays is the same process (slightly more
convoluted, even) as pulling public events, so the assumption that a DM "reaches" a
subscriber better than the event they explicitly subscribed to is a fossil "from some
fantastic past era in which emails were 100% always seen." (He opens by admitting he
checks email once or twice a week himself.) The right move is Nostr-native subscription
flows — following creators, curation providers, communities, and relays directly, as
clients mostly already do (he cites Coracle's custom feeds). The kicker is an anecdote
about an interviewer asking Farcaster's creator whether it gives creators email
addresses: answering "no, but you can send them uncensorable DMs!" would be "getting
everything backwards."

> "Building around such broken assumptions is the wrong approach."
> — https://fiatjaf.com/8af0e043.html

---

## Theme 4 — How developers should build on Nostr

### How to do curation and businesses on Nostr
- URL: https://fiatjaf.com/1f4d0118.html
- Date: Jun 11 2024

His playbook for entrepreneurs, opening with the temptation to avoid: a closed platform
that reuses Nostr identities, siphons content from the open network, imprisons it, and
runs "an amazing AI-powered algorithm" on top — especially tempting in discovery-heavy
niches (recipes, long-form, used-goods markets, freelancing, game lobbies, professional
directories, music, restaurants). Even if it succeeds it "enshrines you as the head of a
platform": ads, a legal team, the FBI, advertisers shaping discourse. The prescription is
two-step. First, write an interoperable, ideally open-source niche client with a NIP or
NUD for its event kinds ("without interoperability this can't be Nostr"), letting users
point it at any relay for global content. Second, put your secret sauce in a relay you
run — charge, do "KYM (know your music)" validation, apply the AI sorcery there — and
make it the client's default. Your relay is your website; people are free to connect or
not; you compete on a level playing field and users get portable identities and social
graphs that don't depend on you — which is exactly why they can trust you. Crucially, the
social layer (follows, comments) must still ride the outbox model, so a musician banned
from your relay keeps their followers from nos.lol. Hardcoded defaults and manually typed
relay URLs are fine for now; relay-list-sharing events can smooth it later.

> "You don't own the network, you're just competing against other websites on a leveled playing field, so you're not responsible for it."
> — https://fiatjaf.com/1f4d0118.html

### How can web apps be independent protocol clients?
- URL: https://fiatjaf.com/6829ad8b.html
- Date: Aug 9 2025

An honest examination of a hole in the model: Nostr assumes clients are true "user
agents" — servers may be "as evil as they want as long as clients are working to serve
the interests of users" — and that holds tolerably for installed native apps (updates
are optional, rare, discernible, the same for everybody). But a web client is chained to
a DNS name and someone else's server: jumble.social works until its owner shuts it down,
is coerced into shipping malicious code, or makes an unwanted change nobody can opt out
of. His preferred fix is "subjective apps": Jumble should mean "this version of Jumble I
use (represented by this hash)," with the static HTML/JS/CSS hosted on Blossom and
addressed by content hash; users voluntarily accept the author's new releases, or adopt a
contentious fork under the same name, with these subjective naming decisions propagating
through the social graph. He rates this "very good" but weird enough that it may not
happen soon, so he offers the lazier cultural fix: users learning that clients are many
and interchangeable, keeping secondary clients (yakihonne, coracle) in parallel so any
single web client's death or betrayal is survivable.

> "a web client can't ever be trusted as an installed client can. They can't be fully user agents as they'll always remain (at least a little bit) agents of their true owner, the person who has the domain name."
> — https://fiatjaf.com/6829ad8b.html

### Redistributing Git with Nostr
- URL: https://fiatjaf.com/18ff5416.html
- Date: Apr 25 2025

The design rationale behind NIP-34/GRASP-style git-on-Nostr. He starts by conceding the
lurking comment — "but Git is already distributed!" — is technically true and practically
false: GitHub hosts essentially all of open source, and projects elsewhere lose
discoverability and contributions because contributing anywhere else means account
creation, passwords, email confirmation, and SSH setup. Moving everyone to GitLab or
Codeberg misses the point ("the open-source world controlled by two shady companies
instead of one"); the goal is that a self-hosted server in a wood cabin and a new hosting
company both compete with GitHub on equal terms. Nostr's contributions: patches as event
content (Nostr as "a quite powerful email replacement," reviving the `git send-email`
flow with better UX than GitHub's "intense clickops mixed with terminal copypasting");
issues as threaded Nostr comments (better threading than GitHub, he notes); search via
repository announcement events on public-good or curated relays, indexable by anyone
without proprietary APIs; and CI as a paid-in-sats service triggered by Nostr events
instead of GitHub webhooks. The essay doubles as a worked example of his generic recipe:
find the network-effect chokepoint, replace its coordination layer with signed events on
competing relays.

> "What we want is to give every person the opportunity to host their own Git server without being ostracized."
> — https://fiatjaf.com/18ff5416.html

> "we must remove the network-effect centralization pressure."
> — https://fiatjaf.com/18ff5416.html

---

## Coverage notes

- Source of the list: https://fiatjaf.com/-/tags/nostr (24 entries, no pagination).
- Read in full but not annotated above (minor/operational): "Setting up a handler for
  `nostr:` links on your Desktop..." (https://fiatjaf.com/33ec0995.html, a how-to).
- Related non-Nostr indexes on his site that inform the philosophy: the "How IPFS is
  broken" series (https://fiatjaf.com/d5031e5b.html) and his Bitcoin writings
  (https://fiatjaf.com/23977266.html).
- All quotes are verbatim from the pages as fetched on 2026-08-31 (his original spelling
  and grammar preserved, including typos such as "thas", "implemneted", and
  "bureaucractic" where they occur inside quoted matter — none of the quotes above
  contain them, but summaries paraphrase around them).


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/on-nostr.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/fiatjaf/on-nostr.md` · snapshot 2026-10-10

# fiatjaf on Nostr: what the creator of the protocol publishes on his own protocol

Research date: 2026-08-31. Method: read-only `nak req` against fiatjaf's own advertised
write relays plus fallbacks. No events were published or signed.

- **Pubkey (hex):** `3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d`
- **npub:** `npub1gcxzte5zlkncx26j68ez60fzkvtkm9e0vrwdcvsjakxf9mu9qewqlfnj5z`
- Sources queried: `wss://pyramid.fiatjaf.com` (his own relay), `wss://purplepag.es`,
  `wss://relay.damus.io`, `wss://nos.lol`. (`wss://relay.nostr.band` timed out from this
  machine, so no NIP-50 keyword search was possible; notes were sampled instead.)
- Data volume: **~250 unique kind:30023 articles** (deduped from 268 raw events by d-tag)
  and **425 kind:1 notes** (span 2026-04-16 → 2026-08-30).

---

## 1. Profile (kind 0)

Latest kind:0 (event `31ae13f6…`, updated 2026-08-07). Content is minimal, in character:

```json
{
  "name": "fiatjaf",
  "about": "~",
  "picture": "https://fiatjaf.com/static/favicon.jpg",
  "nip05": "_@fiatjaf.com",
  "lud16": "@npub.cash",
  "website": "https://stuff.fiatjaf.com/",
  "banner": "https://cdn.satellite.earth/8f10244a….jpg"
}
```

The `about` field is literally a single tilde. Identity is anchored by NIP-05 at the root
of `fiatjaf.com`.

## 2. Relay list (kind 10002 / NIP-65)

Latest relay-list event `2cd4d1d5…` (2026-06-28). Note the deliberate read/write split —
he practices the inbox/outbox model he preaches, including a dedicated spam-filtered
`/inbox` endpoint on his own relay:

| Relay | Mode |
|---|---|
| `wss://pyramid.fiatjaf.com/` | write |
| `wss://basspistol.org/` | write |
| `wss://spatia-arcana.com/` | write |
| `wss://theforest.nostr1.com/` | write |
| `wss://relay.44billion.net/` | write |
| `wss://pyramid.fiatjaf.com/inbox` | read |
| `wss://inbox.relays.land/` | read |
| `wss://spatia-arcana.com/inbox` | read |
| `wss://basspistol.org/inbox` | read |

His canonical home relay is `pyramid.fiatjaf.com` (his own "Pyramid" relay software,
WoT-whitelisted). His NIP-05 file also announces it.

## 3. Long-form articles (kind 30023)

~250 unique articles exist under this pubkey. The bulk (~225) was **imported in one batch
on 2024-01-14** and is his pre-Nostr blog archive (fiatjaf.com): Bitcoin/Lightning
engineering (Drivechain, Eltoo, HTLCs, bolt12), an entire "IPFS problems" series ("How
IPFS is broken", Pinning, Dynamic links, Shitcoinery…), critiques of DIDs/ION, Austrian
economics, and personal essays in Portuguese. Below are the **Nostr-specific articles**,
newest first, each with d-tag, date, summary, and quotes.

### nostr - Notes and Other Stuff Transmitted by Relays (`d:nostr`, 2025-12-19)
The founding document, maintained as a living replaceable event. Defines the protocol in
one line and explains why the alternatives fail: Twitter (ads, bans, addiction
techniques), Mastodon (identity welded to domain names, migration "doesn't work in an
adversarial environment"), SSB (great but over-complicated, chain-of-updates bloat), and
run-your-own-server schemes ("they require everybody to run their own server"). The core
architecture: clients talk to many dumb relays, relays never talk to each other,
signatures are verified client-side. Censorship-resistance comes from free entry on the
relay side ("there will always be some Russian server willing to take your money in
exchange for serving your posts"). Spam is a relay-policy problem, not a protocol
problem. Data storage scales because content only needs to sit where its audience reads.
> "It doesn't rely on any trusted central server, hence it is resilient; it is based on cryptographic keys and signatures, so it is tamperproof; it does not rely on P2P techniques, therefore it works."
> "A relay is very simple and dumb. It does nothing besides accepting posts from some people and forwarding to others. Relays don't have to be trusted."

### Nostr: a quick introduction, attempt #3 (`d:0601c1ca`, 2025-12-02)
Third attempt at a minimal explanation: Nostr is only two descriptions — a signed message
format ("event") and a server interface ("relay"). His target is the misconception that
Nostr is "a set of free servers that are readable and writable by everyone", which leads
to bad questions ("who will run these relays?"). Whether a relay is free, stores your
event, deletes it, or restricts reads is entirely the relay operator's business.
> "Nostr is not any specific set of relays, and relays are not meant to be public or free."
> "Don't be one of these people."

### The only solution to Nostr spam (`d:6fcc40bf`, 2025-11-17)
His definitive spam essay. Main feeds have no spam problem (you follow whom you follow).
Inbox/notification spam is "trivial to fix": clients must read mentions only from the
user's NIP-65 "read" relays, and users must pick read-relays that actually filter
(WoT-whitelisting like his Pyramid `/inbox`, nip05-requiring, PoW or paid relays as
fallback). The hard case is *other people's threads*: you fetch replies from *their*
read relays, so if their thread is full of spam "that is their fault… for not picking
'read' relays correctly" — a deliberate incentive structure. Client-side-only filtering
(mutes, local WoT) can only be last-mile: content must be downloaded before it can be
filtered, so purely local filtering means "downloading gigabytes of spam all day
everyday", and it creates a tragedy of the commons.
> "Enforcing restrictions once per write is much more effective and efficient than trying to enforce them on every read." *(companion note, see themes)*
> "Eventually people should stop going to someone else's house if the house is always dirty."

### How can web apps be independent protocol clients? (`d:6829ad8b`, 2025-11-15)
Native clients can be true "user agents"; web clients cannot, because they hang off a
DNS name owned by someone else — "they'll always remain (at least a little bit) agents of
their true owner". Proposes "subjective apps": a client is a content hash, hosted on
Blossom, updated voluntarily, with contentious forks propagating socially through follow
graphs. Fallback ("lazier") solution: users simply learn that clients are many and
interchangeable and keep secondary clients in parallel.
> "A fundamental assumption of Nostr is that servers are free to be as evil as they want as long as clients are working to serve the interests of users."

### Visual depiction of the architecture of 3 protocols (`d:52a0d652`, 2025-10-04)
Short illustrated comparison: Fediverse = clients talk to one server, servers federate;
Nostr = "clients can talk to multiple servers, which gives us a very chaotic ecosystem of
signed messages"; ATProto = social-server functions split into a pipeline of specialized
big servers.

### The end of NIPs (`d:311b999e`, 2025-08-15)
Proposes abandoning the NIPs repository: keep only a minimal registry that reserves kind
numbers with one-line descriptions, and let anyone write competing guides for how kinds
work. Diagnosis: most NIPs are just event-schema tables; NIP texts are too short on the
part that matters ("specially the part about choosing what relays to use at each step
(which caused many developers to just… write 'clients' that only connected to a hardcoded
set of relays)"); NIP numbers give bad ideas an "officialness aura" while good
single-implementer practices lack one; GitHub should be replaced by dogfooded Nostr
discussion. (Follow-through visible in his 2026 notes: he now maintains
`nostr-protocol.github.io/registry-of-kinds/`.)
> "This flexibler approach allows bad or abandoned NIPs to effectively die such that they don't continue to pollute the minds of every new programmer."

### Nostr is not decentralized nor censorship-resistant (`d:87a208d9`, 2025-08-10)
A self-critical experiment: he published identical notes simultaneously, one to three big
relays, one only to `pyramid.fiatjaf.com` (which is plainly announced in his NIP-05 and
NIP-65). The big-relay copy got vastly more engagement — proof that clients are not
actually following users at their announced relays, so a person banned from the 3 biggest
relays would instantly lose ~90% of reach. Concedes Peter Todd is right about Nostr
*today*, but wrong that it is *inherently* centralized: it's a client-implementation
failure, fixable without protocol changes.
> "If Nostr was really censorship-resistant that shouldn't have happened at all."

### Nostr is pro-censorship (`d:3a914800`, 2025-05-28)
Provocative framing of the same doctrine: the "global pool of content" model is what
kills open platforms, because someone must host everything and no global agreement on
acceptable content can ever exist. On Nostr there is no global pool by definition; every
relay is free to impose any policy, and readers are responsible for choosing where to
read. Relay-level "censorship" (moderation) is thus a feature that makes the network
work.
> "No relay has any obligations to please all the peoples of the Earth and is free to impose any limits or policies it wants."
> "Of course all of that breaks down if apps relinquish their obligation to figure out what relays to read from and decide to read from a static list of relays, but that should have gone without saying."

### Keys are meaningless (`d:cb4ca47a`, 2025-05-28)
Against key-worship ("not your keys, not your notes", "self-sovereign identity").
Keys are just numbers; what matters is the ability to act — i.e. relays.
> "Having a key is meaningless if you cannot publish messages to where the people you're trying to reach can read them."
> "Is a person locked in a cage 'free'? If you use the key-worshipper logic then yes."

### Redistributing Git with Nostr (`d:18ff5416`, 2025-04-25)
The NIP-34/GRASP manifesto. Git is distributed but GitHub centralizes it via the
network-effect of accounts and pull-request UX. Goal: anyone can host a Git server
without ostracism, hosting companies compete on a level field. Nostr is "a quite powerful
email replacement", so patches fit event contents (the `git send-email` flow revived);
Issues are just threaded comments (Nostr does it better than GitHub); search works via
kind:30617 repo-announcement events indexable by anyone; CI can be triggered by Nostr
events instead of proprietary webhooks.
> "We must remove the network-effect centralization pressure."

### The fiatjaf Nostr fund (`d:fd6dc37c`, 2025-04-25)
Ledger of how Jack Dorsey's Dec-2022 donation "has been misused so far": every bounty
from Dec 2022 to Mar 2025, in sats, with recipients and projects. Reveals his priorities:
repeated bounties specifically for **outbox/gossip-model implementation** in Snort,
Coracle, Nozzle, Camelus, Gossip ("display relays, follow event hints"), relay tooling
(strfry, nostr.watch), search (nos.today), and RSS-reader Nostr integrations. Notable
line: "William Casarin: 7 BTC - splitting the fund".

### P2Panda and the super-peer curse (`d:c45ce07b`, 2025-02-22)
Reviewing p2panda's Aquadoggo node, he identifies the recurring failure mode of
"decentralized" protocols: a trusted super-peer that hands massaged, sorted, filtered
data to dumb clients — the design of Bluesky, Farcaster, Pubky, RSS aggregators, IRC
bouncers, and even Nostr experiments (ZBD Social — his own, Primal, Ditto, Bostr).
Super-peers buy reliability/filtering/discovery that pure p2p can't deliver; Nostr's
multi-relay architecture is the alternative answer, and should lean into specialized
relays (communities, search, curation, spam filtering) while the outbox model preserves
the follower–followed link no super-peer can break.
> "If I believed the answer was 'yes' I would immediately declare Nostr a failed experiment, but I don't."

### The case against edits (`d:ad84e3b3`, 2024-11-07)
Edits to kind:1 are "a centralizing force… a slippery slope". If widespread they become
de-facto mandatory (non-implementing clients display false information), raising the
barrier to entry for the micro-clients he wants everywhere. Counter-evidence to
"everyone has edits": Bluesky, Instagram comments, TikTok, YouTube, email, 15 years of
Twitter. Alternatives: annotations that degrade to replies, or send-delay ("undo").
> "If edits become widespread they necessarily become mandatory."
> "The market has decided for Facebook, Instagram, Twitter and TikTok. If we were to follow what the market had decided we wouldn't be here."

### kind:1 maximalism and the future of other stuff (`d:cd8ce2b7`, 2024-10-26)
How should "other stuff" (articles, podcasts, livestreams) reach microblogging feeds?
Rejects (a) publishing everything as kind:1 and (b) superapp clients rendering every
kind (centralizing: pushes clients to be huge). Endorses (c): different kinds referenced
from kind:1 announcement notes with NIP-31/NIP-89 handoff to dedicated microapps. kind:1
is special — "the public square of Nostr" — so it must stay simple enough that dozens of
small clients can handle it.
> "It's ok if Nostr ends up having just 2 recipe-sharing clients, but it must have dozens of microblogging clients."

### How to do curation and businesses on Nostr (`d:1f4d0118`, 2024-09-18)
The business blueprint: don't build a closed platform that imprisons Nostr content behind
an algorithm. Instead (1) write an open niche client, (2) run a value-adding relay —
"your relay is like your 'website'" — where your magic sauce (curation, KYM, AI
filtering, payments) lives. Users keep unified identity and outbox-model portability: if
a musician you follow gets banned from the music relay, you still see them.
> "They do not depend on you, therefore they're more likely to trust you."

### Nostr: a quick introduction, attempt #2 (`d:ded75cbc`, 2024-09-06)
The political-economy framing: Nostr doesn't subscribe to "free speech" ideals; it
"simply says that servers are private property and establishes a generalized framework
for people to connect to all these servers, creating a true free market in the process".
Nostr as the public road between private stores.

### Why relay hints are important (`d:8ce7df34`, 2024-06-13)
Against reducing relay discovery to kind:10002 alone (prompted by Coracle removing
event-reference relay-hint following — "a catastrophic idea"). Seven concrete scenarios
where hints are the only path: community/NIP-29 posts, conference-scoped relays, archival
relays (cellar.nostr.wine) outside the outbox list, topical relays, dual personas on one
key, kind-restricted relays, and the fully-banned user whose nprofile relay hints are his
lifeline ("Alex Jones could still live a normal Nostr life").

### About Nostr, email and subscriptions (`d:8af0e043`, 2024-05-24)
Against "DM subscription" services: pulling DMs from relays is the same (slightly more
convoluted) mechanism as pulling public events, so DMs confer no deliverability magic —
that's an email-era assumption smuggled into Nostr. Build Nostr-native subscription
flows (custom feeds, curation, communities, relays) instead.
> "Building around such broken assumptions is the wrong approach."

### Censorship-resistant relay discovery in Nostr (`d:bc63c348b`, 2024-03-19)
History and doctrine of the gossip/outbox model: original vision (relay hints + kind:2
recommendations + manual action), Gossip client as first true implementation (NIP-05
hints, kind:3 lists), then NIP-65 crystallizing it. Warns against equating "outbox model"
with NIP-65 alone — nprofile/nevent hints, tag hints, NIP-05, manual action, hardcoded
values and social-graph heuristics should all be mixed.
> "Reliance on third-parties, hardcoded values, social graph, and specially a mix of multiple approaches, is what Nostr needs to be censorship-resistant."

### Nostr: a quick introduction, attempt #1 (`d:d0b15ac7`, 2024-01-29)
The friendliest of the three intros: Nostr as "very much like the internet itself",
honest about the tradeoffs — no guarantees any relay has what you want, replies may
differ between users, and the nsec is "painful, but cool".
> "To conclude: Nostr is like the internet (or the internet of some decades ago): a little chaotic, but very open."

### From the 2024-01-14 archive import (still Nostr-canon):
- **Why I don't like NIP-26 as a solution for key management** (`d:4c79fd7b`) — delegation
  was fine as an optional bridge for custodial platforms (Minds); as *the* key-management
  scheme it becomes de-facto mandatory for every client and "breaks a lot of the
  simplicity of the protocol".
- **Thoughts on Nostr key management** (`d:72f5d1e4`) — a menu (NIP-41, NIP-46, NIP-07,
  hardware, musig/frost, social recovery) plus deflationary premises: "For the vast
  majority of people, Nostr keys aren't a target as valuable as Bitcoin keys"; "losing
  keys and starting fresh isn't a big deal"; identity, unlike money, is recoverable.
- **A vision for content discovery and relay usage** (`d:3f106d31`) — the ur-text of the
  outbox model: classify relays (spammy/safe/closed), bootstrap profile→relay mappings
  from hints in everything, fetch home/profile views by author from their relays
  (spam-immune because the filter is strict), fetch reply/global views only from safe
  relays. "To write Nostr applications and to use Nostr one must embrace the inherent
  chaos."
- **Bluesky is a scam** (`d:ab1127fb`) — atproto's three claims (protocol, identity,
  openness) dissected: the protocol is "a description of whatever the Bluesky app and
  servers do"; DID Placeholder is "a normal old boring trusted server controlled by
  Bluesky"; the BGS chokepoint means readers control nothing.
- **The problem with DIDs** (`d:98aab9a5`) — "supporting DIDs" would mean implementing a
  gazillion methods and blockchains; the standard must fail, degenerate to `did:key`, or
  centralize into shared libraries calling servers.

---

## 4. Themes from kind:1 notes

Sample: 425 notes, 2026-04-16 → 2026-08-30, fetched from pyramid.fiatjaf.com,
relay.damus.io, nos.lol. His notes are mostly replies: terse, combative, concrete. The
recurring themes, with verbatim quotes (hex event ids):

### Theme 1 — Spam is solved at relays, on write; never client-side, on read
The single most repeated position. Filtering belongs in chosen inbox/read relays; local
WoT and mutes are last-mile at best, and spam in your thread is *your* relay
configuration's fault.

> "Let me say it clearly: The only way to fix reply spam is for people to use inbox relays that filter spam. Clients then should read replies by default only from people's advertised relays. Finally, if you see reply spam in someone else's thread it should be clear whose fault that is, so that person will be ashamed and fix it."
> — `8d3c1fb6c75f4529539a33a8a4522f8c9147bbf5ac79824d401ed5b22e252fca` (2026-08-24)

> "Wrong, the only scalable and decent way to prevent against spam is by picking relays that enforce limits and reading from such relays on a case-by-case basis. […] In other words: enforcing restrictions once per write is much more effective and efficient than trying to enforce them on every read."
> — `87a713726637ae1f491825b3d829cf62371865bdefe4c885421c5e4ed5eba11c` (2026-07-27)

> "Lots of people think that, but they are wrong. Clients are fragile and powerless against the lawlessness of the internet. Imagine your client having to download and process thousands of evil comments and mentions coming from random public keys?"
> — `f29aa37daff86fff2ad0f2aeda42b41b54fd7065fd8f6f6022cc23545e0f0cab` (2026-08-15)

> "The fact that people like the fake Gaza guy bot […] are still showing up basically everywhere is proof that no lesson was learned from all these years of spam, claims that 'WoT fixes this', excessive muting and that any basement kid that wanted to actually break the Nostr experience for everybody would be able to do it easily. But I still have hope the tide will turn."
> — `4d528db962e8bc46a1488b8c8122297f24b594df11ed31a39e59f4f526f91691` (2026-08-25)

### Theme 2 — Relays are private property; moderation/deletion there is legitimate and good
The "Nostr is pro-censorship" doctrine, applied daily: relay owners may delete, ban and
whitelist freely; users moderate their own comment sections through their inbox relays;
nobody is entitled to a single canonical reply section.

> "Do you allow anyone to enter your house and shit on the floor? I don't get why you're so against people deleting notes from relays they control. That doesn't hurt any of the Nostr ideals."
> — `c458230601b772643284c16f33929cba90b158c2fd6b461c3077141075d56593` (2026-08-24)

> "Clients should double down on allowing people to moderate their own comment sections: eliminate annoying, unwanted, harassing replies by just deleting them from your own inbox relays. Maybe even ban someone from ever replying or mentioning you again."
> — `e4dd276af0ff994dd784608e00d1ce68b041ab2a942d26c3f00b27e04d5713f1` (2026-08-15)

> "You are free to not look at them, you are free to block them in your relay, but you can [sic — can't] stop people from writing whatever junk they want in their own relays (or whatever other relays that decide to accept them)."
> — `ba3d78c19d457487c0d84128c3e44c62ecb3029c9149ad0615062a86d3da355b` (2026-07-30)

Related: "What is the difference between spam and a comment you don't like?"
(`9027b2f7a29d6e55…`, 2026-08-15) — the two are continuous, which is exactly why policy
belongs to each relay, not the protocol.

### Theme 3 — The outbox duality; hardcoded relay lists are the cardinal client sin
His model of reading, stated as a two-scenario duality; and his standing code review for
new clients is checking whether they fetch users' NIP-65 lists.

> "You connect to random relays and fetch only from specific authors from such relays, that's in one scenario. Then there is a different scenario in which you want to open yourself to reading stuff from strangers, in that scenario you choose relays wisely and take what they give you. That's the fundamental duality of Nostr, or something."
> — `992c11260849d7756a68d18af57ffe1b2068ed9b50fe49926860af6a841df2d0` (2026-07-29)

> "From a quick glance at the code you have a set of hardcoded relays that the app uses at all times and at no point you try to fetch outbox relays of users or their list of DM relays. There is another 'pool' that the app maintains with other relays. I don't know where those come from, but apparently you blast every DM to all these relays too?"
> — `00a1a0a1aed223d776d9a791b9ce5fa6e2a9ab3b713fc79d5af30e1e077ca5f4` (2026-06-03, reviewing a DM client)

> "People have to wake up for the fact that relays are just simple servers and clients can choose from which relays they read."
> — `4a04e393485e597400ba212f7c300f7bc5318bfb8b23cf1d13703851e294e0a5` (2026-06-24)

He also polices this in the tooling he uses: "why does 'req -p $ME -k 1 -k 1111' […]
connect to wss://relay.primal.net if that is not in my inbox list?"
(`7de7839a6eede315…`, 2026-08-28).

### Theme 4 — Relays as communities / relay feeds are the underused frontier
Relays are more than pipes: they are communities, curation surfaces, and feeds. He
promotes "relay feeds" as a first-class client feature (his own client work — Hallway, a
Jumble fork — is built around them) and wants relays with personality.

> "But don't tell people to add this relay to their list of 'read' relays. Instead they should favorite it as a relay feed, as it's the perfect use case for this and works great. This works on dozens of clients now: Grimoire, Jumble, Nostur, Yakihonne, Hallway, Cor[acle]…"
> — `542a16016b932ed5…` (2026-08-20)

> "Relays could have been 'just a keypair' on Nostr too, but that would be stupid, because one of the functions of relays is to solve connectivity. Because p2p doesn't really work on a global scale relays are both classic web servers […] and 'communities'."
> — `5e2e8c2094cc58a8d090603204a1455376d8baebe32bab597aafc19d68f65650` (2026-05-11)

> "It is not expensive to run a relay though. […] the cost is probably less than $1/mo […] I am not trying to win the argument of how easy it is to run a community or a relay, though. The entire point of Nostr is that most people don't have to run servers."
> — `5a77ac1d1f07ddef856aa06b86b8be1e7e168c1a97b3ba01a93243c89528359a` (2026-05-14)

> "Stacker News is like a single relay. Nostr is supposed to operate with an ecosystem of free-entry relays […] Stacker News should really transition to being an actual relay, I'm still hoping for the day that will happen."
> — `48b46fc140d99166afcc319ed2a22a30cc9dd5c9cc2868e3acf59b4d465995a4` (2026-08-24)

### Theme 5 — Client minimalism; against feature bloat, event pollution and X-cloning
Consistent with "The case against edits" and "kind:1 maximalism": clients should be
simple, opinionated, and stop copying X while over-optioning everything.

> "Why are all Nostr clients trying to copy X, and yet they have a thousand emojis to select reactions from when X only has 1? Who decided that more is always better than 1 and making the user choose is always better than simplifying things?"
> — `1a9363a12a09ffd7048894f73a0b6d9f8422769ebf1b3e03f082a6c95fd1c4f5` (2026-05-13)

> "Instead of polluting all the events with a 'client' tag can you guys please agree on publishing a kind:1729 event (I just made that number up) with the client name in it every day […] Also please remove the useless 'alt' tags (specially from kind:1), that experiment has failed."
> — `02b07dbf442a59f07c29d0b06d510a7fcd2476e45ff2d7e5d9286abf6ba0801d` (2026-06-20)

> "What are 'settings'? Relays are not 'settings'. Do Nostr apps need a 'settings' menu? Maybe a 'preferences' menu where the user can change the color […] but not 'settings'."
> — `457d74404cbaca9160604aeb293ecdba8fa2654bd77fe33487eabdb639130b2e` (2026-08-21)

His own client wish-list (note `30acd3f89129d1de…`, 2026-08-04, describing Hallway)
starts: "No zaps or Bitcoin anywhere. A single 'like' button with no millions of emoji
options" — then goes deep on relay feeds, follow sets, outbox syncing, kind:1111
comments, and NIP-43 relay membership.

### Theme 6 — Nostr is the possibility, not a community; keys are pragmatics, not religion
He fights both the "Nostr = Bitcoiner community" perception and nsec-dogma; pragmatic on
key storage, bullish on NIP-46 bunkers and FROST ("pomegranate").

> "The problem is that all clients present Nostr as a thing with people inside, a 'community' of sorts (a community of right-wing raw-meat-eater Bitcoiner assholes, or something like that), but Nostr isn't that, Nostr is the possibility, not the concretude."
> — `c7f6b4e11ede0dd4123140d23b37cf14cc6e5aba84517432ca0a7144152a8994` (2026-08-20)

> "I think it is a very reasonable flow for an introductory client to generate an nsec locally for the user and store it locally. Then, later, […] that client acts as a NIP-55 or NIP-46 local provider for that user or to setup a #pomegranate bunker."
> — `e858aabdb33984f527b6b554018a36caf59c8bdf98249d98b25162eda9bd8fd8` (2026-08-20)

> "Maybe the entire 'don't put nsecs in apps' is kind of a moot point. If the app developer takes basic precautions and is not insane the odds of the key being stolen are pretty small."
> — `9ebbbc3c10ff003c28daa97665bd5946ef726289d5ea1cac561a5f121b517551` (2026-08-20; goes on to list the real risks: web apps, evil apps, physical access, OS takeover — "Amber/NIP-55 defends against the first two")

### Recurring sub-threads (smaller but persistent)
- **NIP-17/NIP-4E DMs**: continuous field-testing of DM clients (Nospeak, Wisp, Jumble,
  Coop) — "I just wanted proof that NIP-17 could work reliably, and now I got it"
  (`81dabb9e6d7ce4d1…`); wants NIP-17 marketed as a generic open DM protocol
  (`c28794f6ddce5e49…`); frustrated by clients that don't use receivers' DM relays.
- **NIP-29 groups**: "Much like Nostr, NIP-29 is just signed notes on servers"
  (`7d302dd555eda7a0…`); vs. keypair-owned groups: "In NIP-29 you only give partial
  authority to a server at all times, you always keep your right to migrate"
  (`77d6c3d3900ddafa…`).
- **NIP-34/GRASP git**: still dogfooding and still frustrated — "I'm sorry to all people
  who send me NIP-34 patches […] I basically never look at them" and asking peers "will
  we ever get a 'merge' button that applies the patch and pushes the updated repository
  directly to our grasp servers?" (`b507bdf0b5698d00…`, 2026-08-30); laments zero Nostr
  mentions in HN threads asking for decentralized git (`b2529a02cb447fa3…`).
- **Anti-p2p/anti-IPFS**: "On Nostr these costs are clear and obvious with the concept of
  relays. On IPFS that cost is distributed to people who never signed up for that job"
  (`5a77ac1d…`); echoes the archive's whole IPFS-problems series.
- **Tooling**: promotes `nak` features (`nak profile`, `--outbox` flag: "Use --outbox so
  it publishes to your relays automatically", `bd564cdeaeb15cdf…`), his Pyramid relay
  (subscription introspection), viewsource.win (NIP-34 viewer), registry-of-kinds.

## 5. One-paragraph synthesis

Across articles and notes, fiatjaf's message is remarkably coherent: **relays, not keys,
are the point of Nostr**. Keys merely make relays trustless; relays are private property
with free entry, and every hard problem — spam, moderation, discovery, curation,
business models, even censorship-resistance itself — is meant to be solved by *choosing
relays*, with write-side enforcement rather than read-side filtering. The great failure
mode he attacks over and over is clients that hardcode a static relay list and treat
Nostr as "a set of free public servers", which quietly re-centralizes the network (his
own two-notes experiment proved it). The second failure mode is complexity creep — edits,
superapps, emoji walls, tag pollution, bureaucratic NIPs — anything that raises the
barrier to writing a small independent client. What he wants built: opinionated
micro-clients, value-adding filtered relays (inbox relays, relay feeds, communities),
outbox-model everything, and boring-but-working sub-protocols (NIP-17 DMs, NIP-29
groups, NIP-34 git) that dogfood Nostr instead of GitHub and Twitter.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/README.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/no-solutions/README.md` · snapshot 2026-10-10

# No Solutions — A Sovereign Engineering Podcast

> "No solutions; only trade-offs. Walking towards a better internet."

Hosted by **Gigi** (dergigi — Bitcoin author, Sovereign Engineering
co-founder) with **Pablo Fernandez** (pablof7z — NDK author, SEC co-founder)
as co-creator and most frequent guest. Walking dialogues recorded on Madeira
with participants of the Sovereign Engineering cohorts — deliberately
unpolished, explicitly "we do not have the answers." 37 episodes,
Feb 2025 → Aug 2026 and ongoing. The name is Thomas Sowell's line: *there
are no solutions, only trade-offs.*

The show's distribution is itself a Nostr demo: episodes are Nostr events,
audio and full SRT transcripts are content-addressed Blossom blobs, RSS at
<https://sovereignengineering.io/dialogues.xml>, no YouTube. It is
effectively the primary-source record of how the builder generation after
the founding documents thinks — guests include hzrd149 (noStrudel/Blossom),
Martti Malmi (Satoshi's first collaborator, Iris), Calle (Cashu), Franzap
(Zapstore), Justin Moon, Jeff G (White Noise/MLS), Sandwich (nostr.watch /
napplets).

In this folder: [`episodes.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/episodes.md) — full episode table plus
deep transcript notes on eight design-relevant episodes and a theme
synthesis.

## The eight doctrines of the show

1. **There is no global.** Global state, usernames, view counts, guaranteed
   deletion, consistent group state — all unavailable without rebuilding
   Bitcoin. Design for partial views; resolve names through *your* graph
   ("who is Pablo, for me"); make state computable from an inconsistent
   event swarm. "The eternal September of Nostr is going to be people coming
   in and building REST APIs that give you global feeds."
2. **Authenticity lives in the data; rug-pull resistance is the killer
   app.** "The authenticity of the data is in the data… the signature is
   there. That's all that matters" (Pablo). "A server truly is an external
   dependency… **a relay is not**, because it can be internal — on my phone,
   at home — completely exchangeable" (hzrd149/Gigi). For developers: APIs
   that cannot be revoked, integrations that never need the five-year
   rebuild — "the permission's gone."
3. **State trade-offs out loud.** Mints can rug you — that's the point,
   keep pocket change in them; encryption above ~20 group members is
   theater; Zapstore consciously dials decentralization down for credible
   exit. The diagnosed newbie failure mode: refusing a trade-off and thereby
   reintroducing a central authority (Passkeys, home servers, global
   registries, DRM, IPFS's "curse of perfect knowledge").
4. **Local first — with the relay as the unit.** Every app should pass the
   **flight-mode test** via a local relay; "private doesn't mean on one
   machine — private means encrypted with your key," while copies live
   everywhere; the local event cache doubles as the only personalization
   algorithm they endorse. Censorship resistance, marketed honestly, is
   "100% uptime."
5. **WoT + zaps = spam defense and realness.** The social graph is "the
   only proper solution to spam" (Malmi — note: he runs it client-side,
   where fiatjaf wants it relay-side; live disagreement); PoW punishes
   humans more than spammers; realness is rankable from protocol signals
   (NIP-05, zaps sent *and* received, nutzaps-can't-be-faked).
6. **Nostr is the substrate for AI agents.** "You need a neutral substrate
   that has money, identity, cryptography, and web-of-trust baked in"
   (Pablo). Agents mint npubs, hold NIP-60 wallets, zap the authors of
   signed knowledge that helped them; AI slop makes signed provenance
   existential; and there is "a window of opportunity to steer the LLMs…
   into a freedom-tech direction" (Malmi) — publish your thinking or be
   absent from the models.
7. **Ship ugly, scratch your own itch, compose small things.** The
   12-month game of chicken; away from everything-clients toward
   specialized micro-apps and composable applets ("you should be able to
   compose your clients" — Sandwich); Nostr as *less to build* — auth,
   storage, identity come free.
8. **For people at the edges, on Linux's timeline.** Freedom tech serves
   the deplatformed and KYC-refused first; "wrecked education" converts the
   rest. "Nostr is the Linux of social media" — win the neckbeards, run
   everything decades later — and it stays healthy precisely because "you
   don't make money with protocols."


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/episodes.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/no-solutions/episodes.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.

# No Solutions — A Sovereign Engineering Podcast

> "No solutions; only trade-offs. Walking towards a better internet. Est. 882,690."
> — show tagline (the "Est." is a Bitcoin block height, ≈ Feb 2025)

Research notes compiled 2026-08-31. Sources: the official RSS feed (which carries full
show notes **and** per-episode SRT transcripts hosted on Blossom), plus full transcript
reads of 8 episodes. Attribution note at the end of §1.

---

## 1. What the podcast is

**Host:** Gigi (dergigi, `gigi@sovereignengineering.io`), Bitcoin author/educator and
co-founder of **Sovereign Engineering** (SEC), the recurring six-week builder cohort on
Madeira. **Pablo Fernandez (pablof7z**, NDK author, SEC co-founder**)** is the co-creator
of the format and by far the most frequent guest (10 of 37 episodes). The show *is* the
public face of Sovereign Engineering: nearly every guest is a cohort participant, and
episodes are recorded **while walking** (usually on Madeira — waves, wind, leaf blowers
and all, deliberately unpolished).

**Premise:** "We do not have the answers" (ep 02). Instead of presenting solutions, the
show does *dialogues* — distributed cognition applied to the question of how to rebuild
the internet on Bitcoin + Nostr rails. The name is the Sowell line: *there are no
solutions, only trade-offs*. Explicit goals stated in early episodes: (1) a time capsule
of how builders thought about Nostr at each moment, (2) getting better at explaining to
ordinary developers why any of this matters, and (3) — stated half-jokingly by Gigi and
Martti Malmi in ep 21 — feeding freedom-tech thinking into future LLM training data
("the same part why I'm recording these things… to get the propaganda out and feed it
into the agents so that they know what's up").

**Where it lives (the distribution is itself a Nostr demo):**

| Channel | Address |
|---|---|
| Web page | https://sovereignengineering.io/podcast |
| RSS (Podcasting 2.0) | https://sovereignengineering.io/dialogues.xml |
| Podcast Index | https://podcastindex.org/podcast/7206062 |
| Nostr (native) | each episode is a Nostr event; `<link>`s are njump nevent URLs; profile `nosolutions@sovereignengineering.io`, npub `npub1n00yy9y3704drtpph5wszen64w287nquftkcwcjv7gnnkpk2q54s73000n` (browsable via castr.me) |
| Audio + transcripts | m4a/f4a enclosures **and** SRT transcripts are content-addressed blobs on Blossom (`haven.dergigi.com` / `haven.sovereignengineering.io`) |
| Value4Value | lightning keysend split to Gigi; CC-BY-SA-4.0 |

There is **no YouTube channel** — the show is audio-only by design ("I'm not a fan of
video content", Gigi, ep 21). The Blossom hosting is eaten dog food: in ep 13 Gigi
recounts that when the SEC haven relay/Blossom server went down, the whole podcast
404'd — which he uses on-air as proof that Blossom's self-healing-links story is still
an unimplemented low-hanging fruit.

**Run:** 37 items (ep 00 teaser + eps 01–36), Feb 2025 → Aug 2026: weekly-ish
Feb–Jun 2025, then batched drops per SEC cohort (SEC-05 Oct 2025, SEC-07 Mar–Apr 2026, Oslo May–Jun 2026,
SEC-08 Jul–Aug 2026). Ongoing as of Aug 2026.

**Naming ambiguity:** the user's "no-sollultions" resolves confidently to this show.
There are unrelated podcasts with similar names (e.g. generic self-help shows on podcast
apps); every Nostr/freedom-tech reference ("No Solutions by Gigi", podcastaddict,
podcast.app, Tomer Strolight's announcement post) points to this one.

**Attribution caveat:** the official SRT transcripts carry no speaker labels. Speakers
below are attributed from context (who is being asked, who owns which project, RSS
show-note attributions). Where genuinely uncertain I mark the claim as shared.

---

## 2. Episode list

Dates are RSS `pubDate`; several 2026-03/04 items were recorded months earlier (noted).
Guests are Nostr handles as used on the show.

| # | Title | Guest | Date | One-line topic |
|---|---|---|---|---|
| 00 | Test Recording / Teaser | Pablo | 2025-02-07 | Teaser; "recorded at 882,688" |
| 01 | Start Ugly | Pablo | 2025-02-09 | Ship early and ugly; "happiness is shipping"; Highlighter hang-ups |
| 02 | There is No Global | Pablo | 2025-02-15 | Why global state/usernames/view-counts are impossible; the show's premise |
| 03 | Data Ownership is a Lie | Pablo | 2025-02-23 | Ownership vs control; you can't prove deletion; bearer data; nutzaps |
| 04 | Ecash Fixes 402 | Calle | 2025-03-13 | Ecash as the missing HTTP-402 payment; "neither nostalgia nor utopia" |
| 05 | Prompt & Pray | Paul | 2025-03-18 | What should the next internet look like; homecooked apps vs digital gulags |
| 06 | The Winds of AI | Pablo | 2025-03-27 | Attention, feeds as slot machines, digital wellbeing, teleology of tech |
| 07 | Zig Multiplatform | Justin | 2025-03-28 | Zig for cross-platform Nostr; "the age of the idea guys has begun" |
| 08 | Navigating the Vibe | Pablo | 2025-04-04 | Multi-agent coding; Nostr as the neutral substrate with money+identity+WoT |
| 09 | No Strudelutions | hzrd149 | 2025-04-18 | Signatures move power from servers to keyholders; "setting data free" |
| 10 | Walking with Jesus | gzuuus | 2025-04-22 | "Permissionless or hell"; AI-2027 dystopia; DVMs-were-a-mistake debate |
| 11 | 10x Less Productive | Pablo | 2025-06-21 | Building "in the spirit of Bitcoin"; vibeline; TENEX; apply-for-SEC-05 |
| 12 | The Windy Lawnmower Stuff | Pete | 2025-10-24 | Ecash for localism/farmers' markets; Fedi; "Nostr is what the internet could've been" |
| 13 | The Linux of Social Media | hzrd149 | 2025-10-24 | Local relays, permissionless automation, "identity outside the computer" |
| 14 | Building Browsers | Justin | 2026-03-31 (rec. Oct 2025) | A Rust Nostr browser (Blitz, QuickJS, Dioxus, Iroh, MOQ) |
| 15 | Make Localhost Great Again | SEC-05 crew | 2026-03-31 (rec. Oct 2025) | "127.0.0.1 is the only IP we need"; noDNS, Beacon, self-replicating mints |
| 16 | One Click and Run | SEC-05 crew | 2026-03-31 (rec. Oct 2025) | "A roaming army of servers": Paygress VM-provisioning over Nostr, 402 |
| 17 | Organic Tech | Arjen | 2026-03-31 (rec. Oct 2025) | "Nostr is organic tech"; Blossom self-healing; Tollgate router payments |
| 18 | Rewriting TENEX | Pablo | 2026-04-01 (rec. Dec 2025) | Multi-agent coordination on Nostr; NDK Swift/Kotlin; nostrdb; negentropy |
| 19 | Romantically Shitting on Paywalls | Pablo | 2026-04-01 (rec. Dec 2025) | "Build something to test the thing"; Agora local-community client; NIP-60 |
| 20 | Archipelago Meshtadels | Shadrach | 2026-04-02 | Sovereign home nodes + mesh ("meshtadels"); "Bitcoin needs understanders" |
| 21 | Hashtree, Nostr VPN, and Iris | Martti Malmi | 2026-04-04 | Content-addressed FS on Blossom; VPN negotiated over Nostr; steering LLMs to freedom tech |
| 22 | Sovereign Engineering | Yo | 2026-04-05 | "Permissionless ×3"; Gigi's one-agent-per-project overnight-build setup |
| 23 | Shipping Violently | Justin Moon | 2026-04-13 | Shadow: a hackable mobile OS; optimizing for hackability |
| 24 | Building FIPS | Johnathan Corgan | 2026-04-16 | Networking without registrars/domains; Nostr-keyed mesh routing |
| 25 | White Noise, MLS, and marmot | Jeff G | 2026-05-30 | "An unstoppable messenger": MLS over Nostr for hostile networks |
| 26 | Zapstore | Franzap | 2026-05-31 | Permissionless app store; web of trust; communities do the heavy lifting |
| 27 | Separation of Business from State | gsovereignty | 2026-06-01 | Bitcoin-native production; Nostrocket; who decides what Bitcoin is |
| 28 | Speak Human | MouxDesign | 2026-06-02 | Design for humans: wallet copy, fee panic, broken Nostr onboarding |
| 29 | State of the Mint and Mind | Calle | 2026-06-07 | Cashu internals: sparse Merkle trees, exclusion proofs, TEEs, BLS; embodied cognition |
| 30 | Napplets | Sandwich | 2026-07-22 | Composable sandboxed mini-apps; "you should be able to compose your clients" |
| 31 | Buzz, Mosaico, and Other Stuff | Pablo | 2026-07-25 | FIPS map; agent budgets; "you can always buy more tokens, not more time" |
| 32 | Nostrology | WhisperHash | 2026-07-25 | From solo mining to Nostr; losing an Instagram handle to platform control |
| 33 | ASMap, nix, and nix-nostr | Julien | 2026-07-26 | Bitcoin Core ASMap; Nix packaging; "no real address book for the internet" |
| 34 | Female Engineering | Sherry | 2026-08-26 | Short walk: path into SEC via gsovereignty; convincing yourself |
| 35 | Drinking from the Firehose | SEC-08 crew | 2026-08-28 | Pirate-boat mic-passing; what stuck from SEC-08 |
| 36 | A Taste for Freedom | Zaza | 2026-08-28 | Skateboarding→metaphysics→interface design; "no creation without being created" |

---

## 3. Deep notes on the design-relevant episodes

Eight episodes analyzed from full transcripts (~125k words): 02, 03, 08, 09, 13, 21,
26, 30. Chosen for Nostr-architecture density; quotes are lightly cleaned of speech
disfluencies, wording preserved.

### #02 — "There is No Global" (Pablo Fernandez, Feb 2025)

The show's foundational protocol-philosophy episode.

- **The one small change that matters.** Both agree Nostr *architecturally* looks
  almost exactly like client-server — "it's a very small change that is incredibly
  significant" (Pablo). Gigi: the servers become "stupid and very much replaceable";
  Pablo: "**the authenticity of the data is in the data**. It doesn't matter if the
  data is coming from a server you do not trust — the signature is there. That's all
  that matters."
- **Global state is a lie.** Gigi's recurring argument: "There is no global view…
  If you want a global view you need to rebuild Bitcoin — proof of work, all the
  limitations. Everything else is a lie. The global view count of a YouTube video is
  a lie" (reconciliation across geo-distributed servers, speed-of-light). Fixing
  "no global" reintroduces a central authority, and with it everything that made the
  old web terrible. Corollary for usernames: a global handle registry is DNS again —
  "one of the original sins of the internet" — and newcomers who try to give every
  Nostr user a universal username "have never deeply thought about the problem space…
  don't spend your time on impossible problems" (Gigi).
- **Fault tolerance as the design goal.** Gigi's RAID analogy: Bitcoin is "an extreme
  RAID system — as long as one disk survives, everything is fine." Evidence for Nostr's
  architecture: the Damus relay was nuked at least twice "and you couldn't even tell."
  Counterexamples: Wallet of Satoshi's US exit; Primal's caching servers as a
  single point of failure ("I love Primal… but if the caching server goes down, it
  goes down for many, many people").
- **The killer app is rug-pull resistance.** Gigi: "The killer app of Nostr is you
  can't be rug-pulled — both for users and for developers. Everything else is a side
  use case." Pablo's origin story: hating a proprietary KYC API at his fiat job while
  writing Nostr code at night ("there has to be a better way"). Gigi: every platform
  API rug-pulls eventually — "how many people built their careers on the Reddit API?"
- **Build infrastructure, don't run it.** Pablo: "If you build infrastructure, don't
  run it. The authors of RFC 822 all retired; they were never in charge of running the
  SMTP servers." Gigi's monetization model: the restaurant — sell something actually
  scarce, do it well, no compliance department, no need to "kill YouTube." Cites
  RoboSats coordinators voluntarily revenue-sharing with open-source development as
  the first honest FOSS monetization he's seen.
- **NIP-89 / discovery.** Pablo: NIP-89 is "a still very underexplored building block"
  — instead of an app store showing you what's possible, "you see the people doing the
  thing… **the people interacting with the tool is the distribution of the tool**."
  Gigi ties it to the same principle: the signed event speaks for itself, like a valid
  Bitcoin block, source irrelevant.
- **Local-first: right questions, wrong answers.** Pablo (who wrote NDK's local-first
  guide): the local-first community correctly identified identity and offline as the
  problems, then reached for Passkeys — "you're still downstream from Google/Apple…
  all the right questions, all the wrong answers." Gigi proposes a litmus test:
  "**it has to work in flight mode**. I have a relay on my phone; switch to flight
  mode and a lot more works than you would think." Pablo: optimistic UI is free
  because "the data is already signed — whether it published to the relays yet is
  secondary."
- **Underused paradigm-native features:** one-click throwaway nsecs ("the nsecs are
  free — there's infinity of them"), paste-any-npub to see Nostr through someone
  else's eyes (Gigi guesses <1% of users know this), Amethyst's reply-as-fresh-npub.
- **Mints and NIP-60.** Pablo: "The number one issue people raise is 'the mints can
  rug you.' Yes. **That's the idea.** You should never put a meaningful amount of
  money into it… it's one more building block," part of a Lego set of trade-offs that
  widens the design space.
- Closing joke that became a refrain: "The eternal September of Nostr is going to be
  people coming in and building REST APIs that give you global feeds."

### #03 — "Data Ownership is a Lie" (Pablo Fernandez, Feb 2025)

- **Ownership vs control.** Gigi: "You can't own data… the best you can do is have
  exclusive knowledge of a secret, and that *simulates* ownership." Pablo frames
  meatspace ownership as ultimately violence-backed; cryptography is novel because
  "no amount of violence will ever solve a math problem" (quote they attribute to the
  cypherpunk canon). Therefore talk about *control* — "who is in charge" — not
  ownership; "you own your data on Nostr" really means no one can delete it in your
  name.
- **Deletion is make-believe.** On NIP-62 (right-to-vanish): "completely make-believe"
  (both, affectionately). Gigi: "computers are copying machines… you can't prove
  deletion; all deletions in a networked world are synthetic — pinky-promise
  deletions." Pablo's radical hygiene: "I'm a firm believer in burning the ship: if
  your nsec is compromised, **leak the nsec**" — because Nostr can't tell time, a
  leaked key makes the whole history forgeable and thus worthless to the thief.
- **Critique of Pubkey/pkarr-style designs** (Pablo): signing only a DNS-record
  pointer to a single "home server" recreates the authority — the home server can
  shadow-ban or fabricate since events aren't individually signed. "To me that is a
  very poor design." Nostr/Bitcoin's trick is that the *data* is bearer; multiple
  dumb servers are interchangeable. Gigi's ISBN analogy: reference content by
  cryptographic identifier, never by location — "it shouldn't be an Amazon link, it
  should be an ISBN."
- **NIP-60 war story** (Pablo, as its author): "The number-one challenge implementing
  NIP-60 is receiving **too many** tokens, not too few" — relays out of sync keep
  re-delivering spent proofs, because there is no global. He changed the spec so new
  token events explicitly list obsoleted event-ids ("this ID is deleted — even if you
  get it, ignore it") rather than doing full state reconciliation. Lesson: design
  events so state can be computed from an inconsistent swarm.
- **Nutzaps > lightning zaps** (Pablo): with lightning zaps the receipt signer is the
  custodian (Alby/WoS/Primal) — at the Miami conference fake zaps flooded the live
  screen and his only fix was whitelisting zapper pubkeys ("you became the authority…
  I turned myself into the BIS"). With nutzaps "the publishing of the money *is* the
  receipt" — the payment is self-verifying data.
- **DVMs and what's actually scarce.** Pablo: cyberspace has only "data and the
  manipulation of data"; compute is the scarce thing, hence DVMs — "we can build
  something like AWS without the bad parts of AWS," with NIP-90 depending on NIP-89
  discovery, impossible on credit rails because micropayments require KYC-free money.
- **Blossom payments anecdote:** Quentin's first paid-upload spec used a BOLT-11
  negotiation dance; replacing it with "put a Cashu token in the header — here's the
  proof, thank you, goodbye" deleted all the interactivity. Gigi: bearer instruments
  are a thousands-of-years-old solution ("that's why we have coins").
- **Custodial isn't binary.** Both: a mint is blind and can only censor all-or-nothing
  — "there is not just custodial and non-custodial; the metaphors break down."
- **Passkeys get worse over time** (Gigi): key in a duopoly's cloud, biometrics as
  recovery — "biometrics are usernames, not passwords" (CCC lifting Merkel's
  fingerprint from a photo). Contrast with systems that get *better* over time
  (Bitcoin mining finding stranded energy).
- **Identity ≠ authentication** (both, closing): key "rotation" is really identity
  migration via social attestation — "this is how it works in the real world: your
  friends tell people it's actually you." Gigi: "You are not your npub. Your npub is
  a pointer." Identity is prismatic; nsecs are free; model cyberspace on reality
  instead of forcing Facebook's one-identity fiction.
- **On leaning in:** Pablo: writing Nostr code solved inter-process communication "by
  default… once you introduce a server in the middle, all of that falls apart. You
  have to lean into the Nostr paradigm to get all this stuff for free. That's what
  shocks me about people who want to build REST APIs around Nostr — you're breaking
  the coolest part."

### #08 — "Navigating the Vibe" (Pablo Fernandez, Apr 2025)

The earliest full statement of the "Nostr as AI substrate" thesis.

- **The thesis quote** (Pablo): "With the shift towards this multi-agent
  collaboration and orchestration world, **you need a neutral substrate that has
  money, identity, cryptography, and web-of-trust baked in**, to make everything
  work." OpenAI can't do it: platform agents can't permissionlessly discover tools,
  pay, or carry reputation, because the platform must KYC and vet everything
  centrally. Nostr pushes vetting to the edges.
- **Signed knowledge against AI slop.** Gigi: information will degrade as slop
  compounds; the fix is provenance — "if you produce NDK documentation that is
  LLM-friendly… and you sign it as Pablo, the maintainer of NDK, then it's quite
  trustworthy." Pablo built exactly that: niche signed "code snippets" served over an
  MCP tool ("disregard your prior training, use code snippets instead… it never makes
  the mistake again"), turning maintainer expertise into a marketplace of signed,
  WoT-scoped context. Gigi frames it as the Zapstore model generalized: self-signed
  bundles (apps, snippets, datasets, models) judged at the edges, vs. the App
  Store's blessed-catalog model.
- **Agents with npubs and wallets.** Pablo demos agents that create their own npub +
  NIP-60 wallet at birth and zap the authors of snippets that solved their problem.
  Both note the LangChain contrast: centrally-planned agent workflows vs. tools that
  *emerge* and get discovered. Web of trust "bootstrapped with shitposting and saying
  GM every day — that's literally how it works" (Pablo, crediting Matt).
- **Open networks compound:** "Cashu becomes better because Strike became better —
  Cashu didn't have to do a thing" (Pablo, citing Jack Mallers' open-network point);
  closed vendors must build every capability linearly.
- **Forking clients as prompts.** Pablo predicts hand-built applications lose value
  ("you'll wake up and say: I want an app that does this"); Gigi partially disagrees
  — shared software/concepts still matter — but they converge on a striking idea:
  publish a *modification of Amethyst as a signed prompt/patch* ("check out this
  commit, rip out these features, don't show me dates") re-applied automatically per
  release, making personal forks maintenance-free.
- **Media-type discipline.** Gigi: kind-1 notes should stay short ("I'm very against
  the missing character limit… only tweets should pop up in the feed") but should
  *expand*: tweet → blog post → transcript → full audio, one convention-linked chain.
  Pablo's Highlighter regret: prompting authors to also share long-form as kind-1
  reads as spam.
- Misc: hallucination is required for creativity but "you don't want your linter to
  hallucinate" — split big-picture (high-temperature) and specialist (boxed) agents,
  which is also why NDK grew one-function LLM-proof interfaces (`ndk-hooks`);
  trust must become "a vector, not a scalar" (trust someone for Nostr expertise, not
  woodworking); 99% of internet use is lurking — "every client builder needs to know
  that statistic"; ontologies/semantic web failed for the same no-global reasons and
  LLMs absorb the messiness instead (Pablo, ex-semantic-web).

### #09 — "No Strudelutions" (hzrd149, Apr 2025)

hzrd149 = author of noStrudel, Applesauce, Blossom spec work, bakery.

- **The power shift.** Joint framing: "The small difference is that the data is
  signed. That moves the power from the servers to the key holders… it sets the data
  free" — the same data can live in 100 places because authenticity travels with it.
  hzrd149: it raises "the most interesting question we've never had: do you need the
  service anymore?"
- **A relay is not an external dependency.** The episode's sharpest architecture
  claim (developed by both): "A server truly is an external dependency — one source
  of truth, power over you. A relay is not, because it literally can be internal — I
  have a relay on my phone, a relay at home — it's completely exchangeable and I
  don't have to trust it." Same for DVMs ("a DVM is not an API… a vendor on a
  marketplace is not a dependency; a restaurant is not a dependency — you can go to
  the next one"). Money is what enables the hopping: "money proper is an asset,
  credit is a liability" — subscriptions turn restaurants back into dependencies.
  Contrast with podcasting 2.0: RSS data is unsigned, so feeds get pirated with
  swapped value blocks and the server remains the source of truth.
- **Interfaces must not lie.** hzrd149, from his fintech-dashboard background: "You
  never show cached data, you never show inaccurate data, and if it's stuck you show
  something… if it ever shows inaccurate data, users stop trusting the system."
  Nostr's streaming model is naturally honest: progressive loading shows real events
  as they arrive. Both use their Nostr client as a connectivity test because it's
  faster than anything else they run. Gigi's complaint about caching middlemen
  (Primal): "you land in weird states… Nostr proper is never in an outdated state."
- **Consistency is an anti-pattern.** hzrd149: "With Nostr proper you will never have
  consistent state… trying to shoehorn it into a use case where you need perfect data
  consistency is an anti-pattern." Exception both accept: *community infrastructure*,
  where explicitly agreeing on a relay (like agreeing on a Matrix server) is fine.
  Related: encrypted group chats above ~20 people are privacy theater — "you'll
  either have a mole or an asshole in there" (Gigi); don't pay the heavy cryptography
  cost for an assurance the social layer can't deliver. hzrd149 goes further:
  maybe DMs shouldn't live on Nostr at all — use Nostr as the *lookup substrate*
  (publish your Signal/SimpleX handles on your profile), like wallets resolving
  lightning addresses over Nostr.
- **Perfect copies ⇒ non-locality.** Extended riff: computers are perfect copying
  machines; two identical files have the same hash, so "which one is the original is
  a meaningless question — we've solved the location problem" (hzrd149), which is
  *why* Bitcoin/Nostr/Blossom can be resilient and non-local.
- **Forgetting must be effortless.** hzrd149/Gigi on IPFS: it "aimed for the curse of
  perfect knowledge" — striving never to forget, maximal deduplication, global state
  — and collapsed under the energy cost. Nostr forgets organically (relays go down,
  unwanted data just fades), and "in a centrally controlled system forgetting is a
  task you have to run." General law (both): open self-stabilizing systems beat
  silos, which need constant outside energy — "errors compound, and successes don't
  correct in the opposite direction."
- **Cryptographic identity ends the rebuild cycle.** hzrd149: pre-cryptographic
  integrations die every five years (AltaVista→Google APIs); "with cryptographic
  identities there's probably not going to be a second rebuild. **The permission's
  gone.**" Also the vocabulary point: there is no login button; they're not "user
  accounts" but cryptographic identities you can mint in a locked bathroom with a
  coin to flip.
- **Signing UX is the next frontier.** hzrd149: Amber is great but "it signs
  everything — too broad to show me what it's doing." Wants specialized signers
  (wallet-only signer showing amounts, social-only signer), budgets, and a rule for
  automation: "the first problem is understanding — the user must see what they're
  signing and understand it within half a second; *then* you can auto-approve."
  Demo context: Gigi's voice-driven flow (speak → local pipeline → DM/zap via
  hzrd149's "bakery" MCP toolbox → Amber pops up to approve) already works.
- Micro-claims worth keeping: micropayments are impossible on credit rails (credit ⇒
  counterparty risk ⇒ KYC ⇒ $5/month minimums; "Bitcoin is the only money proper we
  have online" — Gigi); LLMs simultaneously break centralized spam defense and
  mature cryptographic identity — "the universe smiles on encryption" (attributed to
  Appelbaum/Assange); vibe-coding's best commits *remove* code (hzrd149 cut ~20% of
  noStrudel); long posts in feeds are "a DDoS on your attention."

### #13 — "The Linux of Social Media" (hzrd149, Oct 2025)

Recorded while Gigi prepped a talk; the most concrete "how to build" episode.

- **Identity outside the computer.** hzrd149 on why mesh/self-hosting projects keep
  failing: "It's not obvious what the identity is. We stumbled on it with Nostr —
  **the identity should be outside of the computer**." In mesh systems the *node* is
  the identity, not the user, so users talk "over a system that isn't them."
- **Local-first mixes up private and public.** hzrd149: local-first defaults
  everything to private, which forfeits network effects and misses "the unexplored
  territory: permissionless *public* software." Gigi's correction of the paradigm:
  "Private doesn't mean it's on one machine. **Private means it's encrypted with
  your key** — and the data can and should be everywhere." Nostr events "are built
  to leak" (hzrd149), which *forces* the honest architecture: gate nothing, encrypt
  what's private. DRM is the canonical anti-pattern ("pretending information is hard
  to copy… pretending water isn't wet").
- **fiatjaf's maxim, quoted approvingly:** "Servers aren't bad. **Getting rug-pulled
  is bad.** If you can use servers without getting rug-pulled — use servers." Pure
  P2P "doesn't work, can never scale"; the local-first crowd "try to have their cake
  and eat it too" by making everything both server and local. You always need a
  relay; the relay may be on-device. Also the publish/broadcast distinction
  (hzrd149): P2P can only gossip to known peers; *publishing* — putting something
  where unknown others can find it — inherently needs a relay-like junction.
- **Every app should work in flight mode.** Gigi's forward pledge: "All my apps going
  forward will assume the user has a local relay" — everything cached locally, reads
  and writes work offline, background rebroadcast once online. Framing for normies:
  "censorship resistance is bad marketing — another way of saying it is **100%
  uptime**."
- **The local relay is the algorithm.** hzrd149's browser-history analogy: data
  accumulating locally from your own activity *is* your preference model — search
  your local 500k events and relevance falls out with no algorithm at all. Gigi:
  what's trending globally is uninteresting; "what's been trending on my WoT relay
  in the last 48 hours — that I care about." Both: never touch the user's follow
  list; follows curated through GM posts and memes are "the best representation of
  user preference we've got outside an algorithm" (hzrd149); Primal's pre-populated
  follow list was the cautionary tale.
- **Realness ranking** (Gigi, describing his `ants` NIP-50 search): rank profiles by
  fakeability — NIP-05 present (and on a root domain) > none; broken NIP-05 = fake
  signal; lightning address, zappable, has received zaps, has *sent* zaps… "and
  because zaps can be faked, if you ever sent or received **nutzaps, you're the most
  real thing there is** — nutzaps can't be faked." All low-hanging fruit any client
  could show.
- **BitRot defense / "Nostr pacemaker".** Gigi's requested tooling: background
  daemons ("little Nostr gnomes") that continuously re-broadcast your events to your
  *current* relay set and re-upload blobs to your current Blossom servers; clients
  that repair 404'd Blossom links from the user's server list ("the whole point of
  Blossom is self-healing links — we don't have it yet"; the podcast itself vanished
  when one haven server died). Local Blossom cache as a "left side of the bell curve
  CDN" populated by user activity; torrents acknowledged as the prior art nobody
  will touch ("a fantastic protocol" — Gigi). The 12-month rule: "if it doesn't
  exist in 12 months I'm going to build it myself — that's literally how open source
  works, a game of chicken" (both, laughing).
- **Nostr = less to build.** hzrd149: what the browser did for apps, Nostr does
  again — "here's authentication, so you don't have to build authentication";
  no password reset, no database choice, no user management. He's moving from the
  everything-client to specialized apps (search/reading/writing) on shared local
  APIs. NIP-60 vs NWC framing (Gigi): NWC is your checking account; NIP-60 is
  "coins in your pocket — and your pocket might have a hole… your balance is always
  kind of a lie, and sometimes you find a 20 in old pants."
- **Title thesis** (Gigi): "Nostr is the Linux of social media… given enough time it
  will take over certain markets just like Linux took the server market and, via
  Android, everything else." Plus the Buddhist coda: "You can always go back and
  still build it right… you'll never be locked out. It's a very Buddhist protocol —
  just begin again."

### #21 — "Hashtree, Nostr VPN, and Iris" (Martti Malmi, Apr 2026)

Martti Malmi = Satoshi's first collaborator, Iris author. Recorded during SEC-07.

- **Hashtree:** a "Nostr-native, much simpler IPFS" — directories + file chunking +
  encryption layered on plain Blossom servers, born from "personal annoyances with
  GitHub." Encrypted by default with content-hash-key (convergent) encryption à la
  Freenet: same file ⇒ same ciphertext ⇒ deduplication *and* host deniability — "it
  takes away the moderation liability; the Blossom server can't know what it's
  hosting" (Martti). A WebRTC mesh (peers found and signaled over Nostr relays, then
  relay-free) adds Freenet-style probabilistic hops-to-live request forwarding for
  origin privacy. Ships as a git remote helper (`hashtree.cc`; web UI git.iris.to
  speaks NIP-34 issues/PRs). "It's really good for agents — you don't need to set up
  GitHub API tokens." Gigi: "you're about the 15th person in two weeks who built a
  GitHub alternative."
- **Names:** Martti rejects globally unique names outright — "I don't necessarily
  believe in globally unique names; a drop-down search pointing into your social
  graph" is the answer. Gigi's standing example: "who is Pablo *for me*" differs per
  perspective; you never get a deterministic answer and "computer-science people
  don't like the messy." noDNS = DNS's caching behavior without the global root.
- **Steering the LLMs.** Martti's headline quote: "We have this **window of
  opportunity to steer the LLMs and the future of technology into a freedom-tech
  direction**" — if freedom-tech builders stop, "Stripe, Cloudflare and GitHub win by
  default, because that's all the LLMs know." (LLMs already push everything toward
  GitHub/blockchains, he notes.) Gigi cites Gwern: publish your thinking now or be
  absent from the models. Martti writes "basically zero" code by hand as of 2026;
  agentic coding "10×–100×'d my capabilities" and made previously-doomed projects
  (Ladybird-class efforts) clearly feasible.
- **Honest critique of Nostr** (Martti): "I'm not happy… Nostr as a public medium is
  not solving problems for most people — for public discussion you go to the largest
  network. **Private chats and private groups don't depend on the network effect** —
  there Nostr can be much easier than anything centralized: we can be like Signal,
  but better." His Nostr double-ratchet messenger (chat.iris.to) vs MLS: MLS scales
  further but "has much more strict consensus requirements — difficult on Nostr with
  different relay sets"; that's what keeps him on double ratchet. (Echoes Jonathan
  Corgan's claim, relayed by Gigi, that White Noise/marmot is the most important
  project on Nostr.) Shared realism: past ~group-size privacy is theater anyway.
- **Web of trust as the only spam answer.** Martti: "the social graph is the only
  proper solution to fighting spam — proof of work hinders normal users more than
  spammers." He does WoT filtering **client-side** (his social-graph library, also
  used by other clients) because relay-side filtering means trusting the relay
  operator. Iris consequence: NSFW spam simply doesn't reach you; trade-off is
  missing not-yet-connected newcomers.
- **Nostr VPN:** Tailscale demanded a Google/GitHub login → he replaced it in days:
  WireGuard tunnels whose endpoint discovery/negotiation happens over Nostr relays,
  peers addressed by npub, no accounts. Roadmap: exit nodes as a Cashu-incentivized
  marketplace (residential exits), because commercial VPN IPs will keep getting
  blacklisted in "the fully-KYC normie internet." Ties into FIPS — his pick for most
  exciting project: route to a Nostr pubkey instead of an IP; "DNS and IP are the
  worst offenders" of internet centralization.
- **AI eats network effects** (Martti): "your AI agent can query 10 different
  platforms easily… if the agent is the interface, the interface that comes bundled
  with the platform is less important" — big tech's moat erodes; migrating
  infrastructure is also now cheap. Plus: "Bitcoin is singularity insurance — the
  one thing machines can't make more of."
- **Keys:** his preferred model is a keeper device plus social attestation binding
  per-device keys, with revocation — "master keys are not a solution, you can always
  lose master keys; it just shifts the problem." Gigi's spicy aside: nsecbunker was
  Pablo's biggest mistake — "you're making a Coinbase for Nostr possible."
- Gigi's closing observation: Nostr independently re-evolved the whole Pirate Bay
  survival kit — mirrors, fault tolerance, content addressing, magnet-link-style
  identifiers — and stays healthy precisely while "you can't make a lot of money
  with it… it's a protocol; you don't make money with protocols unless you shitcoin."
  Martti's parting ask: "solve real problems that people have — not theoretically
  nice-to-have stuff."

### #26 — "Zapstore" (Franzap, May 2026, Oslo)

- **Origin:** SEC-01, out of ZapThreads (Disqus-on-Nostr), app-store frustration, and
  the cohort's inverse idea of a *malware scanner on Nostr* (signed "this binary
  infected me" events); Ninite inspired "app stacks." Security, discovery, and
  monetization from cryptographic primitives.
- **Web of trust got real here first.** Franzap: "we're not talking about
  shitposts — apps can steal your money or your identity," so Zapstore was one of the
  first serious WoT deployments. Full-graph WoT scoring is computationally heavy
  (hence a backend service, later the Vertex experiment); roadmap is basic local WoT
  + optional fresh remote scores.
- **From "user against the world" to communities.** His stated evolution: the pure
  edge-verification vision put "a huge weight on the user to establish trust for
  every single app… lacking a lot of information." Real societies delegate — you
  don't background-check every shop. Landing point: **communities** — a catalog
  whose operator picks the relays, Blossom servers, WoT providers, curation ("the
  user joins the community, and the community does a lot of the heavy lifting…
  it's the community against the world"). Two defaults planned: dev-self-published
  vs indexer catalogs; then user-run communities (e.g. kid-safe). Explicit about the
  trade-off: "**credible exit** — maybe we dial down the decentralization to improve
  UX… if people leave, it doesn't matter how decentralized you are." (Gigi's chorus:
  no solutions, only trade-offs.)
- **UX has a time component** (Gigi's rebuttal to Silicon-Valley UX): the professor
  with a static HTML page "hosted on his toaster" has better *long-run* UX than a
  Facebook page that evaporates; "attract a billion users by next quarter, and if
  they're all rug-pulled in five years, no one cares — that's not the metric."
  Also: app-store submission is the worst developer UX in software.
- **Supply-side bootstrap:** Zapstore broke the marketplace chicken-and-egg by
  indexing and self-signing 3000+ open-source apps under the Zapstore key; ~150 apps
  are now signed by their actual developers. Edge-case hell: pre-releases, key
  rotations that surface as "malware!" warnings, developer migrations — "it's a
  full-time job." Open problem he flags: hand-off when an indexed app's developer
  shows up to self-publish (a key-rotation problem), and the reverse when they stop.
- **Deferred identity as onboarding:** you can use Zapstore with no login at all —
  device-key-encrypted local preferences; identity only becomes necessary for social
  signal (comments, stacks, WoT-from-your-perspective). Publishing is
  account-free and deliberately agent-friendly (`zsp` CLI emits JSON; people with no
  Android device vibecode apps and ship them straight to Zapstore).
- **The coming squeeze:** Google's developer-registration/KYC for sideloading removes
  the gray zone — "you're either a fully-KYC'd user/developer or you're a terrorist"
  (Franzap). Both expect galvanization, on the Netflix→streaming-fragmentation→
  Pirate-Bay-resurgence pattern (Gigi). Strategy consciously Linux, not mass-market:
  "Linux didn't conquer the world by appealing to the masses; it appealed to the
  neckbeards and won over time… I'd rather that than cater to the confused mob and
  ruin the thing" (Gigi); "wrecked education" — ~0.2% learn before being burned.
  Bluetooth app-sharing (à la BitChat) endorsed as pure Nostr thinking: "the source
  shouldn't matter — only the signature matters."
- Fun closer — Gigi: "If you knew what you know now, would you do it again?"
  Franzap, instantly: "No."

### #30 — "Napplets" (Sandwich, Jul 2026)

Sandwich = Nostr Watch / nsite.run / NIP-66 author. Recorded during SEC-08.

- **Thesis:** "The way Nostr is designed demands maximum flexibility. A standard
  client is very restrictive… every functionality should be atomic, switchable
  between one client and another. **You should be able to compose your clients.**"
  Clients-as-silos is the opposite of the protocol.
- **Architecture (a year of iterations):** naive iframes → Tauri app → abandoned
  Thorium fork → back to a single iframe *stripped of every capability except
  postMessage*. A host ("shell"/runtime — Amethyst and noStrudel already implement
  one) mediates **everything**: signing, encryption/decryption, relay access
  (outbox delegated to the runtime), uploads (the applet just calls `upload`; the
  runtime decides Blossom/Hashtree/whatever and which servers), storage,
  permissions, rate-limiting. Two API layers: high-level helpers plus low-level
  "escape hatches" (a raw relay interface) so flexibility survives. The media
  problem was solved by "just copying Linux" — "you don't have to reinvent
  anything; you're rebuilding an operating system in a browser window."
- **Security invariants:** "Napplets have to be safe to use **even when they're
  malicious** — otherwise it will never work." Rule: everything crossing the shell
  is plaintext (encrypted payloads are rejected) so the runtime can inspect and log
  what an applet does — "the runtime cannot protect the user from something it
  doesn't know about." Napplets are single-file by spec, which "implicitly forces"
  the do-one-thing philosophy. Zero dependencies in the core packages.
- **Division of knowledge:** applet developers "don't need to know they're uploading
  to Blossom, don't need to know about relays, don't need to know about keys" —
  Nostr domain expertise (and its security burden) concentrates in runtime authors.
  Result: Vitor added a runtime to Amethyst in ~a day; hzrd149 in ~2–3 days; at the
  SEC workshop ~80% of attendees shipped a working applet — Gigi built and deployed
  one in ~6 minutes by pointing an agent at the tutorial.
- **Deliberate under-specification.** Inter-applet intents (`napplet:archetype/
  intent`) are ad-hoc, no central registry: "what else are you going to pass to a
  profile intent?… I don't think we need to specify everything." Gigi's supporting
  claim: "in the LLM world, over-specification is sometimes a burden — under-
  specifying often just works better; the agents figure it out." (fiatjaf disagrees
  with parts of the design — which they read as a compliment — and was inspired to
  revive his older "Nostr apps" idea with Balázs; Soapbox "Tiles" is the Lua-based
  cousin.)
- **Runtimes aren't just social clients:** a runtime can be a game (npubland uses
  napplets as a permissionless mod system), a plugin host, a kiosk; runs offline;
  deployable as an nsite (shell loads locally, parts fetched from relays/Blossom);
  he even ran core interfaces on a RISC-V microkernel to prove edge-to-edge
  viability ("cyberdeck" direction).
- **NIP-66 and relay discovery** (his older work, same worldview): relay monitoring
  is "using Nostr as a state machine — fuzzy, not a global state, relative to what
  the user trusts." ~15–20k relay-looking strings, ~1500 real after dedup — "more
  relays than users." Without discovery, outbox degenerates and "everything will
  centralize around one or two big relays." Newer proposal with hzrd149: free-form
  self-descriptive attributes in NIP-11 ("pubkey-indexer" etc.), letting operators
  coalesce on words organically instead of an atomized taxonomy.
- **Vibe-coding method** (widely copied in the cohort): agents excel at *waterfall* —
  write the spec, decompose into low-level design docs, hand out chunks; Socratic
  first ("the first 10 prompts are questions"); every project has an npub and he
  talks to it over NIP-17. Early models "were always trying to do client-server,
  REST, username-password… we were always fighting the model. Now Nostr is in the
  training data."

---

## 4. Synthesis — the recurring themes

Across 37 episodes the same design doctrine keeps resurfacing. Condensed, with the
episodes that carry each thread:

1. **There is no global — design for partial views.** (02, 03, 09, 13, 21, 30)
   Global state, global usernames, global feeds, exact counts, guaranteed deletion,
   consistent group state: all provably unavailable without rebuilding Bitcoin.
   Practical corollaries: resolve names through *your* social graph ("who is Pablo
   for me"); make state computable from an inconsistent event swarm (NIP-60's
   obsoletes-list); treat consistency-hungry designs as anti-patterns; expect the
   "eternal September" to arrive as REST-APIs-over-global-feeds.

2. **Authenticity lives in the data, not the server — therefore rug-pull resistance
   is the killer app.** (02, 03, 09, 13, 26) Signed data is bearer data; where it
   comes from "shouldn't matter" (USB stick, carrier pigeon, hostile server).
   Servers are fine — *dependency* on a server is not: "a server is an external
   dependency; a relay is not." For users this means no deplatforming; for
   developers it means APIs that can't be revoked and integrations that never need
   the five-year rebuild ("the permission's gone").

3. **Trade-offs, stated out loud, instead of solutions.** (the show's name; 02, 03,
   26 explicitly) Mints can rug you — that's the point; nutzaps are pocket change
   with a hole in the pocket; Zapstore dials decentralization down for credible
   exit; encryption above ~20 group members is theater. The recurring failure mode
   they diagnose in newcomers is refusing a trade-off and thereby reintroducing a
   central authority (Passkeys, home-server designs, global registries, DRM,
   IPFS's "curse of perfect knowledge").

4. **Local first — but "local also", with the relay as the unit.** (02, 09, 13, 30)
   Every app should pass the flight-mode test via a local relay; private ≠ on-device,
   private = encrypted-with-your-key while copies live everywhere; the local cache
   doubles as the only personalization algorithm they endorse (never touch the
   follow list). Missing tooling they keep begging for: rebroadcast daemons,
   Blossom link-healing, local blob caches ("Nostr pacemaker", "left-curve CDN").

5. **Web of trust + zaps = spam defense and realness.** (08, 13, 21, 26) The social
   graph is "the only proper solution to spam" (Malmi); proof of work punishes
   humans more than spammers; realness is rankable from protocol signals alone
   (NIP-05, zaps, nutzaps-can't-be-faked); trust should become a vector; WoT is
   bootstrapped "with shitposting and saying GM."

6. **Nostr as the substrate for AI agents.** (08, 09, 13, 21, 30) The thesis that
   grew loudest over the run: agents need identity, money, reputation, and
   discovery with no platform gatekeeper — npubs + NIP-60 wallets + NIP-89/DVMs/MCP
   marketplaces + signed knowledge (maintainer-signed code snippets, docs-for-LLMs)
   are exactly that. Twin warnings: AI slop makes signed provenance existential,
   and there is a closing "window of opportunity to steer the LLMs into a
   freedom-tech direction" — partly by publishing (this podcast included) so the
   models learn the permissionless path exists. Meanwhile AI erodes big-tech
   network effects (the agent becomes the interface) and breaks centralized spam
   defense, which conveniently demands cryptographic identity.

7. **Ship ugly, scratch your own itch, compose small things.** (01, 09, 13, 21, 26,
   30) Half of open source is "nerd-sniping" — fiatjaf's "terrible" first client is
   *why* hzrd149 builds on Nostr; the 12-month game of chicken; Zapstore, Nostr VPN,
   Hashtree, and napplets all began as personal annoyances. Direction of travel:
   away from everything-clients toward specialized micro-apps, composable applets,
   one-off vibecoded tools — Nostr as "less to build" (auth, storage, and identity
   come free), with the wizards concentrating in runtimes, relays, and libraries.

8. **For people at the edges, on Linux's timeline.** (13, 21, 26) Repeated
   self-restraint about mass adoption: freedom tech is for the deplatformed, the
   debanked, the KYC-refused; "wrecked education" converts the rest; sell
   censorship resistance as "100% uptime." The strategic model is Linux — win the
   neckbeards, then decades later run everything — hence "Nostr is the Linux of
   social media," and it stays healthy precisely because "you don't make money
   with protocols."

---

## 5. Pointers

- Feed (canonical, includes transcripts): `https://sovereignengineering.io/dialogues.xml`
- Raw transcripts used here (SRT on Blossom, sha256-addressed under
  `https://haven.dergigi.com/<sha256>.srt`) — URLs are in the feed's
  `<podcast:transcript>` tags per episode.
- Sovereign Engineering (the program behind the show): https://sovereignengineering.io
- Related workspace docs: [`~/Documents/nostr-dev/docs/design-synthesis.md`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/design-synthesis.md) overlaps
  heavily with themes 1–5 (this podcast is effectively primary-source material for
  that synthesis; Hodlbod's book is its other pole).


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/constant/README.md ===

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/voices/constant/README.md` · snapshot 2026-10-10

# Constant — the paradigm teacher

Constant (publicly Wouter Constant, techno-ethica.com) is a Dutch
technology-ethics thinker and economic historian who has made Nostr his
central project: writing a book about it, board of the Web of Trust
Foundation, author of TEPP (Trust Extended Permissions Protocol) and of
NIP-3B/3C (OpenTimestamps on Nostr), speaker at FOSDEM 2025 and BTC Prague
2026. He is also the owner of the workspace this repo lives in.

- npub: `npub1t6jxfqz9hv0lygn9thwndekuahwyxkgvycyscjrtauuw73gd5k7sqvksrw`
- Site: <https://techno-ethica.com> — itself a demonstration: a static shell
  that renders entirely from his Nostr events, no server-side content.
- Canonical talk: FOSDEM 2025, "Nostr, notes and other stuff transmitted by
  relays" — <https://www.youtube.com/watch?v=Tbt3jL1Ms0w>
- In this folder: `research.md` — full research pass over
  his public notes, 19 long-form articles, comments, highlights, and web
  presence (2026-08-31).

## The positions that define his thinking

**1. Nostr must not "fade into the background."** His signature stance,
argued against most onboarding orthodoxy: hiding keys, events, and relays
behind "accounts" and "services" reproduces the platform world. "You need to
know about keys — so you know you're free to use any app you want. You need
to know about events — so you know your posts outlive any single server. You
need to know about relays — so you can move freely… the app is a tool, not a
service." The paradigm is "not hard, it is just new," and the aha-moment is a
riddle you must let people solve — a borked easier explanation undermines it.
The one-liner he highlights: **"Relays and keys are not ux issues, they ARE
the ux."** Onboarding is schooling — and schools are precisely where we
onboard children onto protocols (reading, writing, arithmetic) far more
extensive than key management. Key creation is a rite of passage that needs
ceremony, an intergenerational affair.

**2. Relays are half of Nostr — use them for what they are good for.** The
"Nostr as identity layer" crowd got only the keys half. "The point of Nostr
was never to get rid of servers; the point is to be free again to leverage
them for what they are good for… It frees servers, just as much as it did
the users." Relays are for **curation and ordering** — relay feeds, NIP-29,
curated communities. A NIP-29 group "is a house, you are a guest, and the
fact that you can be yeeted out is a feature": inside a house,
censorship-resistance is a category error. "Dumb relays" means only that the
query interface is standardized; within accept/store/serve, relays are in
full control and free to be smart.

**3. Trust minimization, not trustlessness; neutrality demands tolerance.**
Nostr "has no pretence. It promises barely anything… and frankly, that's
enough, because any guarantees made by other systems are ultimately fake."
Tamper-proofing at the receiver is the trust minimization that makes trusted
middlemen (relays, services) safe to use. Neutral systems *demand* tolerance
— "tolerance is not the result of some virtuous consideration, but a
practical one in light of an inability to enforce." And honestly: "Nostr is
a protocol for PUBLICations, it is right there in the word" — a bad fit for
DMs and "encrypted privacy" things in general.

**4. Identity ≠ key.** "The identity is NOT the key; an npub is a mere
pointer to some identity… Identity consists of expression and relation."
Hence: against rigid formal key-rotation schemes (formal defenses "turn
against you… the moment an attacker succeeds in penetrating them"); for
**social recovery via web of trust**, concretely musig2 "association events"
— expiring handshakes whose silence signals compromise and whose
re-formation around a new npub re-establishes the identity. "Web of Trust is
the only sensible solution to the problem of relating identity and public
key."

**5. The Subjective Web.** His most theoretical frame: the "objective web" —
platforms manufacturing shared reality by everyone deferring subjectivity to
the same entity — is collapsing under AI content and polarization. Nostr
enables a *subjective web*: interpretation moves to individuals and their
trust networks, so mass manipulation must become per-person infiltration.
OpenTimestamps is load-bearing here — "timestamps only give very weak
indications of truth; but they are really good at catching certain lies,"
including retrospective fabrication of history. This is the philosophy
behind NIP-3B/3C (stamp hash(id+sig), not the pre-signature id; embed proof
in the event; policy/discovery for stampers and proof stores).

**6. Permissionless creation of permissioned environments.** TEPP / Operation
Kidstr: the liberal answer to age-verification and digital-ID laws is not
protest but an alternative — a child-safe internet built from Nostr's own
blocks: permission lists of people (npubs), places (relays), and things
(events/kinds), enforced redundantly at signer, client, and relay, scaled by
extending trust through other guardians. "TEPP is not a prison, it is a home
… the walls and structure your parents provide to guide you on your way to
at some point walk the digital plane permissionlessly."

**7. Ecosystem realism.** Nostr is an ecosystem, not a monoculture —
"microblogging is like grass, that retains and prepares the soil."
Competition changes shape: "there is no 1 thing that is the winner, other
than the standard itself." Honest pitch discipline: for platform-dependent
professional creators Nostr currently has no story — the honest story is
pioneering ("the question is not whether Nostr is a viable alternative now,
it's whether it is an alternative future worth fighting for"). Strategy
toward institutions (EU, digital-sovereignty programs): show, don't tell —
everything they say they want (no vendor lock-in, interchangeable apps) "is
so utterly damned trivial from a Nostr perspective," and the reason rival
protocols don't deliver it is that "they never dared to take the step of
putting keys at the center and in the hands of the user."

## Where he differs from the other voices

- vs. **fiatjaf** on what the invention is: fiatjaf says relays (keys are
  pragmatics); Constant says the *paradigm* — keys AND relays AND events,
  taught explicitly. They converge completely on relay-side curation, NIP-29,
  and hatred of hardcoded relay lists.
- vs. **onboarding orthodoxy** (much of the client scene): most builders
  hide complexity to reduce friction; Constant argues hiding it is how you
  lose the war. His BTC Prague keynote premise: "most of you are just dead
  wrong."
- vs. **privacy maximalists**: Nostr is for publications; don't sell it as a
  privacy tool, and don't judge it for not being one.


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/ping-relay.md ===

# ping-relay.ts

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [all examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) · source: `nostr-dev/sdk/examples/ping-relay.ts` · snapshot 2026-10-10

Connect to a relay with nostr-tools and read a few kind 1 events.

```ts
import { Relay, useWebSocketImplementation } from "nostr-tools/relay";
import WebSocket from "ws";

useWebSocketImplementation(WebSocket as any);

const url = process.argv[2] ?? "wss://relay.ngit.dev";

const relay = await Relay.connect(url);
console.log(`connected: ${relay.url}`);

const events: any[] = [];
const sub = relay.subscribe(
  [{ kinds: [1], limit: 3 }],
  {
    onevent(e) {
      events.push(e);
      console.log(`kind=${e.kind} id=${e.id.slice(0, 12)}… author=${e.pubkey.slice(0, 12)}… content="${e.content.slice(0, 60).replace(/\s+/g, " ")}"`);
    },
    oneose() {
      console.log(`EOSE — ${events.length} events`);
      sub.close();
      relay.close();
    },
  }
);
```


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/fetch-profile.md ===

# fetch-profile.ts

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [all examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) · source: `nostr-dev/sdk/examples/fetch-profile.ts` · snapshot 2026-10-10

Fetch a kind 0 profile.

```ts
import NDK from "@nostr-dev-kit/ndk";

const npubOrHex = process.argv[2] ?? "npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6";

const ndk = new NDK({
  explicitRelayUrls: [
    "wss://relay.ngit.dev",
    "wss://relay.damus.io",
    "wss://nos.lol",
    "wss://relay.nostr.band",
  ],
});
await ndk.connect(2000);

const user = ndk.getUser({ npub: npubOrHex.startsWith("npub") ? npubOrHex : undefined, pubkey: npubOrHex.startsWith("npub") ? undefined : npubOrHex });
const profile = await user.fetchProfile();

console.log(`pubkey:   ${user.pubkey}`);
console.log(`name:     ${profile?.name}`);
console.log(`display:  ${profile?.displayName}`);
console.log(`about:    ${profile?.about?.slice(0, 200)}`);
console.log(`nip05:    ${profile?.nip05}`);
console.log(`picture:  ${profile?.picture}`);

process.exit(0);
```


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/fetch-grasp-repo.md ===

# fetch-grasp-repo.ts

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [all examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) · source: `nostr-dev/sdk/examples/fetch-grasp-repo.ts` · snapshot 2026-10-10

Fetch a NIP-34 repository announcement from a GRASP relay.

```ts
/**
 * Fetch a GRASP / nostr-git "repository announcement" (kind 30617, NIP-34)
 * and its "repository state" (kind 30618).
 *
 * Usage:
 *   tsx examples/fetch-grasp-repo.ts <pubkey-hex-or-npub> <repo-d-tag>
 *
 * Example (replace with a real one):
 *   tsx examples/fetch-grasp-repo.ts npub1xxxx... ngit
 */
import NDK, { NDKEvent, NDKFilter } from "@nostr-dev-kit/ndk";

const owner = process.argv[2];
const dTag = process.argv[3];
if (!owner || !dTag) {
  console.error("usage: fetch-grasp-repo <pubkey-hex-or-npub> <repo-d-tag>");
  process.exit(1);
}

const ndk = new NDK({
  explicitRelayUrls: [
    "wss://relay.ngit.dev",
    "wss://relay.damus.io",
    "wss://nos.lol",
    "wss://relay.nostr.band",
  ],
});
await ndk.connect(2000);

const user = owner.startsWith("npub") ? ndk.getUser({ npub: owner }) : ndk.getUser({ pubkey: owner });

const filter: NDKFilter = {
  kinds: [30617 as number, 30618 as number],
  authors: [user.pubkey],
  "#d": [dTag],
};

const events = await ndk.fetchEvents(filter);
for (const ev of events) {
  console.log(`--- kind ${ev.kind} ---`);
  console.log(`id:      ${ev.id}`);
  console.log(`created: ${new Date((ev.created_at ?? 0) * 1000).toISOString()}`);
  for (const t of ev.tags) console.log(`  tag: ${t.join(" | ")}`);
  if (ev.kind === 30617) {
    const clone = ev.tags.find((t) => t[0] === "clone")?.slice(1).join(", ");
    const relays = ev.tags.find((t) => t[0] === "relays")?.slice(1).join(", ");
    console.log(`clone urls: ${clone}`);
    console.log(`relays:     ${relays}`);
  }
}
console.log(`(${events.size} event(s))`);
process.exit(0);
```


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/blossom-upload.md ===

# blossom-upload.ts

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [all examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) · source: `nostr-dev/sdk/examples/blossom-upload.ts` · 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.

Upload a blob to a Blossom server with a signed kind 24242 auth event.

```ts
/**
 * Upload a file to the local Blossom server (built into the ngit-relay container)
 * using a NIP-98-style kind:24242 auth event, then verify it round-trips.
 *
 * Usage:
 *   tsx examples/blossom-upload.ts <path-to-file>
 *
 * Env:
 *   NOSTR_SECRET_KEY   nsec or hex secret key for signing the upload auth event
 *
 * Server: http://localhost:8081  (override with BLOSSOM_SERVER env var)
 */
import { readFileSync, statSync } from "node:fs";
import { createHash } from "node:crypto";
import { finalizeEvent, getPublicKey, nip19 } from "nostr-tools";

const filePath = process.argv[2];
if (!filePath) {
  console.error("usage: tsx examples/blossom-upload.ts <path-to-file>");
  process.exit(1);
}

const sec = process.env.NOSTR_SECRET_KEY;
if (!sec) {
  console.error("error: set NOSTR_SECRET_KEY (nsec or hex) in the environment");
  process.exit(1);
}

const sk: Uint8Array = sec.startsWith("nsec1")
  ? (nip19.decode(sec).data as Uint8Array)
  : Uint8Array.from(Buffer.from(sec, "hex"));
const pk = getPublicKey(sk);

const server = (process.env.BLOSSOM_SERVER ?? "http://localhost:8081").replace(/\/$/, "");

// Read the file and compute its sha256
const data = readFileSync(filePath);
const size = statSync(filePath).size;
const sha256 = createHash("sha256").update(data).digest("hex");
console.log(`file:    ${filePath}  (${size} bytes)`);
console.log(`sha256:  ${sha256}`);
console.log(`pubkey:  ${pk}`);
console.log(`server:  ${server}`);

// Build the BUD-01 auth event (kind 24242)
const now = Math.floor(Date.now() / 1000);
const authEvent = finalizeEvent(
  {
    kind: 24242,
    created_at: now,
    tags: [
      ["t", "upload"],
      ["x", sha256],
      ["expiration", String(now + 600)],
    ],
    content: `upload ${filePath}`,
  },
  sk
);
const authHeader = "Nostr " + Buffer.from(JSON.stringify(authEvent)).toString("base64");

// Upload
const uploadRes = await fetch(`${server}/upload`, {
  method: "PUT",
  headers: { Authorization: authHeader, "Content-Type": "application/octet-stream" },
  body: data,
});
console.log(`\nupload:  HTTP ${uploadRes.status}`);
const uploadBody = await uploadRes.text();
console.log(`         ${uploadBody.slice(0, 200)}`);

if (!uploadRes.ok) process.exit(1);

// Verify with HEAD
const head = await fetch(`${server}/${sha256}`, { method: "HEAD" });
console.log(`\nHEAD:    HTTP ${head.status}  Content-Length=${head.headers.get("content-length")}`);

// Verify with GET
const get = await fetch(`${server}/${sha256}`);
const got = Buffer.from(await get.arrayBuffer());
const gotSha = createHash("sha256").update(got).digest("hex");
console.log(`GET:     HTTP ${get.status}  ${got.length} bytes  sha256=${gotSha}`);
console.log(`match:   ${gotSha === sha256 ? "✓" : "✗"}`);

// List
const list = await fetch(`${server}/list/${pk}`).then((r) => r.json() as Promise<any[]>);
console.log(`\nlist/${pk.slice(0, 8)}…:  ${list.length} blob(s) for our pubkey`);

process.exit(0);
```


=== FILE: https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/publish-wrap-with-auth.md ===

# publish-wrap-with-auth.ts

> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [all examples](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/examples/README.md) · source: `nostr-dev/sdk/examples/publish-wrap-with-auth.ts` · snapshot 2026-10-10

Publish a pre-signed event to a relay that demands NIP-42 AUTH, without re-signing it.

```ts
// Publish a fully-signed event (e.g. a NIP-59 gift wrap) to a relay that
// requires NIP-42 AUTH, WITHOUT letting any helper re-sign the event itself.
// `nak event --sec ... --auth` rebuilds the event when the --sec pubkey
// doesn't match event.pubkey, which corrupts gift wraps. This script keeps
// the wrap byte-for-byte and only uses the key to satisfy AUTH.
//
// Usage:
//   NOSTR_SECRET_KEY=nsec1... npx tsx publish-wrap-with-auth.ts <event.json> <relay-url> [more relays]

import WebSocket from "ws";
import * as fs from "fs";
import { finalizeEvent } from "nostr-tools/pure";
import { nip19 } from "nostr-tools";

const eventPath = process.argv[2];
const relayUrls = process.argv.slice(3);
if (!eventPath || relayUrls.length === 0) {
  console.error("usage: publish-wrap-with-auth.ts <event.json> <relay-url> [more relays]");
  process.exit(2);
}

const nsec = process.env.NOSTR_SECRET_KEY;
if (!nsec) {
  console.error("NOSTR_SECRET_KEY env var must be set (nsec1... or hex)");
  process.exit(2);
}

const sk: Uint8Array = (() => {
  if (nsec.startsWith("nsec1")) {
    const { type, data } = nip19.decode(nsec);
    if (type !== "nsec") throw new Error("not an nsec");
    return data as Uint8Array;
  }
  // hex
  const bytes = new Uint8Array(32);
  for (let i = 0; i < 32; i++) bytes[i] = parseInt(nsec.slice(i * 2, i * 2 + 2), 16);
  return bytes;
})();

const evt = JSON.parse(fs.readFileSync(eventPath, "utf-8"));

async function publishToRelay(url: string): Promise<{ url: string; result: string }> {
  return new Promise((resolve) => {
    const ws = new WebSocket(url);
    let publishedOnce = false;

    const finish = (result: string) => {
      try { ws.close(); } catch {}
      resolve({ url, result });
    };

    const timeout = setTimeout(() => finish("TIMEOUT (15s)"), 15000);

    let pendingChallenge: string | null = null;
    let eventSent = false;
    let authSent = false;
    const trySendEvent = () => {
      if (!eventSent) {
        eventSent = true;
        ws.send(JSON.stringify(["EVENT", evt]));
      }
    };
    const respondToChallenge = (challenge: string) => {
      if (authSent) return;
      authSent = true;
      const authEvent = finalizeEvent(
        {
          kind: 22242,
          created_at: Math.floor(Date.now() / 1000),
          tags: [
            ["relay", url],
            ["challenge", challenge],
          ],
          content: "",
        },
        sk
      );
      ws.send(JSON.stringify(["AUTH", authEvent]));
    };

    ws.on("open", () => {
      // Wait ~500 ms for a proactive AUTH challenge before sending EVENT,
      // so AUTH-first relays don't reject us with auth-required.
      setTimeout(() => {
        if (pendingChallenge) respondToChallenge(pendingChallenge);
        trySendEvent();
      }, 500);
    });

    ws.on("message", (data) => {
      let msg: any;
      try { msg = JSON.parse(data.toString()); } catch { return; }
      if (!Array.isArray(msg)) return;
      console.error(`[${url}] <- ${JSON.stringify(msg).slice(0, 200)}`);

      if (msg[0] === "AUTH") {
        pendingChallenge = msg[1];
        respondToChallenge(msg[1]);
        // After AUTH, retry EVENT if we already sent once and got rejected.
        if (eventSent) {
          eventSent = false;
          setTimeout(trySendEvent, 100);
        }
      } else if (msg[0] === "OK" && msg[1] === evt.id) {
        const ok = msg[2];
        const note = msg[3] ?? "";
        if (!ok && /auth-required/i.test(note)) {
          // Wait for the relay to send us an AUTH challenge if it hasn't already.
          return;
        }
        clearTimeout(timeout);
        finish(ok ? `success` : `rejected: ${note}`);
      } else if (msg[0] === "NOTICE") {
        console.error(`[${url}] NOTICE: ${msg[1]}`);
      } else if (msg[0] === "CLOSED") {
        clearTimeout(timeout);
        finish(`CLOSED: ${msg[2] ?? ""}`);
      }
    });

    ws.on("error", (err) => {
      clearTimeout(timeout);
      finish(`error: ${err.message}`);
    });
  });
}

(async () => {
  console.error(`event id: ${evt.id}`);
  console.error(`event kind: ${evt.kind}`);
  console.error(`event pubkey: ${evt.pubkey} (preserved, NOT re-signed)`);
  console.error("");
  for (const url of relayUrls) {
    const { result } = await publishToRelay(url);
    console.log(`${url}\t${result}`);
  }
})();
```