nips/43.md

NIP-43

Relay Access Metadata and Requests

draft optional

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

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

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"]
  ],
  // ...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": "<nip11.self>",
  "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.