diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index 52edf072..20c2d42b 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -4,6 +4,7 @@ get: - Validator operationId: "produceBlindedBlock" summary: "Produce a new blinded block, without signature." + deprecated: true description: | Requests a beacon node to produce a valid blinded block, which can then be signed by a validator. A blinded block is a block with only a transactions root, rather than a full transactions list. diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index 403d4ffb..29ac4cc9 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -4,6 +4,7 @@ get: - Validator operationId: "produceBlockV2" summary: "Produce a new block, without signature." + deprecated: true description: | Requests a beacon node to produce a valid block, which can then be signed by a validator. diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml new file mode 100644 index 00000000..632863a3 --- /dev/null +++ b/apis/validator/block.v3.yaml @@ -0,0 +1,98 @@ +get: + tags: + - ValidatorRequiredApi + - Validator + operationId: "produceBlockV3" + summary: "Produce a new block, without signature." + description: | + Requests a beacon node to produce a valid block, which can then be signed by a validator. The + returned block may be blinded or unblinded, depending on the current state of the network as + decided by the execution and beacon nodes. + + The beacon node must return an unblinded block if it obtains the execution payload from its + paired execution node. It must only return a blinded block if it obtains the execution payload + header from an MEV relay. + + Metadata in the response indicates the type of block produced, and the supported types of block + will be added to as forks progress. + parameters: + - name: slot + in: path + required: true + description: "The slot for which the block should be proposed." + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" + - name: randao_reveal + in: query + required: true + description: "The validator's randao reveal value." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Signature' + - name: graffiti + in: query + required: false + description: "Arbitrary data validator wants to include in block." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Graffiti' + - name: skip_randao_verification + in: query + required: false + description: | + Skip verification of the `randao_reveal` value. If this flag is set then the + `randao_reveal` must be set to the point at infinity (`0xc0..00`). This query parameter + is a flag and does not take a value. + schema: {} + allowEmptyValue: true + responses: + "200": + description: Success response + headers: + Eth-Consensus-Version: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + Eth-Execution-Payload-Blinded: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Blinded' + Eth-Execution-Payload-Value: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Value' + content: + application/json: + schema: + title: ProduceBlockV3Response + type: object + properties: + version: + type: string + enum: [ phase0, altair, bellatrix, capella, deneb ] + example: "phase0" + execution-payload-blinded: + type: boolean + example: false + execution-payload-value: + type: string + example: "12345" + data: + oneOf: + - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconBlock' + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBlockContents" + application/octet-stream: + schema: + description: "SSZ serialized block or blinded block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and block type in `Eth-Blinded-Payload`." + "400": + description: "Invalid block production request" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + examples: + InvalidRequest: + value: + code: 400 + message: "Invalid request to produce a block" + "500": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' + "503": + $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index c63c6df4..01560874 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -174,6 +174,8 @@ paths: $ref: "./apis/validator/duties/sync.yaml" /eth/v2/validator/blocks/{slot}: $ref: "./apis/validator/block.v2.yaml" + /eth/v3/validator/blocks/{slot}: + $ref: "./apis/validator/block.v3.yaml" /eth/v1/validator/blinded_blocks/{slot}: $ref: "./apis/validator/blinded_block.yaml" /eth/v1/validator/attestation_data: @@ -330,6 +332,7 @@ components: Bellatrix.SignedBlindedBeaconBlock: $ref: './types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock' ConsensusVersion: + type: string enum: [phase0, altair, bellatrix, capella, deneb] example: "phase0" SignedValidatorRegistration: @@ -421,3 +424,13 @@ components: required: true schema: $ref: '#/components/schemas/ConsensusVersion' + Eth-Execution-Payload-Blinded: + description: Required in response so client can deserialize returned json or ssz data to the correct object. + required: true + schema: + type: boolean + Eth-Execution-Payload-Value: + description: Required in response so client can determine relative value of execution payloads. + required: true + schema: + $ref: './types/primitive.yaml#/Wei' diff --git a/types/primitive.yaml b/types/primitive.yaml index 65fe7dde..f87a4718 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -23,6 +23,9 @@ GenesisTime: - example: "1590832934" - description: "The genesis_time configured for the beacon node, which is the unix time in seconds at which the Eth2.0 chain began." +Wei: + $ref: "./primitive.yaml#/Uint256" + Gwei: $ref: "./primitive.yaml#/Uint64"