NIP-65: new kind 10102, add support for DM relays

65.md

@@ -6,59 +6,137 @@ Relay List Metadata
 
 `draft` `optional`
 
-Defines a replaceable event using `kind:10002` to advertise preferred relays for discovering a user's content and receiving fresh content from others.
+Defines two replaceable events to advertise preferred relays for discovering a user's content and receiving fresh content from others.
 
-The event MUST include a list of `r` tags with relay URIs and a `read` or `write` marker. Relays marked as `read` / `write` are called READ / WRITE relays, respectively. If the marker is omitted, the relay is used for both purposes.
+Relay Usages
+------------
+
+There are three defined usages for a relay:
+
+- `INBOX` relays are for events that the relay list owner will be reading, specifically watching for events that tag them. These do not include DMs (except in the deprecated form of relay list).
+
+- `OUTBOX` relays are for events that the relay list owner has authored and is publishing for public consumption.
+
+- `DIRECT MESSAGE` relays are like INBOX relays, except they are for reciept of Direct Messages (DMs) as they are considered more secure for this purpose by the relay list owner.
+
+
+### When to use which
+
+When posting events (except DMs):
+
+- Clients SHOULD post events to all of their client user's OUTBOX relays,
+- For each p-tag in a posted event, clients SHOULD post the event to at least some of the INBOX relays of the tagged person.
+
+When posting DMs:
+
+- Clients SHOULD post events to at least some (preferably all) of the the p-tag recipient's DM relays.
+- Clients SHOULD post a copy to their client user's own DM relays.
+- If a user has no DM relays, INBOX relays should be used instead.
+
+When seeking events from a user:
+
+- Clients SHOULD seek them from at least some of that user's OUTBOX relays.
+
+When seeking events about a client's user (where the user was tagged):
+
+- Clients SHOULD seek them from all of their user's INBOX relays.
+
+When seeking **DM**s for a client's user:
+
+- Clients SHOULD seek them from all of their user's DM and INBOX relays.
+
+In general, when interacting with a user's own relays, clients should interact with all of them (write to all OUTBOX relays, read from all INBOX and DM relays). When interacting with other user's relays, clients need only interact with a subset of them (read from some of their OUTBOX relays, write to some of their OUTBOX and DM relays).
+
+Relay List Event
+----------------
+
+`kind:10102` is a relay list event.
+
+This event SHOULD include `relay-usage` tags of the following form:
+
+```json
+["relay-usage", "<relay-url>", "<usage-flags>"]
+```
+
+`usage-flags` includes a sequence of letters, which of which MUST be one of the following:
+
+- `i` - This indicates the relay is used as the user's INBOX
+- `o` - This indicates the relay is used as the user's OUTBOX
+- `d` - This indicates the relay is used for the user's DIRECT MESSAGES
+
+`usage-flags` SHOULD not have duplicate letters. Clients should ignore any other letters found that they do not understand.
 
 The `.content` is not used.
 
+### Example:
+
 ```json
 {
-  "kind": 10002,
+  "kind": 10102,
   "tags": [
-    ["r", "wss://alicerelay.example.com"],
-    ["r", "wss://brando-relay.com"],
-    ["r", "wss://expensive-relay.example2.com", "write"],
-    ["r", "wss://nostr-relay.example.com", "read"]
+    ["relay-usage", "wss://alicerelay.example.com", "io"],
+    ["relay-usage", "wss://brando-relay.com", "io"],
+    ["relay-usage", "wss://expensive-relay.example2.com", "o"],
+    ["relay-usage", "wss://nostr-relay.example.com", "i"],
+    ["relay-usage", "wss://secure.example.com", "d"],
   ],
   "content": "",
   ...other fields
 }
 ```
 
-This NIP doesn't fully replace relay lists that are designed to configure a client's usage of relays (such as `kind:3` style relay lists). Clients MAY use other relay lists in situations where a `kind:10002` relay list cannot be found.
+Deprecated Relay List Event
+---------------------------
 
