nip29: support for unmanaged groups, top-level relay-local groups and invite codes

29.md

@@ -22,6 +22,12 @@ Relays are supposed to generate the events that describe group metadata and grou
 
 A group may be identified by a string in the format `<host>'<group-id>`. For example, a group with _id_ `abcdef` hosted at the relay `wss://groups.nostr.com` would be identified by the string `groups.nostr.com'abcdef`.
 
+Group identifiers must be strings restricted to the characters `a-z0-9-_`.
+
+When encountering just the `<host>` without the `'<group-id>`, clients can choose to connect to the group with id `_`, which is a special top-level group dedicated to relay-local discussions.
+
+Group identifiers in most cases should be random or pseudo-random, as that mitigates message replay confusiong and ensures they can be migrated or forked to other relays easily without risking conflicting with other groups using the same id in these new relays. This isn't a hard rule, as, for example, in `unmanaged` and/or ephemeral relays groups might not want to migrate ever, so they might not care about this. Notably, the `_` relay-local group isn't expected to be migrated ever.
+
 ## The `h` tag
 
 Events sent by users to groups (chat messages, text notes, moderation events etc) must have an `h` tag with the value set to the group _id_.
@@ -36,8 +42,22 @@ This is a hack to prevent messages from being broadcasted to external relays tha
 
 Relays should prevent late publication (messages published now with a timestamp from days or even hours ago) unless they are open to receive a group forked or moved from another relay.
 
+## Unmanaged groups
+
+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.
+
+In `unmanaged` groups, everybody is considered to be a member.
+
+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.
+
 ## Event definitions
 
+These are the events expected to be found in NIP-29 groups.
+
+### Normal user-created events
+
+These events generally can be sent by all members of a group and they require the `h` tag to be present so they're attached to a specific group.
+
 - *text root note* (`kind:11`)
 
 This is the basic unit of a "microblog" root text note sent to a group.
@@ -79,6 +99,14 @@ Similar to `kind:12`, this is the basic unit of a chat message sent to a group.
 
 `kind:10` SHOULD use NIP-10 markers, just like `kind:12`.
 
+- other events:
+
+Groups may also accept other events, like long-form articles, calendar, livestream, market announcements and so on. These should be as defined in their respective NIPs, with the addition of the `h` tag.
+
+### User-related group management events
+
+These are events that can be sent my user to manage their situation in a group, they also require the `h` tag.
+
 - *join request* (`kind:9021`)
 
 Any user can send one of these events to the relay in order to be automatically or manually added to the group. If the group is `open` the relay will automatically issue a `kind:9000` in response adding this user. Otherwise group admins may choose to query for these requests and act upon them.
@@ -88,11 +116,14 @@ Any user can send one of these events to the relay in order to be automatically
   "kind": 9021,
   "content": "optional reason",
   "tags": [
-    ["h", "<group-id>"]
+    ["h", "<group-id>"],
+    ["claim", "<optional-invite-code>"]
   ]
 }
 ```
 
+The optional `claim` tag may be used by the relay to preauthorize acceptances in `closed` groups, together with the `kind:9009` `create-invite` moderation event.
+
 - *leave request* (`kind:9022`)
 
 Any user can send one of these events to the relay in order to be automatically removed from the group. The relay will automatically issue a `kind:9001` in response removing this user.
@@ -107,6 +138,10 @@ Any user can send one of these events to the relay in order to be automatically
 }
 ```
 
+### Group state -- or moderation
+
+These are events expected to be sent by the relay master key or by group admins -- and relays should reject them if they don't come from an authorized admin. They also require the `h` tag.
+
 - *moderation events* (`kinds:9000-9020`) (optional)
 
 Clients can send these events to a relay in order to accomplish a moderation action. Relays must check if the pubkey sending the event is capable of performing the given action. The relay may discard the event after taking action or keep it as a moderation log.
@@ -124,24 +159,33 @@ Clients can send these events to a relay in order to accomplish a moderation act
 
 Each moderation action uses a different kind and requires different arguments, which are given as tags. These are defined in the following table:
 
-| kind | name                | tags                                      |
-| ---  | ---                 | ---                                       |
-| 9000 | `add-user`          | `p` (pubkey hex)                          |
-| 9001 | `remove-user`       | `p` (pubkey hex)                          |
-| 9002 | `edit-metadata`     | `name`, `about`, `picture` (string)       |
-| 9003 | `add-permission`    | `p` (pubkey), `permission` (name)         |
-| 9004 | `remove-permission` | `p` (pubkey), `permission` (name)         |
-| 9005 | `delete-event`      | `e` (id hex)                              |
-| 9006 | `edit-group-status` | `public` or `private`, `open` or `closed` |
-| 9007 | `create-group`      |                                           |
-| 9008 | `delete-group`      |                                           |
+| kind | name                | tags                                           |
+| ---  | ---                 | ---                                            |
+| 9000 | `add-user`          | `p` (pubkey hex)                               |
+| 9001 | `remove-user`       | `p` (pubkey hex)                               |
+| 9002 | `edit-metadata`     | `name`, `about`, `picture` (string)            |
+| 9003 | `add-permission`    | `p` (pubkey), `permission` (name)              |
+| 9004 | `remove-permission` | `p` (pubkey), `permission` (name)              |
+| 9005 | `delete-event`      | `e` (id hex)                                   |
+| 9006 | `edit-group-status` | `public` or `private`, `open` or `closed`      |
+| 9007 | `create-group`      |                                                |
+| 9008 | `delete-group`      |                                                |
+| 9009 | `create-invite`     | `code`, `uses` (how many times it can be used) |
+
+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.
+
+### Group metadata events
+
+These events contain the group id in a `d` tag instead of the `h` tag. They are expected to 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).
 
 - *group metadata* (`kind:39000`) (optional)
 
 This event defines the metadata for the group -- basically how clients should display it. It must be generated and signed by the relay in which is found. Relays shouldn't accept these events if they're signed by anyone else.
 
 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.
 
+When this event is not found, clients may still connect to the group, but treat it as having a different status, `unmanaged`,
+
 ```jsonc
 {
   "kind": 39000,
@@ -194,7 +238,9 @@ The list of capabilities, as defined by this NIP, for now, is the following:
 
 Similar to *group admins*, this event is supposed to be generated by relays that host the group.
 
-It's a NIP-51-like list of pubkeys that are members of the group. Relays might choose to not to publish this information or to restrict what pubkeys can fetch it.
+It's a list of pubkeys that are members of the group. Relays might choose to not to publish this information or to restrict what pubkeys can fetch it.
+
+Clients should not assume this will always be present or that it will contain a full list of members, as relays may opt to not publish it or publish a shortened version.
 
 ```json
 {
@@ -209,6 +255,20 @@ It's a NIP-51-like list of pubkeys that are members of the group. Relays might c
 }
 ```
 
-## Storing the list of groups a user belongs to
+## Implementation quirks
+
+### Checking your own membership in a group
+
+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.
+
+### Adding yourself to a group
+
+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.
+
+### Storing your list of groups
+
+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.
+
+### Using `unmanaged` relays
 
-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.
+To prevent event leakage, replay and confusion, 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.