nips/34.md

NIP-34

Algorithmic Filter

draft optional author:arthurfranca

According to NIP-01, 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 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 respect dumb relays/smart clients nostr philosophy so that any relay can easily adopt it.

This NIP also takes into account the relay database software diversity, as explained ahead, so to not rule out as many relays as possible.

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 Extra Endpoints

Relays MUST make available an extra URL clients can connect to for each supported NIP-34 algorithm.

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/nip34a, i.e. the additional URL has the algo field name appended to the path.

Then when clients connect to wss://relay.url/r1/nip34a 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 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.

All algorithms' field values MUST be unique strings for each event. This is needed to support the most rudimentary databases that relays may be using such as file DBs. The event id may be appended to the string to make it unique, similar to NIP-34asc solution.

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	Ascending	Events with older created_at are retrieved first	27 / jun / 2023
34seen	Seen At	Events are desc sorted by first seen at timestamp	27 / jun / 2023