nips/17.md

NIP-17
======

Event Metadata
---------------

`draft` `optional` `author:arthurfranca`

Relays may attach event metadata to requested events.

## Motivation

To save relay bandwidth while helping clients show event metadata estimates faster.

## Fields

All fields are optional and live inside an extra nip17 key.

Some fields only make sense for a subset of kinds.

New fields may be added to this NIP later.

### Returned Event Example

```js
{
  "kind": ..., // 1, 30023, 0, ...
  ..., // regular keys
  "nip17": {
    "country": "US", // ISO 3166-1 alpha-2 code extracted from NIP-32 label (geohash/country/... l tag) or detected by IP
    "followers": 500, // sent with kind 0 events
    "language": "en", // ISO 639-1 code of detected event.content language
    "reactions": {
      "+": 8, // kind 7 "+" reaction count (should be the sum of "+" and all emoji reactions)
      "-": 0, // kind 7 "-" reaction count
      "🤙️": 10 // kind 7 specific emoji reaction count
    },
    "relays": ["wss://relay.url"], // event found originally on these relays
    "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
    "zaps": 7, // kind 9735 count
    "zap_amount": 10000 // kind 9735 millisats amount sum
  }
}
```

## Filter Extensions

Clients can use extra filter attributes when requesting events. They additional attributes
are limited to a subset of the NIP-17 fields and are namespaced in the `nip17` filter key.

Relays should use NIP-11 `supported_nip_extensions` when supporting an extension.

For example: { "supported_nips": [17], "supported_nip_extensions": ["nip17language", "nip17country"] }

### NIP-17country

Filter by country.

Example request: `["REQ", <sub_id>, { "kinds": [1], ..., "nip17": { "country": ["US", "GB"] } }]`

### NIP-17followers

Filter by number of followers.

Example request: `["REQ", <sub_id>, { "kinds": [0], ..., "nip17": { "followers": ">100000" } }]`

### NIP-17language

Filter by language.

Example request: `["REQ", <sub_id>, { "kinds": [1], ..., "nip17": { "language": ["en", "pt"] } }]`

### NIP-17reactions

Filter by number of reactions. Just `reactions.+` and `reactions.-` fields.

Example request: `["REQ", <sub_id>, { "kinds": [1], ..., "nip17": { "reactions.+": ">1000", "reactions.-": "<1000" } }]`

### NIP-17replies

Filter by number of replies.

Example request: `["REQ", <sub_id>, { "kinds": [1], ..., "nip17": { "replies": ">100" } }]`