This specification explains the Waku Store protocol which enables querying of messages received through relay protocol and stored by other nodes. It also supports pagination for more efficient querying of historical messages.
Peers communicate with each other using a request / response API. The messages sent are Protobuf RPC messages. The followings are the specifications of the Protobuf messages.
To perform pagination, each `WakuMessage` stored at a node running the store protocol is associated with a unique `Index` that encapsulates the following parts.
-`digest`: a sequence of bytes representing the hash of a `WakuMessage`.
-`receivedTime`: the UNIX time at which the waku message is received by the node running the store protocol.
`PagingInfo` holds the information required for pagination. It consists of the following components.
-`pageSize`: A positive integer indicating the number of queried `WakuMessage`s in a `HistoryQuery` (or retrieved `WakuMessage`s in a `HistoryResponse`).
-`cursor`: holds the `Index` of a `WakuMessage`.
-`direction`: indicates the direction of paging which can be either `FORWARD` or `BACKWARD`.
- The `topics` field MUST indicate the list of topics to query.
-`PagingInfo` holds the information required for pagination. Its `pageSize` field indicates the number of `WakuMessage`s to be included in the corresponding `HistoryResponse`. If the `pageSize` is zero then no pagination is required. If the `pageSize` exceeds a threshold then the threshold value shall be used instead. In the forward pagination request, the `messages` field of the `HistoryResponse` shall contain at maximum the `pageSize` amount of waku messages whose `Index` values are larger than the given `cursor` (and vise versa for the backward pagination). Note that the `cursor` of a `HistoryQuery` may be empty (e.g., for the initial query), as such, and depending on whether the `direction` is `BACKWARD` or `FORWARD` the last or the first `pageSize` waku messages shall be returned, respectively.
The queried node MAY sort the `WakuMessage`s based on their `Index`, where the `receivedTime` constitutes the most significant part and the `digest` comes next, and then perform pagination on the sorted result. As such, the retrieved page contains an ordered list of `WakuMessage`s from the oldest message to the most recent one.
- The `messages` field MUST contain the messages found, these are [`WakuMessage`] types as defined in the corresponding [specification](./waku-message.md).
-`PagingInfo` holds the paging information based on which the querying node can resume its further history queries. The `pageSize` indicates the number of returned waku messages (i.e., the number of messages included in the `messages` field of `HistoryResponse`). The `direction` is the same direction as in the corresponding `HistoryQuery`. In the forward pagination, the `cursor` holds the `Index` of the last message in the `HistoryResponse``messages` (and the first message in the backward paging). The requester shall embed the returned `cursor` inside its next `HistoryQuery` to retrieve the next page of the waku messages. The `cursor` obtained from one node SHOULD NOT be used in a request to another node because the result MAY be different.
