Validator identities endpoint. (#452)

In support of #449. Co-authored-by: Paul Harris <[email protected]> Co-authored-by: Nico Flaig <[email protected]>
ethereum · Sep 24, 2024 · 30f0568 · 30f0568
1 parent 203410d
commit 30f0568
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 0 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -14,6 +14,7 @@ There are likely to be descriptions etc outside of the list below, but new query
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attestations` added              |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/pool/attester_slashings` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attester_slashings` added        |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#452](https://github.com/ethereum/beacon-APIs/pull/452) `POST /eth/v1/beacon/states/{state_id}/validator_identities` added |                                          |                                                  |                                                    |                                                 |                                           |
 | [#456](https://github.com/ethereum/beacon-APIs/pull/456) `POST /eth/v2/validator/aggregate_and_proofs` added        |                                                  |                                                  |                                                    |                                                 |                                           |
 
 

diff --git a/apis/beacon/states/validator_identities.yaml b/apis/beacon/states/validator_identities.yaml
@@ -0,0 +1,71 @@
+post:
+  operationId: "postStateValidatorIdentities"
+  summary: "Get validator identities from state"
+  description: |
+    Returns filterable list of validators identities.
+
+    Identities will be returned for all indices or public keys that match known validators. If an index or public key does not
+    match any known validator, no identity will be returned but this will not cause an error. There are no guarantees for the
+    returned data in terms of ordering.
+
+     Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
+  tags:
+    - Beacon
+  parameters:
+    - name: state_id
+      in: path
+      $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
+  requestBody:
+    description: "An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a validator index."
+    required: false
+    content:
+      application/json:
+        schema:
+          type: array
+          uniqueItems: true
+          items:
+            description: "Either hex encoded public key (any bytes48 with 0x prefix) or validator index"
+            type: string
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            title: PostStateValidatorIdentitiesResponse
+            type: object
+            required: [execution_optimistic, finalized, data]
+            properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              finalized:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
+              data:
+                type: array
+                items:
+                  $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorIdentityResponse'
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized results. Use Accept header to choose this response type"
+    "400":
+      description: "Invalid state ID or malformed request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid state ID: current"
+    "404":
+      description: "State not found"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 404
+            message: "State not found"
+    "406":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml
@@ -81,6 +81,8 @@ paths:
     $ref: "./apis/beacon/states/validator.yaml"
   /eth/v1/beacon/states/{state_id}/validator_balances:
     $ref: "./apis/beacon/states/validator_balances.yaml"
+  /eth/v1/beacon/states/{state_id}/validator_identities:
+    $ref: "./apis/beacon/states/validator_identities.yaml"
   /eth/v1/beacon/states/{state_id}/committees:
     $ref: "./apis/beacon/states/committee.yaml"
   /eth/v1/beacon/states/{state_id}/sync_committees:
@@ -239,6 +241,8 @@ components:
       $ref: './types/api.yaml#/ValidatorResponse'
     ValidatorBalanceResponse:
       $ref: './types/api.yaml#/ValidatorBalanceResponse'
+    ValidatorIdentityResponse:
+      $ref: './types/api.yaml#/ValidatorIdentityResponse'
     ValidatorStatus:
       $ref: './types/api.yaml#/ValidatorStatus'
     Committee:

diff --git a/types/api.yaml b/types/api.yaml
@@ -45,6 +45,20 @@ ValidatorBalanceResponse:
       $ref: "./primitive.yaml#/Gwei"
       description: "Current validator balance in gwei."
 
+ValidatorIdentityResponse:
+  type: object
+  required: [index, pubkey, activation_epoch]
+  properties:
+    index:
+      $ref: './primitive.yaml#/Uint64'
+      description: "Index of validator in validator registry."
+    pubkey:
+      $ref: './primitive.yaml#/Pubkey'
+      description: "Public key of validator."
+    activation_epoch:
+      $ref: "./primitive.yaml#/Uint64"
+      description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated"
+
 ValidatorStatus:
   description: |
     Possible statuses: