NIP-33: Parameterized Replaceable Events
Some Nostr objects need stable names and editable versions
NIP-33 is one of the standards that looks empty today because it succeeded. The file now says the idea was renamed to Addressable events and moved to NIP-01. The behavior it introduced is everywhere: long-form articles, lists, badges, app data, calendars, communities, emoji sets and many other objects need stable coordinates that survive edits.
A normal event ID is immutable. That is good for verification, but awkward for things that have a living identity. A blog post can be corrected. A list can change. A profile-like app record can be updated. Users still need a stable way to refer to 'this article' or 'this list' instead of only one historical event ID.
Addressable events solve that by combining kind, author pubkey and a d tag value. The latest valid event for that coordinate becomes the current version. The older versions can remain in history, but clients and relays have a rule for which one represents the object now.
The 30000-39999 range and the d-tag coordinate
The current NIP-01 text says kinds 30000 through 39999 are addressable by kind, pubkey and d tag value. For each combination, relays keep the latest event and can discard older versions. The coordinate is written as kind:pubkey:d-tag and can be referenced with an a tag.
NIP-01 also defines how a tags refer to addressable or replaceable events, including relay hints. NIP-19 turns coordinates into naddr strings for sharing. NIP-21 can wrap those naddr strings in nostr: links. Those three layers make addressable objects usable in clients and on the web.
The tie-breaking rule matters. If replaceable events share the same timestamp, the event with the lowest ID wins. That sounds like a tiny implementation note, but without a deterministic rule different relays and clients could disagree on the current version of the same object.
From parameterized replaceable events to addressable events
Semisol added NIP-33 in January 2023 through PR #54. Early commits added d tag requirements and examples with multiple values. Fiatjaf then connected the idea to NIP-19 naming work, moving through nref, nitem and eventually naddr plus a tags.
Leo Wandersleb's March 2023 commit title, 'events cannot really be replaced,' captures the conceptual refinement. Old signed events do not vanish from the universe. What changes is the current version selected for a coordinate. Doug Hoyte later specified same-timestamp replacement behavior, and Asai Toshiya added a description for d tag values.
In August 2023, PR #703 merged NIP-33 into NIP-01. In August 2024, fiatjaf completed the terminology shift from parameterized replaceable events to addressable events. The rename is better: users and clients address an object; they do not literally rewrite history.
Addressable events are now a foundation for apps, media and lists
Nostrbook's kind-range overview still describes kinds 30000 to 39999 as parameterized replaceable events while pointing people back to NIP-01. That older language remains common in code and documentation, even though the official term is addressable events.
NIP-23 long-form articles use kind 30023 and a d tag. NIP-51 lists use addressable list kinds. NIP-30 emoji sets can point at kind 30030. NIP-29 group metadata uses addressable events signed by relays. NIP-19 naddr exists because addressable coordinates need a shareable form.
Implementers need to store by coordinate, not only by event ID. A relay answering a query for an addressable kind has to return the latest version for that author and d tag. A client showing an article or list has to avoid displaying stale versions as if they were current unless it is intentionally showing history.
Stable coordinates can hide version history
The main risk is assuming 'latest' means 'only.' Addressable events make current state easy to find, but older signed versions may still exist on relays or in archives. A wiki, marketplace or article you needs to know when it is showing the current version and when historical evidence matters.
The second risk is stale relay behavior. If relays disagree on replacement ordering or keep old versions in ordinary queries, users may see conflicting article titles, list contents or group metadata. Addressability is a base protocol rule because it has to be applied consistently.
Read NIP-33 in the wild
NIP-33 introduces parameterized replaceable events. That is the foundation for addressable objects like articles, lists or profiles that can be updated while keeping a stable coordinate.
This is a deep portability feature. Without it, clients are stuck choosing between immutable event history and app-specific records. With it, a named object can move through relays while still having a current version.
What changes when you actually use it
For you, NIP-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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-33: Parameterized Replaceable Events 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 addressable events, PR #54: NIP-33, PR #703: merge into NIP-01, NIP-19 naddr. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-33 source is the anchor for exact wording, and NIP-33 commit history shows how that wording moved over time. The strongest secondary clues here are NIP-01 addressable events, PR #54: NIP-33, PR #703: merge into NIP-01. 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-33: Parameterized Replaceable Events: 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-33 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-33 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-33: Parameterized Replaceable Events in that order: Official NIP-33 source for the current wording; NIP-33 commit history for the change record; NIP-01 addressable events, PR #54: NIP-33, PR #703: merge into NIP-01 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.
