nips/45.md

NIP-45
======

Event Counts
--------------

`draft` `optional` `author:staab`

Relays may support the verb `COUNT`, which provides a mechanism for obtaining event counts.

## Motivation

Some queries a client may want to execute against connected relays are prohibitively expensive, for example, in order to retrieve follower counts for a given pubkey, a client must query all kind-3 events referring to a given pubkey only to count them. The result may be cached, either by a client or by a separate indexing server as an alternative, but both options erode the decentralization of the network by creating a second-layer protocol on top of Nostr.

## Filters and return values

This NIP defines the verb `COUNT`, which accepts a subscription id and filters as specified in [NIP 01](01.md) for the verb `REQ`.

```
["COUNT", <subscription_id>, <filters JSON>...]
```

Counts are returned using a `COUNT` response with positional "count" objects in the form `{"count": <integer>}`. Relays may use probabilistic counts to reduce compute requirements.

```
["COUNT", <subscription_id>, {"count": <integer>}]
```

Examples:

```
# Followers count
["COUNT", <subscription_id>, {"kinds": [3], "#p": [<pubkey>]}]
["COUNT", <subscription_id>, {"count": 238}]

# Count posts and reactions
["COUNT", <subscription_id>, {"kinds": [1, 7], "authors": [<pubkey>]}]
["COUNT", <subscription_id>, {"count": 5}]

# Both of the above in one `COUNT`
["COUNT", <subscription_id>, {"kinds": [3], "#p": [<pubkey>]}, {"kinds": [1, 7], "authors": [<pubkey>]}]
["COUNT", <subscription_id>, {"count": 238}, {"count": 5}]
```