Relays & the wire protocol

You have a keypair and you know how to sign an event. But a signed note sitting on your laptop is a diary, not a social network. To reach other people it has to travel somewhere. On Nostr, that somewhere is a relay.

Relays are dumb (and that’s a compliment)

Picture a relay as a community notice board in a café. Anyone can pin a card on it, anyone can walk up and read the cards, and the café owner decides house rules: no ads, members only, cards taken down after a month. That’s it. The notice board doesn’t know your friends, doesn’t rank your feed, and doesn’t talk to the notice board in the café across the street.

Your client (the app you use) is the opposite: it’s your personal assistant. It knows which notice boards your friends use, walks to several of them, collects the cards, throws away duplicates, checks every signature, and lays everything out nicely for you.

This split is on purpose:

• Relays stay simple, so they’re cheap to run. Thousands of people run one, from big public relays to a tiny one in someone’s closet.
• Clients hold the intelligence, so you choose the algorithm, not a company.
• Nothing depends on one relay. If a board disappears, your assistant just reads another one. That’s where Nostr’s censorship resistance comes from.

Eavesdropping on the wire

Clients and relays talk over a WebSocket: a phone line that stays open, so both sides can speak whenever they like. Every message on that line is a tiny JSON array whose first item is a shouty uppercase word: the verb.

Pick a conversation below, then press play, step through it with the arrows, or drag the scrubber. Click any packet type in the legend to jump straight to it. Keep an eye on the client’s notebook: that’s all the bookkeeping relays don’t do.

The whole vocabulary fits on a sticky note

NIP-01 defines the core language. Your client says three things:

The relay answers with five:

And there’s one extra pair for logging in, from NIP-42: AUTH. The relay sends a random challenge; your client signs it with your key and sends it back. No password ever crosses the wire, only a signature. (There’s also COUNT from NIP-45, for “how many?” questions, but you rarely see it.)

["REQ", "feed", {"authors": ["e550c6e9…"], "kinds": [1], "limit": 2}]
["EVENT", "feed", {"id": "…", "pubkey": "…", "created_at": 1735686600, "kind": 1, "tags": [], "content": "…", "sig": "…"}]
["EOSE", "feed"]
["CLOSE", "feed"]

["EVENT", {"id": "…", "kind": 1, "…": "…"}]
["OK", "<event id>", true, ""]
["OK", "<event id>", false, "pow: difficulty 16 or more is required"]
["CLOSED", "feed", "rate-limited: slow down, too many requests"]
["NOTICE", "heads up: this relay restarts at 03:00 UTC"]

["AUTH", "ostrich-7f3a9c2e"]
["CLOSED", "dms", "auth-required: gift wraps are only served to their recipient"]

["AUTH", {"kind": 22242, "tags": [["relay", "wss://relay.delta.example"], ["challenge", "ostrich-7f3a9c2e"]], "content": "", "…": "id, pubkey, created_at, sig"}]
["OK", "<auth event id>", true, ""]

import { SimplePool } from "nostr-tools/pool";
import { finalizeEvent, generateSecretKey } from "nostr-tools/pure";

const relays = ["wss://relay.damus.io", "wss://nos.lol", "wss://relay.primal.net"];
const pool = new SimplePool();

// REQ to every relay; onevent fires once per unique event, oneose when all relays sent EOSE.
const sub = pool.subscribeMany(relays, { kinds: [1], limit: 3 }, {
  onevent: (event) => console.log(event.pubkey.slice(0, 8), event.content),
  oneose: () => sub.close(), // sends CLOSE to each relay
});

// Publishing = one EVENT per relay; each promise settles with that relay's OK.
const event = finalizeEvent(
  { kind: 1, created_at: Math.floor(Date.now() / 1000), tags: [], content: "hello relays" },
  generateSecretKey(),
);
const results = await Promise.allSettled(pool.publish(relays, event));
console.log(results.map((r) => r.status)); // e.g. ["fulfilled", "fulfilled", "rejected"]

Don’t put all your notes in one relay

Because relays don’t copy events between each other, your client usually sends every note to several relays at once. If one goes offline, gets overloaded, or decides it doesn’t like you, your followers can still find your note on the others. Some relays are free, some are paid (a small fee is a great spam filter), and each has its own house rules. Mix and match.

Try it: choose where to publish, then start knocking relays offline.

How does Bob’s client know which relays to check for your notes? You publish a small list of “where I write” relays, and his client goes there. That’s the outbox model (NIP-65), and it’s coming up in chapter 7.

Listen to the real thing

Everything above was scripted. This panel sends a real REQ and shows every frame exactly as it arrives. By default it talks to our practice relays; flip Live mode in the header and it talks to real public relays instead. Don’t worry: it only ever reads. We never publish anything.

Notice the CLOSE frames at the end: once every relay has said EOSE, the panel politely hangs up. A real client would often keep the subscription open to receive new notes as they’re posted.

Quick check