From 7fcc61a956ddfbb790f1c410de7943d093b0c645 Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 03:08:20 +0200
Subject: [PATCH 1/6] Updated /admin/v1 endpoint with modified and new scema
 types and endpoints

---
 api-spec/adminapi_peer.yaml                   | 30 ++++++
 .../{adminapi.yaml => adminapi_peers.yaml}    | 13 ++-
 api-spec/adminapi_peers_connected.yaml        | 20 ++++
 .../adminapi_peers_connected_on_shard.yaml    | 33 +++++++
 api-spec/adminapi_peers_mesh.yaml             | 20 ++++
 api-spec/adminapi_peers_mesh_on_shard.yaml    | 31 ++++++
 api-spec/adminapi_peers_relay.yaml            | 20 ++++
 api-spec/adminapi_peers_relay_on_shard.yaml   | 31 ++++++
 api-spec/adminapi_peers_service.yaml          | 20 ++++
 api-spec/openapi.yaml                         | 18 +++-
 api-spec/schemas/apitypes.yaml                | 96 ++++++++++++-------
 11 files changed, 292 insertions(+), 40 deletions(-)
 create mode 100644 api-spec/adminapi_peer.yaml
 rename api-spec/{adminapi.yaml => adminapi_peers.yaml} (78%)
 create mode 100644 api-spec/adminapi_peers_connected.yaml
 create mode 100644 api-spec/adminapi_peers_connected_on_shard.yaml
 create mode 100644 api-spec/adminapi_peers_mesh.yaml
 create mode 100644 api-spec/adminapi_peers_mesh_on_shard.yaml
 create mode 100644 api-spec/adminapi_peers_relay.yaml
 create mode 100644 api-spec/adminapi_peers_relay_on_shard.yaml
 create mode 100644 api-spec/adminapi_peers_service.yaml

diff --git a/api-spec/adminapi_peer.yaml b/api-spec/adminapi_peer.yaml
new file mode 100644
index 0000000..0af76dc
--- /dev/null
+++ b/api-spec/adminapi_peer.yaml
@@ -0,0 +1,30 @@
+get:
+  summary: Get connected peers info
+  description: Retrieve information about connected peers.
+  operationId: getPeerInfo
+  tags:
+    - admin
+  parameters:
+    - in: path
+      name: peerId
+      required: true
+      schema:
+        type: string
+      description: ID of the peer to retrieve information for    
+  responses:
+    '200':
+      description: Information about a Waku v2 node.
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/apitypes.yaml#/WakuPeer"
+    '400':
+      description: Invalid argument.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
diff --git a/api-spec/adminapi.yaml b/api-spec/adminapi_peers.yaml
similarity index 78%
rename from api-spec/adminapi.yaml
rename to api-spec/adminapi_peers.yaml
index 596b540..0912c60 100644
--- a/api-spec/adminapi.yaml
+++ b/api-spec/adminapi_peers.yaml
@@ -13,8 +13,11 @@ get:
             type: array
             items:
               $ref: "./schemas/apitypes.yaml#/WakuPeer"
-    '5XX':
-      description: Unexpected error.
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
 post:
   summary: Adds new peer(s) to connect with
   description: Adds new peer(s) to connect with.
@@ -33,5 +36,11 @@ post:
       description: Ok
     '400':
       description: Cannot connect to one or more peers.
+      content:
+        text/plain:
+          type: string
     '5XX':
       description: Unexpected error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_connected.yaml b/api-spec/adminapi_peers_connected.yaml
