Merge 7198ecc52e456d96e73850de522b78d21a2441d5 into 0619f370bca3485bb9c5870bc2defa03c7c3d10e

86.md

@@ -17,7 +17,7 @@ When a relay receives an HTTP(s) request with a `Content-Type` header of `applic
 }
 ```
 
-Then it should return a response in the format
+Then it should return a response in the format:
 
 ```json
 {
@@ -31,60 +31,116 @@ This is the list of **methods** that may be supported:
 * `supportedmethods`:
   - params: `[]`
   - result: `["<method-name>", "<method-name>", ...]` (an array with the names of all the other supported methods)
-* `banpubkey`:
-  - params: `["<32-byte-hex-public-key>", "<optional-reason>"]`
-  - result: `true` (a boolean always set to `true`)
-* `listbannedpubkeys`:
+  - This lists the methods that the relay supports.
+* `stats`:
   - params: `[]`
-  - result: `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
-* `allowpubkey`:
-  - params: `["<32-byte-hex-public-key>", "<optional-reason>"]`
-  - result: `true` (a boolean always set to `true`)
-* `listallowedpubkeys`:
-  - params: `[]`
-  - result: `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
-* `listeventsneedingmoderation`:
-  - params: `[]`
-  - result: `[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}]`, an array of objects
-* `allowevent`:
-  - params: `["<32-byte-hex-event-id>", "<optional-reason>"]`
-  - result: `true` (a boolean always set to `true`)
-* `banevent`:
-  - params: `["<32-byte-hex-event-id>", "<optional-reason>"]`
-  - result: `true` (a boolean always set to `true`)
-* `listbannedevents`:
-  - params: `[]`
-  - result: `[{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - result: `{"x": "y"}` (an array with various statistics and their values)
+  - This lists various statistics from the server to be displayed. The particular statistics are not defined by this NIP.
 * `changerelayname`:
   - params: `["<new-name>"]`
   - result: `true` (a boolean always set to `true`)
+  - This changes the name of the relay in the NIP-11 output
 * `changerelaydescription`:
   - params: `["<new-description>"]`
   - result: `true` (a boolean always set to `true`)
+  - This changes the description of the relay in the NIP-11 output
 * `changerelayicon`:
   - params: `["<new-icon-url>"]`
   - result: `true` (a boolean always set to `true`)
-* `allowkind`:
-  - params: `[<kind-number>]`
+  - This changes the icon of the relay in the NIP-11 output
+* `banpubkey`:
+  - params: `["<32-byte-hex-public-key>", "<optional-reason>"]`
   - result: `true` (a boolean always set to `true`)
+  - This adds the pubkey to a banned pubkey list (and clears from any allowed pubkeys list)
+* `allowpubkey`:
+  - params: `["<32-byte-hex-public-key>", "<optional-reason>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This puts the pubkey onto an allowed pubkey list (and clears from any banned pubkey list).
+* `clearpubkey`:
+  - params: `["<32-byte-hex-public-key>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This removes the pubkey from both allowed and banned lists.
+* `listbannedpubkeys`:
+  - params: `[]`
+  - result: `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - This lists pubkeys that are on the banned pubkey list
+* `listallowedpubkeys`:
+  - params: `[]`
+  - result: `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - This lists pubkeys that are on the allowed pubkey list
+* `banevent`:
+  - params: `["<32-byte-hex-event-id>", "<optional-reason>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This adds the event to a banned event list (and clears from any allowed event list). If in the moderation queue, it is removed from that queue.
+* `allowevent`:
+  - params: `["<32-byte-hex-event-id>", "<optional-reason>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This adds the event to an allowed event list (and clears from any banned event list). If in the moderation queue, it is removed from that queue.
+* `clearevent`:
+  - params: `["<32-byte-hex-event-id>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This removes the event from any lists (banned or allowed).
+* `listbannedevents`:
+  - params: `[]`
+  - result: `[{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - This lists all events on the banned event list.
+* `fetchbannedevents`:
+  - params: `[]`
+  - result: `[<serialized-event-as-string>, ...]`, an array of serialized events
+  - This returns all events on the banned event list (if not deleted).
+* `listallowedevents`:
+  - params: `[]`
+  - result: `[{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - This lists all events that are on the allowed event list.
+* `removeevent`:
+  - params: `["<32-byte-hex-event-id>"]`
+  - result: `true` (a boolean always set to `true`)
+  - This removes the event from the relay.
+  - NOTE: `banevent` may not remove the event for relays that allow unbanning later.
+* `listeventsneedingmoderation`:
+  - params: `[]`
+  - result: `[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}]`, an array of objects
+  - This lists events that are in a moderation queue.
 * `disallowkind`:
   - params: `[<kind-number>]`
   - result: `true` (a boolean always set to `true`)
+  - This adds the kind to a disallowed kind list (and clears from any allowed kinds list).
+* `allowkind`:
+  - params: `[<kind-number>]`
+  - result: `true` (a boolean always set to `true`)
+  - This adds the kind to an allowed kind list (and clears from any disallowed kinds list).
+* `listdisallowedkinds`:
+  - params: `[]`
+  - result: `[<kind-number>, ...]`, an array of numbers
+  - This lists the kinds on the disallowed kinds list
 * `listallowedkinds`:
   - params: `[]`
   - result: `[<kind-number>, ...]`, an array of numbers
+  - This lists the kinds on the allowed kinds list
 * `blockip`:
   - params: `["<ip-address>", "<optional-reason>"]`
   - result: `true` (a boolean always set to `true`)
+  - This adds the IP to a banned IP list, meaning future connections from this IP are blocked.
 * `unblockip`:
   - params: `["<ip-address>"]`
   - result: `true` (a boolean always set to `true`)
+  - This removes the IP from the banned IP list.
 * `listblockedips`:
   - params: `[]`
   - result: `[{"ip": "<ip-address>", "reason": "<optional-reason>"}, ...]`, an array of objects
+  - This lists IPs in the banned IP list.
+* `grantrole`:
+  - params: `[<rolename>, <pubkey>]`
+  - result: `true` (a boolean always set to `true`)
+* `revokerole`:
+  - params: `[<rolename>, <pubkey>]`
+  - result: `true` (a boolean always set to `true`)
+* `listrole`:
+  - params: `[<rolename>]`
+  - result: `[<pubkey>, ...]`
 
 ### Authorization
 
-The request must contain an `Authorization` header with a valid [NIP-98](./98.md) event, except the `payload` tag is required. The `u` tag is the relay URL.
+The request MUST contain an `Authorization` header with a valid [NIP-98](./98.md) event, except the `payload` tag is required. The `u` tag is the relay URL.
 
-If `Authorization` is not provided or is invalid, the endpoint should return a 401 response.
+If `Authorization` is not provided or is invalid, the endpoint should return a response with a 401 status code.