-
Notifications
You must be signed in to change notification settings - Fork 207
Produce block v4 with payload #580
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
shane-moore
wants to merge
7
commits into
ethereum:master
Choose a base branch
from
shane-moore:produce-block-v4-with-payload
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
e902e3b
add flag to include payload in produceBlockV4
shane-moore 56be573
chore: add include_payload_flag
shane-moore e74fde6
chore: add get payload envelope
shane-moore 5c28168
stateful and stateless envelope post
shane-moore 6ee20eb
update validator flow
shane-moore 25de51f
chore: update changelog
shane-moore 0c45859
chore: remove builder index from get execution payload envelope
shane-moore File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| post: | ||
| operationId: publishExecutionPayloadEnvelope | ||
| summary: Publish signed execution payload envelope | ||
| description: | | ||
| Instructs the beacon node to broadcast a signed execution payload envelope to the network, | ||
| to be gossiped for payload validation. A success response (20x) indicates | ||
| that the envelope passed gossip validation and was successfully broadcast onto the network. | ||
|
|
||
| The request body can be either: | ||
| - A `SignedExecutionPayloadEnvelopeContents` object containing the signed envelope along with | ||
| blobs and KZG proofs. This is used in stateless operation (multi-BN setups, DVs, failover) | ||
| where the receiving beacon node does not have the blobs cached. | ||
| - A `SignedExecutionPayloadEnvelope` object containing only the signed envelope. This is used | ||
| in stateful operation where the beacon node already has the blobs and KZG proofs cached | ||
| from block production. | ||
| tags: | ||
| - Beacon | ||
| - ValidatorRequiredApi | ||
| parameters: | ||
| - in: header | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion" | ||
| required: true | ||
| name: Eth-Consensus-Version | ||
| description: "The active consensus version to which the execution payload envelope being submitted belongs." | ||
| requestBody: | ||
| description: "The `SignedExecutionPayloadEnvelopeContents` or `SignedExecutionPayloadEnvelope` object to be broadcast." | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| anyOf: | ||
| - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelopeContents" | ||
| - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `SignedExecutionPayloadEnvelopeContents` or `SignedExecutionPayloadEnvelope` bytes. Use Content-Type header to specify this format" | ||
| responses: | ||
| "200": | ||
| description: "The envelope was validated successfully and has been broadcast." | ||
| "400": | ||
| description: "The SignedExecutionPayloadEnvelope object is invalid or failed gossip validation" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 400 | ||
| message: "Invalid signed execution payload envelope" | ||
| "415": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" | ||
| "500": | ||
| $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| get: | ||
| tags: | ||
| - Validator | ||
| - ValidatorRequiredApi | ||
| operationId: "produceBlockV4" | ||
| 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. | ||
|
|
||
| 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 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 | ||
| 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, 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}`. 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 | ||
| description: | | ||
| Percentage multiplier to apply to the builder's payload value when choosing between a | ||
| builder payload header and payload from the paired execution node. This parameter is only | ||
| relevant if the beacon node is connected to a builder, deems it safe to produce a builder | ||
| payload, and receives valid responses from both the builder endpoint _and_ 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 full (unblinded) block containing the execution node payload. | ||
| * otherwise, return a blinded block containing the builder payload header. | ||
|
|
||
| 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 external builder payload 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 this parameter is | ||
| provided and the beacon node is not configured with a builder then the beacon node MUST | ||
| respond with a full block, 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" | ||
| 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: "ProduceBlockV4Response" | ||
| 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" | ||
| "500": | ||
| $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' | ||
| "503": | ||
| $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| get: | ||
| operationId: getExecutionPayloadEnvelope | ||
| summary: Get execution payload envelope | ||
| description: | | ||
| Retrieves the cached execution payload envelope for the current proposer's slot, which can | ||
| then be signed and published by the validator. The envelope contains the full execution payload | ||
| along with associated metadata. | ||
|
|
||
| The beacon node only caches the envelope for the current slot's self-built payload. Requests for | ||
| older slots or slots where no envelope has been cached will return a 404 error. This endpoint does | ||
| not fetch payloads from the execution layer. | ||
|
|
||
| Depending on `Accept` header, the response can be returned either as JSON or as bytes serialized by SSZ. | ||
| tags: | ||
| - Validator | ||
| - ValidatorRequiredApi | ||
| parameters: | ||
| - name: slot | ||
| in: path | ||
| required: true | ||
| description: "Slot for which the execution payload envelope is requested." | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" | ||
| - name: beacon_block_root | ||
| in: query | ||
| required: false | ||
| description: | | ||
| Optional root of the beacon block associated with this execution payload envelope. | ||
| When provided, the beacon node will verify that the cached envelope matches the | ||
| given block root, returning a 404 if there is no match. This is useful for | ||
| disambiguation in fork scenarios where the same slot may have multiple competing blocks. | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/Root" | ||
| responses: | ||
| "200": | ||
| description: "Successful response" | ||
| headers: | ||
| Eth-Consensus-Version: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetExecutionPayloadEnvelopeResponse | ||
| type: object | ||
| required: [version, data] | ||
| properties: | ||
| version: | ||
| type: string | ||
| enum: [gloas] | ||
| example: "gloas" | ||
| data: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadEnvelope" | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `ExecutionPayloadEnvelope` bytes. Use Accept header to choose this response type" | ||
| "400": | ||
| description: "Invalid execution payload envelope request" | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 400 | ||
| message: "Invalid slot parameter" | ||
| "404": | ||
| description: "No cached execution payload envelope available for the requested slot. The beacon node only caches the envelope for the current proposer's self-built payload." | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" | ||
| example: | ||
| code: 404 | ||
| message: "Execution payload envelope not available for slot" | ||
| "406": | ||
| $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" | ||
| "500": | ||
| $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
while implementing this, I noticed the slot alone is not definitive enough (eg. in case of forks), we should consider also passing the
beacon_block_roothereThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hm, what do you think about making it optional to pass
beacon_block_rootlike in 0c45859? pretty sure the VC already computes the block's tree hash root during signing, so passing it here should be straightforwardThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, we do already compute the block root on the vc side. I am not a big fan of optional parameters, so I'd rather have it as required or remove it if it's not needed, so far it makes our implementation simpler, maybe get more feedback from others who already implemented the apis