nips/45.md

45 lines
1.7 KiB
Markdown
Raw Permalink Normal View History

2023-01-04 04:11:17 +00:00
NIP-45
======
Event Counts
--------------
`draft` `optional` `author:staab`
Relays may support the verb `COUNT`, which provides a mechanism for obtaining event counts.
2023-01-04 04:11:17 +00:00
## 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.
2023-01-04 04:11:17 +00:00
## 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`. Multiple filters are OR'd together and aggregated into a single count result.
2023-04-12 15:18:22 +00:00
```
["COUNT", <subscription_id>, <filters JSON>...]
```
2023-01-04 04:11:17 +00:00
Counts are returned using a `COUNT` response in the form `{"count": <integer>}`. Relays may use probabilistic counts to reduce compute requirements.
In case a relay uses probabilistic counts, it MAY indicate it in the response with `approximate` key i.e. `{"count": <integer>, "approximate": <true|false>}`.
2023-01-04 04:11:17 +00:00
2023-04-12 15:18:22 +00:00
```
["COUNT", <subscription_id>, {"count": <integer>}]
```
2023-01-04 04:11:17 +00:00
Examples:
```
# Followers count
2023-04-12 15:18:22 +00:00
["COUNT", <subscription_id>, {"kinds": [3], "#p": [<pubkey>]}]
["COUNT", <subscription_id>, {"count": 238}]
2023-01-04 04:11:17 +00:00
# Count posts and reactions
2023-04-12 15:18:22 +00:00
["COUNT", <subscription_id>, {"kinds": [1, 7], "authors": [<pubkey>]}]
["COUNT", <subscription_id>, {"count": 5}]
# Count posts approximately
["COUNT", <subscription_id>, {"kinds": [1]}]
["COUNT", <subscription_id>, {"count": 93412452, "approximate": true}]
2023-01-04 04:11:17 +00:00
```