Add Gloas state builders Beacon API endpoint

CHANGELOG.md

@@ -17,6 +17,8 @@
 
 ### Additions and Improvements
 
+ - Added the Gloas `POST /eth/v1/beacon/states/{state_id}/builders` Beacon API endpoint from ethereum/beacon-APIs#614, with JSON and SSZ response support.
+
 ### Bug Fixes
  - Fixed a scenario where keys added via validator-api that rely on external signer are not slashing protected locally until the node is restarted. 
    To work around this issue, users should either keep slashing protection enabled on the external signer or restart the node after calling the add api. 

data/beaconrestapi/src/integration-test/resources/tech/pegasys/teku/beaconrestapi/beacon/paths/_eth_v1_beacon_states_{state_id}_builders.json

@@ -0,0 +1,100 @@
+{
+  "post" : {
+    "tags" : [ "Beacon" ],
+    "operationId" : "getStateBuilders",
+    "summary" : "Get builders from state",
+    "description" : "Returns filterable list of builders with their status and index.",
+    "parameters" : [ {
+      "name" : "state_id",
+      "required" : true,
+      "in" : "path",
+      "schema" : {
+        "type" : "string",
+        "description" : "State identifier. Can be one of: \"head\" (canonical head in node's view), \"genesis\", \"finalized\", \"justified\", <slot>, <hex encoded stateRoot with 0x prefix>.",
+        "example" : "head"
+      }
+    } ],
+    "requestBody" : {
+      "required" : false,
+      "content" : {
+        "application/json" : {
+          "schema" : {
+            "$ref" : "#/components/schemas/PostStateBuildersRequestBody"
+          }
+        }
+      }
+    },
+    "responses" : {
+      "200" : {
+        "description" : "Request successful",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/GetStateBuildersResponse"
+            }
+          },
+          "application/octet-stream" : {
+            "schema" : {
+              "type" : "string",
+              "format" : "binary"
+            }
+          }
+        }
+      },
+      "404" : {
+        "description" : "Not found",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/HttpErrorResponse"
+            }
+          }
+        }
+      },
+      "406" : {
+        "description" : "Not acceptable",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/HttpErrorResponse"
+            }
+          }
+        }
+      },
+      "503" : {
+        "description" : "Service unavailable",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/HttpErrorResponse"
+            }
+          }
+        }
+      },
+      "204" : {
+        "description" : "Data is unavailable because the chain has not yet reached genesis",
+        "content" : { }
+      },
+      "400" : {
+        "description" : "The request could not be processed, check the response for more information.",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/HttpErrorResponse"
+            }
+          }
+        }
+      },
+      "500" : {
+        "description" : "Internal server error",
+        "content" : {
+          "application/json" : {
+            "schema" : {
+              "$ref" : "#/components/schemas/HttpErrorResponse"
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/beaconrestapi/src/integration-test/resources/tech/pegasys/teku/beaconrestapi/beacon/schema/BuilderResponse.json

@@ -0,0 +1,19 @@
+{
+  "title" : "BuilderResponse",
+  "type" : "object",
+  "required" : [ "index", "status", "builder" ],
+  "properties" : {
+    "index" : {
+      "type" : "string",
+      "description" : "unsigned 64 bit integer",
+      "example" : "1",
+      "format" : "uint64"
+    },
+    "status" : {
+      "type" : "number"
+    },
+    "builder" : {
+      "$ref" : "#/components/schemas/Builder"
+    }
+  }
+}

data/beaconrestapi/src/integration-test/resources/tech/pegasys/teku/beaconrestapi/beacon/schema/GetStateBuildersResponse.json

@@ -0,0 +1,19 @@
+{
+  "title" : "GetStateBuildersResponse",
+  "type" : "object",
+  "required" : [ "execution_optimistic", "finalized", "data" ],
+  "properties" : {
+    "execution_optimistic" : {
+      "type" : "boolean"
+    },
+    "finalized" : {
+      "type" : "boolean"
+    },
+    "data" : {
+      "type" : "array",
+      "items" : {
+        "$ref" : "#/components/schemas/BuilderResponse"
+      }
+    }
+  }
+}

data/beaconrestapi/src/integration-test/resources/tech/pegasys/teku/beaconrestapi/beacon/schema/PostStateBuildersRequestBody.json

@@ -0,0 +1,13 @@
+{
+  "title" : "PostStateBuildersRequestBody",
+  "type" : "object",
+  "required" : [ ],
+  "properties" : {
+    "ids" : {
+      "type" : "array",
+      "items" : {
+        "type" : "string"
+      }
+    }
+  }
+}

data/beaconrestapi/src/main/java/tech/pegasys/teku/beaconrestapi/addon/GloasRestApiBuilderAddon.java

@@ -19,6 +19,7 @@
 import tech.pegasys.teku.beaconrestapi.handlers.v1.beacon.GetPayloadAttestations;
 import tech.pegasys.teku.beaconrestapi.handlers.v1.beacon.PostPayloadAttestations;
 import tech.pegasys.teku.beaconrestapi.handlers.v1.beacon.PostPublishExecutionPayloadBid;
+import tech.pegasys.teku.beaconrestapi.handlers.v1.beacon.PostStateBuilders;
 import tech.pegasys.teku.beaconrestapi.handlers.v1.validator.GetExecutionPayloadBid;
 import tech.pegasys.teku.infrastructure.restapi.RestApiBuilder;
 import tech.pegasys.teku.spec.Spec;
@@ -50,6 +51,7 @@ public RestApiBuilder apply(final RestApiBuilder builder) {
         .endpoint(new GetPayloadAttestations(dataProvider, schemaCache))
         .endpoint(new PostPayloadAttestations(dataProvider, spec, schemaCache))
         .endpoint(new GetExecutionPayloadBid(dataProvider, schemaCache))
-        .endpoint(new PostPublishExecutionPayloadBid(dataProvider, schemaCache));
+        .endpoint(new PostPublishExecutionPayloadBid(dataProvider, schemaCache))
+        .endpoint(new PostStateBuilders(dataProvider));
   }
 }

data/beaconrestapi/src/main/java/tech/pegasys/teku/beaconrestapi/handlers/v1/beacon/PostStateBuilders.java

@@ -0,0 +1,125 @@
+/*
+ * Copyright Consensys Software Inc., 2026
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package tech.pegasys.teku.beaconrestapi.handlers.v1.beacon;
+
+import static tech.pegasys.teku.beaconrestapi.BeaconRestApiTypes.PARAMETER_STATE_ID;
+import static tech.pegasys.teku.ethereum.json.types.beacon.StateBuilderRequestBodyType.STATE_BUILDER_REQUEST_TYPE;
+import static tech.pegasys.teku.infrastructure.http.HttpStatusCodes.SC_BAD_REQUEST;
+import static tech.pegasys.teku.infrastructure.http.HttpStatusCodes.SC_OK;
+import static tech.pegasys.teku.infrastructure.http.RestApiConstants.EXECUTION_OPTIMISTIC;
+import static tech.pegasys.teku.infrastructure.http.RestApiConstants.FINALIZED;
+import static tech.pegasys.teku.infrastructure.http.RestApiConstants.TAG_BEACON;
+import static tech.pegasys.teku.infrastructure.json.types.CoreTypes.BOOLEAN_TYPE;
+import static tech.pegasys.teku.infrastructure.json.types.CoreTypes.RAW_INTEGER_TYPE;
+import static tech.pegasys.teku.infrastructure.json.types.CoreTypes.UINT64_TYPE;
+
+import com.fasterxml.jackson.core.JsonParseException;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.google.common.base.Throwables;
+import java.util.List;
+import java.util.Optional;
+import tech.pegasys.teku.api.ChainDataProvider;
+import tech.pegasys.teku.api.DataProvider;
+import tech.pegasys.teku.api.migrated.StateBuilderData;
+import tech.pegasys.teku.ethereum.json.types.EthereumTypes;
+import tech.pegasys.teku.ethereum.json.types.beacon.StateBuilderRequestBodyType;
+import tech.pegasys.teku.infrastructure.async.SafeFuture;
+import tech.pegasys.teku.infrastructure.json.types.SerializableTypeDefinition;
+import tech.pegasys.teku.infrastructure.restapi.endpoints.AsyncApiResponse;
+import tech.pegasys.teku.infrastructure.restapi.endpoints.EndpointMetadata;
+import tech.pegasys.teku.infrastructure.restapi.endpoints.RestApiEndpoint;
+import tech.pegasys.teku.infrastructure.restapi.endpoints.RestApiRequest;
+import tech.pegasys.teku.infrastructure.ssz.SszList;
+import tech.pegasys.teku.spec.datastructures.metadata.ObjectAndMetaData;
+import tech.pegasys.teku.spec.datastructures.state.versions.gloas.Builder;
+
+public class PostStateBuilders extends RestApiEndpoint {
+  public static final String ROUTE = "/eth/v1/beacon/states/{state_id}/builders";
+  private final ChainDataProvider chainDataProvider;
+
+  static final SerializableTypeDefinition<StateBuilderData> STATE_BUILDER_DATA_TYPE =
+      SerializableTypeDefinition.<StateBuilderData>object()
+          .name("BuilderResponse")
+          .withField("index", UINT64_TYPE, StateBuilderData::getIndex)
+          .withField("status", RAW_INTEGER_TYPE, StateBuilderData::getStatus)
+          .withField(
+              "builder", Builder.SSZ_SCHEMA.getJsonTypeDefinition(), StateBuilderData::getBuilder)
+          .build();
+
+  static final SerializableTypeDefinition<ObjectAndMetaData<SszList<StateBuilderData>>>
+      RESPONSE_TYPE =
+          SerializableTypeDefinition.<ObjectAndMetaData<SszList<StateBuilderData>>>object()
+              .name("GetStateBuildersResponse")
+              .withField(
+                  EXECUTION_OPTIMISTIC, BOOLEAN_TYPE, ObjectAndMetaData::isExecutionOptimistic)
+              .withField(FINALIZED, BOOLEAN_TYPE, ObjectAndMetaData::isFinalized)
+              .withField(
+                  "data",
+                  SerializableTypeDefinition.listOf(STATE_BUILDER_DATA_TYPE),
+                  data -> data.getData().asList())
+              .build();
+
+  public PostStateBuilders(final DataProvider dataProvider) {
+    this(dataProvider.getChainDataProvider());
+  }
+
+  PostStateBuilders(final ChainDataProvider chainDataProvider) {
+    super(
+        EndpointMetadata.post(ROUTE)
+            .operationId("getStateBuilders")
+            .summary("Get builders from state")
+            .description("Returns filterable list of builders with their status and index.")
+            .pathParam(PARAMETER_STATE_ID)
+            .optionalRequestBody()
+            .requestBodyType(STATE_BUILDER_REQUEST_TYPE)
+            .tags(TAG_BEACON)
+            .response(SC_OK, "Request successful", RESPONSE_TYPE, EthereumTypes.sszResponseType())
+            .withNotFoundResponse()
+            .withNotAcceptedResponse()
+            .withChainDataResponses()
+            .build());
+    this.chainDataProvider = chainDataProvider;
+  }
+
+  @Override
+  public void handleRequest(final RestApiRequest request) throws JsonProcessingException {
+    final Optional<StateBuilderRequestBodyType> requestBody;
+
+    try {
+      requestBody = request.getOptionalRequestBody();
+    } catch (RuntimeException e) {
+      final Throwable throwable = Throwables.getRootCause(e);
+      if (throwable instanceof JsonParseException) {
+        request.respondError(SC_BAD_REQUEST, throwable.getMessage());
+      } else {
+        throw e;
+      }
+      return;
+    }
+
+    final List<String> builderIds =
+        requestBody.map(StateBuilderRequestBodyType::getIds).orElse(List.of());
+
+    final SafeFuture<Optional<ObjectAndMetaData<SszList<StateBuilderData>>>> future =
+        chainDataProvider.getStateBuilders(
+            request.getPathParameter(PARAMETER_STATE_ID), builderIds);
+
+    request.respondAsync(
+        future.thenApply(
+            maybeData ->
+                maybeData
+                    .map(AsyncApiResponse::respondOk)
+                    .orElseGet(AsyncApiResponse::respondNotFound)));
+  }
+}