Kinds & NIPs

One envelope, many stamps

So far every event has looked the same: an id, a pubkey, a timestamp, some tags, some content and a signature. A tweet-style note, your profile, a “like”, a blog post and a Lightning receipt all travel in the exact same envelope.

So how does an app know which is which? One tiny field: the kind. It’s just an integer, like a stamp on the envelope. 1 means “short text note”, 0 means “my profile”, 7 means “reaction”, 30023 means “long-form article”. That’s it. No new message types, no new endpoints: Nostr grows by inventing new numbers.

Think of the kind as the section of a library. The books (events) are all bound the same way, but the sticker on the spine tells the librarian (the relay) which shelf to put it on, and tells readers (clients) how to display it.

The periodic table of kinds

Chemists sort elements by their properties. We can do the same with kinds: the color of a tile is its storage category, which is decided purely by the number’s range. Click around: every tile opens a real example event. Try to visit all four colors.

▸  { "id": "ea2e3eb8fe5e6cfbc202da21df546f68c6673e9a00c0aed61cffbac7aed9faf7" ,"pubkey": "a73883912a48c3551c1548fd454876d577126a61c76b5486c807bfec5869e183" ,"created_at": 1735686600 ,"kind": 1 , "tags": [  ] ,"content": "testing testing is this thing on" ,"sig": "82bc74fdbd5b113f257f4c8b2a6db64410ae897362bd42839fe9a34737d5ecb518a99f8517058ef8c2beadc222142e4d68f034e829edc9dd1b6bd13d2a139a7d"  } 

["REQ","kinds-demo",{"kinds":[1],"limit":10}]

import { kinds } from "nostr-tools";

kinds.ShortTextNote;            // 1
kinds.LongFormArticle;          // 30023
kinds.classifyKind(30023);      // "parameterized" (nostr-tools' older name for addressable)
kinds.isReplaceableKind(10002); // true

Four ways to be stored

The number tells a relay what to keep. NIP-01 splits the number line into four neighborhoods:

• Regular (1, 2, 4–44, 1000–9999): a diary. Every page is kept. Notes, reactions, reposts and zap receipts pile up forever (or until the relay decides otherwise).
• Replaceable (0, 3, 10000–19999): a whiteboard. Each person gets one per kind; writing a new one wipes the old. Your profile (kind 0), your follow list (kind 3) and your relay list (kind 10002) work this way.
• Ephemeral (20000–29999): a phone call. Relays pass it to whoever is listening right now and then forget it. Perfect for login challenges and signer chatter.
• Addressable (30000–39999): a set of labeled whiteboards. One per person, per kind, per d tag. That’s how you can edit several long-form articles independently.

Play with it. Publish a few versions, switch categories, and then try re-sending an older copy:

["a", "30023:e550c6e92808f358382b7b8c14345344f5ef9a299529834d1c26d57b6ace44cc:relays-explained", "wss://relay.alpha.example"]

["REQ", "article", { "kinds": [30023], "authors": ["e550c6…"], "#d": ["relays-explained"] }]

Want to test your intuition? Type any number and see which neighborhood it lives in:

NIPs: how Nostr grows without a boss

Who decides that 7 means “reaction”? Nobody, and everybody. A NIP (Nostr Implementation Possibility) is a short, public document describing a convention: which kind to use, which tags, what the content means. They live in one GitHub repository, but they work more like recipes shared at a potluck than laws:

1. Someone has an idea. A developer wants polls, or calendars, or marketplaces.
2. They build it first. Ideally in a real client and relay, picking a kind number nobody else uses.
3. They open a pull request. People argue, simplify, and poke holes in it in public.
4. It gets merged when it’s real. The README asks that a NIP be implemented in at least two clients and one relay (where applicable), make sense, be optional and backwards-compatible, and not add a second way to do the same thing.

The key trick is the word optional. A client that doesn’t understand kind 31922 (a calendar event) simply ignores it. Nothing breaks. That’s why Nostr can grow sideways: microblogging, long-form, livestreams, code collaboration and wallets all share the same relays and the same keys.

Quick check