new file mode 100644
index 0000000..6014f3a
--- /dev/null
+++ b/api-spec/adminapi_peers_connected.yaml
@@ -0,0 +1,20 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about connected peers
+  operationId: getConnectedPeers
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "./schemas/apitypes.yaml#/WakuPeer"
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_connected_on_shard.yaml b/api-spec/adminapi_peers_connected_on_shard.yaml
new file mode 100644
index 0000000..0e064c0
--- /dev/null
+++ b/api-spec/adminapi_peers_connected_on_shard.yaml
@@ -0,0 +1,33 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about connected peers for a specific shard.
+  operationId: getConnectedPeersByShard
+  parameters:
+    - in: path
+      name: shardId
+      required: true
+      schema:
+        type: integer
+        format: uint16
+      description: ID of the shard to retrieve information for
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "./schemas/apitypes.yaml#/WakuPeer"
+    '400':
+      description: Invalid argument.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_mesh.yaml b/api-spec/adminapi_peers_mesh.yaml
new file mode 100644
index 0000000..8a958d4
--- /dev/null
+++ b/api-spec/adminapi_peers_mesh.yaml
@@ -0,0 +1,20 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about relay peers in node's direct mesh, grouped by shards.
+  operationId: getMeshPeers
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "./schemas/apitypes.yaml#/PeersOfShard"
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_mesh_on_shard.yaml b/api-spec/adminapi_peers_mesh_on_shard.yaml
new file mode 100644
index 0000000..d00c039
--- /dev/null
+++ b/api-spec/adminapi_peers_mesh_on_shard.yaml
@@ -0,0 +1,31 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about relay peers in node's direct mesh for a specific shard.
+  operationId: getMeshPeersByShard
+  parameters:
+    - in: path
+      name: shardId
+      required: true
+      schema:
+        type: integer
+        format: uint16
+      description: ID of the shard to retrieve information for
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/apitypes.yaml#/PeersOfShard"
+    '400':
+      description: Invalid argument.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_relay.yaml b/api-spec/adminapi_peers_relay.yaml
new file mode 100644
index 0000000..16e4ba7
--- /dev/null
+++ b/api-spec/adminapi_peers_relay.yaml
@@ -0,0 +1,20 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about relay peers in node's gossip network, grouped by shards.
+  operationId: getRelayPeers
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "./schemas/apitypes.yaml#/PeersOfShard"
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_relay_on_shard.yaml b/api-spec/adminapi_peers_relay_on_shard.yaml
new file mode 100644
index 0000000..e64407e
--- /dev/null
+++ b/api-spec/adminapi_peers_relay_on_shard.yaml
@@ -0,0 +1,31 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about relay peers in node's gossip network for a specific shard.
+  operationId: getRelayPeersByShard
+  parameters:
+    - in: path
+      name: shardId
+      required: true
+      schema:
+        type: integer
+        format: uint16
+      description: ID of the shard to retrieve information for
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/apitypes.yaml#/PeersOfShard"
+    '400':
+      description: Invalid argument.
+      content:
+        text/plain:
+          type: string
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/adminapi_peers_service.yaml b/api-spec/adminapi_peers_service.yaml
new file mode 100644
index 0000000..ab56963
--- /dev/null
+++ b/api-spec/adminapi_peers_service.yaml
@@ -0,0 +1,20 @@
+get:
+  tags:
+    - admin
+  summary: Get peers by service
+  description: Returns information about peers offering specific services
+  operationId: getPeersByService
+  responses:
+    '200':
+      description: Successful service peers response
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "./schemas/apitypes.yaml#/WakuPeer"
+    '500':
+      description: Internal server error.
+      content:
+        text/plain:
+          type: string
\ No newline at end of file
diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml
index c359de9..756eed1 100644
--- a/api-spec/openapi.yaml
+++ b/api-spec/openapi.yaml
@@ -36,7 +36,23 @@ paths:
   /version:
      $ref: "./debugapi_version.yaml"
   /admin/v1/peers:
