The social graph

Your friends list is a note you sign

On a big platform, “who follows whom” is a giant table inside the company’s database. You can look at your row, but you don’t own it, and you can’t take it with you.

Nostr has no such table. Instead, each person publishes their own follow list: a small, signed event of kind 3 that says “these are the people I follow.” Each follow is one line, a p tag holding the other person’s public key.

Think of it like the contacts page in your own notebook. Nobody else writes in it. You can photocopy it and leave copies at several relays, and any app you open later can read it and rebuild your timeline. New phone? New app? Your friends come with you, because the list was never the app’s in the first place.

Put everyone’s notebook pages side by side and you get a social graph. Here are our seven fixture friends, drawn from their real (signed!) kind 3 events:

Try this: hover Grace with the “Who follows them” lens on. Only Carol and Erin follow her. Now select Alice: six people follow her. Thicker double arrows mean a mutual follow (both lists mention each other). Drag a few people around; the graph wobbles back into shape like a jelly.

{
  "kind": 3,
  "pubkey": "<Grace's pubkey>",
  "created_at": 1735682400,
  "tags": [
    ["p", "e550c6e9…44cc", "wss://relay.alpha.example", "alice"],
    ["p", "a7388391…e183", "wss://relay.beta.example", "bob"],
    ["p", "c7175000…5deb", "wss://relay.alpha.example", "erin"]
  ],
  "content": "",
  "id": "…",
  "sig": "…"
}

import { SimplePool } from "nostr-tools/pool";

const pool = new SimplePool();
const relays = ["wss://relay.alpha.example"];

// Who does Grace follow? Her newest kind 3.
const list = await pool.get(relays, { kinds: [3], authors: [gracePubkey] });
const follows = (list?.tags ?? []).filter((t) => t[0] === "p").map((t) => t[1]);

// Who follows Grace? Search for kind 3 events that tag her (an estimate!).
const followers = await pool.querySync(relays, { kinds: [3], "#p": [gracePubkey] });

Replaceable means “the newest copy wins”

Kind 3 is a replaceable event. A relay keeps only the newest follow list per person and throws older ones away. That keeps things tidy, but it has a sharp edge: a new list doesn’t add to the old one, it replaces it whole.

So what happens if an app that hasn’t synced in a month publishes your list? Let’s find out. You’re Grace. Follow a few people, publish from your phone, then let that dusty old tablet publish its own (outdated) idea of your list:

Ouch. This isn’t a theoretical bug: people have lost their whole follow list this way. Good apps always fetch your newest kind 3 right before editing it, which is exactly what the “Sync phone from relay” button does.

const newest = (events: NostrEvent[]) =>
  events.reduce((best, e) =>
    e.created_at > best.created_at ||
    (e.created_at === best.created_at && e.id < best.id) ? e : best);

But where do I find my friends’ notes?

Here’s a puzzle. Erin follows Alice, Carol, Frank and Grace. Her app wants to show their latest notes. But there are thousands of relays, and nobody is on all of them. Which ones should the app ask?

The naive answer is “everyone’s on the big relay, just ask that one.” That works… until someone isn’t. The better answer is the outbox model, described in NIP-65.

Every person publishes one more small event, kind 10002, listing their relays, each one marked as:

• write: “I publish my notes here.” This is their outbox. Go here to read them.
• read: “I check here for replies and mentions.” This is their inbox. Go here to reach them.
• no marker: both.

It’s like a friend telling you “I post my letters from the Alpha and Beta post offices, and I collect my mail at Gamma.” To read their letters you visit Alpha or Beta. To write to them, you drop your letter at Gamma.

Press play and watch Erin’s client work it out. Then switch to Everyone on one relay and compare. And try Reply to a friend to see the inbox side.

Notice two things:

1. In the outbox model the app opens a subscription on each relay asking only for the authors who write there. Nobody goes missing, even Grace, who only uses tiny Gamma.
2. With one relay, Frank and Grace silently vanish. Nobody gets an error; Erin just never sees their notes. That’s the real danger: the network looks fine.

{
  "kind": 10002,
  "tags": [
    ["r", "wss://relay.gamma.example"],
    ["r", "wss://relay.alpha.example", "write"]
  ],
  "content": ""
}

import { SimplePool } from "nostr-tools/pool";

const pool = new SimplePool();
const INDEXERS = ["wss://relay.alpha.example"];

// 1. Where does each followed person write?
const lists = await pool.querySync(INDEXERS, { kinds: [10002], authors: follows });
const writeRelaysOf = new Map(
  lists.map((e) => [
    e.pubkey,
    e.tags.filter((t) => t[0] === "r" && t[2] !== "read").map((t) => t[1]),
  ]),
);

// 2. Group authors by relay, then subscribe per relay with just those authors.
const byRelay = new Map<string, string[]>();
for (const [author, relays] of writeRelaysOf)
  for (const url of relays) byRelay.set(url, [...(byRelay.get(url) ?? []), author]);

for (const [url, authors] of byRelay)
  pool.subscribeMany([url], { kinds: [1], authors, limit: 20 }, { onevent: show });

Beyond follows

The follow graph is useful for more than your timeline. Apps use it as a web of trust: “show replies from people my friends follow, hide strangers” is a surprisingly strong spam filter, and nobody had to build a central reputation database to get it. Your kind 3 also doubles as a portable backup and a list of relay hints for the people you follow.

That’s the trick of this chapter: a social network built entirely from small notes that each person signs, stores where they like, and can take anywhere.

Quick check