NIP-43

Relay Access Metadata and Requests

draft optional relay

This NIP defines a way for relays to advertise membership lists, and for clients to request admission to relays on behalf of users.

Role Definitions

Relays MAY publish a kind 33534 event which defines a role which may be assigned to members. This event MUST be signed by the pubkey specified in the self field of the relay’s NIP 11 document.

The following tags are required:

• A NIP 70 - tag
• The event’s d tag defines the role id.

The following tags are optional:

• label - a label for the role.
• description - a description of the role.
• color - a hue value from 0 to 360 for the role.
• order - a order integer for the role (for client display only).

{
  "kind": 33534,
  "pubkey": "<nip11.self>",
  "tags": [
    ["-"],
    ["d", "28b7e50f"],
    ["label", "king"],
    ["description", "ruler of the relay"],
    ["color", "37"],
    ["order", "1"],
  ],
  // ...other fields
}

Relays MAY treat members with a given role differently in terms of relay access policies, but no mechanism for introspection is defined at this time.

Membership Lists

Relays MAY publish a kind 13534 event which indicates pubkeys that have access to a given relay. This event MUST be signed by the pubkey specified in the self field of the relay’s NIP 11 document.

The following tags are required:

• A NIP 70 - tag
• A member tag containing a hex pubkey should be included for each member. Assigned roles may be included as subsequent arguments.

This list should not be considered exhaustive or authoritative. To determine membership, both a kind 13534 event by the relay, and a kind 10010 event by the member should be consulted.

Example:

{
  "kind": 13534,
  "pubkey": "<nip11.self>",
  "tags": [
    ["-"],
    ["member", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"],
    ["member", "ee1d336e13779e4d4c527b988429d96de16088f958cbf6c074676ac9cfd9c958", "28b7e50f"]
  ],
  // ...other fields
}

Add User

Relays MAY publish a kind 8000 event when a member is added to the relay. This event MUST be signed by the pubkey specified in the self field of the relay’s NIP 11 document.

The following tags are required:

• A NIP 70 - tag
• A p tag indicating the member’s hex pubkey

Example:

{
  "kind": 8000,
  "pubkey": "<nip11.self>",
  "tags": [
    ["-"],
    ["p", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"]
  ],
  // ...other fields
}

Remove User

Relays MAY publish a kind 8001 event when a member is removed from the relay. This event MUST be signed by the pubkey specified in the self field of the relay’s NIP 11 document.

The following tags are required:

• A NIP 70 - tag
• A p tag indicating the member’s hex pubkey

Example:

{
  "kind": 8001,
  "pubkey": "<nip11.self>",
  "tags": [
    ["-"],
    ["p", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"]
  ],
  // ...other fields
}

Join Request

A user MAY send a kind 28934 to a relay in order to request admission. It MUST have a claim tag containing an invite code. The event’s created_at MUST be now, plus or minus a few minutes.

{
  "kind": 28934,
  "pubkey": "<user pubkey>",
  "tags": [
    ["-"],
    ["claim", "<invite code>"]
  ],
  // ...other fields
}

Upon receiving a claim, a relay MUST notify the client as to what the status of the claim is using an OK message. Failed claims SHOULD use the same standard "restricted: " prefix specified by NIP 42.

Relays SHOULD update their kind 13534 member list and MAY publish a kind 8000 “add member” event.

Some examples:

["OK", <event-id>, false, "restricted: that invite code is expired."]
["OK", <event-id>, false, "restricted: that is an invalid invite code."]
["OK", <event-id>, true, "duplicate: you are already a member of this relay."]
["OK", <event-id>, true, "info: welcome to wss://relay.bunk.skunk!"]

Invite Request

Users may request a claim string from a relay by making a request for kind 28935 events. This event MUST be signed by the pubkey specified in the self field of the relay’s NIP 11 document.

{
  "kind": 28935,
  "pubkey": "<nip11.self>",
  "tags": [
    ["-"],
    ["claim", "<invite code>"],
  ],
  // ...other fields
}

Note that these events are in the ephemeral range, which means relays must explicitly opt-in to this behavior by generating claims on the fly when requested. This allows relays to improve security by issuing a different claim for each request, only issuing claims to certain users, or expiring claims.

Leave Request

A user MAY send a kind 28936 to a relay in order to request that their access be revoked. The event’s created_at MUST be now, plus or minus a few minutes. This event MUST include a NIP 70 - tag.

{
  "kind": 28936,
  "tags": [["-"]],
  // ...other fields
}

Relays SHOULD update their kind 13534 member list and MAY publish a kind 8001 “remove member” event.

Implementation

Clients MUST only request kind 28935 events from and send kind 28934 events to relays which include this NIP in the supported_nips section of its NIP 11 relay information document.