-    $ref: "./adminapi.yaml"
+    $ref: "./adminapi_peers.yaml"
+  /admin/v1/peer/{peerId}:
+    $ref: "./adminapi_peer.yaml"
+  /admin/v1/peers/service:
+    $ref: "./adminapi_peers_service.yaml"
+  /admin/v1/peers/connected:
+    $ref: "./adminapi_peers_connected.yaml"
+  /admin/v1/peers/connected/on/{shardId}:
+    $ref: "./adminapi_peers_connected_on_shard.yaml"  
+  /admin/v1/peers/relay:
+    $ref: "./adminapi_peers_relay.yaml"
+  /admin/v1/peers/relay/on/{shardId}:
+    $ref: "./adminapi_peers_relay_on_shard.yaml"
+  /admin/v1/peers/mesh:
+    $ref: "./adminapi_peers_mesh.yaml"
+  /admin/v1/peers/mesh/on/{shardId}:
+    $ref: "./adminapi_peers_mesh_on_shard.yaml"
   /admin/v1/filter/subscriptions:
     $ref: "./adminapi_filter.yaml"
   /debug/v1/info:
diff --git a/api-spec/schemas/apitypes.yaml b/api-spec/schemas/apitypes.yaml
index 3fd1a41..3bbe04f 100644
--- a/api-spec/schemas/apitypes.yaml
+++ b/api-spec/schemas/apitypes.yaml
@@ -3,6 +3,9 @@ WakuPeer:
   required:
     - multiaddr
     - protocols
+    - shards
+    - agent
+    - connected
     - origin
   properties:
     multiaddr:
@@ -10,17 +13,37 @@ WakuPeer:
     protocols:
       type: array
       items:
-        type: object
-        required:
-          - protocol
-          - connected
-        properties:
-          protocol:
-            type: string
-          connected:
-            type: boolean
+        type: string
+    shards:
+      type: array
+      items:
+        type: integer
+        format: int32
+    connected:
+      type: string
+      enum:
+        - "NotConnected"
+        - "CannotConnect"
+        - "CanConnect"
+        - "Connected"
+    agent:
+      type: string
     origin:
       type: string
+    score:
+      type: number
+      format: double
+
+PeersOfShard:
+  type: object
+  properties:
+    shard:
+      type: integer
+      format: int32
+    peers:
+      type: array
+      items:
+        $ref: "#/WakuPeer"
 
 WakuInfo:
   type: object
@@ -42,7 +65,7 @@ ContentTopic:
 FilterGetMessagesResponse:
   type: array
   items:
-    $ref: '#/WakuMessage'
+    $ref: "#/WakuMessage"
 
 FilterSubscribeRequest:
   type: object
@@ -52,13 +75,13 @@ FilterSubscribeRequest:
     contentFilters:
       type: array
       items:
-        $ref: '#/ContentTopic'
+        $ref: "#/ContentTopic"
     pubsubTopic:
       $ref: "#/PubsubTopic"
   required:
-    -  requestId
-    -  contentFilters
-    -  pubsubTopic
+    - requestId
+    - contentFilters
+    - pubsubTopic
 
 FilterUnsubscribeRequest:
   type: object
@@ -68,12 +91,12 @@ FilterUnsubscribeRequest:
     contentFilters:
       type: array
       items:
-        $ref: '#/ContentTopic'
+        $ref: "#/ContentTopic"
     pubsubTopic:
       $ref: "#/PubsubTopic"
   required:
-    -  requestId
-    -  contentFilters
+    - requestId
+    - contentFilters
 
 FilterUnsubscribeAllRequest:
   type: object
@@ -81,7 +104,7 @@ FilterUnsubscribeAllRequest:
     requestId:
       type: string
   required:
-    -  requestId
+    - requestId
 
 FilterSubscriptionResponse:
   type: object
@@ -91,7 +114,7 @@ FilterSubscriptionResponse:
     statusDesc:
       type: string
   required:
-    -  requestId
+    - requestId
 
 WakuMessage:
   type: object
@@ -100,7 +123,7 @@ WakuMessage:
       type: string
       format: byte
     contentTopic:
-      $ref: '#/ContentTopic'
+      $ref: "#/ContentTopic"
     version:
       type: integer
       format: int32
