NIP-67: "auth" hint

42.md

@@ -84,6 +84,10 @@ relay: ["EVENT", "sub_1", {...}]
 
 In this case, the `AUTH` message from the relay could be sent right as the client connects or it can be sent immediately before the `CLOSED` is sent. The only requirement is that _the client must have a stored challenge associated with that relay_ so it can act upon that in response to the `auth-required` `CLOSED` message.
 
+### `auth` hint in `EOSE`
+
+Relays MAY use the `"auth"` hint in an `EOSE` message (as defined in [NIP-67](67.md)) to notify the client that more results may be available if they authenticate. In this case, the relay MUST send the `AUTH` challenge before the `EOSE` message.
+
 ### `auth-required` in response to an `EVENT` message
 
 The same flow is valid for when a client wants to write an `EVENT` to the relay, except now the relay sends back an `OK` message instead of a `CLOSED` message:

67.md

@@ -30,10 +30,11 @@ A relay that implements this NIP MAY append a third element to the `EOSE` messag
 ["EOSE", <subscription_id>, [<hint>, ...]]
 ```
 
-Currently two hint values are defined:
+Currently three hint values are defined:
 
 - `"finish"`: the relay has sent every stored event matching the subscription's filters. The client SHOULD NOT paginate this subscription further.
 - `"more"`: the relay holds more matching stored events than it has sent. The client SHOULD paginate to retrieve them. A relay MAY send this hint, but is not required to, since detecting whether more events exist is not cheap on every storage backend.
+- `"auth"`: the relay may have more stored events matching the subscription's filters if the user performs `AUTH` ([NIP-42](42.md)). Relays MUST ensure an `AUTH` message (containing a challenge) is sent _before_ the `EOSE` containing an `"auth"` hint.
 
 The array MAY carry multiple hints simultaneously, and MAY be empty. Clients MUST ignore unknown hint values without error.
 
@@ -55,15 +56,6 @@ Relays implementing this NIP SHOULD include `67` in the `supported_nips` field o
 
 ## Examples
 
-Relay has more matching events than its internal cap (legacy-shaped response, client paginates):
-
-```
-["REQ", "sub1", {"authors": ["abcd..."], "kinds": [1]}]
-["EVENT", "sub1", {...}]
-... (300 events total)
-["EOSE", "sub1"]
-```
-
 Relay has sent every matching stored event:
 
 ```
@@ -72,7 +64,7 @@ Relay has sent every matching stored event:
 ["EOSE", "sub2", ["finish"]]
 ```
 
-Relay has more matching events and says so explicitly:
+Relay has more matching events:
 
 ```
 ["REQ", "sub2b", {"authors": ["abcd..."], "kinds": [1]}]
@@ -81,11 +73,11 @@ Relay has more matching events and says so explicitly:
 ["EOSE", "sub2b", ["more"]]
 ```
 
-Relay does not implement this NIP (legacy behavior — client falls back to heuristic):
+Relay has more matching events that require authentication:
 
 ```
-["REQ", "sub3", {"kinds": [1], "limit": 500}]
-["EVENT", "sub3", {...}]
-... (N events)
-["EOSE", "sub3"]
+["REQ", "sub2b", {"authors": ["abcd..."], "kinds": [1]}]
+["EVENT", "sub4", {...}]
+["AUTH", "challenge..."]
+["EOSE", "sub4", ["auth", "finish"]]
 ```