NIP-17 - Event Metadata

17.md

@@ -0,0 +1,73 @@
+NIP-17
+======
+
+Event Metadata
+---------------
+
+`draft` `optional` `author:arthurfranca`
+
+Relays may attach event metadata to requested events.
+
+## Motivation
+
+To save relay and client bandwidth.
+
+## Fields
+
+All extra fields live inside an extra `meta` key.
+
+### Returned Event Example
+
+```js
+{
+  "kind": ..., // 1, 30023, 0, ...
+  ..., // regular event fields
+  "meta": {
+    // v REQUIRED v
+    "isRoot": true, // true when the event holds no `e` nor `a` tags
+    "language": "en", // ISO 639-1 code of detected using event.content language
+    // ISO 3166-1 alpha-2 code. Detection strategies:
+    // - detected by IP
+    // - extracted from "g" (geohash) tag
+    // - selecting one of the countries that use the detected "language" as the main one
+    "country": "US",
+    // ^ REQUIRED ^
+
+    // v OPTIONAL v
+    "replies": 10, // direct descendant kind 1 reply count
+    "reposts": 20, // NIP-18 repost count
+    "views": 900, // request count from different IPs, device ids or pubkeys
+    "followers": 500, // sent with kind 0 events; the value is 0 otherwise
+    "zaps": 7, // kind 9735 count
+    "zap_amount": 10000, // kind 9735 millisats amount sum
+    "reactions": {
+      "+": 12, // kind 7 "+" reaction count (should be the sum of "+" and all emoji reactions)
+      "-": 3, // kind 7 "-" reaction count
+      "🤙️": 10 // kind 7 specific emoji reaction count
+    },
+    "relays": ["wss://relay.url"] // event found originally on these relays
+    // ^ OPTIONAL ^
+  }
+}
+```
+
+## Filters
+
+Relays MUST support extra `REQ` message's filter attributes inside the `meta` field. Multiple
+fields inside the `meta` key are considered "AND" conditions.
+
+#### Is Root
+
+`["REQ", <sub_id>, { "kinds": [1], ..., "meta": { "isRoot": false } }]`
+
+### Language
+
+The array is considered "OR" condition.
+
+`["REQ", <sub_id>, { "kinds": [1], ..., "meta": { "language": ["en", "pt"] } }]`
+
+#### Country
+
+The array is considered "OR" condition.
+
+`["REQ", <sub_id>, { "kinds": [1], ..., "meta": { "country": ["US", "GB"] } }]`