1NIP-432======34Relay Access Metadata and Requests5----------------------------------67`draft` `optional` `relay`89This NIP defines a way for relays to advertise membership lists, and for clients to request admission to relays on behalf of users.1011## Role Definitions1213Relays 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](./11.md) document.1415The following tags are required:1617- A [NIP 70](./70.md) `-` tag18- The event's `d` tag defines the role id.1920The following tags are optional:2122- `label` - a label for the role.23- `description` - a description of the role.24- `color` - a `hue` value from `0` to `360` for the role.25- `order` - a `order` integer for the role (for client display only).2627```yaml28{29 "kind": 33534,30 "pubkey": "<nip11.self>",31 "tags": [32 ["-"],33 ["d", "28b7e50f"],34 ["label", "king"],35 ["description", "ruler of the relay"],36 ["color", "37"],37 ["order", "1"],38 ],39 // ...other fields40}41```4243Relays MAY treat members with a given role differently in terms of relay access policies, but no mechanism for introspection is defined at this time.4445## Membership Lists4647Relays 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](./11.md) document.4849The following tags are required:5051- A [NIP 70](./70.md) `-` tag52- A `member` tag containing a hex pubkey should be included for each member. Assigned roles may be included as subsequent arguments.5354This 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.5556Example:5758```yaml59{60 "kind": 13534,61 "pubkey": "<nip11.self>",62 "tags": [63 ["-"],64 ["member", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"],65 ["member", "ee1d336e13779e4d4c527b988429d96de16088f958cbf6c074676ac9cfd9c958", "28b7e50f"]66 ],67 // ...other fields68}69```7071## Add User7273Relays 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](./11.md) document.7475The following tags are required:7677- A [NIP 70](./70.md) `-` tag78- A `p` tag indicating the member's hex pubkey7980Example:8182```yaml83{84 "kind": 8000,85 "pubkey": "<nip11.self>",86 "tags": [87 ["-"],88 ["p", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"]89 ],90 // ...other fields91}92```9394## Remove User9596Relays 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](./11.md) document.9798The following tags are required:99100- A [NIP 70](./70.md) `-` tag101- A `p` tag indicating the member's hex pubkey102103Example:104105```yaml106{107 "kind": 8001,108 "pubkey": "<nip11.self>",109 "tags": [110 ["-"],111 ["p", "c308e1f882c1f1dff2a43d4294239ddeec04e575f2d1aad1fa21ea7684e61fb5"]112 ],113 // ...other fields114}115```116117## Join Request118119A 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.120121```yaml122{123 "kind": 28934,124 "pubkey": "<user pubkey>",125 "tags": [126 ["-"],127 ["claim", "<invite code>"]128 ],129 // ...other fields130}131```132133Upon 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.134135Relays SHOULD update their `kind 13534` member list and MAY publish a `kind 8000` "add member" event.136137Some examples:138139```140["OK", <event-id>, false, "restricted: that invite code is expired."]141["OK", <event-id>, false, "restricted: that is an invalid invite code."]142["OK", <event-id>, true, "duplicate: you are already a member of this relay."]143["OK", <event-id>, true, "info: welcome to wss://relay.bunk.skunk!"]144```145146## Invite Request147148Users 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](./11.md) document.149150```yaml151{152 "kind": 28935,153 "pubkey": "<nip11.self>",154 "tags": [155 ["-"],156 ["claim", "<invite code>"],157 ],158 // ...other fields159}160```161162Note 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.163164## Leave Request165166A 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](./70.md) `-` tag.167168```yaml169{170 "kind": 28936,171 "tags": [["-"]],172 // ...other fields173}174```175176Relays SHOULD update their `kind 13534` member list and MAY publish a `kind 8001` "remove member" event.177178## Implementation179180Clients 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](./11.md) relay information document.