2024-04-16 13:09:29 -04:00
|
|
|
NIP-32
|
|
|
|
======
|
|
|
|
|
|
|
|
Custom Feeds
|
|
|
|
------------
|
|
|
|
|
|
|
|
`draft` `optional`
|
|
|
|
|
|
|
|
This NIP introduces a new data structure representing custom nostr feeds. These are to be
|
|
|
|
used in the context of an user's session to fetch a list of matching events.
|
|
|
|
|
|
|
|
# Data Format
|
|
|
|
|
|
|
|
Custom feeds are represented using lists of lists. The first parameter of every list is a `type`,
|
|
|
|
which determines the content of subsequent arguments to the feed.
|
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
## Address
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
A `address` feed includes one or more addresses of events to fetch.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
```json
|
2024-05-09 18:57:31 -04:00
|
|
|
[
|
|
|
|
"address",
|
|
|
|
"30023:d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f:98127054",
|
|
|
|
"30023:d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f:12877394"
|
|
|
|
]
|
2024-04-16 13:09:29 -04:00
|
|
|
```
|
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
## Author
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
A `author` feed includes one or more pubkeys to use in an `authors` filter.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
```json
|
2024-05-09 18:57:31 -04:00
|
|
|
["author", "d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f"]
|
2024-04-16 13:09:29 -04:00
|
|
|
```
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
## Created At
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
A `created_at` feed includes one or more objects describing date ranges for events to fetch.
|
|
|
|
These MAY include values `since`, `until`, and `relative`, which may be a list containing
|
|
|
|
`since` and `until` as strings.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
If included in the `relative` list, `since` and `until` values MUST be interpreted as
|
|
|
|
`seconds before now`. Negative numbers MUST be interpreted as `seconds after now`.
|
|
|
|
|
|
|
|
```json
|
2024-05-17 11:45:08 -04:00
|
|
|
["created_at", {"since": 1715293673, "until": 86400, "relative": ["until"]}]
|
2024-05-09 18:57:31 -04:00
|
|
|
```
|
|
|
|
|
|
|
|
## DVM
|
|
|
|
|
|
|
|
A `dvm` feed includes one or more objects describing a DVM request. Each object MUST
|
|
|
|
have a request `kind`, and MAY have a list of request `tags`, `relays` to send the
|
|
|
|
request to, and a list of `mappings` mapping response tags to feeds. If omitted,
|
2024-05-17 11:45:08 -04:00
|
|
|
applications SHOULD provide a reasonable set of default `mappings`.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
"dvm",
|
|
|
|
{
|
|
|
|
"kind": 5300,
|
2024-05-09 18:57:31 -04:00
|
|
|
"tags": [["i", "philosophy", "text"]],
|
|
|
|
"mappings": [["e", ["tag", "#e"]]]
|
2024-04-16 13:09:29 -04:00
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
## ID
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `id` feed includes one or more ids of events to fetch.
|
|
|
|
|
|
|
|
```json
|
|
|
|
["id", "b1ee83587c4ebab697719fd5bad22319741134e49933b0528b8cca426cafd59e"]
|
|
|
|
```
|
2024-04-16 13:09:29 -04:00
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
## Kind
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `kind` feed includes one or more kinds of events to fetch.
|
|
|
|
|
|
|
|
```json
|
|
|
|
["kind", 1, 30023]
|
|
|
|
```
|
2024-05-09 18:57:31 -04:00
|
|
|
|
|
|
|
## List
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `list` feed includes one or more objects defining one or more `addresses` and optional
|
|
|
|
`mappings` for how to translate list tags into feeds. If omitted, applications SHOULD
|
|
|
|
provide a reasonable set of default `mappings`.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
2024-05-09 18:57:31 -04:00
|
|
|
"list",
|
|
|
|
{
|
|
|
|
"addresses": ["3:4d7600c1da0b69185fcbcb6b86cbaa010c9ea137fa83a3f4be4c713e1f217dad:"],
|
|
|
|
"mappings": [["p", ["authors"]]]
|
|
|
|
}
|
2024-04-16 13:09:29 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
## WOT
|
|
|
|
|
|
|
|
A `wot` feed includes one or more objects with optional `min` and `max` properties. These
|
|
|
|
MUST be between 0 and 1 (inclusive) so that the interpeting application can scale the filter
|
|
|
|
to their own web of trust's score range. If empty, `min` MUST be interpreted as `0`, and
|
2024-05-17 11:45:08 -04:00
|
|
|
`max` as `1`.
|
2024-05-09 18:57:31 -04:00
|
|
|
|
|
|
|
```json
|
|
|
|
["wot", {"min": 0.3}]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Relay
|
|
|
|
|
|
|
|
A `relay` feed includes one or more relay urls to request notes from. These can be composed
|
|
|
|
with other feeds using `intersection` to limit those feeds to the given relays.
|
|
|
|
|
|
|
|
```json
|
|
|
|
["relay", "wss://relay.example.com", "wss://relay.example.org"]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Scope
|
|
|
|
|
|
|
|
A `scope` feed includes one or more strings representing groups of people relative to the
|
|
|
|
current user. Valid strings are:
|
|
|
|
|
|
|
|
- `followers` - Pubkeys who follow the current user
|
|
|
|
- `follows` - Pubkeys the current user follows
|
|
|
|
- `network` - Pubkeys followed by pubkeys the current user follows
|
|
|
|
- `self` - The current user's pubkey
|
|
|
|
|
|
|
|
```json
|
|
|
|
["scope", "follows", "self"]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Search
|
|
|
|
|
|
|
|
A `search` feed includes one or more search terms. These should be acceptable based on NIP-50,
|
|
|
|
but can be interpreted as the application sees fit.
|
|
|
|
|
|
|
|
```json
|
|
|
|
["search", "tomato"]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Tag
|
|
|
|
|
|
|
|
A `tag` feed includes a tag key and one or more values. These should be interpreted the same
|
|
|
|
as standard tag filters.
|
|
|
|
|
|
|
|
```json
|
|
|
|
["tag", "#t", "asknostr"]
|
|
|
|
```
|
|
|
|
|
2024-04-16 13:09:29 -04:00
|
|
|
## Union
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `union` feed includes zero or more feeds. An event may match any feed to match the parent feed.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
"union",
|
2024-05-09 18:57:31 -04:00
|
|
|
["scope", "followers"],
|
|
|
|
["tag", "#t", "asknostr"]
|
2024-04-16 13:09:29 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Intersection
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
An `intersection` feed includes zero or more feeds. An event must match all given feeds to
|
2024-04-16 13:09:29 -04:00
|
|
|
match the parent feed.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
"intersection",
|
2024-05-09 18:57:31 -04:00
|
|
|
["wot", {"max": 0.2}],
|
|
|
|
["tag", "#t", "introductions"]
|
2024-04-16 13:09:29 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Difference
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `difference` feed MAY include a base feed to fetch, and zero or more feeds used to exclude
|
2024-04-16 13:09:29 -04:00
|
|
|
events from the base feed.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
"difference",
|
2024-05-09 18:57:31 -04:00
|
|
|
[
|
|
|
|
"list",
|
|
|
|
{
|
|
|
|
"addresses": [
|
|
|
|
"10001:4d7600c1da0b69185fcbcb6b86cbaa010c9ea137fa83a3f4be4c713e1f217dad:"
|
|
|
|
]
|
|
|
|
}
|
|
|
|
],
|
|
|
|
["wot", {"max": 0.1}]
|
2024-04-16 13:09:29 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Symmetric Difference
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
A `symmetric_difference` feed includes zero or more feeds. An event must match only one feed to match
|
|
|
|
the base feed.
|
2024-04-16 13:09:29 -04:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
"symdiff",
|
2024-05-09 18:57:31 -04:00
|
|
|
[
|
|
|
|
"list",
|
|
|
|
{
|
|
|
|
"addresses": [
|
|
|
|
"10001:4d7600c1da0b69185fcbcb6b86cbaa010c9ea137fa83a3f4be4c713e1f217dad:"
|
|
|
|
]
|
|
|
|
}
|
|
|
|
],
|
|
|
|
[
|
|
|
|
"list",
|
|
|
|
{
|
|
|
|
"addresses": [
|
|
|
|
"10001:3375d9fe514d19bca737ba1ca2e7a43e19884385f0275a17999e05500bc177c6:"
|
|
|
|
]
|
|
|
|
}
|
|
|
|
]
|
2024-04-16 13:09:29 -04:00
|
|
|
]
|
|
|
|
```
|
|
|
|
|
2024-05-17 11:45:08 -04:00
|
|
|
# Implementation notes
|
|
|
|
|
|
|
|
If a `union`, `difference`, `intersection`, or `symmetric_difference` feed has no entries, it should
|
|
|
|
be treated as an empty feed. Likewise with other feed types that have no arguments; for example
|
|
|
|
`["authors"]` should be interprete the same way as a `{"authors": []}` filter.
|
|
|
|
|
2024-04-16 13:09:29 -04:00
|
|
|
# Feed Event
|
|
|
|
|
2024-05-09 18:57:31 -04:00
|
|
|
A `kind:31890` event defines a feed in an addressable way. The `content` SHOULD be a human-
|
|
|
|
readable description of the feed. The following tags SHOULD be included:
|
|
|
|
|
|
|
|
- A `d` tag
|
2024-05-13 11:39:37 -04:00
|
|
|
- A `title` tag indicating the feed's name
|
2024-05-09 18:57:31 -04:00
|
|
|
- A `feed` tag whose value is a JSON-encoded feed
|