diff --git a/42.md b/42.md index c2b6ded037..e750c7cdf9 100644 --- a/42.md +++ b/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: diff --git a/67.md b/67.md index 8006304d02..6ca4209033 100644 --- a/67.md +++ b/67.md @@ -30,10 +30,11 @@ A relay that implements this NIP MAY append a third element to the `EOSE` messag ["EOSE", , [, ...]] ``` -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"]] ```