diff options
Diffstat (limited to '29.md')
| -rw-r--r-- | 29.md | 54 |
1 files changed, 21 insertions, 33 deletions
| @@ -4,7 +4,7 @@ NIP-29 | |||
| 4 | Relay-based Groups | 4 | Relay-based Groups |
| 5 | ------------------ | 5 | ------------------ |
| 6 | 6 | ||
| 7 | `draft` `optional` | 7 | `draft` `optional` `relay` |
| 8 | 8 | ||
| 9 | This NIP defines a standard for groups that are only writable by a closed set of users. They can be public for reading by external users or not. | 9 | This NIP defines a standard for groups that are only writable by a closed set of users. They can be public for reading by external users or not. |
| 10 | 10 | ||
| @@ -48,14 +48,6 @@ The roles supported by the group as to having some special privilege assigned to | |||
| 48 | 48 | ||
| 49 | Users with any roles that have any privilege can be considered _admins_ in a broad sense and be returned in the `kind:39001` event for a group. | 49 | Users with any roles that have any privilege can be considered _admins_ in a broad sense and be returned in the `kind:39001` event for a group. |
| 50 | 50 | ||
| 51 | ## Unmanaged groups | ||
| 52 | |||
| 53 | Unmanaged groups are impromptu groups that can be used in any public relay unaware of NIP-29 specifics. They piggyback on relays' natural white/blacklists (or lack of) but aside from that are not actively managed and won't have any admins, group state or metadata events. | ||
| 54 | |||
| 55 | In `unmanaged` groups, everybody is considered to be a member. | ||
| 56 | |||
| 57 | Unmanaged groups can transition to managed groups, in that case the relay master key just has to publish moderation events setting the state of all groups and start enforcing the rules they choose to. | ||
| 58 | |||
| 59 | ## Event definitions | 51 | ## Event definitions |
| 60 | 52 | ||
| 61 | These are the events expected to be found in NIP-29 groups. | 53 | These are the events expected to be found in NIP-29 groups. |
| @@ -83,7 +75,7 @@ Any user can send a kind `9021` event to the relay in order to request admission | |||
| 83 | } | 75 | } |
| 84 | ``` | 76 | ``` |
| 85 | 77 | ||
| 86 | The optional `code` tag may be used by the relay to preauthorize acceptances in `closed` groups, together with the `kind:9009` `create-invite` moderation event. | 78 | The optional `code` tag may be used by the relay to preauthorize acceptance, together with the `kind:9009` `create-invite` moderation event. |
| 87 | 79 | ||
| 88 | - *leave request* (`kind:9022`) | 80 | - *leave request* (`kind:9022`) |
| 89 | 81 | ||
| @@ -120,21 +112,21 @@ Clients can send these events to a relay in order to accomplish a moderation act | |||
| 120 | 112 | ||
| 121 | Each moderation action uses a different kind and requires different arguments, which are given as tags. These are defined in the following table: | 113 | Each moderation action uses a different kind and requires different arguments, which are given as tags. These are defined in the following table: |
| 122 | 114 | ||
| 123 | | kind | name | tags | | 115 | | kind | name | tags | |
| 124 | | --- | --- | --- | | 116 | | --- | --- | --- | |
| 125 | | 9000 | `put-user` | `p` with pubkey hex and optional roles | | 117 | | 9000 | `put-user` | `p` with pubkey hex and optional roles | |
| 126 | | 9001 | `remove-user` | `p` with pubkey hex | | 118 | | 9001 | `remove-user` | `p` with pubkey hex | |
| 127 | | 9002 | `edit-metadata` | fields from `kind:39000` to be modified | | 119 | | 9002 | `edit-metadata` | fields to be modified, and optionally `unrestricted`, `open`, `visible` `public` | |
| 128 | | 9005 | `delete-event` | `e` with event id hex | | 120 | | 9005 | `delete-event` | `e` with event id hex | |
| 129 | | 9007 | `create-group` | | | 121 | | 9007 | `create-group` | | |
| 130 | | 9008 | `delete-group` | | | 122 | | 9008 | `delete-group` | | |
| 131 | | 9009 | `create-invite` | | | 123 | | 9009 | `create-invite` | arbitrary `code` | |
| 132 | 124 | ||
| 133 | It's expected that the group state (of who is an allowed member or not, who is an admin and with which permission or not, what are the group name and picture etc) can be fully reconstructed from the canonical sequence of these events. | 125 | It's expected that the group state (of who is an allowed member or not, who is an admin and with which permission or not, what are the group name and picture etc) can be fully reconstructed from the canonical sequence of these events. |
| 134 | 126 | ||
| 135 | ### Group metadata events | 127 | ### Group metadata events |
| 136 | 128 | ||
| 137 | These events contain the group id in a `d` tag instead of the `h` tag. They MUST be created by the relay master key only and a single instance of each (or none) should exist at all times for each group. They are merely informative but should reflect the latest group state (as it was changed by moderation events over time). | 129 | These events contain the group id in a `d` tag instead of the `h` tag. They MUST be created by the relay master key only (as stated by the [NIP-11](11.md) `"self"` pubkey) and a single instance of each (or none) should exist at all times for each group. They are merely informative but should reflect the latest group state (as it was changed by moderation events over time). |
| 138 | 130 | ||
| 139 | - *group metadata* (`kind:39000`) (optional) | 131 | - *group metadata* (`kind:39000`) (optional) |
| 140 | 132 | ||
| @@ -142,8 +134,6 @@ This event defines the metadata for the group -- basically how clients should di | |||
| 142 | 134 | ||
| 143 | If the group is forked and hosted in multiple relays, there will be multiple versions of this event in each different relay and so on. | 135 | If the group is forked and hosted in multiple relays, there will be multiple versions of this event in each different relay and so on. |
| 144 | 136 | ||
| 145 | When this event is not found, clients may still connect to the group, but treat it as having a different status, `unmanaged`, | ||
| 146 | |||
| 147 | ```jsonc | 137 | ```jsonc |
| 148 | { | 138 | { |
| 149 | "kind": 39000, | 139 | "kind": 39000, |
| @@ -153,14 +143,18 @@ When this event is not found, clients may still connect to the group, but treat | |||
| 153 | ["name", "Pizza Lovers"], | 143 | ["name", "Pizza Lovers"], |
| 154 | ["picture", "https://pizza.com/pizza.png"], | 144 | ["picture", "https://pizza.com/pizza.png"], |
| 155 | ["about", "a group for people who love pizza"], | 145 | ["about", "a group for people who love pizza"], |
| 156 | ["public"], // or ["private"] | 146 | ["private"], |
| 157 | ["open"] // or ["closed"] | 147 | ["closed"] |
| 158 | ] | 148 | ] |
| 159 | // other fields... | 149 | // other fields... |
| 160 | } | 150 | } |
| 161 | ``` | 151 | ``` |
| 162 | 152 | ||
| 163 | `name`, `picture` and `about` are basic metadata for the group for display purposes. `public` signals the group can be _read_ by anyone, while `private` signals that only AUTHed users can read. `open` signals that anyone can request to join and the request will be automatically granted, while `closed` signals that members must be pre-approved or that requests to join will be manually handled. | 153 | - `name`, `picture` and `about` are basic metadata for the group for display purposes. |
| 154 | - `private` indicates that only members can _read_ group messages. Omitting this tag indicates that anyone can read group messages. | ||
| 155 | - `restricted` indicates that only members can _write_ messages to the group. Omitting this tag indicates that anyone can send messages to the group. | ||
| 156 | - `hidden` indicates that relays should hide group metadata from non-members. Omitting this tag indicates that anyone can request group metadata events. | ||
| 157 | - `closed` indicates that join requests are ignored. Omitting this tag indicates that users can expect join requests to be honored. | ||
| 164 | 158 | ||
| 165 | - *group admins* (`kind:39001`) (optional) | 159 | - *group admins* (`kind:39001`) (optional) |
| 166 | 160 | ||
| @@ -227,18 +221,12 @@ The process through which the relay decides what roles to support and how to han | |||
| 227 | 221 | ||
| 228 | ### Checking your own membership in a group | 222 | ### Checking your own membership in a group |
| 229 | 223 | ||
| 230 | The latest of either `kind:9000` or `kind:9001` events present in a group should tell a user that they are currently members of the group or if they were removed. In case none of these exist the user is assumed to not be a member of the group -- unless the group is `unmanaged`, in which case the user is assumed to be a member. | 224 | The latest of either `kind:9000` or `kind:9001` events present in a group should tell a user that they are currently members of the group or if they were removed. In case none of these exist the user is assumed to not be a member of the group. |
| 231 | 225 | ||
| 232 | ### Adding yourself to a group | 226 | ### Adding yourself to a group |
| 233 | 227 | ||
| 234 | When a group is `open`, anyone can send a `kind:9021` event to it in order to be added, then expect a `kind:9000` event to be emitted confirming that the user was added. The same happens with `closed` groups, except in that case a user may only send a `kind:9021` if it has an invite code. | 228 | Anyone can send a `kind:9021` join request to a group. The relay may then generate a `kind:9000` event immediately, or defer that decision to an administator. If a group is `closed`, join requests are not honored unless they include an invite code. |
| 235 | 229 | ||
| 236 | ### Storing your list of groups | 230 | ### Storing your list of groups |
| 237 | 231 | ||
| 238 | A definition for `kind:10009` was included in [NIP-51](51.md) that allows clients to store the list of groups a user wants to remember being in. | 232 | A definition for `kind:10009` was included in [NIP-51](51.md) that allows clients to store the list of groups a user wants to remember being in. |
| 239 | |||
| 240 | ### Using `unmanaged` relays | ||
| 241 | |||
| 242 | To prevent event leakage, when using `unmanaged` relays, clients should include the [NIP-70](70.md) `-` tag, as just the `previous` tag won't be checked by other `unmanaged` relays. | ||
| 243 | |||
| 244 | Groups MAY be named without relay support by adding a `name` to the corresponding tag in a user's `kind 10009` group list. | ||