Validator identities endpoint.

In support of ethereum#449.

Author: mcdee

apis/beacon/states/validator_identities.yaml

@@ -0,0 +1,69 @@
+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 either hex encoded public keys (any bytes48 with 0x prefix) or validator indices"
+    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"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'

beacon-node-oapi.yaml

@@ -75,6 +75,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:
@@ -223,6 +225,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:

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: