nips/51.md
2024-05-26 12:10:42 -05:00

11 KiB

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 (see the "Encryption" section below) and stored in the .content.

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 non-parameterized 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
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)
Bookmarks 10003 uncategorized, "global" list of things a user wants to save "e" (kind:1 notes), "a" (kind:30023 articles), "t" (hashtags), "r" (URLs)
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)
Simple groups 10009 NIP-29 groups the user is in "group" (NIP-29 group ids + mandatory relay URL)
Interests 10015 topics a user may be interested in and pointers "t" (hashtags) and "a" (kind:30015 interest set)
Emojis 10030 user preferred emojis and pointers to emoji sets "emoji" (see NIP-30) and "a" (kind:30030 emoji set)
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)

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), "t" (hashtags), "r" (URLs)
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 "a" (kind:34235 videos)
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 groups of files of a software release "e" (kind:1063 file metadata events), "i" (application identifier, typically reverse domain notation), "version"

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"],
    ["name", "Yaks"],
    ["picture", "https://cdn.britannica.com/40/188540-050-9AC748DE/Yak-Himalayas-Nepal.jpg"],
    ["about", "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,
  "tags": [
    ["d", "ak8dy3v7"],
    ["i", "com.example.app"],
    ["version", "0.0.1"],
    ["title", "Example App"],
    ["image", "http://cdn.site/p/com.example.app/icon.png"],
    ["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"], // Windows exe
    ["e", "f27e2c91051de0c4e1da0d5dce22bfff9db0a9340e0326b4941ed78bae996c9e"], // MacOS dmg
    ["e", "9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad02332"], // Linux AppImage
    ["e", "340e0326b340e0326b4941ed78ba340e0326b4941ed78ba340e0326b49ed78ba"] // PWA
  ],
  "content": "Example App is a decentralized marketplace for apps",
  "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd"
}

Encryption

If the event content is non-empty, the list content is an encrypted JSON tag array. The data is encrypted using the author's public and private keys.

An optional ["encrypted", <encryption>] tag may be included, where encryption is one of:

  • nip04 - NIP-04 encryption
  • nip44 - NIP-44 encryption

If the tag is not included, the encryption method is assumed to be NIP-04 for backwards-compatibility.

Pseudocode

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