feat: add store v3 specification

api-spec/legacystoreapi.yaml

@@ -0,0 +1,137 @@
+# /store/v1/messages:
+get:
+  summary: Gets message history
+  description: >
+    Retrieves WakuV2 message history. The returned history
+    can be potentially filtered by optional request parameters.
+  operationId: getMessageHistory
+  tags:
+    - legacy_store
+  parameters:
+    - name: peerAddr
+      in: query
+      schema:
+        type: string
+      description: >
+        P2P fully qualified peer multiaddress
+        in the format `(ip4|ip6)/tcp/p2p/$peerId` and URL-encoded.
+      example: '%2Fip4%2F127.0.0.1%2Ftcp%2F60001%2Fp2p%2F16Uiu2HAmVFXtAfSj4EiR7mL2KvL4EE2wztuQgUSBoj2Jx2KeXFLN'
+
+    - name: pubsubTopic
+      in: query
+      schema:
+        type: string
+      description: >
+        The pubsub topic on which a WakuMessage is published.
+        If left empty, no filtering is applied.
+        It is also intended for pagination purposes.
+        It should be a URL-encoded string.
+      example: 'my%20pubsub%20topic'
+
+    - name: contentTopics
+      in: query
+      schema: string
+      description: >
+        Comma-separated list of content topics. When specified,
+        only WakuMessages that are linked to any of the given
+        content topics will be delivered in the get response.
+        It should be a URL-encoded-comma-separated string.
+      example: 'my%20first%20content%20topic%2Cmy%20second%20content%20topic%2Cmy%20third%20content%20topic'
+
+    - name: startTime
+      in: query
+      schema:
+        type: string
+      description: >
+        The inclusive lower bound on the timestamp of
+        queried WakuMessages. This field holds the
+        Unix epoch time in nanoseconds as a 64-bits
+        integer value.
+      example: '1680590945000000000'
+
+    - name: endTime
+      in: query
+      schema:
+        type: string
+      description: >
+        The inclusive upper bound on the timestamp of
+        queried WakuMessages. This field holds the
+        Unix epoch time in nanoseconds as a 64-bits
+        integer value.
+      example: '1680590945000000000'
+
+    - name: senderTime
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        Represents the Unix time in nanoseconds at which a message was generated.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: '1680590947000000000'
+
+    - name: storeTime
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        Represents the Unix time in nanoseconds at which a message was stored.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: '1680590945000000000'
+
+    - name: digest
+      in: query
+      schema:
+        type: string
+      description: >
+        Cursor field intended for pagination purposes.
+        URL-base64-encoded string computed as a hash of the
+        a message content topic plus a message payload.
+        It could be empty for retrieving the first page,
+        and will be returned from the GET response so that
+        it can be part of the next page request.
+      example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D'
+
+    - name: pageSize
+      in: query
+      schema:
+        type: string
+      description: >
+        Number of messages to retrieve per page
+      example: '5'
+
+    - name: ascending
+      in: query
+      schema:
+        type: string
+      description: >
+        "true" for paging forward, "false" for paging backward
+      example: "true"
+
+  responses:
+    '200':
+      description: WakuV2 message history.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/StoreResponse'
+    '400':
+      description: Bad request error.
+      content:
+        text/plain:
+          type: string
+    '412':
+      description: Precondition failed.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string

api-spec/openapi.yaml

@@ -21,6 +21,8 @@ tags:
   - name: relay
     description: Control of the relaying of messages. See [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/) RFC
   - name: store
+    description: Retrieve the message history. #TODO See [13/WAKU2-STORE]() RFC
+  - name: legacy_store
     description: Retrieve the message history. See [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) RFC
   - name: filter
     description: Control of the content filtering. See [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) RFC
@@ -50,6 +52,8 @@ paths:
   /relay/v1/auto/subscriptions:
     $ref: "./relayapi_auto_subscriptions.yaml"
   /store/v1/messages:
+    $ref: "./legacystoreapi.yaml"
+  /store/v3/messages:
     $ref: "./storeapi.yaml"
   /filter/v1/subscriptions:
     $ref: "./filterapi_v1_subscriptions.yaml"

api-spec/schemas/apitypes.yaml

