diff --git a/apis/beacon/blocks/blocks.yaml b/apis/beacon/blocks/blocks.yaml new file mode 100644 index 00000000..586991e4 --- /dev/null +++ b/apis/beacon/blocks/blocks.yaml @@ -0,0 +1,52 @@ +post: + tags: + - Beacon + - ValidatorRequiredApi + summary: "Publish a signed block." + operationId: "publishBlock" + description: | + Instructs the beacon node to broadcast a newly signed beacon block to the beacon network, + to be included in the beacon chain. The beacon node is not required to validate the signed + `BeaconBlock`, and a successful response (20X) only indicates that the broadcast has been + successful. The beacon node is expected to integrate the new block into its state, and + therefore validate the block internally, however blocks which fail the validation are still + broadcast but a different status code is returned (202) + parameters: + - in: header + schema: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' + required: false + name: Eth-Consensus-Version + description: "Version of the block being submitted, if using SSZ encoding." + requestBody: + description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature." + required: true + content: + application/json: + schema: + oneOf: + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock' + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock" + application/octet-stream: + schema: + description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." + responses: + "200": + description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database." + "202": + description: "The block failed validation, but was successfully broadcast anyway. It was not integrated into the beacon node's database." + "400": + description: "The `SignedBeaconBlock` object is invalid" + content: + application/json: + schema: + allOf: + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + - example: + code: 400 + message: "Invalid block: missing signature" + "500": + $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' + "503": + $ref: '../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' \ No newline at end of file diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 9b523107..da38f4b7 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -80,6 +80,8 @@ paths: $ref: "./apis/beacon/blocks/header.yaml" /eth/v1/beacon/blinded_blocks: $ref: "./apis/beacon/blocks/blinded_blocks.yaml" + /eth/v1/beacon/blocks: + $ref: "./apis/beacon/blocks/blocks.yaml" /eth/v2/beacon/blocks/{block_id}: $ref: "./apis/beacon/blocks/block.v2.yaml" /eth/v1/beacon/blocks/{block_id}/root: