1 Overview
NIP-16 answered one question: what should a relay do when it receives an event? The original NIP-01 only said a relay stores events. NIP-16 split events into storage classes, based on the kind number, and gave each class its own storage rule.
Three classes existed at first: regular events, which a relay keeps in full; replaceable events, where only the newest event per author and kind survives; and ephemeral events, which a relay forwards but does not store at all.
NIP-16 is closed and carries no separate rules of its own anymore. Its storage classes now live in NIP-01, section 4 (Kinds and Storage Classes). Read this page for history, then read NIP-01 for the current spec.
2 What NIP-16 Defined
NIP-16 stated these rules, restated here in Simplified Technical English:
| Class | Kind range | Rule |
|---|---|---|
| Regular | 1000 - 9999 | The relay stores every regular event and forwards it to matching subscriptions. Newer events never affect older ones. |
| Replaceable | 10000 - 19999 | For each author and kind pair, the relay keeps only the newest event. It discards older ones. |
| Ephemeral | 20000 - 29999 | The relay forwards the event to matching subscriptions but must not store it. |
A later addition specified the tie-break rule for replaceable events: when two events share the same created_at timestamp, the relay keeps the one whose id sorts first, and discards the other. NIP-16 also recommended that clients use the relay's supported_nips field to check for support, and warned that ephemeral events sent to a relay without NIP-16 support would likely be stored by mistake.
Where It Lives Now
NIP-01 kept the three classes and their names, and added a fourth: addressable events, absorbed separately from NIP-33. NIP-01 also widened the replaceable range: it now treats kind 0 and kind 3 as replaceable too, alongside the 10000-19999 range. The same-timestamp tie-break rule that NIP-16 introduced carried over unchanged.
3 Historical Example
NIP-16 suggested these use cases for its new event classes. They still apply under NIP-01 today.
-- Replaceable: a profile status that overwrites itself -- -- Ephemeral: a typing indicator in a chat app -- -- Ephemeral: two pubkeys messaging live without relay storage --
4 Version History
- Closed2023-08-13Merged into NIP-01 along with NIP-12, NIP-20, and NIP-33 (PR #703). All four were already "final, mandatory" — folding them into the root spec meant a client or relay only had to read one document to reach baseline compliance.
- 20232023-11-15Repo-wide cleanup removed the per-file author badge from the now-stub page.
- 20232023-05-19Doug Hoyte specified the same-timestamp tie-break rule: keep the event with the lowest
id. - 20232023-03-26Leo Wandersleb clarified the wording: events are not truly replaced in place, older ones are simply discarded from what queries return.
- 20222022-12-08Jonathan Staab clarified how kind 1 and the 1000-10000 range relate to the regular-event class.
- 20222022-11-10alex clarified which pubkey's signature counts when a replaceable event is replaced.
- 20222022-05-27Semisol switched the design from per-tag markers to numeric kind ranges.
- Origin2022-05-26Semisol published NIP-16 as a draft.
Original Proposal - Credits
| Author | Semisol |
| First commit | 2022-05-26 — “nip16: create draft” |
| Status | final mandatory — merged, no longer a standalone document |
| Source | 16.md on GitHub - full change history |