sneak filter.limit in nip-01.

1 files changed, 6 insertions, 3 deletions

diff --git a/01.md b/01.md
index 39aac0e..8b81828 100644
--- a/01.md
+++ b/01.md
@@ -4,7 +4,7 @@ NIP-01
 Basic protocol flow description
 -------------------------------
 
-`draft` `mandatory` `author:fiatjaf` `author:distbit` `author:scsibug` `author:kukks`
+`draft` `mandatory` `author:fiatjaf` `author:distbit` `author:scsibug` `author:kukks` `author:jb55`
 
 This NIP defines the basic protocol that should be implemented by everybody. New NIPs may add new optional (or mandatory) fields and messages and features to the structures and flows described here.
 
@@ -62,16 +62,17 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th
 ```
 {
   "ids": <a list of event ids or prefixes>,
+  "authors": <a list of pubkeys or prefixes, the pubkey of an event must be one of these>,
   "kinds": <a list of a kind numbers>,
   "#e": <a list of event ids that are referenced in an "e" tag>,
   "#p": <a list of pubkeys that are referenced in a "p" tag>,
   "since": <a timestamp, events must be newer than this to pass>,
   "until": <a timestamp, events must be older than this to pass>,
-  "authors": <a list of pubkeys or prefixes, the pubkey of an event must be one of these>
+  "limit": <maximum number of events to be returned in the initial query>
 }
 ```
 
-Upon receiving a `REQ` message, the relay MUST query its internal database and return events that match the filter, then store that filter and send again all future events it receives to that same websocket until the websocket is closed. The `CLOSE` event is received with the same `<subscription_id>` or a new `REQ` is sent using the same `<subscription_id>`, in which case it should overwrite the previous subscription.
+Upon receiving a `REQ` message, the relay SHOULD query its internal database and return events that match the filter, then store that filter and send again all future events it receives to that same websocket until the websocket is closed. The `CLOSE` event is received with the same `<subscription_id>` or a new `REQ` is sent using the same `<subscription_id>`, in which case it should overwrite the previous subscription.
 
 Filter attributes containing lists (such as `ids`, `kinds`, or `#e`) are JSON arrays with one or more values.  At least one of the array's values must match the relevant field in an event for the condition itself to be considered a match.  For scalar event attributes such as `kind`, the attribute from the event must be contained in the filter list.  For tag attributes such as `#e`, where an event may have multiple values, the event and filter condition values must have at least one item in common.
 
@@ -81,6 +82,8 @@ All conditions of a filter that are specified must match for an event for it to
 
 A `REQ` message may contain multiple filters. In this case events that match any of the filters are to be returned, i.e., multiple filters are to be interpreted as `||` conditions.
 
+The `limit` property of a filter is only valid for the initial query and can be ignored afterwards. When `limit: n` is present it is assumed that the the events returned in the initial query will be the latest `n` events. It is safe to return less events than `limit` specifies, but it is expected that relays do not return (much) more events than requested so clients don't get unnecessarily overwhelmed by data.
+
 ### From relay to client: sending events and notices
 
 Relays can send 2 types of messages, which must also be JSON arrays, according to the following patterns: