Lists

1 Overview

Users collect things: people, notes, relays, hashtags, emojis, apps. This NIP defines the list: an event whose tags hold references to those things. A list can point to anything.

There are two families. A standard list is a normal replaceable event. A user has at most one list per kind. A set is an addressable event with a d tag. A user can have many sets per kind, one per d value.

Each item in a list is public or private. Public items live in the event tags array. Private items live in the content field, encrypted with NIP-44. Everyone can read the public items. Only the author can read the private items.

2 Public and Private Items

Public items are normal tags in the event tags array. Private items use a hidden second tags array. Build it like this:

1. Collect the private items as a JSON array. It mimics the structure of the event tags array.
2. Stringify the array.
3. Encrypt the string with the NIP-44 scheme. Compute the shared key from the author's own public and private key.
4. Store the ciphertext in event.content.

private_items = [
  ["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"],
  ["a", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"],
]
base64blob = nip44.encrypt(json.encode_to_string(private_items))
event.content = base64blob

3 Standard Lists

Standard lists use normal replaceable events. A user may have only a single list of each kind. These lists have special meaning. Clients may rely on them to augment a user's profile or browsing experience.

For example, the mute list can contain the public keys of spammers and bad actors. The user does not want to see them in feeds or receive notifications from them.

4 Sets

Sets are lists with well-defined meaning. They can enhance the functionality and the UI of clients that rely on them. Unlike standard lists, a user is expected to have more than one set of each kind. Therefore each set must have a different d tag identifier.

For example, relay sets can appear in a dropdown UI. The user picks which relays to publish to, or which relays to read replies from. Curation sets let apps showcase curations made by others, tagged to different topics.

Aside from the main d identifier, a set can carry three optional tags that enhance its UI: title, image, and description.

5 Deprecated Standard Lists

Some clients used the rows below in the past. They should transition to the standard list kinds in section 3.

6 Worked Examples

Four real list events follow. The first is a standard list with mixed public and private items. The other three are sets.

A mute list with public and encrypted items

Two muted pubkeys are public tags. More items hide inside content. Only the author can decrypt them.

{
  "id": "a92a316b75e44cfd…8beebcd0",
  "pubkey": "854043ae8f1f9743…2750ae4cb",
  "created_at": 1699597889,
  "kind": 10000,
  "tags": [
    ["p", "07caba282f764419…cdc1da3a9"],
    ["p", "a55c15f5e41d5aeb…4fd18dcc4"]
  ],
  "content": "TJob1dQrf2ndsmdbeGU+05HT5GMnBSx3fx8QdDY/g3NvCa7klfzgaQCmRZuo1d3W…
              …4vYFsq35BeZl4v1Cse7n2htZicVkItMz3wjzj1q1I1VqbnorNXFgllkRZn4/
              YXfTG/RMnoK/bDogRapOV+XToZ+IvsN0BqwKSUDx+ydKpci6htDRF2WDRkU+
              VQMqwM0CoLzy2H6A2cqyMMMD9SLRRzBg==?iv=S3rFeFr1gsYqmQA7bNnNTQ==",
  "sig": "1173822c53261f8c…853dba6ca"
}
-- the "?iv=" suffix marks legacy NIP-04 ciphertext; new events use NIP-44 --

A curation set of articles and notes about yaks

A kind 30004 set. The d tag makes it addressable. The title, image, and description tags feed the UI.

{
  "id": "567b41fc9060c758…4dd220ef",
  "pubkey": "d6dc95542e18b8b7…d0593a0c",
  "created_at": 1695327657,
  "kind": 30004,
  "tags": [
    ["d", "jvdy9i4"],
    ["title", "Yaks"],
    ["image", "https://cdn.britannica.com/40/…/Yak-Himalayas-Nepal.jpg"],
    ["description", "The domestic yak, also known as the Tartary ox, …"],
    ["a", "30023:26dc95542e18b8b7…d0593a0c:95ODQzw3ajNoZ8SyMDOzQ"],
    ["a", "30023:54af95542e18b8b7…d0593a0c:1-MYP8dAhramH9J5gJWKx"],
    ["a", "30023:f8fe95542e18b8b7…d0593a0c:D2Tbd38bGrFvU0bIbvSMt"],
    ["e", "d78ba0d5dce22bff…326b4941e"]
  ],
  "content": "",
  "sig": "a9a4e2192eede77e…1294a96bd"
}

A release artifact set of an example app

A kind 30063 set. Each e tag points to one kind 1063 file metadata event. The a tag points to the parent software application event.

{
  "id": "567b41fc9060c758…4dd220ef",
  "pubkey": "d6dc95542e18b8b7…d0593a0c",
  "created_at": 1695327657,
  "kind": 30063,
  "content": "Release notes in markdown",
  "tags": [
    ["d", "com.example.app@0.0.1"],
    ["e", "d78ba0d5dce22bff…326b4941e"],  // Windows exe
    ["e", "f27e2c91051de0c4…ed78bae996c9e"],  // MacOS dmg
    ["e", "9d24ddfab95ba3ff…04aad02332"],  // Linux AppImage
    ["e", "340e0326b340e032…b49ed78ba"],  // PWA
    ["a", "32267:d6dc95542e18b8b7…d0593a0c:com.example.app"]  // parent software application
  ],
  "sig": "a9a4e2192eede77e…1294a96bd"
}

An app curation set

A kind 30267 set. Each a tag references one kind 32267 software application event.

{
  "id": "d8037fa866eb5acd…2b431b611",
  "pubkey": "78ce6faa72264387…f026307d",
  "sig": "c1ce0a04521c020a…fae863d95",
  "kind": 30267,
  "created_at": 1729302793,
  "content": "My nostr app selection",
  "tags": [
    ["d", "nostr"],
    ["a", "32267:7579076d9aff0a4c…1bbfcb19:com.example.app1"],
    ["a", "32267:045f2486c7e5d8bc…9aff0a4cfdefa7e2:net.example.app2"],
    ["a", "32267:264387284e647ba6…725737e55130:pl.code.app3"]
  ]
}

7 Version History

NIP-51 grows whenever the network invents a new thing worth collecting. It started as a family of small list NIPs that merged into one page on day one. Notable changes, newest first:

• 20262026-07Added kind 10011 favorite follow sets; clarified kind 10013 private relays with NIP-37.
• 20262026-03/05Added Blossom servers (10063), NIP-34 git authors and repositories (10017, 10018), and NIP-F4 podcast lists (10054, 10064). Profile badges moved to kind 10008; badge sets 30008 arrived.
• 20252025-08/12Switched private-item encryption to NIP-44 and deprecated NIP-04. Removed hashtag and URL tags from bookmarks. Added picture curation sets (30006); video curation sets (30005) switched to e tags.
• 20252025-02/05Added starter packs (39089, 39092), relay feeds (10012), media follows (10020), and the kind 10002 relay list row.
• 20242024Added kind mute sets (30007), wiki lists (10101, 10102), simple groups (10009), release artifact sets (30063), app curation sets (30267), and DM relays (10050). "Parameterized replaceable" became "addressable".
• 20232023-11The big rewrite: lists split from sets, kind 30001 deprecated, and mute words, blocked relays, search relays, interests, emojis, and more lists added. The append-to-end rule arrived weeks later.
• 20232023-04/08Typo fixes and an extended kind 30001 description, later removed.
• Origin2023-03-09monlovesmango opened NIP-51 "Lists" (PR #183). The same day fiatjaf merged the separate 51x list NIPs into this single document.

8 See Also

• NIP-01 — replaceable and addressable events; the storage classes lists depend on.
• NIP-02 — the kind 3 follow list, the oldest standard list.
• NIP-44 — the encryption scheme for private list items.
• NIP-04 — the deprecated legacy encryption still found in old lists.
• NIP-65 — the kind 10002 read/write relay list in detail.
• NIP-17 — direct messages and the kind 10050 DM relay list.
• NIP-58 — badges, shown through the kind 10008 profile badges list.
• NIP-52 — calendar events, collected by the kind 31924 calendar set.