deploy: 875882d

builder-oapi.yaml

@@ -5,6 +5,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
@@ -199,6 +210,20 @@ paths:
       responses:
         '200':
           description: Success response.
+          headers:
+            Eth-Consensus-Version:
+              required: false
+              schema:
+                enum:
+                  - bellatrix
+                  - capella
+                  - deneb
+                  - electra
+                example: bellatrix
+                type: string
+              description: |
+                The active consensus version to which the data belongs. Required in response so client can deserialize returned json or ssz data 
+                more effectively.
           content:
             application/json:
               schema:
@@ -968,6 +993,9 @@ paths:
                         value: '1'
                         pubkey: '0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a'
                       signature: '0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505'
+            application/octet-stream:
+              schema:
+                description: SSZ serialized `SignedBuilderBid` bytes. Use Accept header to choose this response type
         '204':
           description: No header is available.
         '400':
@@ -997,6 +1025,31 @@ paths:
                   value:
                     code: 400
                     message: 'Unknown hash: missing parent hash'
+        '406':
+          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
         '500':
           description: Builder node internal error.
           content:
@@ -1036,20 +1089,21 @@ paths:
         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:
-            type: string
             enum:
-              - phase0
-              - altair
               - bellatrix
               - capella
               - deneb
               - electra
-            example: phase0
+            example: bellatrix
+            type: string
           required: false
           name: Eth-Consensus-Version
           description: Version of the block being submitted
@@ -4428,9 +4482,28 @@ paths:
                             source_pubkey: '0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a'
                             target_pubkey: '0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a'
                   signature: '0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505'
+          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:
+              required: false
+              description: |
+                The active consensus version to which the data belongs. Required in response so client can deserialize returned json or ssz data 
+                more effectively.
+              schema:
+                type: string
+                enum:
+                  - phase0
+                  - altair
+                  - bellatrix
+                  - capella
+                  - deneb
+                  - electra
+                example: phase0
           content:
             application/json:
               schema:
@@ -4933,6 +5006,9 @@ paths:
                           - '0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a'
                         blobs:
                           - '0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739'
+            application/octet-stream:
+              schema:
+                description: SSZ serialized `ExecutionPayload` or `ExecutionPayloadAndBlobsBundle` bytes. Use Accept header to choose this response type
         '400':
           description: Error response.
           content:
@@ -4959,6 +5035,56 @@ paths:
                   - example:
                       code: 400
                       message: 'Invalid block: missing signature'
+        '406':
+          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
+        '415':
+          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.
         '500':
           description: Builder node internal error.
           content:
@@ -5053,6 +5179,14 @@ components:
           type: array
           items:
             type: string
+    ConsensusVersion:
+      enum:
+        - bellatrix
+        - capella
+        - deneb
+        - electra
+      example: bellatrix
+      type: string
     Bellatrix.ExecutionPayload:
       allOf:
         - type: object
@@ -8908,6 +9042,72 @@ components:
           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.
+  headers:
+    Eth-Consensus-Version:
+      schema:
+        type: string
+        enum:
+          - phase0
+          - altair
+          - bellatrix
+          - capella
+          - deneb
+          - electra
+        example: phase0
+      description: |
+        The active consensus version to which the data belongs. Required in response so client can deserialize returned json or ssz data 
+        more effectively.
+      required: true
   examples:
     Bellatrix.SignedBlindedBeaconBlock:
       value: