diff --git a/CHANGES.md b/CHANGES.md index b18d861f..0ef2bad0 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,6 +8,7 @@ There are likely to be descriptions etc outside of the list below, but new query | Endpoint | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) | |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| +| [#627](https://github.com/ethereum/beacon-APIs/pull/627) `POST /eth/v4/validator/blocks/{slot}/with_bid` added | | | | | | | [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v4/validator/blocks/{slot}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}` added | | | | | | | [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}` added | | | | | | diff --git a/apis/validator/block.v4_with_bid.yaml b/apis/validator/block.v4_with_bid.yaml new file mode 100644 index 00000000..e1600e8d --- /dev/null +++ b/apis/validator/block.v4_with_bid.yaml @@ -0,0 +1,175 @@ +post: + tags: + - Validator + - ValidatorRequiredApi + operationId: "produceBlockV4WithBid" + summary: "Produce a new block with best-effort inclusion of a supplied execution payload bid, without signature." + description: | + Requests a beacon node to produce a valid block with best-effort inclusion of the supplied + signed execution payload bid, which can then be signed by a validator. + + The beacon node MAY replace the supplied bid when its circuit breaker mechanism is active or + when the supplied bid is invalid. If the supplied bid is well-formed but fails validation, + the beacon node MUST continue block production using another viable bid or a local execution + payload. + + Post-Gloas, proposers submit execution payload bids rather than full execution payloads, + 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 the supplied 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 + 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 + $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, distributed validators, 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_envelopes/{slot}/{beacon_block_root}`. 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 the supplied external + builder 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 + description: | + Percentage multiplier to apply to the builder bid's value when choosing between that bid + and a payload from the paired execution node. The beacon node SHOULD use the supplied + `SignedExecutionPayloadBid` when it is valid, but MAY replace an invalid supplied bid with + another viable bid. This parameter is only relevant if a viable bid is available and the + beacon node receives a valid response from the paired execution node. When these + preconditions are met, the server MUST act as follows: + + * if `exec_node_payload_value >= builder_boost_factor * (builder_payload_value // 100)`, + then return a block committing to the local execution node payload (with the payload + itself included if `include_payload` is set to true). + * otherwise, return a block committing to the selected builder bid (without execution + payload, as it is not yet available). + + Servers must support the following values of the boost factor which encode common + preferences: + + * `builder_boost_factor=0`: prefer the local execution node payload unless an error makes + it unviable. + * `builder_boost_factor=100`: profit maximization mode; choose whichever payload pays + more. + * `builder_boost_factor=2**64 - 1`: prefer the selected builder bid unless an error or + beacon node health check makes it unviable. + + Servers should use saturating arithmetic or another technique to ensure that large values + of the `builder_boost_factor` do not trigger overflows or errors. If no viable bid is + available, the beacon node MUST respond with a block committing to the local execution + node payload, which the caller can choose to reject if it wishes. If the value is provided + but out of range for a 64-bit unsigned integer, then an error response with status code 400 + MUST be returned. + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" + requestBody: + description: "The `SignedExecutionPayloadBid` to consider for best-effort inclusion in the block." + required: true + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadBid" + application/octet-stream: + schema: + description: "SSZ serialized `SignedExecutionPayloadBid` bytes. Use Content-Type header to specify this format." + responses: + "200": + description: Success response + headers: + Eth-Consensus-Version: + $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: "ProduceBlockV4WithBidResponse" + type: object + required: [version, consensus_block_value, execution_payload_included, data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + consensus_block_value: + 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: + 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` 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: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + examples: + InvalidRequest: + value: + code: 400 + message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" + "415": + $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + "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 369a8f18..8a409c66 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -198,6 +198,8 @@ paths: $ref: "./apis/validator/block.v3.yaml" /eth/v4/validator/blocks/{slot}: $ref: "./apis/validator/block.v4.yaml" + /eth/v4/validator/blocks/{slot}/with_bid: + $ref: "./apis/validator/block.v4_with_bid.yaml" /eth/v1/validator/attestation_data: $ref: "./apis/validator/attestation_data.yaml" /eth/v1/validator/payload_attestation_data: diff --git a/validator-flow.md b/validator-flow.md index 79dc94e1..a9a55a84 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -23,6 +23,10 @@ If proposing block, then at immediate start of slot: - `include_payload=false`: returns only the `BeaconBlock`. The beacon node caches the execution payload envelope and blobs internally (stateful operation, must publish via the same beacon node). - When using an external builder's bid, only the `BeaconBlock` is returned regardless of `include_payload`. + - A validator client that already has a signed execution payload bid can instead use + [produceBlockV4WithBid](#/Validator/produceBlockV4WithBid). Inclusion is best effort: the + beacon node may replace the supplied bid when it is invalid or when its circuit breaker + mechanism is active. 2. Sign block 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature) 4. Post-Gloas, if self-building (proposer's own bid included in block):