Add block v3 endpoint. #339
There are no files selected for viewing
This file contains 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 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 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,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-Blinded-Payload: | ||
| $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Blinded-Payload' | ||
| Eth-Payload-Value: | ||
| $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Payload-Value' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: ProduceBlockV3Response | ||
| type: object | ||
| properties: | ||
| consensus-version: | ||
mcdee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| type: string | ||
| enum: [ phase0, altair, bellatrix, capella, deneb ] | ||
| example: "phase0" | ||
| blinded-payload: | ||
| type: boolean | ||
| example: false | ||
| 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' | ||
This file contains 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 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 |
|---|---|---|
|
|
@@ -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" | ||
|
|
||
|
|
||
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.
Headers are required for SSZ returns. Should the added two headers be also present as JSON values to the
application/jsonresponse type? Otherwise, why include version as property but not the payload value.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.
Yeah, wasn't sure about that. In the past we added the version to the JSON to allow for decoding, but it has pretty much been replaced with the header values now (as you don't need to do any mucking around with parsing streams to obtain the values from the headers). I'm not averse to putting these new values in the JSON metadata, but not sure if they add significant value any more.
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.
do we do something controversial and just return the json object not wrapped in a 'data' and have it just the json object or the ssz object determined by header?
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.
It would definitely break the standard from other routes and prevent allowing to add more fields in the future. I would mirror the header values in the JSON type for overall consistency. It's easier to parse a JSON reply than headers for client side tooling that deals with JSON only
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.
@dapplion yeah I'm thinking the same. If the metadata fields are in the JSON then it will allow parsing of the JSON separate from the HTTP response (e.g. if the JSON is saved and parsed later). I'll update accordingly.
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.
Updated. One question that rises from this is the naming of the fields: do we want to explicitly state which values are related to the execution payload, i.e.
blinded-execution-payloadrather thanblinded-payloadexecution-payload-valuerather thanpayload-value(and equivalent change for the header fields). Obviously this makes them a little more verbose, but is safer if we ever end up with other payloads in the beacon block. Thoughts?
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.
if we went that way, i'd probably suggest something like
i don't mind either way on whether we expand it...
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.
Have updated to use these names, agree that they are a bit clearer. I think that this looks like the best way forward;
@dapplion @rolfyone agree/disagree?