Merge 6975e15e0b into a551c5b693

Some cleaning up, and removing over-explanation of AND and OR logic as it becomes overwhelming to read such unnecessary details. 

It is mentioned once when filter attributes are introduced (AND for attributes, OR for lists), and again for grouping filters (OR), left as is. 

Some other minor changes to improve readability.

01.md

@@ -115,35 +115,27 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th
   * `["REQ", <subscription_id>, <filters1>, <filters2>, ...]`, used to request events and subscribe to new updates.
   * `["CLOSE", <subscription_id>]`, used to stop previous subscriptions.
 
-`<subscription_id>` is an arbitrary, non-empty string of max length 64 chars. It represents a subscription per connection. Relays MUST manage `<subscription_id>`s independently for each WebSocket connection. `<subscription_id>`s are not guaranteed to be globally unique.
+The `<subscription_id>` is an arbitrary, non-empty string of max length 64 chars generated by the client. It represents a subscription per connection. Relays MUST manage `<subscription_id>`s independently for each WebSocket connection. `<subscription_id>`s are not guaranteed to be globally unique.
 
-`<filtersX>` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes:
+`<filtersX>` is a JSON object containing filter attributes to determine which events will be sent in that subscription. The possible attributes are listed below, and they are filtered with logical AND. If an attribute contains a list (JSON array), the list is filtered with logical OR. 
 
 ```json
 {
   "ids": <a list of event ids>,
-  "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>,
+  "authors": <a list of lowercase pubkeys>,
   "kinds": <a list of a kind numbers>,
   "#<single-letter (a-zA-Z)>": <a list of tag values, for #e — a list of event ids, for #p — a list of pubkeys, etc.>,
-  "since": <an integer unix timestamp in seconds, events must be newer than this to pass>,
-  "until": <an integer unix timestamp in seconds, events must be older than this to pass>,
-  "limit": <maximum number of events relays SHOULD return in the initial query>
+  "since": <an integer Unix timestamp in seconds, events must be newer than this to pass>,
+  "until": <an integer Unix timestamp in seconds, events must be older than this to pass>,
+  "limit": <maximum number of events relays SHOULD return in the INITIAL query>
 }
 ```
 
 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 relay MUST overwrite the previous subscription.
 
-Filter attributes containing lists (`ids`, `authors`, `kinds` and tag filters like `#e`) are JSON arrays with one or more values. At least one of the arrays' values must match the relevant field in an event for the condition to be considered a match. For scalar event attributes such as `authors` and `kind`, the attribute from the event must be contained in the filter list. In the case of tag attributes such as `#e`, for which an event may have multiple values, the event and filter condition values must have at least one item in common.
-
-The `ids`, `authors`, `#e` and `#p` filter lists MUST contain exact 64-character lowercase hex values.
-
-The `since` and `until` properties can be used to specify the time range of events returned in the subscription. If a filter includes the `since` property, events with `created_at` greater than or equal to `since` are considered to match the filter. The `until` property is similar except that `created_at` must be less than or equal to `until`. In short, an event matches a filter if `since <= created_at <= until` holds.
-
-All conditions of a filter that are specified must match for an event for it to pass the filter, i.e., multiple conditions are interpreted as `&&` conditions.
-
 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 MUST be ignored afterwards. When `limit: n` is present it is assumed that the events returned in the initial query will be the last `n` events ordered by the `created_at`. 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.
+The `limit` property of a filter is only valid for the initial query and MUST be ignored afterwards. When `limit: n` is present it is assumed that the events returned in the initial query will be the last `n` events ordered by the `created_at`. It is acceptable to return fewer events than `limit` specifies, but it is expected that relays do not return (much) more events than requested, to avoid clients getting overwhelmed by data.
 
 ### From relay to client: sending events and notices
 

89.md

@@ -116,7 +116,7 @@ User B might see in their timeline an event referring to a `kind:31337` event (e
 User B's client, not knowing how to handle a `kind:31337` might display the event using its `alt` tag (as described in NIP-31). When the user clicks on the event, the application queries for a handler for this `kind`:
 
 ```json
-["REQ", <id>, '[{ "kinds": [31989], "#d": ["31337"], 'authors': [<user>, <users-contact-list>] }]']
+["REQ", <id>, { "kinds": [31989], "#d": ["31337"], "authors": [<user>, <users-contact-list>] }]
 ```
 
 User B, who follows User A, sees that `kind:31989` event and fetches the `a`-tagged event for the app and handler information.
@@ -127,5 +127,5 @@ User B's client sees the application's `kind:31990` which includes the informati
 Alternatively, users might choose to query directly for `kind:31990` for an event kind. Clients SHOULD be careful doing this and use spam-prevention mechanisms or querying high-quality restricted relays to avoid directing users to malicious handlers.
 
 ```json
-["REQ", <id>, '[{ "kinds": [31990], "#k": [<desired-event-kind>], 'authors': [...] }]']
+["REQ", <id>, { "kinds": [31990], "#k": [<desired-event-kind>], "authors": [...] }]
 ```