NIP-61 - Event Sets

61.md

@@ -0,0 +1,102 @@
+NIP-61
+======
+
+Event Set
+---------
+
+`draft` `optional`
+
+An event set is represented by a group of events, not a single event.
+Each event of a specific set has the same pubkey and `n` (set "n"ame) tag.
+
+An event can have many `n` tags, thus being member of many event sets.
+To remove an event from a set, remove the corresponding `n` tag from the event or
+send a deletion event (`kind:5`).
+
+## Referencing
+
+An event set is referenced by an `s` tag. It
+references many events from an author instead of a single one:
+
+`["s", "<kind>:<pubkey>:<n-tag>", "<recommended-relay-URL, optional>"]`
+
+One may also use an `nset` [NIP-19](19.md) entity through a [NIP-21](21.md) URI: `nostr:nset1qqstn...794234d`.
+
+## How to add items to a set
+
+Just add an `n` tag to your event. For example, adding one of your long-form posts to a set named "a-set-name-example":
+
+```js
+{
+  "kind": 30023,
+  "tags": [
+    ["d", "<random>"],
+    ["n", "a-set-name-example"]
+    // other tags
+  ]
+  // other fields
+}
+```
+
+## Set Names
+
+There are two types of sets: those with a "standard" name and those with a "custom" one (most likely user-generated name).
+
+### Standard
+
+Standard sets have one of the names (the `n` tag value) listed here to guarantee interoperability.
+The convention is to prefer lowercase English words in singular form with dash separator.
+
+| n-tag | description |
+|-|-|
+| contact | pubkeys to whom the user sent DMs or started an interaction such as an one-on-one audio/video call |
+| file | adds events and files (urls) to a root directory similar to "/" |
+| friend | friends' pubkeys |
+| notification | notes monitored for new replies, zaps and reactions |
+| upload | files (urls) - requires `m` tag set to the MIME type |
+
+### Custom
+
+To **keep track of the custom set names**, the encrypted parameterized replaceable "Custom Sets" `kind:30061` event is used.
+
+Such event with `d-tag=""` lists custom set names with no expected special treatment by clients
+(these sets effectively work like labels).
+
+However, adding a **standard** set name to the `d` tag instructs clients to treat the listed custom sets the same as they treat
+the corresponding **standard** set. For example, sets listed within a `kind:30061` with `d-tag="file"` are treated
+by clients the same way as the "file" set, i.e., they could be presented as file system directories.
+
+A `kind:30061` event has one `map` tag for each custom set. A `map` tag has the first value as the custom set name.
+When the user doesn't want to reveal the real custom set name, the `map` tag's first value can be a fake or random string
+that maps to the `map` tag's second value, which holds the real custom set name that just the user will see.
+
+Examples:
+
+```js
+{
+  "kind": 30061,
+  "tags": [
+    ["d", ""]
+  ]
+  "content": nip44Encrypt(JSON.stringify([
+    ["map", "<public-name>", "<real-name>"],
+    ["map", "Good Fellow", "Good Fellow"],
+    ["map", "6064460175057025", "Debtor"]
+  ])),
+  // ...other fields
+}
+```
+
+```js
+{
+  "kind": 30061,
+  "tags": [
+    ["d", "file"]
+  ]
+  "content": nip44Encrypt(JSON.stringify([
+    ["map", "4234649720408324", "/sub/directory"],
+    ["map", "/home", "/home"]
+  ]))
+  // other fields
+}
+```