@@ -115,9 +138,9 @@ WakuMessage:
       type: string
       format: byte
   required:
-      - payload
-      - contentTopic
-      - timestamp
+    - payload
+    - contentTopic
+    - timestamp
 
 WakuMessageKeyValue:
   type: object
@@ -125,7 +148,7 @@ WakuMessageKeyValue:
     message_hash:
       type: string
     message:
-      $ref: '#/components/schemas/WakuMessage'
+      $ref: "#/components/schemas/WakuMessage"
   required:
     - message_hash
     - message
@@ -143,7 +166,7 @@ StoreQueryResponse:
     messages:
       type: array
       items:
-        $ref: '#/components/schemas/WakuMessageKeyValue'
+        $ref: "#/components/schemas/WakuMessageKeyValue"
     paginationCursor:
       type: string
   required:
@@ -156,22 +179,21 @@ PushRequest:
   type: object
   properties:
     pubsubTopic:
-      $ref: '#/PubsubTopic'
+      $ref: "#/PubsubTopic"
     message:
-      $ref: '#/WakuMessage'
+      $ref: "#/WakuMessage"
   required:
     - message
 
 PushResponse:
   type: object
   properties:
-    statusDesc: 
+    statusDesc:
       type: string
-    relayPeerCount: 
+    relayPeerCount:
       type: integer
       format: uint32
 
-    
 ## TODO: Check if it can be tunneled into the one WakuMessage structure
 ##       mainly because of Relay post message request can break in client code
 RelayWakuMessage:
@@ -181,7 +203,7 @@ RelayWakuMessage:
       type: string
       format: byte
     contentTopic:
-      $ref: '#/ContentTopic'
+      $ref: "#/ContentTopic"
     version:
       type: number
     timestamp:
@@ -197,10 +219,10 @@ RelayWakuMessage:
 RelayGetMessagesResponse:
   type: array
   items:
-    $ref: '#/RelayWakuMessage'
+    $ref: "#/RelayWakuMessage"
 
 RelayPostMessagesRequest:
-  $ref: '#/RelayWakuMessage'
+  $ref: "#/RelayWakuMessage"
 
 StoreResponse:
   type: object
@@ -208,9 +230,9 @@ StoreResponse:
     messages:
       type: array
       items:
-        $ref: '#/WakuMessage'
+        $ref: "#/WakuMessage"
     cursor:
-      $ref: '#/HistoryCursor'
+      $ref: "#/HistoryCursor"
     error_message:
       type: string
   required:
@@ -268,11 +290,11 @@ HealthReport:
   type: object
   properties:
     nodeHealth:
-      $ref: '#/HealthStatus'
+      $ref: "#/HealthStatus"
       description: Overall health status of the node
     protocolsHealth:
       type: array
       items:
         type: object
         additionalProperties:
-          $ref: '#/HealthStatus'
+          $ref: "#/HealthStatus"

From f3702789a1da0eec35b8e70bd4dcfe3ca5932cf3 Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 15:00:06 +0200
Subject: [PATCH 2/6] Update adminapi_peer.yaml - fix descriptions

---
 api-spec/adminapi_peer.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api-spec/adminapi_peer.yaml b/api-spec/adminapi_peer.yaml
index 0af76dc..50bc34f 100644
--- a/api-spec/adminapi_peer.yaml
+++ b/api-spec/adminapi_peer.yaml
@@ -1,6 +1,6 @@
 get:
-  summary: Get connected peers info
-  description: Retrieve information about connected peers.
+  summary: Get peer info about a single peer
+  description: Retrieve information about a single peer.
   operationId: getPeerInfo
   tags:
     - admin

From 935fe95420f4ab794481ef0a10f4a607617264f6 Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 15:01:35 +0200
Subject: [PATCH 3/6] Update adminapi_peers.yaml - fix descriptions

