nips/17.md

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"] } }]`