NIP-29 ====== Relay-based Groups ------------------ `draft` `optional` This NIP defines a standard for the simplest version of groups that can work. There are two goals of this NIP: - Define some conventions for how to use standard relays as groups. - Introduces a mechanism for splitting relay content into multiple rooms. # Relays as groups ## Minus Tag To ensure all messages have the appropriate context and/or are not replicated to other relays, a [NIP 70](70.md) `-` tag SHOULD be used when posting to a group relay (if support is indicated per [NIP 11](11.md)). "Follower" relays intended to back up group state MAY bypass this restriction. ## Relay Migration If a group needs to be moved from one relay to another, this can be done by publishing a `kind xxxxx`, with a `from` tag indicating the current relay, and a `to` tag indicating the next relay: ```json { "kind": "xxxxx", "tags": [ ["from", "wss://relay.dead.com/"], ["to", "wss://relay.live.com/"], ], } ``` These events SHOULD be published to the group's current relay, and MAY be published more broadly if more durability is desired (for example in the case where the relay goes down permanently before the migration is published). Anyone MAY publish these events, but end-users SHOULD be given ultimate discretion as to whether the migration is valid, based on group membership or admin status. ## Policy Policy based on which NIPs/kinds are supported by a given relay should be advertised as defined in [NIP 11](11.md). ## Access Control Access control (both read and write) SHOULD be implemented using [NIP 42](42.md) AUTH. Access control policy MAY be advertised (but should not be relied upon by clients) using the `auth_required` and `restricted_writes` keys in the `limitations` section of the relay's NIP 11 document. After authentication, users MAY request access using a `ACCESS` message sent ONLY to the relay in question. Relay access requests MUST have a `claim` containing an arbitrary string and an optional message to the relay admin. ```json ["ACCESS", "", ""] ``` Users may also send an empty `ACCESS` message to query their current access: ```json ["ACCESS"] ``` In either case, a relay MUST respond with an `ACCESS` message with a list of user permissions, in addition to the standard `OK` message. Some examples: ```json ["ACCESS"] ["ACCESS", "read"] ["ACCESS", "read", "write"] ``` Valid permissions are `read` and `write`. ## Moderation Relay-based groups have a single admin, identified by the `pubkey` listed in the relay's [NIP 11](11.md) document. Any relay member MAY publish a `kind 1984` report to the relay (including a `-` tag if desired/supported). These reports MAY be used by the relay admin to delete events or ban users, or by clients to implement any moderation algorithm desired. Admins or moderators may also choose to escalate reports without banning content by publishing their own `kind 1984` event with the same tags. ## Membership Users MAY track their own group memberships using a [NIP 51](51.md) kind `1xxxx` event. Tags MAY be either public or encrypted with [NIP 44](44.md), depending on user/client preference. Membership lists can contain two types of tags: relay memberships (indicated by `r`), and room memberships (indicated by `h`, and including the relay url): ```json { "kind": "1xxxx", "tags": [ ["r", "wss://relay.example.com/"], ["r", "wss://relay.other.com/"], ["h", "Marlon Brando", "wss://relay.other.com/"], ["h", "James Dean", "wss://relay.other.com/"] ], } ``` ## Member lists A `kind 3xxxx` event is a member list. Anyone MAY publish one, but clients SHOULD only trust lists published by the relay's own pubkey, or by moderators mentioned in the relay's member list event. Lists published by regular members MAY be used for convenience in building member list indexes, but should not be trusted or relied upon. Member lists should have the following tags: - A `d` tag is required so that member lists can be split into pieces, but is semantically meaningless. - An `r` tag indicates the relay's url. - A `p` tag indicates a member and whether they are a moderator. ```json { "kind": "3xxxx", "tags": [ ["d", "9ce3f91a937"], ["r", "wss://relay.example.com/"], ["p", "", ""] ["p", "", "", "moderator"] ], } ``` These events SHOULD be published only to the group relay, and use a `-` tag if supported. ## Content retention Relays are not obligated to retain any content. Relays MAY choose not to support any part of this NIP, for example refusing host member lists in order to protect member privacy. # Rooms Rooms are defined by an arbitrary string containing any text. Names SHOULD be human-readable, and less than 30 characters. Anyone MAY publish `kind xxxxx` index events containing `h` tags and the relay on which they exist. This is only a convenience for helping clients build room lists, and shouldn't be relied upon as being accurate or complete. `h` tags MUST indicate what type the room is. Types of rooms and their corresponding event kinds are defined below. ```json { "kind": "xxxxx", "tags": [ ["h", "salamanders", "wss://relay.froglovers.com", "chat"], ["h", "frogs", "wss://relay.froglovers.com", "chat"], ["h", "frogs", "wss://relay.catlovers.com", "forum"] ] } ``` Events posted to rooms MUST include a simple `h` tag matching the room of the form `["h", ""]`. An empty string MAY be used to indicate the "global" namespace. ## Chat Two kinds of events MAY be posted to a `chat` room: - `kind xxx` events are chat root events, and MUST only be used for top-level messages sent to the room. - `kind xxx` events are chat reply events, and MUST only be used for replies to messages in the same room. In both cases, conventions for `kind 1` notes outlined in [NIP 10](10.md) and [NIP 18](18.md) should be followed when constructing chat events. ## Forums Two kinds of events MAY be posted to a `forum` room: - `kind xxx` events are root thread events, and MUST only be used for the first post in a thread. - `kind xxx` events are thread reply events, and MUST only be used to reply to a _root_ thread event. In both cases, conventions for `kind 1` notes outlined in [NIP 10](10.md) and [NIP 18](18.md) should be followed when constructing chat events.