---
 api-spec/adminapi_peers.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/api-spec/adminapi_peers.yaml b/api-spec/adminapi_peers.yaml
index 0912c60..54c7f3e 100644
--- a/api-spec/adminapi_peers.yaml
+++ b/api-spec/adminapi_peers.yaml
@@ -1,12 +1,12 @@
 get:
-  summary: Get connected peers info
-  description: Retrieve information about connected peers.
+  summary: Get peer info about all peers
+  description: Retrieve information about all peers.
   operationId: getPeerInfo
   tags:
     - admin
   responses:
     '200':
-      description: Information about a Waku v2 node.
+      description: List of peer info about all peers in peer storage of the node.
       content:
         application/json:
           schema:
@@ -43,4 +43,4 @@ post:
       description: Unexpected error.
       content:
         text/plain:
-          type: string
\ No newline at end of file
+          type: string

From 8ca5d19aab3e0f22f31aa281be2f0043f0e02e3e Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 15:04:02 +0200
Subject: [PATCH 4/6] Update adminapi_peers_mesh.yaml

---
 api-spec/adminapi_peers_mesh.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/api-spec/adminapi_peers_mesh.yaml b/api-spec/adminapi_peers_mesh.yaml
index 8a958d4..ad261fd 100644
--- a/api-spec/adminapi_peers_mesh.yaml
+++ b/api-spec/adminapi_peers_mesh.yaml
@@ -1,12 +1,12 @@
 get:
   tags:
     - admin
-  summary: Get peers by service
+  summary: Get peers of mesh bx subscribed shards
   description: Returns information about relay peers in node's direct mesh, grouped by shards.
   operationId: getMeshPeers
   responses:
     '200':
-      description: Successful service peers response
+      description: List of mesh peers grouped by shard
       content:
         application/json:
           schema:
@@ -17,4 +17,4 @@ get:
       description: Internal server error.
       content:
         text/plain:
-          type: string
\ No newline at end of file
+          type: string

From 579661dac99665b945f1ff2595fea233165aee61 Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 15:06:07 +0200
Subject: [PATCH 5/6] Update api-spec/adminapi_peers_mesh_on_shard.yaml

Co-authored-by: gabrielmer <101006718+gabrielmer@users.noreply.github.com>
---
 api-spec/adminapi_peers_mesh_on_shard.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api-spec/adminapi_peers_mesh_on_shard.yaml b/api-spec/adminapi_peers_mesh_on_shard.yaml
index d00c039..34e1fd1 100644
--- a/api-spec/adminapi_peers_mesh_on_shard.yaml
+++ b/api-spec/adminapi_peers_mesh_on_shard.yaml
@@ -1,7 +1,7 @@
 get:
   tags:
     - admin
-  summary: Get peers by service
+  summary: Get mesh peers by shard
   description: Returns information about relay peers in node's direct mesh for a specific shard.
   operationId: getMeshPeersByShard
   parameters:

From 518762bd3f460d7e35113dda3b6f3d452760756c Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Fri, 25 Apr 2025 15:07:00 +0200
Subject: [PATCH 6/6] Update adminapi_peers_mesh_on_shard.yaml

---
 api-spec/adminapi_peers_mesh_on_shard.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api-spec/adminapi_peers_mesh_on_shard.yaml b/api-spec/adminapi_peers_mesh_on_shard.yaml
index 34e1fd1..2623c90 100644
--- a/api-spec/adminapi_peers_mesh_on_shard.yaml
+++ b/api-spec/adminapi_peers_mesh_on_shard.yaml
@@ -14,7 +14,7 @@ get:
       description: ID of the shard to retrieve information for
   responses:
     '200':
-      description: Successful service peers response
+      description: List of peers in the mesh of the shard in question
       content:
         application/json:
           schema:
@@ -28,4 +28,4 @@ get:
       description: Internal server error.
       content:
         text/plain:
-          type: string
\ No newline at end of file
+          type: string