@@ -118,12 +118,48 @@ WakuMessage:
       format: int64
     ephemeral:
       type: boolean
+    proof:
+      type: string
     meta:
       type: string
       format: byte
   required:
       - payload
       - contentTopic
+      - timestamp
+
+WakuMessageKeyValue:
+  type: object
+  properties:
+    message_hash:
+      type: string
+    message:
+      $ref: '#/components/schemas/WakuMessage'
+  required:
+    - message_hash
+    - message
+
+StoreQueryResponse:
+  type: object
+  properties:
+    request_id:
+      type: string
+    status_code:
+      type: integer
+      format: uint32
+    status_desc:
+      type: string
+    messages:
+      type: array
+      items:
+        $ref: '#/components/schemas/WakuMessageKeyValue'
+    pagination_cursor:
+      type: string
+  required:
+    - request_id
+    - status_code
+    - status_desc
+    - messages
 
 PushRequest:
   type: object

api-spec/storeapi.yaml

@@ -1,8 +1,8 @@
-# /store/v1/messages:
+# /store/v3/messages:
 get:
   summary: Gets message history
   description: >
-    Retrieves WakuV2 message history. The returned history
+    Retrieves Waku message history. The returned history
     can be potentially filtered by optional request parameters.
   operationId: getMessageHistory
   tags:
@@ -12,11 +12,23 @@ get:
       in: query
       schema:
         type: string
+      required: true
       description: >
         P2P fully qualified peer multiaddress
         in the format `(ip4|ip6)/tcp/p2p/$peerId` and URL-encoded.
       example: '%2Fip4%2F127.0.0.1%2Ftcp%2F60001%2Fp2p%2F16Uiu2HAmVFXtAfSj4EiR7mL2KvL4EE2wztuQgUSBoj2Jx2KeXFLN'
 
+    - name: includeData
+      in: query
+      schema:
+        type: string
+      description: >
+        Boolean indicating if the query should return messages (data) or hashes only.
+        A value of 'false' returns hashes only.
+        A value of 'true' returns hashes AND messages.
+        Default value is 'false'
+      example: 'true'
+
     - name: pubsubTopic
       in: query
       schema:
@@ -60,38 +72,23 @@ get:
         integer value.
       example: '1680590945000000000'
 
-    - name: senderTime
+    - name: hashes
       in: query
       schema:
         type: string
       description: >
-        Cursor field intended for pagination purposes.
-        Represents the Unix time in nanoseconds at which a message was generated.
-        It could be empty for retrieving the first page,
-        and will be returned from the GET response so that
-        it can be part of the next page request.
-      example: '1680590947000000000'
-
-    - name: storeTime
-      in: query
-      schema:
-        type: string
-      description: >
-        Cursor field intended for pagination purposes.
-        Represents the Unix time in nanoseconds at which a message was stored.
-        It could be empty for retrieving the first page,
-        and will be returned from the GET response so that
-        it can be part of the next page request.
-      example: '1680590945000000000'
+        Comma-separated list of message hashes.
+        URL-base64-encoded string computed as a hash of messages.
+        Used to find messages by hash.
+      example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D'
 
-    - name: digest
+    - name: cursor
       in: query
       schema:
         type: string
       description: >
         Cursor field intended for pagination purposes.
-        URL-base64-encoded string computed as a hash of the
-        a message content topic plus a message payload.
+        URL-base64-encoded string computed as a hash of a message.
         It could be empty for retrieving the first page,
         and will be returned from the GET response so that
         it can be part of the next page request.
@@ -110,16 +107,17 @@ get:
       schema:
         type: string
       description: >
-        "true" for paging forward, "false" for paging backward
+        "true" for paging forward, "false" for paging backward.
+        If not specified or if specified with an invalid value, the default is "true".
       example: "true"
 
   responses:
     '200':
-      description: WakuV2 message history.
+      description: Waku message history.
       content:
         application/json:
           schema:
-            $ref: './schemas/apitypes.yaml#/StoreResponse'
+            $ref: '#/components/schemas/StoreQueryResponse'
     '400':
       description: Bad request error.
       content:
@@ -134,4 +132,4 @@ get:
       description: Internal server error.
       content:
         text/plain:
-          type: string
+          type: string