Kind 10002: Relay List Metadata

Overview

Relay List Metadata events (kind 10002) allow users to advertise their preferred relays for content discovery and distribution. This replaceable event kind serves as a standardized way to tell others where to find a user's content and where they expect to receive communications. By publishing this list, users help optimize the Nostr network by directing clients to connect only to relevant relays rather than broadcasting to all possible relays.

Specification

Property	Value
Kind Number	10002
Event Range	Replaceable
Defined in	NIP-65

Content Format

According to NIP-65, the content field is not used and should be empty.

Schema

"content": ""

Tags

Tag Name	Description	Format	Required
r	Relay URL with optional read/write flags	["r", "<url>", "<read-or-write-flag>"]	Yes

Client Behavior

Clients should:

1. When seeking events from a user:

   • Use the WRITE relays from the user's kind 10002 event
   • These are relays marked with "write" or no marker (both read/write)

2. When seeking events about a user (where they were tagged):

   • Use the READ relays from the user's kind 10002 event
   • These are relays marked with "read" or no marker (both read/write)

3. When broadcasting an event:

   • Send the event to the WRITE relays of the author
   • Send the event to all READ relays of each tagged user

4. For direct messages:

   • Only broadcast to the author's WRITE relays and the receiver's READ relays
   • This maintains maximum privacy

5. Additional recommendations:

   • Guide users to keep relay lists small (2-4 relays)
   • Spread a user's kind 10002 event to as many relays as viable for discovery
   • Deduplicate connections by normalizing relay URIs according to RFC 3986
   • Consider using other heuristics for a user's own client when fetching data

Relay Behavior

Relays should:

1. Handle kind 10002 events as normal replaceable events
2. Store these events to allow clients to discover users' relay preferences
3. If a relay signals support for NIP-65 in their NIP-11 document, it should accept kind 10002 events from a broad range of users, not only paying customers

Use Cases

• Informing followers where to find your content (outbox model)
• Indicating where you expect to receive replies or mentions
• Optimizing network traffic by directing it only to relevant relays
• Reducing broadcast redundancy and relay load
• Supporting more efficient message routing
• Enhancing privacy for direct messages
• Creating relay redundancy for content availability

Example

{
  "id": "bea38d044c8d6e4207de51ed6989fac855dd81f4dccbd2918a09802d8d53c428",
  "pubkey": "854043ae8f1f97430ca8c1f1a090bdde6488bd5115c7a45307a2a212750ae4cb",
  "created_at": 1699597889,
  "kind": 10002,
  "tags": [
    ["r", "wss://relay.damus.io"],
    ["r", "wss://relay.nostr.band", "read"],
    ["r", "wss://purplepag.es"],
    ["r", "wss://relay.snort.social", "write"],
    ["r", "wss://expensive-relay.example.com", "write"]
  ],
  "content": "",
  "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd"
}

Relay Flags

In the r tags, the read/write flags indicate the intended purpose:

• No flag: The relay is used for both reading and writing
• read: The relay is used by the user for reading content
• write: The relay is used by the user for writing content

Examples:

• ["r", "wss://example.com"] - Used for both reading and writing
• ["r", "wss://example.com", "read"] - Used for reading only
• ["r", "wss://example.com", "write"] - Used for writing only

The Outbox Model

NIP-65 implements what's known as the "outbox model" for Nostr, which:

1. Reduces centralization around popular relays
2. Decreases event duplication across relays
3. Allows users to directly connect to relevant relays for specific users
4. Makes message routing more efficient
5. Improves privacy, especially for direct messages

This model moves away from broadcasting to every popular relay toward a more targeted approach where events are only sent to relays actually used by the intended recipients.

References

• NIP-65: Relay List Metadata
• NIP-51: Lists
• NIP-11: Relay Information Document

Related Kinds

• Kind 10006: Blocked Relays - Relays clients should never connect to
• Kind 10007: Search Relays - Relays recommended for search queries
• Kind 10050: DM Relays - Relays for direct messages
• Kind 30002: Relay Sets - Categorized relay groups for different purposes

Notes

• This kind is specifically defined in NIP-65 but also mentioned in NIP-51
• The r tag format differs from other relay tags in the NIP-51 lists which use "relay" as the tag name
• This kind doesn't fully replace relay lists designed to configure a client's own relay usage
• Clients may use other relay lists (like kind 3) when kind 10002 can't be found
• This specification aims to reduce network load and improve efficiency across the Nostr network
• URI normalization should follow RFC 3986, including lowercasing the hostname and removing default ports