nips/34.md

NIP-34
======

Algorithmic Filter
------------------

`draft` `optional` `author:arthurfranca`

According to [NIP-01](01.md), filters with `limit` attribute are replied with events
sorted in **descending** order by the `created_at` event field (newest events first).

For filters containing `limit` attribute, this NIP-34 adds `nip34` as a new filter attribute
whose value indicates the algorithm the `client` wishes to use for sorting events.

For instance, if a `client` sends the message `["REQ", <sub_id>, { kinds: [1], ..., limit: 5, nip34: "a" }]`,
it is asking the `relay` to sort five kind 1 events in **descending** order by the `nip34a` event field instead of by `created_at`.

In the above example, `relays` that want to support the NIP-34a algorithm must add the `nip34a` event field to each event saved to their internal databases. The new field is populated following rules described at the NIP-34a NIP extension.

Besides that, upon replying to such requests, the supporting `relay` MUST add `nip34: { score: "<nip34a value>" }` field to each returned event JSON.

It is a backward-compatible proposal because non-supporting `relays` ignore the `nip34` filter attribute and sort by `created_at`, as usual.

`Relays` should advertise support using both [NIP-11](11.md) `supported_nips` and `supported_nip_extensions` fields.

`Relays` should limit max daily user events, such as likes, reposts, zaps and comments, per IP to avoid bad actors gaming the algorithms.

## Motivation

Different algorithms are required to support diverse apps' event sorting needs.

However, they should be presented as optional and backward-compatible features that are easy to support.

Considering the request example above, we expect most `relays` to simply swap the `created_at` field
on a regular query for the `nip34a` one. If a `relay` implementation uses a SQL DB, the above filter would turn this:

`SELECT * FROM events WHERE kind in (1) ORDER BY        created_at        DESC LIMIT 5`

Into this:

`SELECT * FROM events WHERE kind in (1) ORDER BY          nip34a          DESC LIMIT 5`

## Relay Connection URL Query Parameter

For each supported NIP-34 algorithm, the `relay` MUST allow `clients` to specify the algo as a `nip34` query param on connection URL string.

For example, if supporting the NIP-34a algo, a `relay` whose regular URL is `wss://relay.url/r1` must
also respond at `wss://relay.url/r1?nip34=a`.

Then when `clients` connect to `wss://relay.url/r1?nip34=a` and request events using `limit`
filter attribute, the relay will automatically sort events in **descending** order by the `nip34a` event field instead of by `created_at` when replying. Clients can still override the chosen algorithm if using the
`nip34` filter attribute.

## How Clients Make Custom Requests for a Specific User

The algorithms are generic, meaning the "score" represented by the new event field does not differ for different users.

However, smart `clients` may keep track of pubkeys from whom the user is consuming content, also hashtags, for instance, and use such pubkeys/hashtags as a way to tailor the query to that specific user. For example:

`["REQ", <sub_id>, { kinds: [1], limit: 5, nip34: "b", authors: ["pubkey1 user follows", "pubkey2 user has read content from recently", "pubkey3 that user has liked content recently"] }, { kinds: [1], limit: 5, nip34: "b", "#t": ["cat", "bitcoin"] }]`

## Rules for Submitting a NIP-34 Algorithm

Each algorithm section describes **how** and **when** to compute the corresponding database field for each event.

For example, [NIP-34asc](34asc.md) extension teaches `relays` the math used to update the `nip34asc` event field.

The NIP extension MUST have atleast one example in any programming language, preferably with inline comments.

Bugfixes and small updates to embrace new event kinds may be submitted at any time by the algorithm author(s).

## Available Algorithms

| Extension           | Name      | Description                                        | Modification Date |
| ------------------- | ----------| -------------------------------------------------- | ----------------- |
| [34asc](34asc.md)   | Ascending | Events with older `created_at` are retrieved first | 18 / jul / 2023   |
| [34seen](34seen.md) | Seen At   | Events are desc sorted by first seen at timestamp  | 18 / jul / 2023   |