nips/29.md

NIP-29

Simple Group Chat

draft optional author:fiatjaf author:ismyhc depends:33 depends:27 depends:11 depends:42

This NIP defines a model for group chat that relies on relays as ultimate sources of authority. Clients can connect to multiple relays and interact with different groups in each of these relays. A group can live in more than one relay or migrate between relays, but for practical purposes it is expected to rely on a single relay for as long as that is working well. This approach minimizes bandwidth consumption and computation costs and ensures the group can have fine-grained permissions and other niceties commonly expected from any group chat platforms without putting a huge amount of overhead on clients. The fundamental assumption here is that censorship is not a big concern for this kind of application.

Each group has an identifier, which is used as the d tag (see NIP-33) in events that hold group metadata. The default top-level group in a relay is identified by "/", with subgroups added after the slash and even deeper subgroups separated by other slashes. The imagined user flow for opening a group is to type a hostname with an optional path suffix. For example, if the user types pizza.com/ that goes to the top-level group at the wss://pizza.com relay. If the user types pizza.com/flavors that goes to the group "flavors" on the wss://pizza.com relay.

The entire metadata of the group (kinds 39000-3900x) must only be signed by the relay main pubkey given by the "pubkey" field in the relay's NIP-11 response. Other metadata events not signed by that public key must be ignored by clients. Upon opening a group, the chat client is supposed to fetch (or use locally cached values) these metadata events in order to render the group details, and then fetch the messages (kind:9).

Event definitions

• chat message (kind:9)

This is the basic unit of a message sent to a group.

It must commit in the g tag to the subgroup path and also to the relay hostname (in order to prevent these events from being sent to other relays and groups out of context and cause confusion).

e and p tags can also be used to signal an immediate reply to another message on the group or to call for the attention of some other group user.

When inserting references -- in the body of the text -- to users, other messages (quotes) and to other Nostr events that outside of the group must be made following the NIP-27 pattern (nostr:nevent1...).

  "kind": 9,
  "content": "hello my friends lovers of pizza",
  "tags": [
    ["g", "/flavors", "pizza.com"]
  ]
  ...

• 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 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.

{
  "kind": 39000,
  "content": "a nip-29 chat group for debating pizza flavors and other topics",
  "tags": [
    ["d", "/flavors"],
    ["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-message
• ban-user

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

• moderation event (kind:39002) (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.

{
  "kind": 9000,
  "content": "action description and/or reason",
  "tags": [
    ["g", "/flavors", "pizza.com"],
    ["action", "add-user", "<pubkey-to-add>"],
    ["action", "ban-user", "<pubkey-to-ban>"],
    ["action", "delete-message", "<event-id-to-delete>"],
    ["action", "edit-metadata", "<field-name>", "<field-value>"],
  ]
}