diff --git a/01.md b/01.md index b45887e..15c4cb5 100644 --- a/01.md +++ b/01.md @@ -79,7 +79,7 @@ Specific ranges define storage behaviors: | Ephemeral | `20000 <= kind < 30000` | Nothing | | Parameterized | `30000 <= kind < 40000` | The newest event for each `pubkey`, `kind` and `d`-tag | -Parameterized Repleaceable events MUST include a `d`-tag with an identifier value to be used as reference. Tag values want to reference the newest repleceable MUST use this format: `:<32-byte lowercase hex of a pubkey>:`. +Parameterized Repleaceable events MUST include a `d`-tag with an identifier value to be used as reference. Tag values that reference the newest repleceable MUST use this format: `:<32-byte lowercase hex of a pubkey>:`. In case of replaceable events with the same timestamp, the event with the lowest `.id` (first in lexical order) SHOULD be retained. Older versions MAY be kept but SHOULD not be returned on queries. @@ -122,11 +122,15 @@ Subscriptions stay indefinitely open until either side closes the subscription o ### Subscription Requests -To open, update, and close subscriptions, Clients MUST use the following formats: - * `["REQ", , , , ...]`, used to request events and subscribe to new updates. - * `["CLOSE", ]`, used to stop previous subscriptions. +To open and update, and close subscriptions, Clients MUST use the following formats: + * `["REQ", , , , ...]`, + * `["CLOSE", ]` -`` is a non-empty string with a maximum length of 64 chars. Relays MUST manage ``s independently for each WebSocket connection. ``s are not globally unique. A `REQ` message on an existing subscription overrides the previous subscription. +`REQ` requests events and subscribe to new updates. A `REQ` message on an existing subscription overrides the previous subscription. + +`CLOSE` stops the respective subscription. + +`` is a non-empty string with a maximum length of 64 chars. Relays MUST manage ``s independently for each WebSocket connection. ``s are not globally unique. `` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes: @@ -155,16 +159,20 @@ The `since` and `until` properties are used to specify the time range of events The `limit` property informs the maximum number of events to return, sorted by created_at desc. It operates over the previously-stored events and is ignored afterward. -### Receiving Events +### Subscription Responses Relays send 3 types of messages during a subscription: - * `["EVENT", , ]`, used to send events requested by clients. - * `["EOSE", ]`, used to indicate the _end of stored events_ and the beginning of events newly received in real-time. - * `["CLOSED", , :]`, used to indicate that a subscription was ended on the server side. + * `["EVENT", , ]` + * `["EOSE", ]`, + * `["CLOSED", , :]` All messages MUST be sent with the `subscription_id` initiated by the client (using the `REQ` message above). +The `EVENT` message is used to send events requested by clients. + +`EOSE` indicates the _end of stored events_ and the beginning of events newly received in real-time. + `CLOSED` messages MUST be sent in response to a `REQ` when the relay refuses to fulfill it. It can also be sent when a relay decides to kill a subscription on its side before a client has disconnected or sent a `CLOSE`. The message MUST be a string formed by a machine-readable single-word prefix followed by a `:` and then a human-readable message. ## Publishing @@ -175,7 +183,7 @@ To send an event to the Relay, Clients send a broadcast message in the format: Relays reply with an ACK message in the format of: - * `["OK", , , :]`, used to indicate acceptance (true) or denial (false) of an `EVENT`. + * `["OK", , , :]` `OK` messages MUST be sent in response to `EVENT` messages received from clients, they must have the 3rd parameter set to `true` when an event has been accepted by the relay, `false` otherwise. The 4th parameter MUST always be present, but MAY be an empty string when the 3rd is `true`. @@ -183,9 +191,9 @@ If present, the message MUST be a string formed by a machine-readable single-wor ## Notices -Notices are warnings that might help explain or debug the behavior of a given relay or filter. +Notices are human-readable warnings that might help explain or debug the behavior of a given relay or filter. - * `["NOTICE", ]`, used to send human-readable error messages or other things to clients. + * `["NOTICE", ]` ## Message Prefixes