nips/fe.md

NIP-fe

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.

Address

A address feed includes one or more addresses of events to fetch.

[
  "address",
  "30023:d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f:98127054",
  "30023:d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f:12877394"
]

Author

A author feed includes one or more pubkeys to use in an authors filter.

["author", "d97a7541e4603d393c61eaad810c2e2e72684fb5672bde962c75c023d70e763f"]

Created At

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.

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.

["created_at", {"since": 1715293673, "until": 86400, "relative": ["until"]}]

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, applications SHOULD provide a reasonable set of default mappings.

[
  "dvm",
  {
    "kind": 5300,
    "tags": [["i", "philosophy", "text"]],
    "mappings": [["e", ["tag", "#e"]]]
  }
]

ID

A id feed includes one or more ids of events to fetch.

["id", "b1ee83587c4ebab697719fd5bad22319741134e49933b0528b8cca426cafd59e"]

Kind

A kind feed includes one or more kinds of events to fetch.

["kind", 1, 30023]

List

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.

[
  "list",
  {
    "addresses": ["3:4d7600c1da0b69185fcbcb6b86cbaa010c9ea137fa83a3f4be4c713e1f217dad:"],
    "mappings": [["p", ["authors"]]]
  }
]

Label

A label feed includes one or more objects defining filters for fetching kind 1985 label events and optional mappings for how to translate label tags into feeds. If omitted, applications SHOULD provide a reasonable set of default mappings.

Label items may have the following keys:

• mappings - a list of lists mapping tag names to filter keys
• authors - a list of authors
• relays - a list of relays to request events from
• Any single-letter tag filter (beginning with #)

[
  "label",
  {
    "#l": ["#p"],
    "#L": ["pub.ditto.trends"],
    "authors": ["db0e60d10b9555a39050c258d460c5c461f6d18f467aa9f62de1a728b8a891a4"],
    "mappings": [["p", ["authors"]]]
  }
]

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 max as 1.

["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.

["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

["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.

["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.

["tag", "#t", "asknostr"]

Union

A union feed includes zero or more feeds. An event may match any feed to match the parent feed.

Example:

[
  "union",
  ["scope", "followers"],
  ["tag", "#t", "asknostr"]
]

Intersection

An intersection feed includes zero or more feeds. An event must match all given feeds to match the parent feed.

Example:

[
  "intersection",
  ["wot", {"max": 0.2}],
  ["tag", "#t", "introductions"]
]

Difference

A difference feed MAY include a base feed to fetch, and zero or more feeds used to exclude events from the base feed.

Example:

[
  "difference",
  [
    "list",
    {
      "addresses": [
        "10001:4d7600c1da0b69185fcbcb6b86cbaa010c9ea137fa83a3f4be4c713e1f217dad:"
      ]
    }
  ],
  ["wot", {"max": 0.1}]
]

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.

Feed Event

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
• A title tag indicating the feed's name
• A feed tag whose value is a JSON-encoded feed