nip-86: updating methods, adding new ones.

2025-02-23 13:49:00 +00:00 · 2025-02-01 21:58:27 +00:00 · 2025-02-01 21:58:27 +00:00 · 8e5d19ecaf
commit 8e5d19ecaf
parent e09f6dad27
1 changed files with 376 additions and 58 deletions
--- a/86.md
+++ b/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 below format:

 ```json
 {
@ -26,65 +26,383 @@ Then it should return a response in the format
 }
 ```

-This is the list of **methods** that may be supported:
+## Standard Methods

-* `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`:
-  - 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
-* `changerelayname`:
-  - params: `["<new-name>"]`
-  - result: `true` (a boolean always set to `true`)
-* `changerelaydescription`:
-  - params: `["<new-description>"]`
-  - result: `true` (a boolean always set to `true`)
-* `changerelayicon`:
-  - params: `["<new-icon-url>"]`
-  - result: `true` (a boolean always set to `true`)
-* `allowkind`:
-  - params: `[<kind-number>]`
-  - result: `true` (a boolean always set to `true`)
-* `disallowkind`:
-  - params: `[<kind-number>]`
-  - result: `true` (a boolean always set to `true`)
-* `listallowedkinds`:
-  - params: `[]`
-  - result: `[<kind-number>, ...]`, an array of numbers
-* `blockip`:
-  - params: `["<ip-address>", "<optional-reason>"]`
-  - result: `true` (a boolean always set to `true`)
-* `unblockip`:
-  - params: `["<ip-address>"]`
-  - result: `true` (a boolean always set to `true`)
-* `listblockedips`:
-  - params: `[]`
-  - result: `[{"ip": "<ip-address>", "reason": "<optional-reason>"}, ...]`, an array of objects
+Here is a list of **methods** that MAY be supported:
+
+### System
+
+* Supported methods
+
+**name:** `supported_methods`
+
+**params:** `[]`
+
+**result:**
+
+```json
+["<method-name>", "<method-name>", /* rest of method names... */ ] 
+```
+
+---
+
+* Stats
+
+**name:** `stats`
+
+**params:** `[]`
+
+**result:**
+
+```jsonc
+[
+  {
+    "num_connections": <number>,
+    "uptime": <uptime-in-seconds>,
+    "bytes_received": <number>,
+    "bytes_sent": <number>,
+    "num_events": <number>,
+    "event_bytes": <number>,
+    "num_files": <number>,
+    "file_bytes": <number>
+    // and more...
+  }
+]
+```
+
+Extra fields MAY be sent from relay depending on implementation.
+
+---
+
+* Set NIP11
+
+**name:** `set_nip11`
+
+**params:** 
+
+```jsonc
+[
+  {
+    "name": "new name",
+    "description": "new description",
+    "icon": null // removes icon. 
+    // and more...
+  }
+]
+```
+
+**result:**
+
+```jsonc
+true
+```
+
+The provided input is a potentially incomplete json object of [NIP-11](./11.md) document. 
+Relay SHOULD replace provides fields with new ones, add non existing fields and remove fields set to null.
+
+---
+
+* List Events Needing Moderation
+
+**name:** `list_events_needing_moderation`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}]
+```
+
+Relay MAY return reported, muted profiles and similar events as result.
+
+* Write Policy
+
+* Ban pubkey
+
+**name:** `ban_pubkey`
+
+**params:** 
+
+```json
+["<32-byte-hex-public-key>", "<optional-reason>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+Relay MAY remove events sent by `pubkey` and prevent new events from them to be written.
+
+---
+
+* List Banned Pubkeys
+
+**name:** `list_banned_pubkeys`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, /* and more... */]
+```
+
+---
+
+* Allow Pubkey
+
+**name:** `allow_pubkey`
+
+**params:** 
+
+```json
+["<32-byte-hex-public-key>", "<optional-reason>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* List Allowed Pubkeys
+
+**name:** `list_allowed_pubkeys`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, /* and more... */]
+```
+
+---
+
+* Allow Event
+
+**name:** `allow_event`
+
+**params:** 
+
+```json
+["<32-byte-hex-event-id>", "<optional-reason>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* Ban Event
+
+**name:** `ban_event`
+
+**params:** 
+
+```json
+["<32-byte-hex-event-id>", "<optional-reason>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+Relay SHOULD delete and prevent re-broadcasting of event.
+
+---
+
+* List Banned Events
+
+**name:** `list_banned_events`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...]
+```
+
+---
+
+* Allow Kinds
+
+**name:** `allow_kinds`
+
+**params:** 
+
+```json
+[<kind-number>, <another-kind-number>, /* and more... */]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* Disallow Kinds
+
+**name:** `disallow_kinds`
+
+**params:** 
+
+```json
+[<kind-number>, <another-kind-number>, /* and more... */]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* List Disallowed Kinds
+
+**name:** `list_disallow_kinds`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[<kind-number>, <another-kind-number>, /* and more... */]
+```
+
+---
+
+* List Allowed Kinds
+
+**name:** `list_allowed_kinds`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[<kind-number>, <another-kind-number>, /* and more... */]
+```
+
+---
+
+* Block IP
+
+**name:** `block_ip`
+
+**params:** 
+
+```json
+["<ip-address>", "<optional-reason>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* Unblock IP
+
+**name:** `unblock_ip`
+
+**params:** 
+
+```json
+["<ip-address>"]
+```
+
+**result:**
+
+```json
+true
+```
+
+---
+
+* List Blocked IPs
+
+**name:** `list_blocked_ips`
+
+**params:** `[]`
+
+**result:**
+
+```json
+[{"ip": "<ip-address>", "reason": "<optional-reason>"}, /* and more... */]
+```
+
+### Access control
+
+---
+
+* Grant Admin
+
+**name:** `grant_admin`
+
+**params:** 
+
+```jsonc
+["<32-byte-hex-public-key>", {
+  "allowed_methods": [
+    "method-name",
+    // an array of method names.
+  ]
+}]
+```
+
+**result:**
+
+```json
+true
+```
+
+If admin right is already granted, allowed methods list must be rewritten.
+
+---
+
+* Revoke Admin
+
+**name:** `revoke_admin`
+
+
+**params:** 
+
+```jsonc
+["<32-byte-hex-public-key>", {
+  "disallowed_methods": [
+    "method-name",
+    // an array of method names.
+  ]
+}]
+```
+
+**result:**
+
+```json
+true
+```
+
+If resulting `allowed_methods` list for admin was empty, admin can be removed.

 ### 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 401 status code.