Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Add block v3 endpoint. #339

Merged
merged 6 commits into from
Jul 28, 2023
Merged

Add block v3 endpoint. #339

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
07d9752
Add block v3 endpoint.
mcdee Jul 16, 2023
7d11c25
Deprecate blinded block request.
mcdee Jul 16, 2023
8766d92
Add JSON metadata.
mcdee Jul 21, 2023
d3b9cce
Clearer metadata names.
mcdee Jul 22, 2023
fca70b2
Use standard name for metadata.
mcdee Jul 24, 2023
6a0755e
Merge branch 'master' into block-v3
mcdee Jul 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions apis/validator/blinded_block.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions apis/validator/block.v2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
98 changes: 98 additions & 0 deletions apis/validator/block.v3.yaml
View file
Open in desktop
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-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'
13 changes: 13 additions & 0 deletions beacon-node-oapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Required in response so client can deserialize returned json or ssz data to the correct object.
description: Required in response so client can deserialize returned JSON or SSZ data to the correct object.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing Eth-Consensus-Version uses lower-case so I stuck with it for consistency.

required: true
schema:
type: boolean
Eth-Execution-Payload-Value:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without the consensus value, there's no (reasonable) way for a VC to compare blocks for profit - should we add this here?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does Nimbus already compute this value during block proposal? Lighthouse sort of does, but approximates slightly (if there are slashable attestations we don't keep track of the rewards from both).

It would make VC block choosing more fair, as the heuristics Vouch uses currently seem to favour Prysm despite Prysm's blocks being less profitable than Lighthouse and Nimbus on average (according to my blockprint nodes, public dash coming soon).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could this be a new PR? this one is closed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does Nimbus already compute this value during block proposal?

We do it for offline analysis for historical blocks (to pick out more detail than is needed for state transitions) but making it "online" would probably not be too hard - indeed, the VC currently has to do a lot of guesswork and it will likely always be wrong / skewed - further exacerbating the problem is that in that guesswork, it's not working with eth-denominated data usually but rather "fresh attestation count" and similar proxies which prevents the value from being compared with the execution profit (ie low cl+high el vs low cl+high el score)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could this be a new PR? this one is closed.

#358

description: Required in response so client can determine relative value of execution payloads.
required: true
schema:
$ref: './types/primitive.yaml#/Wei'
3 changes: 3 additions & 0 deletions types/primitive.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
Loading