nips/122.md

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` and `a` tags referring to the requested events  by ID or addresses, respectively.

**Public Request For Events** are ephemeral events with `kind:21122` used to ask for missing events from any user. One or more `e` or `a` tags refer to the requested events by ID or address. The `content` field is unused and left as an empty string.

##### Example (Direct Request):

```js
const events = JSON.stringify([
  ['e','<requested-event-id>', '<preferred relay URL>'],
  ['a', '<event-address>', '<preferred relay URL>']
]);
const encrypted_content = nip44_encrypt(events, ...);
```

```json
{
  "kind": 21122,
  "content": "<encrypted_content>"
}
```

##### Example (Public Request):

```json
{
  "kind": 21122,
  "tags": [
    ["e", "<missing-event-id>", "<optional preferred relay URL>"],
    ["a", "<missing-event-address>", "<optional preferred relay URL>"]
  ],
  "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 SHOULD send back the actual requested events to the relay from which it received the request when relay URL hints are missing or when publishing to the relay hint is not possible.
- Clients SHOULD NOT respond with any ephemeral events they may have in store including the original Request For Events nor issue a new Request For Events for the same event IDs.
- Clients MAY respond to requests from users they follow or that belong to their Web of Trust.
- Clients MAY respond to a fraction of requests (e.g. 5% sample rate) and/or adhere to data caps if they have limited resources (i.e. mobile clients).
- Clients MAY reject requests without sufficient Proof-of-Work. (e.g. [NIP-13](13.md))

### Guidelines for Relays

- Relays SHOULD implement rate limits to prevent denial-of-service (DoS) attacks.
- Relays MAY forward public requests to a fraction of connected clients (e.g. 10% sample rate).
- Relays MAY reject public request for events if at least one of the requested events is already in their store.
- Relays MAY reject request for events that have insufficient Proof-of-Work.