Add POST builders query endpoint

CHANGES.md

@@ -18,6 +18,7 @@ There are likely to be descriptions etc outside of the list below, but new query
 | [#580](https://github.com/ethereum/beacon-APIs/pull/580) `POST /eth/v1/beacon/execution_payload_envelopes` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/pool/payload_attestations` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#614](https://github.com/ethereum/beacon-APIs/pull/614) `POST /eth/v1/beacon/states/{state_id}/builders` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v2/beacon/blocks/{block_id}` updated         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated        |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_available EVENT` added         |                                                  |                                                  |                                                    |                                                 |                                           |

apis/beacon/states/builders.yaml

@@ -0,0 +1,85 @@
+post:
+  operationId: "getStateBuilders"
+  summary: "Get builders from state"
+  description: |
+    Returns filterable list of builders with their status and index.
+
+    Information will be returned for all indices or public keys that match known builders. If an index or public key does not
+    match any known builder, no information will be returned but this will not cause an error. There are no guarantees for the
+    returned data in terms of ordering; both the index and public key are returned for each builder, and can be used to confirm
+    for which inputs a response has been returned.
+
+    Returns 400 if the requested state is prior to Gloas.
+  tags:
+    - Beacon
+  parameters:
+    - name: state_id
+      in: path
+      $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
+  requestBody:
+    description: |
+      The lists of builder IDs and statuses to filter on.
+      If no body is supplied then all builders will be returned. To return all active builders, omit `ids` and set `statuses` to `["active"]`.
+    required: false
+    content:
+      application/json:
+        schema:
+          type: object
+          required: []
+          properties:
+            ids:
+              type: array
+              uniqueItems: true
+              description: |
+                An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a builder index.
+
+                If the supplied list is empty (i.e. the value is `[]`) or the property is omitted then all builders will be returned.
+              items:
+                type: string
+            statuses:
+              type: array
+              uniqueItems: true
+              description: |
+                An array of builder statuses to filter on.
+
+                If the supplied list is empty (i.e. the value is `[]`) or the property is omitted then builders with all statuses will be returned.
+              items:
+                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/BuilderStatus'
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            title: GetStateBuildersResponse
+            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/BuilderResponse'
+    "400":
+      description: "Invalid state ID, builder 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

@@ -81,6 +81,8 @@ paths:
     $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}/builders:
+    $ref: "./apis/beacon/states/builders.yaml"
   /eth/v1/beacon/states/{state_id}/committees:
     $ref: "./apis/beacon/states/committee.yaml"
   /eth/v1/beacon/states/{state_id}/sync_committees:
@@ -241,8 +243,12 @@ components:
       $ref: './types/api.yaml#/ValidatorBalanceResponse'
     ValidatorIdentityResponse:
       $ref: './types/api.yaml#/ValidatorIdentityResponse'
+    BuilderResponse:
+      $ref: './types/api.yaml#/BuilderResponse'
     ValidatorStatus:
       $ref: './types/api.yaml#/ValidatorStatus'
+    BuilderStatus:
+      $ref: './types/api.yaml#/BuilderStatus'
     Committee:
       $ref: './types/api.yaml#/Committee'
     AttesterDuty:
@@ -451,6 +457,8 @@ components:
       $ref: "./types/gloas/block.yaml#/Gloas/BeaconBlock"
     Gloas.SignedBeaconBlock:
       $ref: "./types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
+    Gloas.Builder:
+      $ref: "./types/gloas/builder.yaml#/Gloas/Builder"
     Gloas.BlockContents:
       $ref: "./types/gloas/block_contents.yaml#/Gloas/BlockContents"
     Gloas.ExecutionPayloadBid:

types/api.yaml

@@ -40,6 +40,18 @@ ValidatorIdentityResponse:
       $ref: "./primitive.yaml#/Uint64"
       description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated"
 
+BuilderResponse:
+  type: object
+  required: [index, status, builder]
+  properties:
+    index:
+      $ref: './primitive.yaml#/Uint64'
+      description: "Index of builder in builder registry."
+    status:
+      $ref: "#/BuilderStatus"
+    builder:
+      $ref: "./gloas/builder.yaml#/Gloas/Builder"
+
 ValidatorStatus:
   description: |
     Possible statuses:
@@ -57,6 +69,15 @@ ValidatorStatus:
   enum: ["pending_initialized", "pending_queued", "active_ongoing", "active_exiting", "active_slashed", "exited_unslashed", "exited_slashed", "withdrawal_possible", "withdrawal_done"]
   example: "active_ongoing"
 
+BuilderStatus:
+  description: |
+    Possible statuses:
+    - **pending** - When builder has not exited and is not yet active; `builder.withdrawable_epoch == FAR_FUTURE_EPOCH` and `is_active_builder(state, index)` returns `False`.
+    - **active** - When builder is active; `is_active_builder(state, index)` returns `True`, i.e. `builder.deposit_epoch < state.finalized_checkpoint.epoch` and `builder.withdrawable_epoch == FAR_FUTURE_EPOCH`.
+    - **exited** - When builder has exited; `builder.withdrawable_epoch != FAR_FUTURE_EPOCH`.
+  enum: ["pending", "active", "exited"]
+  example: "active"
+
 
 Committee:
   description: Group of validators assigned to attest at specific slot and that have the same committee index (shard in phase 1)

types/gloas/builder.yaml

@@ -0,0 +1,23 @@
+Gloas:
+  Builder:
+    type: object
+    description: "The [`Builder`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/beacon-chain.md#builder) object from the CL Gloas spec."
+    required: [pubkey, version, execution_address, balance, deposit_epoch, withdrawable_epoch]
+    properties:
+      pubkey:
+        $ref: "../primitive.yaml#/Pubkey"
+      version:
+        $ref: "../primitive.yaml#/Uint8"
+        description: "Builder version."
+      execution_address:
+        $ref: "../primitive.yaml#/ExecutionAddress"
+        description: "Execution-layer address that receives builder withdrawals."
+      balance:
+        $ref: "../primitive.yaml#/Gwei"
+        description: "Current builder balance in gwei."
+      deposit_epoch:
+        $ref: "../primitive.yaml#/Uint64"
+        description: "Epoch when the builder deposit was processed."
+      withdrawable_epoch:
+        $ref: "../primitive.yaml#/Uint64"
+        description: "Epoch when the builder can withdraw. 'FAR_FUTURE_EPOCH' if not exiting."