diff --git a/91.md b/91.md new file mode 100644 index 0000000..76e8123 --- /dev/null +++ b/91.md @@ -0,0 +1,53 @@ +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. + +Experimental extensions SHOULD use the `x_` prefix for the object key. + +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 if present, and represents a cursor the client can use to paginate this query. +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: `. + +### `has_more` +`recommended` + +The value of this extension MUST be a boolean if present, and should represent if the client should continue trying to get events. +This MAY be false if the relay has completed the query due to not having more events available, or may not be able to complete this query due to a permanent failure (scan limit exceeded is one).