mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-09-20 23:05:49 -04:00
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
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 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](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.
|
|
|
|
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](34asc.md) | Ascending | Events with older `created_at` are retrieved first | 27 / jun / 2023 |
|
|
| [34seen](34seen.md) | Seen At | Events are desc sorted by first seen at timestamp | 27 / jun / 2023 |
|