upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/01.md
diff options
context:
space:
mode:
Diffstat (limited to '01.md')
-rw-r--r--01.md13
1 files changed, 7 insertions, 6 deletions
diff --git a/01.md b/01.md
index f7f592c..eb9f60c 100644
--- a/01.md
+++ b/01.md
@@ -4,7 +4,7 @@ NIP-01
4Basic protocol flow description 4Basic protocol flow description
5------------------------------- 5-------------------------------
6 6
7`draft` `mandatory` 7`draft` `mandatory` `relay`
8 8
9This 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. 9This 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
15The only object type that exists is the `event`, which has the following format on the wire: 15The 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
88Kinds 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. 88Kinds 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
90This NIP defines one basic kind: 90This 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
145A `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. 145A `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
147The `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. 147The `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.