Add SSZ support to builder api (#104)

* Add SSZ support to builder api

* Add electra to consensus version

Author: nflaig

apis/builder/blinded_blocks.yaml

@@ -11,12 +11,15 @@ post:
     failure.
 
     After Deneb, this endpoint will additionally return the associated blobs in the response.
+
+    Note: SSZ support can be determined by requesting an SSZ encoded response in the `getHeader`
+    request.
   tags:
     - Builder
   parameters:
     - in: header
       schema:
-        $ref: '../../beacon-apis/beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+        $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
       required: false
       name: Eth-Consensus-Version
       description: "Version of the block being submitted"
@@ -40,10 +43,16 @@ post:
             $ref: "../../builder-oapi.yaml#/components/examples/Deneb.SignedBlindedBeaconBlock"
           electra:
             $ref: "../../builder-oapi.yaml#/components/examples/Electra.SignedBlindedBeaconBlock"
-
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `SignedBlindedBeaconBlock` bytes. Use content type header to indicate that SSZ data is contained in the request body."
   responses:
     "200":
       description: Success response.
+      headers:
+        Eth-Consensus-Version:
+          $ref: "../../beacon-apis/beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version"
+          required: false
       content:
         application/json:
           schema:
@@ -69,6 +78,9 @@ post:
               $ref: "../../builder-oapi.yaml#/components/examples/Deneb.ExecutionPayloadAndBlobsBundle"
             electra:
               $ref: "../../builder-oapi.yaml#/components/examples/Deneb.ExecutionPayloadAndBlobsBundle"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `ExecutionPayload` or `ExecutionPayloadAndBlobsBundle` bytes. Use Accept header to choose this response type"
     "400":
       description: Error response.
       content:
@@ -79,5 +91,9 @@ post:
               - example:
                   code: 400
                   message: "Invalid block: missing signature"
+    "406":
+      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
     "500":
       $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/header.yaml

@@ -35,6 +35,10 @@ get:
   responses:
     "200":
       description: Success response.
+      headers:
+        Eth-Consensus-Version:
+          $ref: "../../builder-oapi.yaml#/components/headers/Eth-Consensus-Version"
+          required: false
       content:
         application/json:
           schema:
@@ -61,6 +65,9 @@ get:
               $ref: "../../builder-oapi.yaml#/components/examples/Deneb.SignedBuilderBid"
             electra:
               $ref: "../../builder-oapi.yaml#/components/examples/Electra.SignedBuilderBid"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `SignedBuilderBid` bytes. Use Accept header to choose this response type"
     "204":
       description: No header is available.
     "400":
@@ -74,5 +81,7 @@ get:
               value:
                 code: 400
                 message: "Unknown hash: missing parent hash"
+    "406":
+      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
     "500":
       $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

builder-oapi.yaml

@@ -6,6 +6,17 @@ info:
     API specification for external builder nodes. This interface enables
     validators to delegate block building duties.
 
+    All requests by default send and receive JSON, and as such should have either or both of the "Content-Type: application/json"
+    and "Accept: application/json" headers.  In addition, some requests can send and receive data in the SSZ format.  The header
+    "Content-Type: application/octet-stream" should be set in requests that contain SSZ data; a preference to receive SSZ data in
+    response can be indicated by setting the "Accept: application/octet-stream;q=1.0,application/json;q=0.9" header.  Note that
+    only a subset of requests can respond with data in SSZ format; these are noted in each individual request.
+
+    When handling requests, the server should return a 415 status code if the "Content-Type" header in the request specifies a format
+    that is not supported.  Similarly, it should return a 406 status code if it cannot produce a response in the format accepted by
+    the client as specified in the "Accept" header; if no "Accept" header is provided then it is assumed to be "application/json".
+    In any case, the server should indicate the format of the response by setting the corresponding "Content-Type" header.
+
     API endpoints are individually versioned. As such, there is no direct
     relationship between all v1 endpoints, all v2 endpoints, _etc._ and no such
     relationship should be inferred. The rules that require an increase in
@@ -57,6 +68,10 @@ components:
       $ref: "./beacon-apis/types/primitive.yaml#/Pubkey"
     ErrorMessage:
       $ref: "./beacon-apis/types/http.yaml#/ErrorMessage"
+    ConsensusVersion:
+      $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/schemas/ConsensusVersion"
+      enum: [ bellatrix, capella, deneb, electra ]
+      example: "bellatrix"
     Bellatrix.ExecutionPayload:
       $ref: "./beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
     Bellatrix.SignedBlindedBeaconBlock:
@@ -85,6 +100,16 @@ components:
   responses:
     InternalError:
       $ref: "./types/http.yaml#/InternalError"
+    NotAcceptable:
+      $ref: "./types/http.yaml#/NotAcceptable"
+    UnsupportedMediaType:
+      $ref: "./types/http.yaml#/UnsupportedMediaType"
+
+  headers:
+    Eth-Consensus-Version:
+      $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version"
+      schema:
+        $ref: "#/components/schemas/ConsensusVersion"
 
   examples:
     Bellatrix.SignedBlindedBeaconBlock:

types/http.yaml

@@ -21,3 +21,49 @@ InternalError:
       example:
         code: 500
         message: "Internal server error"
+NotAcceptable:
+  description: "Accepted media type is not supported."
+  content:
+    application/json:
+      schema:
+        type: object
+        required: [code, message]
+        properties:
+          code:
+            description: "The media type in \"Accept\" header is unsupported, and the request has been rejected. This occurs when the server cannot produce a response in the format accepted by the client."
+            type: number
+            example: 406
+          message:
+            description: "Message describing error"
+            type: string
+          stacktraces:
+            description: "Optional stacktraces, sent when node is in debug mode"
+            type: array
+            items:
+              type: string
+      example:
+        code: 406
+        message: "Accepted media type not supported"
+UnsupportedMediaType:
+  description: "Supplied content-type is not supported."
+  content:
+    application/json:
+      schema:
+        type: object
+        required: [code, message]
+        properties:
+          code:
+            description: "The media type in \"Content-Type\" header is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the server is not able to handle."
+            type: number
+            example: 415
+          message:
+            description: "Message describing error"
+            type: string
+          stacktraces:
+            description: "Optional stacktraces, sent when node is in debug mode"
+            type: array
+            items:
+              type: string
+      example:
+        code: 415
+        message: "Cannot read the supplied content type."