diff options
Diffstat (limited to '01.md')
| -rw-r--r-- | 01.md | 13 |
1 files changed, 7 insertions, 6 deletions
| @@ -4,7 +4,7 @@ NIP-01 | |||
| 4 | Basic protocol flow description | 4 | Basic protocol flow description |
| 5 | ------------------------------- | 5 | ------------------------------- |
| 6 | 6 | ||
| 7 | `draft` `mandatory` | 7 | `draft` `mandatory` `relay` |
| 8 | 8 | ||
| 9 | 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. | 9 | 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. |
| 10 | 10 | ||
| @@ -14,7 +14,7 @@ Each user has a keypair. Signatures, public key, and encodings are done accordin | |||
| 14 | 14 | ||
| 15 | The only object type that exists is the `event`, which has the following format on the wire: | 15 | The only object type that exists is the `event`, which has the following format on the wire: |
| 16 | 16 | ||
| 17 | ```jsonc | 17 | ```yaml |
| 18 | { | 18 | { |
| 19 | "id": <32-bytes lowercase hex-encoded sha256 of the serialized event data>, | 19 | "id": <32-bytes lowercase hex-encoded sha256 of the serialized event data>, |
| 20 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, | 20 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, |
| @@ -85,7 +85,7 @@ As a convention, all single-letter (only english alphabet letters: a-z, A-Z) key | |||
| 85 | 85 | ||
| 86 | ### Kinds | 86 | ### Kinds |
| 87 | 87 | ||
| 88 | 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. [NIP-10](10.md), for instance, especifies the `kind:1` text note for social media applications. | 88 | 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. [NIP-10](10.md), for instance, specifies the `kind:1` text note for social media applications. |
| 89 | 89 | ||
| 90 | This NIP defines one basic kind: | 90 | This NIP defines one basic kind: |
| 91 | 91 | ||
| @@ -120,7 +120,7 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th | |||
| 120 | 120 | ||
| 121 | `<filtersX>` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes: | 121 | `<filtersX>` is a JSON object that determines what events will be sent in that subscription, it can have the following attributes: |
| 122 | 122 | ||
| 123 | ```json | 123 | ```yaml |
| 124 | { | 124 | { |
| 125 | "ids": <a list of event ids>, | 125 | "ids": <a list of event ids>, |
| 126 | "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>, | 126 | "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>, |
| @@ -144,7 +144,7 @@ All conditions of a filter that are specified must match for an event for it to | |||
| 144 | 144 | ||
| 145 | 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. | 145 | 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. |
| 146 | 146 | ||
| 147 | 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. | 147 | 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. Relays SHOULD use the `limit` value to guide how many events are returned in the initial response. Returning fewer events is acceptable, but returning (much) more should be avoided to prevent overwhelming clients. |
| 148 | 148 | ||
| 149 | ### From relay to client: sending events and notices | 149 | ### From relay to client: sending events and notices |
| 150 | 150 | ||
| @@ -170,8 +170,9 @@ This NIP defines no rules for how `NOTICE` messages should be sent or treated. | |||
| 170 | * `["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"]` | 170 | * `["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"]` |
| 171 | * `["OK", "b1a649ebe8...", false, "restricted: not allowed to write."]` | 171 | * `["OK", "b1a649ebe8...", false, "restricted: not allowed to write."]` |
| 172 | * `["OK", "b1a649ebe8...", false, "error: could not connect to the database"]` | 172 | * `["OK", "b1a649ebe8...", false, "error: could not connect to the database"]` |
| 173 | * `["OK", "b1a649ebe8...", false, "mute: no one was listening to your ephemeral event and it wasn't handled in any way, it was ignored"]` | ||
| 173 | - `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: | 174 | - `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: |
| 174 | * `["CLOSED", "sub1", "unsupported: filter contains unknown elements"]` | 175 | * `["CLOSED", "sub1", "unsupported: filter contains unknown elements"]` |
| 175 | * `["CLOSED", "sub1", "error: could not connect to the database"]` | 176 | * `["CLOSED", "sub1", "error: could not connect to the database"]` |
| 176 | * `["CLOSED", "sub1", "error: shutting down idle subscription"]` | 177 | * `["CLOSED", "sub1", "error: shutting down idle subscription"]` |
| 177 | - The standardized machine-readable prefixes for `OK` and `CLOSED` are: `duplicate`, `pow`, `blocked`, `rate-limited`, `invalid`, `restricted`, and `error` for when none of that fits. | 178 | - The standardized machine-readable prefixes for `OK` and `CLOSED` are: `duplicate`, `pow`, `blocked`, `rate-limited`, `invalid`, `restricted`, `mute` and `error` for when none of that fits. |