diff --git a/34.md b/34.md index 42011c1b..73f15c07 100644 --- a/34.md +++ b/34.md @@ -8,12 +8,13 @@ Algorithmic Filter This NIP introduces a set of simple algorithms meant to support diverse apps' event sorting needs. -`Relays` MUST store an extra event field for each algo. Today there are two: `asc` and `seen_at`. +`Relays` MUST store an extra event field for each algo. There are two algo event fields: `asc` and `seen_at`. 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). -But now when a `client` requests events while filtering by an algo field, the `relay` MUST replace the `created_at` field in the query with the algo field. For example, a SQL relay should turn this: +But now when a `client` requests events to be filtered by an algo field, the `relay` MUST replace the `created_at` field in the query with the algo field. For example, when filtering by the `asc` +algo, a SQL relay should turn this: `SELECT * FROM events WHERE kind in (1) ORDER BY created_at DESC LIMIT 5` @@ -21,8 +22,6 @@ Into this: `SELECT * FROM events WHERE kind in (1) ORDER BY asc DESC LIMIT 5` -Upon replying to such requests, the supporting `relay` MUST add `algo: { score: "" }` field to each returned event JSON. - ## Querying An extra `algo` filter key holds the selected algorithm as value. For example, the above @@ -30,9 +29,30 @@ query is ran in response to the following request: `["REQ", , { kinds: [1], limit: 5, algo: "asc" }]` +Upon replying to such requests, the supporting `relay` MUST add an extra `score` field, +namespaced in an `algo` key, holding the selected algo's event field value. It must be +added to each returned event JSON. + +The algo field is calculated as described in the [Algorithms](#algorithms) section below. + +For example, considering above request, one of the events replied should be as follows: + +```js +{ + id: "...", + // ... (other regular event fields) + kind: 1, + algo: { + score: 1695408196 // the stored event.asc field value + } +} +``` + ## Algorithms -### Asc +This section describes how the extra event field is calculated for each algo before saving it to the database. + +### Ascending (asc) `Relay` computes `asc` field once upon receiving the event. The lower the `created_at`, the higher `asc` will be. @@ -47,7 +67,7 @@ function getAsc (createdAt) { event.asc = getAsc(event.created_at) ``` -### Seen At +### Seen At (seen_at) `Relay` computes `seen_at` field once upon receiving the event. The event field is set with the timestamp of the moment the `relay` first became aware of it, in seconds.