Parameterized Replaceable Events

1 Overview

NIP-16 gave every relay a way to replace an event: keep only the newest event per author and kind. That worked for a single profile status, but not for a list of items, where an author needs many independent, individually replaceable records of the same kind.

NIP-33 added a fourth event class to solve this. It used a new kind range, and it replaced events per author, kind, and a tag value called d. This let one author keep many replaceable events of the same kind alive at once, each identified by its own d value.

2 What NIP-33 Defined

NIP-33 stated these rules, restated here in Simplified Technical English:

• A parameterized replaceable event is an event with a kind from 30000 to 39999.
• For each author, kind, and first d tag value, the relay keeps only the newest event. It discards older ones.
• When two such events share the same created_at timestamp, the relay keeps the one whose id sorts first.
• A missing d tag, an empty tags array, or a d tag with no value all count as a d value of "" (empty string). If an event has more than one d tag, only the first one counts.
• Clients should always include a d tag with a real value, so the event can be found with a #d filter.

NIP-33 also defined the a tag, for referencing this new event class: ["a", "<kind>:<pubkey>:<d value>", "<relay url, optional>"]. Before settling on a, the tag went through two earlier names during development: nref, then nitem, before the identifier itself was renamed naddr and the tag became a.

Where It Lives Now

NIP-01 kept the kind range, the replacement rule, the tie-break rule, and the a tag exactly as NIP-33 defined them. The one change is the name: in 2024, a separate pull request renamed "parameterized replaceable event" to addressable event everywhere, including inside NIP-01 itself. The behavior did not change, only the term.

3 Historical Example

This is the tag example NIP-33 used to show how the d value distinguishes events. It still works exactly like this under NIP-01 today.

"tags": [
  ["a", "30023:f7234bd4c139…76e9ca:abcd", "wss://relay.example.com"]
]

Kind 30023, author f7234bd4c139…76e9ca, d value abcd. Together, these three fields point at exactly one addressable event, no matter how many times its author has replaced it.

4 Version History

• 20242024-08-20fiatjaf renamed "parameterized replaceable event" to "addressable event" throughout NIP-01 (PR #1418). The stub you are reading now reflects that rename.
• Closed2023-08-13Merged into NIP-01 along with NIP-12, NIP-16, and NIP-20 (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 around what "replaceable" means in practice.
• 20232023-02-04 to 2023-02-13fiatjaf renamed the reference identifier twice in nine days: nref to nitem to naddr, settling the tag name on a.
• 20232023-01-24Semisol specified how missing or repeated d tags should be interpreted.
• Origin2023-01-04Semisol published NIP-33, with Kukks, Cameri, and Giszmo, adding a fourth event class on top of NIP-16 (PR #54).

5 See Also

• NIP-01 — the current, canonical home of addressable events and the a tag.
• NIP-16 — event treatment, the three older event classes this one was added alongside.
• NIP-12 — generic tag queries, merged the same day as NIP-33.
• NIP-20 — command results, merged the same day as NIP-33.
• NIP-19 — defines the naddr bech32 encoding for addressable event coordinates.