nips/91.md

NIP-91
======

EOSE Extensions
---------------

`draft` `optional`

This NIP defines an extension to the EOSE message that allows relays to convey additional information to clients.

## Extended EOSE

An extended EOSE is an EOSE message, with the 2nd parameter being the "extensions object". For example: `["EOSE","example-sub",{"example_ext":"example value"}]`

An EOSE extension is a field in the extensions object. This may contain any value.

Clients MUST NOT rely on relays implementing any extensions.

## Extensions

This NIP defines a set of standard extensions.

### `next_created_at`
`recommended`

The value of this extension MUST be an integer if present, and should specify the next `until` value the client should use for pagination.
This MAY be higher or lower than the lowest `created_at`, and the clients SHOULD NOT perform any modifications to this value.

### `cursor`

The value of this extension MUST be a string or `null` if present, and represents a cursor the client can use to paginate this query.
If the value is `null`, then it indicates that no more events are available for the given set of filters.
To get more events, the client MUST send a `REQ` with the same filters (except limit, which can be changed), and the `cursor` string
in the 1st filter with the key `cursor`. Example:
```jsonc
< ["REQ", "examplereq1", {"kinds": [1], "limit": 1}, {"authors": ["..."], "limit": 1}]
> ["EVENT", "examplereq1", ...]
> ["EOSE", "examplereq1", {"cursor": "example-cursor-string", ...}]
< ["CLOSE", "examplereq1"]
< ["REQ", "examplereq2", {"kinds": [1], "limit": 5, "cursor": "example-cursor-string"}, {"authors": ["..."], "limit": 5}]
> ["EVENT", "examplereq2", ...]
...
```

This cursor MUST be valid for the duration of the connection, and MAY be valid in a new connection. A relay may indicate a cursor is no longer valid
by sending a CLOSED with the prefix `bad-cursor: `.

### `auth_recommended`

The value of this extension MUST be a boolean if present, and indicates if the client should `AUTH` to get more events that match this query.
This is a less disruptive alternative to `CLOSED` with `auth-required:` for filters that don't explicitly ask for access controlled events,
but may match them.