add request for events #NIP-122

Signed-off-by: Ricardo Arturo Cabral Mejía <me@ricardocabral.io>

122.md

@@ -0,0 +1,70 @@
+NIP-122
+=======
+
+Request for Events
+------------------
+
+`draft` `optional`
+
+### Abstract
+
+This NIP defines `kind:21122`: an ephemeral event used to express interest on specific events to other clients. Request for Events can be made directly to specific users or broadcasted to multiple users.
+
+### Motivation
+
+Sometimes it's not possible to access referenced events because they are missing locally, connected relays don't have them, the user chooses not to follow relay hints or otherwise is not able to connect beyond their original list of relays for various reasons (e.g. privacy, internet block).
+Other clients may have a copy of the missing event and are willing to share it, but are unaware of any other interested parties.
+A mechanism to request other clients for missing events will help interested clients obtain the necessary events from others, improving the overall user experience, data availability, and censorship resistance.
+
+#### Specification
+
+**Direct Request For Events** are ephemeral events with `kind:21122` used to ask for events from specific users. The `content` field is a NIP-44 encrypted list of `e` tags referring to the requested events.
+
+**Public Request For Events** are ephemeral events with `kind:21122` used to ask for missing events from any user. One or more `e` tags refer to the requested events. The `content` field is unused and left as an empty string.
+
+##### Example (Direct Request):
+
+```js
+const events = JSON.stringify([['e','<requested-event-id>'], ['e', '<another-event-id>']])
+const encrypted_content = nip44_encrypt(events, ...);
+```
+
+```json
+{
+  "kind": 21122,
+  "content": "<encrypted_content>"
+}
+```
+
+##### Example (Public Request):
+
+```json
+{
+  "kind": 21122,
+  "tags": [
+    ["e", "<missing-event-id>"],
+    ["e", "<another-event-id>"]
+  ],
+  "content": "",
+  "sig": "<sig>"
+}
+```
+
+### Guidelines for Requesting Clients
+
+- Clients MAY send requests to connected relays when an event is missing.
+- Clients SHOULD limit the frequency of requests to avoid spamming the network.
+- Clients MUST subscribe  prior to sending the request for events, wait for EOSE and filter out any received events from the list of missing events.
+
+### Guidelines for Responding Clients
+
+- Clients receiving a `kind:21122` event SHOULD send back the actual requested events to the relay from which it received the request.
+- Clients SHOULD NOT respond with any ephemeral events they may have in store.
+- Clients SHOULD NOT resend the original Request For Events or issue a new Request For Events for the same event IDs.
+- Clients MAY respond to requests from users they follow/trust.
+- Clients MAY respond to a fraction of requests (e.g. 10% sample rate) and/or adhere to data caps if they have limited resources (i.e. mobile clients).
+
+### Guidelines for Relays
+
+- Relays MAY reject public request for events if at least one of the requested events is already in their store.
+- Relays SHOULD implement rate limits to prevent denial-of-service (DoS) attacks.

README.md

@@ -86,6 +86,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 - [NIP-96: HTTP File Storage Integration](96.md)
 - [NIP-98: HTTP Auth](98.md)
 - [NIP-99: Classified Listings](99.md)
+- [NIP-122: Request for Events](122.md)
 
 ## Event Kinds
 | kind          | description                | NIP                      |
@@ -152,6 +153,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 | `10096`       | File storage server list   | [96](96.md)              |
 | `13194`       | Wallet Info                | [47](47.md)              |
 | `21000`       | Lightning Pub RPC          | [Lightning.Pub][lnpub]   |
+| `21122`       | Request For Events         | [122](122.md)            |
 | `22242`       | Client Authentication      | [42](42.md)              |
 | `23194`       | Wallet Request             | [47](47.md)              |
 | `23195`       | Wallet Response            | [47](47.md)              |