NIP-01

Basic protocol flow description

draft mandatory

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.

Events and signatures

Each user has a keypair. Signatures, public key, and encodings are done according to the Schnorr signatures standard for the curve secp256k1.

The only object type that exists is the event, which has the following format on the wire:

{
  "id": <32-bytes lowercase hex-encoded sha256 of the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <unix timestamp in seconds>,
  "kind": <integer between 0 and 65535>,
  "tags": [
    [<arbitrary string>...],
    // ...
  ],
  "content": <arbitrary string>,
  "sig": <64-bytes lowercase hex of the signature of the sha256 hash of the serialized event data, which is the same as the "id" field>
}

To obtain the event.id, we sha256 the serialized event. The serialization is done over the UTF-8 JSON-serialized string (which is described below) of the following structure:

[
  0,
  <pubkey, as a lowercase hex string>,
  <created_at, as a number>,
  <kind, as a number>,
  <tags, as an array of arrays of non-null strings>,
  <content, as a string>
]

Once the sha256 is computed, replace the first 4 bytes of the hash byte array by the 4-byte, unsigned, big-endian representation of the created_at. When verifying the event, Clients MUST check if the id matches the full hash OR the sorted hash.

To prevent implementation differences from creating a different event ID for the same event, the following rules MUST be followed while serializing:

UTF-8 should be used for encoding.
Whitespace, line breaks or other unnecessary formatting should not be included in the output JSON.
The following characters in the content field must be escaped as shown, and all other characters must be included verbatim:
- A line break (0x0A), use \n
- A double quote (0x22), use \"
- A backslash (0x5C), use \\
- A carriage return (0x0D), use \r
- A tab character (0x09), use \t
- A backspace, (0x08), use \b
- A form feed, (0x0C), use \f

Kinds

Kinds specify how clients should interpret the meaning of each event and the other fields of each event (e.g. an "r" tag may have a meaning in an event of kind 1 and an entirely different meaning in an event of kind 10002). Each NIP may define the meaning of a set of kinds that weren't defined elsewhere. This NIP defines two basic kinds:

0: user metadata: the content is set to a stringified JSON object {name: <username>, about: <string>, picture: <url, string>} describing the user who created the event. Extra metadata fields may be set. A relay may delete older events once it gets a new one for the same pubkey.
1: text note: the content is set to the plaintext content of a note (anything the user wants to say). Content that must be parsed, such as Markdown and HTML, should not be used. Clients should also not parse content as those.

And also a convention for kind ranges that allow for easier experimentation and flexibility of relay implementation:

for kind n such that 1000 <= n < 10000 || 4 <= n < 45 || n == 1 || n == 2, events are regular, which means they're all expected to be stored by relays.
for kind n such that 10000 <= n < 20000 || n == 0 || n == 3, events are replaceable, which means that, for each combination of pubkey and kind, only the latest event MUST be stored by relays, older versions MAY be discarded.
for kind n such that 20000 <= n < 30000, events are ephemeral, which means they are not expected to be stored by relays.
for kind n such that 30000 <= n < 40000, events are addressable by their kind, pubkey and d tag value -- which means that, for each combination of kind, pubkey and the d tag value, only the latest event MUST be stored by relays, older versions MAY be discarded.

In case of replaceable events with the same timestamp, the event with the lowest id (first in lexical order) should be retained, and the other discarded.

When answering to REQ messages for replaceable events such as {"kinds":[0],"authors":[<hex-key>]}, even if the relay has more than one version stored, it SHOULD return just the latest one.

These are just conventions and relay implementations may differ.

Communication between clients and relays

Relays expose a websocket endpoint to which clients can connect. Clients SHOULD open a single websocket connection to each relay and use it for all their subscriptions. Relays MAY limit number of connections from specific IP/client/etc.

From client to relay: sending events and creating subscriptions

Clients can send 3 types of messages, which must be JSON arrays, according to the following patterns:

["EVENT", <event JSON as defined above>], used to publish events.
["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.

<filtersX> is a JSON object that determines what events will be sent in that subscription, it can have the following attributes:

{
  "ids": <a list of event ids>,
  "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>,
  "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 have a created_at >= to this to pass>,
  "until": <an integer unix timestamp in seconds. Events must have a created_at <= to this to pass>,
  "limit": <maximum number of events relays SHOULD return in the initial query>
}

Upon receiving a REQ message, the relay SHOULD return events that match the filter. Any new events it receives SHOULD be sent to that same websocket until the connection is closed, a CLOSE event is received with the same <subscription_id>, or a new REQ is sent using the same <subscription_id> (in which case a new subscription is created, replacing the old one).

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. Newer events should appear first, and in the case of ties the event with the lowest id (first in lexical order) should be first. 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 5 types of messages, which must also be JSON arrays, according to the following patterns:

["EVENT", <subscription_id>, <event JSON as defined above>], used to send events requested by clients.
["OK", <event_id>, <true|false>, <message>], used to indicate acceptance or denial of an EVENT message.
["EOSE", <subscription_id>], used to indicate the end of stored events and the beginning of events newly received in real-time.
["CLOSED", <subscription_id>, <message>], used to indicate that a subscription was ended on the server side.
["NOTICE", <message>], used to send human-readable error messages or other things to clients.

This NIP defines no rules for how NOTICE messages should be sent or treated.

EVENT messages MUST be sent only with a subscription ID related to a subscription previously initiated by the client (using the REQ message above).
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, otherwise it MUST be a string formed by a machine-readable single-word prefix followed by a : and then a human-readable message. Some examples:
- ["OK", "b1a649ebe8...", true, ""]
- ["OK", "b1a649ebe8...", true, "pow: difficulty 25>=24"]
- ["OK", "b1a649ebe8...", true, "duplicate: already have this event"]
- ["OK", "b1a649ebe8...", false, "blocked: you are banned from posting here"]
- ["OK", "b1a649ebe8...", false, "blocked: please register your pubkey at https://my-expensive-relay.example.com"]
- ["OK", "b1a649ebe8...", false, "rate-limited: slow down there chief"]
- ["OK", "b1a649ebe8...", false, "invalid: event creation date is too far off from the current time"]
- ["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"]
- ["OK", "b1a649ebe8...", false, "error: could not connect to the database"]
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. This message uses the same pattern of OK messages with the machine-readable prefix and human-readable message. Some examples:
- ["CLOSED", "sub1", "unsupported: filter contains unknown elements"]
- ["CLOSED", "sub1", "error: could not connect to the database"]
- ["CLOSED", "sub1", "error: shutting down idle subscription"]
The standardized machine-readable prefixes for OK and CLOSED are: duplicate, pow, blocked, rate-limited, invalid, and error for when none of that fits.

13 KiB Raw Blame History