diff --git a/apis/validator/block.v4.yaml b/apis/validator/block.v4.yaml index f53f4241..ef7290d2 100644 --- a/apis/validator/block.v4.yaml +++ b/apis/validator/block.v4.yaml @@ -11,6 +11,14 @@ get: so there is no longer a concept of blinded or unblinded blocks. Builders release the payload later. This endpoint is specific to the post-Gloas forks and is not backwards compatible with previous forks. + + When self-building (local execution payload), the response will include the full block contents + including the beacon block, execution payload envelope, blobs, and KZG proofs. + When using an external builder bid, only the `BeaconBlock` is returned as the beacon node + does not have access to the builder's execution payload. + + The `Eth-Execution-Payload-Included` header and `execution_payload_included` response field + indicate which response type was returned. parameters: - name: slot in: path @@ -32,6 +40,29 @@ get: $ref: '../../beacon-node-oapi.yaml#/components/schemas/Graffiti' - name: skip_randao_verification $ref: '../../beacon-node-oapi.yaml#/components/parameters/SkipRandaoVerification' + - name: include_payload + in: query + required: false + description: | + Controls whether the execution payload envelope and blobs are included in the response + when self-building (using local execution payload). + + When `true` (default), the response includes the full block contents: beacon block, + execution payload envelope, blobs, and KZG proofs. This enables stateless operation + where the validator client can use multiple beacon nodes (multi-BN setups, DVs, failover). + + When `false`, only the beacon block is returned and the beacon node caches the execution + payload envelope and blobs internally. The validator client must then fetch them separately + via `GET /eth/v1/validator/execution_payload_envelope/{slot}/{builder_index}`. This saves + bandwidth but requires the validator client to publish via the same beacon node that + produced the block (stateful operation). + + This parameter only affects self-building scenarios. When using an external builder's bid, + only the beacon block is returned regardless of this parameter (the beacon node does not + have access to the builder's execution payload). + schema: + type: boolean + default: true - name: builder_boost_factor in: query required: false @@ -72,12 +103,14 @@ get: $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' Eth-Consensus-Block-Value: $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Block-Value' + Eth-Execution-Payload-Included: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Included' content: application/json: schema: title: "ProduceBlockV4Response" type: object - required: [version, consensus_block_value, data] + required: [version, consensus_block_value, execution_payload_included, data] properties: version: type: string @@ -87,11 +120,21 @@ get: type: string example: "12345" description: "Consensus rewards for this block in Wei" + execution_payload_included: + type: boolean + description: | + Indicates whether the execution payload envelope is included in the response. + When `true`, the `data` field contains the full + execution payload envelope, blobs, and KZG proofs. When `false`, the `data` + field contains only a `BeaconBlock`. + example: false data: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock" + anyOf: + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BlockContents" application/octet-stream: schema: - description: "SSZ serialized `BeaconBlock` bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." + description: "SSZ serialized `BeaconBlock` or `BlockContents` bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and payload inclusion indicated by `Eth-Execution-Payload-Included` header." "400": description: "Invalid block production request" content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index dc612d42..aa3b3b0a 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -451,6 +451,8 @@ components: $ref: "./types/gloas/block.yaml#/Gloas/BeaconBlock" Gloas.SignedBeaconBlock: $ref: "./types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + Gloas.BlockContents: + $ref: "./types/gloas/block_contents.yaml#/Gloas/BlockContents" Gloas.ExecutionPayloadBid: $ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" Gloas.SignedExecutionPayloadBid: @@ -538,3 +540,9 @@ components: required: true schema: $ref: './types/primitive.yaml#/Wei' + Eth-Execution-Payload-Included: + description: | + Indicates whether the execution payload envelope, blobs, and KZG proofs are included in the response. Required in response so client can deserialize returned data. + required: true + schema: + type: boolean diff --git a/types/gloas/block_contents.yaml b/types/gloas/block_contents.yaml new file mode 100644 index 00000000..84206540 --- /dev/null +++ b/types/gloas/block_contents.yaml @@ -0,0 +1,17 @@ +Gloas: + BlockContents: + type: object + description: | + Block contents for self-building, including the execution payload envelope + and blobs. This enables stateless failover to another beacon node for publishing, + as all required data is returned in a single response. + required: [block, execution_payload_envelope, kzg_proofs, blobs] + properties: + block: + $ref: "./block.yaml#/Gloas/BeaconBlock" + execution_payload_envelope: + $ref: "./execution_payload_envelope.yaml#/Gloas/ExecutionPayloadEnvelope" + kzg_proofs: + $ref: "../fulu/block_contents.yaml#/Fulu/KZGProofs" + blobs: + $ref: "../deneb/block_contents.yaml#/Deneb/Blobs"