nips/29.md

NIP-29
======

Relay-based Groups
------------------

`draft` `optional` `author:fiatjaf`

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.

## Timeline references

In order to not be used out of context, events sent to these groups may contain a reference to previous events seen from the same relay.

## Trimmed signatures

For private groups that are not intended to be read by external users, relays must strip the signatures before sending the events to clients.

### Event definitions

- *text note* (`kind:11`)

This is the basic unit of a text note sent to a group.

It must commit in the `h` tag to the subgroup path and may also commit to up to the last 3 events of the same kind seen in the group.

```js
  "kind": 11,
  "content": "hello my friends lovers of pizza",
  "tags": [
    ["h", "<group-id>"],
    ["previous", "<event-id>", "<event-id>", ...]
  ]
  ...
```

- *chat message* (`kind:9`)

Similar to kind 11, this is the basic unit of a chat message sent to a group.

```js
  "kind": 9,
  "content": "hello my friends lovers of pizza",
  "tags": [
    ["h", "<group-id>"],
    ["previous", "<event-id>", "<event-id>", ...]
  ]
  ...
```

- *group metadata* (`kind:39000`) (optional)

If this event does not exist, the group should be identified in the client UI by its identifier (i.e. "/flavors" or "pizza.com/flavors"). All tags are optional. Having the `"private"` tag means the group cannot be read and relays will use [NIP-42](42.md) `AUTH` messages to control who can read from it. The `"closed"` tag means the group can be read by anyone but only explicitly whitelisted pubkeys are allowed to post, again these enforcements happen at the relay level.

```js
{
  "kind": 39000,
  "content": "a nip-29 chat group for debating pizza flavors and other topics",
  "tags": [
    ["d", "<group-id>"],
    ["name", "Pizza Lovers"],
    ["picture", "https://pizza.com/pizza.png"],
    ["private"],
    ["closed"]
  ]
  ...
}
```

- *group admins* (`kind:39001`) (optional)

Each admin gets a label that is only used for display purposes, and a list of permissions it has are listed afterwards. These permissions can inform client building UI, but ultimately are evaluated by the relay in order to become effective.

The list of capabilities, as defined by this NIP, for now, is the following:

- `add-user`
- `edit-metadata`
- `delete-event`
- `ban-user`
- `add-permission`
- `remove-permission`

```js
{
  "kind": 39001,
  "content": "list of admins for the pizza lovers group",
  "tags": [
    ["d", "<group-id>"],
    ["<pubkey1-as-hex>", "admin", "add-user", "edit-metadata", "delete-event", "ban-user"],
    ["<pubkey2-as-hex>", "mod", "add-user", "delete-event"]
  ]
  ...
}
```

- *moderation event* (`kind:9000`) (optional)

An event sent from a client to the relay in order to accomplish a moderation action. The relay should read this event and act on it if the user sending the event has the required permissions and the date is close to the current date. The relay may discard the event after taking action or keep it as a way to expose a moderation log. This is similar to the `kind:9` event in its structure.

```js
{
  "kind": 9000,
  "content": "action description and/or reason",
  "tags": [
    ["g", "<group-id>"],
    ["action", "add-user", "<pubkey-to-add>"],
    ["action", "ban-user", "<pubkey-to-ban>"],
    ["action", "edit-metadata", "<field-name>", "<field-value>"],
    ["action", "add-permission", "<pubkey>", "<permission>"],
    ["action", "remove-permission", "<pubkey>", "<permission>"],
  ]
}
```