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.md34
1 files changed, 17 insertions, 17 deletions
diff --git a/01.md b/01.md
index c1e3748..1da6e83 100644
--- a/01.md
+++ b/01.md
@@ -43,20 +43,20 @@ To obtain the `event.id`, we `sha256` the serialized event. The serialization is
43``` 43```
44 44
45To prevent implementation differences from creating a different event ID for the same event, the following rules MUST be followed while serializing: 45To prevent implementation differences from creating a different event ID for the same event, the following rules MUST be followed while serializing:
46- No whitespace, line breaks or other unnecessary formatting should be included in the output JSON.
47- No characters except the following should be escaped, and instead should be included verbatim:
48 - A line break, `0x0A`, as `\n`
49 - A double quote, `0x22`, as `\"`
50 - A backslash, `0x5C`, as `\\`
51 - A carriage return, `0x0D`, as `\r`
52 - A tab character, `0x09`, as `\t`
53 - A backspace, `0x08`, as `\b`
54 - A form feed, `0x0C`, as `\f`
55- UTF-8 should be used for encoding. 46- UTF-8 should be used for encoding.
47- Whitespace, line breaks or other unnecessary formatting should not be included in the output JSON.
48- The following characters in the content field must be escaped as shown, and all other characters must be included verbatim:
49 - A line break (`0x0A`), use `\n`
50 - A double quote (`0x22`), use `\"`
51 - A backslash (`0x5C`), use `\\`
52 - A carriage return (`0x0D`), use `\r`
53 - A tab character (`0x09`), use `\t`
54 - A backspace, (`0x08`), use `\b`
55 - A form feed, (`0x0C`), use `\f`
56 56
57### Tags 57### Tags
58 58
59Each tag is an array of strings of arbitrary size, with some conventions around them. Take a look at the example below: 59Each tag is an array of one or more strings, with some conventions around them. Take a look at the example below:
60 60
61```jsonc 61```jsonc
62{ 62{
@@ -81,18 +81,18 @@ This NIP defines 3 standard tags that can be used across all event kinds with th
81 - for a parameterized replaceable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:<d tag value>, <recommended relay URL, optional>]` 81 - for a parameterized replaceable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:<d tag value>, <recommended relay URL, optional>]`
82 - for a non-parameterized replaceable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:, <recommended relay URL, optional>]` 82 - for a non-parameterized replaceable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:, <recommended relay URL, optional>]`
83 83
84As a convention, all single-letter (only english alphabet letters: a-z, A-Z) key tags are expected to be indexed by relays, such that it is possible, for example, to query or subscribe to events that reference the event `"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"` by using the `{"#e": "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"}` filter. 84As a convention, all single-letter (only english alphabet letters: a-z, A-Z) key tags are expected to be indexed by relays, such that it is possible, for example, to query or subscribe to events that reference the event `"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"` by using the `{"#e": ["5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"]}` filter.
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. This NIP defines two basic kinds: 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. This NIP defines two basic kinds:
89 89
90- `0`: **metadata**: the `content` is set to a stringified JSON object `{name: <username>, about: <string>, picture: <url, string>}` describing the user who created the event. A relay may delete older events once it gets a new one for the same pubkey. 90- `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](24.md#kind-0) may be set. A relay may delete older events once it gets a new one for the same pubkey.
91- `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. 91- `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.
92 92
93And also a convention for kind ranges that allow for easier experimentation and flexibility of relay implementation: 93And also a convention for kind ranges that allow for easier experimentation and flexibility of relay implementation:
94 94
95- for kind `n` such that `1000 <= n < 10000`, events are **regular**, which means they're all expected to be stored by relays. 95- 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.
96- 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. 96- 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.
97- for kind `n` such that `20000 <= n < 30000`, events are **ephemeral**, which means they are not expected to be stored by relays. 97- for kind `n` such that `20000 <= n < 30000`, events are **ephemeral**, which means they are not expected to be stored by relays.
98- for kind `n` such that `30000 <= n < 40000`, events are **parameterized replaceable**, which means that, for each combination of `pubkey`, `kind` and the `d` tag's first value, only the latest event MUST be stored by relays, older versions MAY be discarded. 98- for kind `n` such that `30000 <= n < 40000`, events are **parameterized replaceable**, which means that, for each combination of `pubkey`, `kind` and the `d` tag's first value, only the latest event MUST be stored by relays, older versions MAY be discarded.
@@ -125,8 +125,8 @@ Clients can send 3 types of messages, which must be JSON arrays, according to th
125 "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>, 125 "authors": <a list of lowercase pubkeys, the pubkey of an event must be one of these>,
126 "kinds": <a list of a kind numbers>, 126 "kinds": <a list of a kind numbers>,
127 "#<single-letter (a-zA-Z)>": <a list of tag values, for #e — a list of event ids, for #p — a list of pubkeys, etc.>, 127 "#<single-letter (a-zA-Z)>": <a list of tag values, for #e — a list of event ids, for #p — a list of pubkeys, etc.>,
128 "since": <an integer unix timestamp in seconds, events must be newer than this to pass>, 128 "since": <an integer unix timestamp in seconds. Events must have a created_at >= to this to pass>,
129 "until": <an integer unix timestamp in seconds, events must be older than this to pass>, 129 "until": <an integer unix timestamp in seconds. Events must have a created_at <= to this to pass>,
130 "limit": <maximum number of events relays SHOULD return in the initial query> 130 "limit": <maximum number of events relays SHOULD return in the initial query>
131} 131}
132``` 132```
@@ -143,11 +143,11 @@ All conditions of a filter that are specified must match for an event for it to
143 143
144A `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. 144A `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 145
146The `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. 146The `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 147
148### From relay to client: sending events and notices 148### From relay to client: sending events and notices
149 149
150Relays can send 4 types of messages, which must also be JSON arrays, according to the following patterns: 150Relays can send 5 types of messages, which must also be JSON arrays, according to the following patterns:
151 151
152 * `["EVENT", <subscription_id>, <event JSON as defined above>]`, used to send events requested by clients. 152 * `["EVENT", <subscription_id>, <event JSON as defined above>]`, used to send events requested by clients.
153 * `["OK", <event_id>, <true|false>, <message>]`, used to indicate acceptance or denial of an `EVENT` message. 153 * `["OK", <event_id>, <true|false>, <message>]`, used to indicate acceptance or denial of an `EVENT` message.