NIP-45

Event Counts

draft optional

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

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 for the verb REQ. Multiple filters are OR'd together and aggregated into a single count result.

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

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>}.

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

Whenever the relay decides to refuse to fulfill the COUNT request, it MUST return a CLOSED message.

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

Count posts approximately

["COUNT", <subscription_id>, {"kinds": [1]}]
["COUNT", <subscription_id>, {"count": 93412452, "approximate": true}]

Relay refuses to count

["COUNT", <subscription_id>, {"kinds": [4], "authors": [<pubkey>], "#p": [<pubkey>]}]
["CLOSED", <subscription_id>, "auth-required: cannot count other people's DMs"]