diff --git a/43.md b/43.md new file mode 100644 index 00000000..c46ce31b --- /dev/null +++ b/43.md @@ -0,0 +1,142 @@ +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](./11.md) document. + +The following tags are required: + +- A [NIP 70](./70.md) `-` 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: + +```jsonc +{ + "kind": 13534, + "pubkey": "", + "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](./11.md) document. + +The following tags are required: + +- A [NIP 70](./70.md) `-` tag +- A `p` tag indicating the member's hex pubkey + +Example: + +```jsonc +{ + "kind": 8000, + "pubkey": "", + "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](./11.md) document. + +The following tags are required: + +- A [NIP 70](./70.md) `-` tag +- A `p` tag indicating the member's hex pubkey + +Example: + +```jsonc +{ + "kind": 8001, + "pubkey": "", + "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. + +```jsonc +{ + "kind": 28934, + "pubkey": "", + "tags": [ + ["-"], + ["claim", ""] + ], + // ...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", , false, "restricted: that invite code is expired."] +["OK", , false, "restricted: that is an invalid invite code."] +["OK", , true, "duplicate: you are already a member of this relay."] +["OK", , 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](./11.md) document. + +```jsonc +{ + "kind": 28935, + "pubkey": "", + "tags": [ + ["-"], + ["claim", ""], + ], + // ...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](./70.md) `-` tag. + +```jsonc +{ + "kind": 28936, + "tags": [["-"]], + // ...other fields +} +``` + +Relays SHOULD update their `kind 13534` member list and MAY publish a `kind 8001` "remove member" event.