diff --git a/apis/builder/blinded_blocks.yaml b/apis/builder/blinded_blocks.yaml index 1e0b0c7..6f896df 100644 --- a/apis/builder/blinded_blocks.yaml +++ b/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" @@ -37,10 +40,16 @@ post: $ref: "../../builder-oapi.yaml#/components/examples/Capella.SignedBlindedBeaconBlock" deneb: $ref: "../../builder-oapi.yaml#/components/examples/Deneb.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: @@ -64,6 +73,9 @@ post: $ref: "../../builder-oapi.yaml#/components/examples/Capella.ExecutionPayload" deneb: $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: @@ -74,5 +86,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" diff --git a/apis/builder/header.yaml b/apis/builder/header.yaml index 5854e1d..fee2984 100644 --- a/apis/builder/header.yaml +++ b/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: @@ -58,6 +62,9 @@ get: $ref: "../../builder-oapi.yaml#/components/examples/Capella.SignedBuilderBid" deneb: $ref: "../../builder-oapi.yaml#/components/examples/Deneb.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": @@ -71,5 +78,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" diff --git a/builder-oapi.yaml b/builder-oapi.yaml index 21d46e3..bf95feb 100644 --- a/builder-oapi.yaml +++ b/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 ] + example: "bellatrix" Bellatrix.ExecutionPayload: $ref: "./beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload" Bellatrix.SignedBlindedBeaconBlock: @@ -81,6 +96,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: diff --git a/types/http.yaml b/types/http.yaml index 0a8f13c..8fff6e3 100644 --- a/types/http.yaml +++ b/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."