NIP-16: Event Treatment
Not every event wants the same life span
NIP-16 answers a basic relay question: when an event arrives, how long is it supposed to matter? A normal post can be stored forever. A profile metadata update replaces the older profile. A typing indicator is useful only in the moment. A long-form article is addressed by a stable coordinate even though new versions may replace older ones.
Those behaviors are not UX polish. They shape relay storage, client queries, sync behavior and user expectations. If a relay stores ephemeral events forever, it wastes space and leaks more than the sender expected. If it fails to replace metadata, clients show stale profiles. If it mishandles addressable events, articles, lists and product pages become harder to reference.
NIP-16 is now only a small archived file because the event-treatment rules moved into NIP-01. That move makes sense. Event lifetime is not an optional plugin. It is part of the base grammar every relay and client has to understand.
The kind ranges that teach relays how to treat events
The current NIP-01 text defines the behavior by kind ranges. Regular events include kind 1, kinds 4 through 44, kind 2 and the 1000 to 9999 range. Relays are expected to store them as normal events.
Replaceable events include kind 0, kind 3 and the 10000 to 19999 range. For a given pubkey and kind, only the latest event needs to be stored. Ephemeral events live in 20000 to 29999; relays are not expected to store them. Addressable events live in 30000 to 39999 and are addressed by kind, pubkey and d tag value.
That last category came from NIP-33 language but now belongs to the same lifetime map. The key lesson is simple: an event's kind is not only a display hint. It tells relays and clients whether the event is a record, current state, a momentary signal or a versioned object.
A storage policy became base protocol
Semisol drafted NIP-16 in May 2022. Early commits moved from tags toward kind ranges, which made the behavior easier for relays to apply quickly. Later changes clarified signer behavior, kind ranges and replacement tie-breaking. Doug Hoyte's 2023 change around same-timestamp replacement behavior is a good example of how small ordering rules become user-visible state.
In August 2023, the same PR #703 that moved NIP-12 into NIP-01 also merged NIP-16 into the base protocol. That consolidation made the NIP file look empty but made the actual rule more important.
The debates did not end. Issue #236 explored generalizing event lifetime preferences beyond fixed ranges using d and expiration tags. Issue #537 showed the practical tension around ephemeral events in Nostr Wallet Connect: if an event is too ephemeral, a mobile wallet that is briefly offline can miss the request.
Relays carry the burden; users see stale or missing state
Relay software has to map kind ranges to storage behavior. A replaceable profile update needs the newest event. An addressable article needs the newest event for a specific coordinate. An ephemeral event may be forwarded to current subscribers and then forgotten. These are storage policies, but the user sees them as product behavior.
Nostrbook's kind-range overview is helpful because it shows how many familiar objects depend on this map: user metadata, follow lists, mute lists, bookmarks, app data, articles, badges, wallet configuration and many more. The ranges are not trivia; they keep a large event universe manageable.
The hard part is edge cases. What if two replaceable events have the same timestamp? What if a relay stores ephemeral events briefly in memory? What if a client depends on an ephemeral event for a payment request but the receiver was offline? NIP-16's archived page is a doorway into those real design choices.
Lifetime rules are easy to hide and hard to debug
The main risk is mismatched relay behavior. A client may expect the latest replaceable event while a relay keeps several, or a client may rely on an ephemeral message that a relay properly refuses to store. The user sees confusion, not a kind-range dispute.
The second risk is designing workflows around the wrong lifetime. A typing indicator belongs in ephemeral space. A payment request that must survive mobile disconnection may not. NIP-16 teaches that storage semantics are product semantics.
Read NIP-16 in the wild
NIP-16 is archived because event treatment became part of NIP-01. Its old job was to distinguish regular, replaceable, ephemeral and addressable behavior so clients and relays knew whether an event was a timeline post, current state, temporary signal or named object.
This is still one of the most important ideas in the protocol. A profile update, relay list, article and chat message do not behave the same way. If a product treats all events as ordinary posts, it will lose the point of half the standards.
What changes when you actually use it
For you, NIP-16: Event Treatment is felt when an app either behaves predictably or suddenly loses context. The visible symptom may be a missing reply, a broken link, a strange reaction count, an empty result or a relay error that looks like the whole network failed. The official terms the event kind, tags, content field, relay behavior and signature path are where that visible behavior begins, so the source is not background material; it is the place where the product promise gets its limits.
What changes for builders and operators
For builders, NIP-16: Event Treatment is compatibility discipline. Implement the event kind, tags, content field, relay behavior and signature path against more than one relay and more than one library, then test malformed, missing and duplicated data. Core standards fail most painfully when the happy path looks fine and the second client exposes the shortcut.
What the official file makes concrete
Read it beside NIP-01 before treating it as isolated.
NIP-16: Event Treatment is a shared contract between independent software. The smallest field can become user-visible when two clients disagree about it.
Where it breaks
The failure mode in NIP-16: Event Treatment is often indirect. Nobody complains about the event kind, tags, content field, relay behavior and signature path; they complain that the feed is wrong, the reply vanished or the relay behaved strangely. Use the official file to diagnose the hidden cause instead of patching only the visual symptom.
Where this appears outside the markdown
In the ecosystem, NIP-16: Event Treatment is not something most people choose directly. It is the invisible grammar behind clients, relays, crawlers, search tools and archives. When a product team treats the event kind, tags, content field, relay behavior and signature path as implementation detail only, the mistake eventually reaches the surface as missing history, bad threading or state that cannot be reconstructed after a client switch.
The nearby-standard trap
The nearby-standard trap in NIP-16: Event Treatment is assuming the base layer solves the higher-level feature. This NIP may define the common grammar, but publishing, wallets, moderation, media or groups still need their own constraints. Read NIP-01 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-16: Event Treatment does not say "the protocol handles it" and move on. It explains the visible consequence: what was sent, what was accepted, what was rejected, what is still loading and what another relay or client may show differently.
What this page does not promise
NIP-16: Event Treatment does not promise a finished social product. It gives software a shared grammar. Feed design, moderation, ranking, notifications, storage duration and recovery remain separate product decisions. That distinction matters because a client can be technically compatible and still give you a weak experience if it hides relay errors, drops context or treats optional fields as if every app understood them.
Read it as a field test
Start NIP-16: Event Treatment with the visible product symptom, then trace it back to the event kind, tags, content field, relay behavior and signature path. That order keeps the article grounded: you see why the field exists, which relay or client behavior depends on it, and where adjacent standards change the story. A core NIP is strong only when it explains both the normal path and the awkward edge case.
Where the standard earns trust
The source links give you places to test the interpretation in public: NIP-01 event kind ranges, Issue #236: event lifetime preferences, Issue #537: ephemeral NIP-47, Nostr-nips mirror: NIP-16. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-16 source is the anchor for exact wording, and NIP-16 commit history shows how that wording moved over time. The strongest secondary clues here are NIP-01 event kind ranges, Issue #236: event lifetime preferences, Issue #537: ephemeral NIP-47. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-16: Event Treatment: first the human promise, then the event kind, tags, content field, relay behavior and signature path, then the implementation record, then the real-world failure case. That order keeps NIP-16 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same the main event fields without a hidden compatibility rule?
- Does the UI explain relay rejection, missing context or state replacement without blaming the whole network?
- Which adjacent standard, especially NIP-01, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find the main event shape in the official file and check how the UI exposes it.
- Read NIP-01 as context before treating NIP-16 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-16: Event Treatment in that order: Official NIP-16 source for the current wording; NIP-16 commit history for the change record; NIP-01 event kind ranges, Issue #236: event lifetime preferences, Issue #537: ephemeral NIP-47 for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
