Versioned Event Kinds

draft

This NIP specifies an additional convention for kind number ranges. This convention for versioned events follows the existing convention for addressable events, but WITHOUT the option for relays to discard older versions.

For kind n such that 40000 <= n < 50000, events are versioned by their kind, pubkey, d tag, and created_at value. For each combination of kind, pubkey and d tag value, only the latest event MUST be delivered by relays. Older versions MAY be delivered by filtering for created_at.

The v tag

A single lowercase v tag SHOULD be used to add versioning metadata for ALL version events (even the first). These MUST take the format of:

["v", "<semver optional>", "<message, optional>"]

• semver is a semver version number for this event version.
• message is a description of the changes made in this version.

eg : ["v", "0.1.0", "you may like the older version, but this is a new one"]

The versions tag

A single versions tag SHOULD be added to new event versions for aiding in the discovery of older event versions. This tag MUST take the format of:

["versions", "<created_at:semver>", ... ]

• This tag MAY have multiple created_at:semver values. Each value MUST start with the created_at value from the older event. This MAY be followed by a single colon : and semver value from the v tag of the older event. (the second part is optional)

eg : ["versions", "1748633717", "1748646538:0.0.2", "1748688753:0.0.3"]

Referencing with a and e tags

To reference the MOST RECENT version from another event, use a standard three part a tag :

["a", "<kind>:<pubkey>:<d_tag>", "<relay_hint, optional>"]

To reference a SPECIFIC version from another event, use EITHER a four part a tag OR a standard e tag :

["a", "<kind>:<pubkey>:<d_tag>:<created_at>", "<relay_hint, optional>"]

• kind is a kind integer
• pubkey is a 32-bytes lowercase hex of the author’s pubkey,
• d_tag is a value of the d tag
• created_at is a value of the event’s created_at timestamp
• relay_hint is a recommended relay URL to find the event

For Addressable Event Kinds

IN ADDITION, this NIP specifies that ANY addressable event (kinds 30000 - 39999) having a v tag SHOULD be retained in storage. HOWEVER, many relays will not store older versions of addressable events, due to conventions specified in NIP-01. Relays claiming compliance with this NIP (via NIP-11 “relay information document”) MUST ALSO comply with this additional specification.