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 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):

const events = JSON.stringify([['e','<requested-event-id>'], ['e', '<another-event-id>']])
const encrypted_content = nip44_encrypt(events, ...);

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

Example (Public Request):

{
  "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.