-## When to Use Read and Write Relays
+`kind:10002` is the deprecated version of the relay list event. Clients will want to create this to support existing clients that have not upgraded to the new `kind:10102`.
 
-When seeking events **from** a user, Clients SHOULD use the WRITE relays of the user's `kind:10002`.
+This event SHOULD include `r` tags of the following form:
 
-When seeking events **about** a user, where the user was tagged, Clients SHOULD use the READ relays of the user's `kind:10002`.
+```json
+["r", "<relay-url>", "<read-or-write>"]
+```
+`read-or-write` MUST be the string `"read"` (for an INBOX) or the string `"write"` (for an OUTBOX), or it should be left out (or empty). If it is left out (or empty) the relay is both an INBOX and an OUTBOX. Clients should ignore any other strings found that they do not understand.
+
+The `.content` is not used.
 
-When broadcasting an event, Clients SHOULD:
+### Example:
 
-- Broadcast the event to the WRITE relays of the author
-- Broadcast the event all READ relays of each tagged user
+```json
+{
+  "kind": 10002,
+  "tags": [
+    ["r", "wss://alicerelay.example.com"],
+    ["r", "wss://brando-relay.com"],
+    ["r", "wss://expensive-relay.example2.com", "write"],
+    ["r", "wss://nostr-relay.example.com", "read"],
+  ],
+  "content": "",
+  ...other fields
+}
+```
 
 ## Motivation
 
-The old model of using a fixed relay list per user centralizes in large relay operators: 
+The old model of using a fixed relay list per user centralizes in large relay operators:
 
   - Most users submit their posts to the same highly popular relays, aiming to achieve greater visibility among a broader audience
   - Many users are pulling events from a large number of relays in order to get more data at the expense of duplication
   - Events are being copied between relays, oftentimes to many different relays
-  
-This NIP allows Clients to connect directly with the most up-to-date relay set from each individual user, eliminating the need of broadcasting events to popular relays. 
+
+This NIP allows Clients to connect directly with the most up-to-date relay set from each individual user, eliminating the need of broadcasting events to popular relays.
 
 ## Final Considerations
 
-1. Clients SHOULD guide users to keep `kind:10002` lists small (2-4 relays). 
+1. Authors may publish to their own INBOX relays events that they intend to read back later. This doesn't make them OUTBOX relays.
+
+2. Clients SHOULD guide users to keep relay lists small (2-6 relays).
 
-2. Clients SHOULD spread an author's `kind:10002` event to as many relays as viable. 
+3. Clients SHOULD advertise an author's relay list events to as many relays as viable.
 
-3. `kind:10002` events should primarily be used to advertise the user's preferred relays to others. A user's own client may use other heuristics for selecting relays for fetching data.
+4. Relay list events should primarily be used to advertise the user's preferred relays to others. A user's own client may use other heuristics for selecting relays for fetching data or for other purposes. Clients MAY use other relay lists (such as `kind:3` contents) in situations where a `kind:10002` relay list cannot be found.
 
-4. DMs SHOULD only be broadcasted to the author's WRITE relays and to the receiver's READ relays to keep maximum privacy. 
+5. DMs SHOULD only be broadasted to the author's DM relays and to the receiver's DM relays to keep maximum privacy. If either party doesn't have DM relays, INBOX relays should be used instead.
 
-5. If a relay signals support for this NIP in their [NIP-11](11.md) document that means they're willing to accept kind 10002 events from a broad range of users, not only their paying customers or whitelisted group.
+6. If a relay signals support for this NIP in their [NIP-11](11.md) document that means they're willing to accept kind 10002 events (and hopefully kind 10102 events) from a broad range of users, not only their paying customers or whitelisted group.
 
-6. Clients SHOULD deduplicate connections by normalizing relay URIs according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-6).
+7. Clients SHOULD deduplicate connections by normalizing relay URIs according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-6).