NIP-51
Lists
draft optional
This NIP defines lists of things that users can create. Lists can contain references to anything, and these references can be public or private.
Public items in a list are specified in the event
tags array, while private items are specified in a
JSON array that mimics the structure of the event
tags array, but stringified and encrypted using the
same scheme from NIP-44 (the shared key
is computed using the author’s public and private key) and stored
in the .content. An earlier version of this
specification used NIP-04 for
encryptions. Those are now deprecated. For backward compatibility,
Clients can automatically discover if the encryption is NIP-04 or
NIP-44 by searching for “iv” in the ciphertext and decrypting
accordingly.
When new items are added to an existing list, clients SHOULD append them to the end of the list, so they are stored in chronological order.
Types of lists
Standard lists
Standard lists use normal replaceable events, meaning users may only have a single list of each kind. They have special meaning and clients may rely on them to augment a user’s profile or browsing experience.
For example, mute list can contain the public keys of spammers and bad actors users don’t want to see in their feeds or receive annoying notifications from.
| name | kind | description | expected tag items |
|---|---|---|---|
| Follow list | 3 | microblogging basic follow list, see NIP-02 | "p" (pubkeys – with optional relay hint and
petname) |
| Mute list | 10000 | things the user doesn’t want to see in their feeds | "p" (pubkeys), "t" (hashtags),
"word" (lowercase string), "e"
(threads) |
| Pinned notes | 10001 | events the user intends to showcase in their profile page | "e" (kind:1 notes) |
| Read/write relays | 10002 | where a user publishes to and where they expect mentions | see NIP-65 |
| Bookmarks | 10003 | uncategorized, “global” list of things a user wants to save | "e" (kind:1 notes), "a" (kind:30023
articles) |
| Communities | 10004 | NIP-72 communities the user belongs to | "a" (kind:34550 community definitions) |
| Public chats | 10005 | NIP-28 chat channels the user is in | "e" (kind:40 channel definitions) |
| Blocked relays | 10006 | relays clients should never connect to | "relay" (relay URLs) |
| Search relays | 10007 | relays clients should use when performing search queries | "relay" (relay URLs) |
| Profile badges | 10008 | NIP-58 badges a user has accepted and chosen to display | "a" (kind:30009 badge definitions) and
"e" (kind:8 badge awards), and "a"
(kind:30008 badge set) |
| Simple groups | 10009 | NIP-29 groups the user is in | "group" (NIP-29 group
id + relay URL + optional group name), "r" for each
relay in use |
| Favorite follow sets | 10011 | user favorite follow sets | "a" (kind:30000 follow set) |
| Relay feeds | 10012 | user favorite browsable relays (and relay sets) | "relay" (relay URLs) and "a"
(kind:30002 relay set) |
| Private relays | 10013 | (nip44-encrypted) NIP-37 private relays (drafts) | "relay" (relay URL) |
| Interests | 10015 | topics a user may be interested in and pointers | "t" (hashtags) and "a" (kind:30015
interest set) |
| Media follows | 10020 | multimedia (photos, short video) follow list | "p" (pubkeys – with optional relay hint and
petname) |
| Emojis | 10030 | user preferred emojis and pointers to emoji sets | "emoji" (see NIP-30)
and "a" (kind:30030 emoji set) |
| DM relays | 10050 | Where to receive NIP-17 direct messages | "relay" (see NIP-17) |
| Blossom servers | 10063 | Servers where to upload and look for images and other blobs | "server" (see NIP-B7) |
| Good wiki authors | 10101 | NIP-54 user recommended wiki authors | "p" (pubkeys) |
| Good wiki relays | 10102 | NIP-54 relays deemed to only host useful articles | "relay" (relay URLs) |
| Git authors | 10017 | code (people who produce NIP-34 events) follow list | "p" (pubkeys – with optional relay hint and
petname) |
| Git repositories | 10018 | NIP-34 followed repositories | "a" (kind:30617 repository announcement
event) |
| Favorite podcasts | 10054 | podcasts a user wants to bookmark as favorites | "p" (NIP-F4 podcast
pubkeys), "url" (RSS/XML podcast URLs) |
| Authored podcasts | 10064 | podcasts the user authors | "p" (NIP-F4 podcast
pubkeys) |
Sets
Sets are lists with well-defined meaning that can enhance the
functionality and the UI of clients that rely on them. Unlike
standard lists, users are expected to have more than one set of
each kind, therefore each of them must be assigned a different
"d" identifier.
For example, relay sets can be displayed in a dropdown UI to give users the option to switch to which relays they will publish an event or from which relays they will read the replies to an event; curation sets can be used by apps to showcase curations made by others tagged to different topics.
Aside from their main identifier, the "d" tag,
sets can optionally have a "title", an
"image" and a "description" tags that
can be used to enhance their UI.
| name | kind | description | expected tag items |
|---|---|---|---|
| Follow sets | 30000 | categorized groups of users a client may choose to check out in different circumstances | "p" (pubkeys) |
| Relay sets | 30002 | user-defined relay groups the user can easily pick and choose from during various operations | "relay" (relay URLs) |
| Bookmark sets | 30003 | user-defined bookmarks categories , for when bookmarks must be in labeled separate groups | "e" (kind:1 notes), "a" (kind:30023
articles) |
| Curation sets | 30004 | groups of articles picked by users as interesting and/or belonging to the same category | "a" (kind:30023 articles), "e"
(kind:1 notes) |
| Curation sets | 30005 | groups of videos picked by users as interesting and/or belonging to the same category | "e" (kind:21 videos) |
| Curation sets | 30006 | groups of pictures picked by users as interesting and/or belonging to the same category | "e" (kind:20 pictures) |
| Kind mute sets | 30007 | mute pubkeys by kinds"d" tag MUST be the kind
string |
"p" (pubkeys) |
| Badge sets | 30008 | NIP-58 categorized groups of badges | "a" (kind:30009 badge definitions) and
"e" (kind:8 badge awards) |
| Interest sets | 30015 | interest topics represented by a bunch of “hashtags” | "t" (hashtags) |
| Emoji sets | 30030 | categorized emoji groups | "emoji" (see NIP-30) |
| Release artifact sets | 30063 | group of artifacts of a software release | "e" (kind:1063 file
metadata events), "a" (software application
event) |
| App curation sets | 30267 | references to multiple software applications | "a" (software application event) |
| Calendar | 31924 | a set of events categorized in any way | "a" (calendar event event) |
| Starter packs | 39089 | a named set of profiles to be shared around with the goal of being followed together | "p" (pubkeys) |
| Media starter packs | 39092 | same as above, but specific to multimedia (photos, short video) clients | "p" (pubkeys) |
Deprecated standard lists
Some clients have used these lists in the past, but they should work on transitioning to the standard formats above.
| kind | “d” tag | use instead |
|---|---|---|
| 30000 | "mute" |
kind 10000 mute list |
| 30001 | "pin" |
kind 10001 pin list |
| 30001 | "bookmark" |
kind 10003 bookmarks list |
| 30001 | "communities" |
kind 10004 communities list |
Examples
A mute list with some public items and some encrypted items
{
"id": "a92a316b75e44cfdc19986c634049158d4206fcc0b7b9c7ccbcdabe28beebcd0",
"pubkey": "854043ae8f1f97430ca8c1f1a090bdde6488bd5115c7a45307a2a212750ae4cb",
"created_at": 1699597889,
"kind": 10000,
"tags": [
["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"],
["p", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"]
],
"content": "TJob1dQrf2ndsmdbeGU+05HT5GMnBSx3fx8QdDY/g3NvCa7klfzgaQCmRZuo1d3WQjHDOjzSY1+MgTK5WjewFFumCcOZniWtOMSga9tJk1ky00tLoUUzyLnb1v9x95h/iT/KpkICJyAwUZ+LoJBUzLrK52wNTMt8M5jSLvCkRx8C0BmEwA/00pjOp4eRndy19H4WUUehhjfV2/VV/k4hMAjJ7Bb5Hp9xdmzmCLX9+64+MyeIQQjQAHPj8dkSsRahP7KS3MgMpjaF8nL48Bg5suZMxJayXGVp3BLtgRZx5z5nOk9xyrYk+71e2tnP9IDvSMkiSe76BcMct+m7kGVrRcavDI4n62goNNh25IpghT+a1OjjkpXt9me5wmaL7fxffV1pchdm+A7KJKIUU3kLC7QbUifF22EucRA9xiEyxETusNludBXN24O3llTbOy4vYFsq35BeZl4v1Cse7n2htZicVkItMz3wjzj1q1I1VqbnorNXFgllkRZn4/YXfTG/RMnoK/bDogRapOV+XToZ+IvsN0BqwKSUDx+ydKpci6htDRF2WDRkU+VQMqwM0CoLzy2H6A2cqyMMMD9SLRRzBg==?iv=S3rFeFr1gsYqmQA7bNnNTQ==",
"sig": "1173822c53261f8cffe7efbf43ba4a97a9198b3e402c2a1df130f42a8985a2d0d3430f4de350db184141e45ca844ab4e5364ea80f11d720e36357e1853dba6ca"
}A curation set of articles and notes about yaks
{
"id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef",
"pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c",
"created_at": 1695327657,
"kind": 30004,
"tags": [
["d", "jvdy9i4"],
["title", "Yaks"],
["image", "https://cdn.britannica.com/40/188540-050-9AC748DE/Yak-Himalayas-Nepal.jpg"],
["description", "The domestic yak, also known as the Tartary ox, grunting ox, or hairy cattle, is a species of long-haired domesticated cattle found throughout the Himalayan region of the Indian subcontinent, the Tibetan Plateau, Gilgit-Baltistan, Tajikistan and as far north as Mongolia and Siberia."],
["a", "30023:26dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:95ODQzw3ajNoZ8SyMDOzQ"],
["a", "30023:54af95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:1-MYP8dAhramH9J5gJWKx"],
["a", "30023:f8fe95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:D2Tbd38bGrFvU0bIbvSMt"],
["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"]
],
"content": "",
"sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd"
}A release artifact set of an Example App
{
"id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef",
"pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c",
"created_at": 1695327657,
"kind": 30063,
"content": "Release notes in markdown",
"tags": [
["d", "com.example.app@0.0.1"],
["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"], // Windows exe
["e", "f27e2c91051de0c4e1da0d5dce22bfff9db0a9340e0326b4941ed78bae996c9e"], // MacOS dmg
["e", "9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad02332"], // Linux AppImage
["e", "340e0326b340e0326b4941ed78ba340e0326b4941ed78ba340e0326b49ed78ba"], // PWA
["a", "32267:d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:com.example.app"] // Reference to parent software application
],
"sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd"
}An app curation set
{
"id": "d8037fa866eb5acd2159960b3ada7284172f7d687b5289cc72a96ca2b431b611",
"pubkey": "78ce6faa72264387284e647ba6938995735ec8c7d5c5a65737e55130f026307d",
"sig": "c1ce0a04521c020ae7485307cd86285530c1f778766a3fd594d662a73e7c28f307d7cd9a9ab642ae749fce62abbabb3a32facfe8d19a21fba551b60fae863d95",
"kind": 30267,
"created_at": 1729302793,
"content": "My nostr app selection",
"tags": [
["d", "nostr"],
["a", "32267:7579076d9aff0a4cfdefa7e2045f2486c7e5d8bc63bfc6b45397233e1bbfcb19:com.example.app1"],
["a", "32267:045f2486c7e5d8bc63bfc6b45397233e1bbfcb197579076d9aff0a4cfdefa7e2:net.example.app2"],
["a", "32267:264387284e647ba6938995735ec8c7d5c5a6f026307d78ce6faa725737e55130:pl.code.app3"]
]
}Encryption process pseudocode
val private_items = [
["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"],
["a", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"],
]
val base64blob = nip44.encrypt(json.encode_to_string(private_items))
event.content = base64blob