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

Add validator spec #18

Merged
merged 7 commits into from
May 27, 2022
Merged

Add validator spec #18

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5b28094
update builder spec file
ralexstokes May 18, 2022
d398503
Add honest validator spec
ralexstokes May 18, 2022
a38375d
Update specs/validator.md
ralexstokes May 23, 2022
02090b4
whitespace
ralexstokes May 27, 2022
08e44e6
change language around how often to submit validator registrations
ralexstokes May 27, 2022
f5dd8e1
be explicit about what data types a validator needs to track for safe…
ralexstokes May 27, 2022
2ab456f
add note about not using builder software until the merge finalizes
ralexstokes May 27, 2022
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
37 changes: 21 additions & 16 deletions specs/README.md → specs/builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,27 @@
# Builder API
# Builder Specification

## Table of Contents

* [Constants](#constants)
* [Domain types](#domain-types)
* [Containers](#containers)
* [Independently Versioned](#independentlyversioned)
* [`ValidatorRegistrationV1`](#validatorregistrationv1)
* [`SignedValidatorRegistrationV1`](#signedvalidatorregistrationv1)
* [Fork Versioned](#forkversioned)
* [Bellatrix](#forkversioned)
* [`BuilderBid`](#builderbid)
* [`SignedBuilderBid`](#signedbuilderbid)
* [`BlindedBeaconBlockBody`](#blindedbeaconblockbody)
* [`BlindedBeaconBlock`](#blindedbeaconblock)
* [`SignedBlindedBeaconBlock`](#signedblindedbeaconblock)
* [Signing](#signing)
* [Endpoints](#endpoints)
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
ralexstokes marked this conversation as resolved.
Show resolved Hide resolved
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Constants](#constants)
- [Domain types](#domain-types)
- [Containers](#containers)
- [Independently Versioned](#independently-versioned)
- [`ValidatorRegistrationV1`](#validatorregistrationv1)
- [`SignedValidatorRegistrationV1`](#signedvalidatorregistrationv1)
- [Fork Versioned](#fork-versioned)
- [Bellatrix](#bellatrix)
- [`BuilderBid`](#builderbid)
- [`SignedBuilderBid`](#signedbuilderbid)
- [`BlindedBeaconBlockBody`](#blindedbeaconblockbody)
- [`BlindedBeaconBlock`](#blindedbeaconblock)
- [`SignedBlindedBeaconBlock`](#signedblindedbeaconblock)
- [Signing](#signing)
- [Endpoints](#endpoints)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Constants

Expand Down
153 changes: 153 additions & 0 deletions specs/validator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
# Builder -- Honest Validator

**Notice**: This document is a work-in-progress for researchers and implementers.

## Table of contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Constants](#constants)
- [Validator registration](#validator-registration)
- [Preparing a registration](#preparing-a-registration)
- [Signing and submitting a registration](#signing-and-submitting-a-registration)
- [Registration dissemination](#registration-dissemination)
- [Beacon chain responsibilities](#beacon-chain-responsibilities)
- [Block proposal](#block-proposal)
- [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
- [ExecutionPayload](#executionpayload)
- [Relation to local block building](#relation-to-local-block-building)
- [How to avoid slashing](#how-to-avoid-slashing)
- [Proposer slashing](#proposer-slashing)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Introduction

This document explains the way in which a beacon chain validator is expected to use the [Builder spec][builder-spec] to
participate in an external builder network.

At a high-level, there is a registration step validators must perform ahead of any proposal duties so builders know how
to craft blocks for their specific proposal. Having performed the registration, a validator waits until it is their turn
to propose the next block in the chain. The validator then requests an `ExecutionPayload` from the external builder
ralexstokes marked this conversation as resolved.
Show resolved Hide resolved
network to put into their `SignedBeaconBlock` in lieu of one they could build locally.
ralexstokes marked this conversation as resolved.
Show resolved Hide resolved

## Prerequisites

This document assumes knowledge of the terminology, definitions, and other material in the [Builder spec][builder-spec]
and by extension the [Bellatrix consensus specs][bellatrix-specs].

## Constants

| Name | Value | Units |
| - | - | - |
| `EPOCHS_PER_VALIDATOR_REGISTRATION_SUBMISSION` | 1 | epoch(s)|
| `BUILDER_PROPOSAL_DELAY_TOLERANCE` | 1 | second(s) |

## Validator registration

A validator begins interacting with the external builder network by submitting a signed registration to each of the
builders it wants to utilize during block production.

### Preparing a registration

To do this, the validator client assembles a [`ValidatorRegistrationV1`][validator-registration-v1] with the following
information:

* `fee_recipient`: an execution layer address where fees for the validator should go.
* `gas_limit`: the value a validator prefers for the execution block gas limit.
* `timestamp`: a recent timestamp later than any previously constructed `ValidatorRegistrationV1`.
Builders use this timestamp as a form of anti-DoS and to sequence registrations.
* `pubkey`: the validator's public key. Used to identify the beacon chain validator and verify the wrapping signature.

### Signing and submitting a registration

The validator takes the constructed `ValidatorRegistrationV1` `message` and signs according to the method given in
the [Builder spec][builder-spec] to make a `signature`.

This `signature` is placed along with the `message` into a `SignedValidatorRegistrationV1` and submitted to a connected
beacon node using the [`registerValidator`][register-validator-api] endpoint of the standard validator
[beacon node APIs][beacon-node-apis].

Validators **should** submit valid registrations well ahead of any potential beacon chain proposal duties to ensure
their building preferences are widely available in the external builder network.

### Registration dissemination

Validators are expected to periodically send their own `SignedValidatorRegistrationV1` messages upstream to the external
builder network using the [`registerValidator`][register-validator-with-builder] endpoint of the standard
[APIs defined in the builder spec][builder-spec-apis].

Registrations should be re-submitted frequently enough that any upstream builder software that comes online is aware of
ralexstokes marked this conversation as resolved.
Show resolved Hide resolved
each validator's latest registration in a timely manner.

This specification suggests validators re-submit to builder software every
`EPOCHS_PER_VALIDATOR_REGISTRATION_SUBMISSION` epochs.

## Beacon chain responsibilities

Refer to the [Bellatrix validator specs][bellatrix-validator-specs] for the expected set of duties a validator is
expected to perform, including a pathway for local block building. The external builder network offers a separate block
building pathway that can be used concurrently with this local process.

### Block proposal

#### Constructing the `BeaconBlockBody`

##### ExecutionPayload

To obtain an execution payload, a block proposer building a block on top of a beacon `state` in a given `slot` must take
the following actions:

1. Call upstream builder software to get an `ExecutionPayloadHeader` with the
required data `slot`, `parent_hash` and `pubkey`, where:
* `slot` is the proposal's slot
* `parent_hash` is the value `state.latest_execution_payload_header.block_hash`
* `pubkey` is the propser's public key
2. Assemble a `BlindedBeaconBlock` according to the process outlined in the [Bellatrix specs][bellatrix-specs] but with
the `ExecutionPayloadHeader` from the prior step in lieu of the full `ExecutionPayload`.
3. The proposer signs the `BlindedBeaconBlock` and assembles a `SignedBlindedBeaconBlock` which is returned to the
upstream builder software.
4. The upstream builder software responds with the full `ExecutionPayload`. The proposer can use this payload
to assemble a `SignedBeaconBlock` following the rest of the proposal process outlined in the
[Bellatrix specs][bellatrix-specs].

ralexstokes marked this conversation as resolved.
Show resolved Hide resolved
#### Relation to local block building

The external builder network offers a service for proposers that may from time to time fail to produce a timely block.
Honest proposers who elect to use the external builder network **MUST** also build a block locally in the event that the
external builder network fails to provide a `SignedBuilderBid` in time in order to propagate the full
`SignedBeaconBlock` during the proposer's slot.

Honest proposers using the external builder network will give the builders a duration of
`BUILDER_PROPOSAL_DELAY_TOLERANCE` before the external builder is considered to have hit the deadline and the external
builder flow must be aborted in favor of a local build process.
Copy link
Contributor

Choose a reason for hiding this comment

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

What do you think about including fallback to a local build process to the steps outlined above? In this case the place from which the fallback becomes dangerous (due to slashing) could be clearly defined.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think it would obscure the flow outlined above but I'm open to it if many think it is clearer.

As far as I know most clients have some version of this implemented already and they have two distinct code paths so it maps directly to say "run these two tasks, race them against a deadline"

Copy link
Contributor

Choose a reason for hiding this comment

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

I am fine with current description as long as implementers clearly understand the last moment where they can safely sign off on a payload that is built locally.

Copy link

Choose a reason for hiding this comment

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

maybe it could be clearer if we refer BUILDER_PROPOSAL_DELAY_TOLERANCE specifically to bid providing.
something like

... will give the builders a duration of BUILDER_PROPOSAL_DELAY_TOLERANCE to provide a SignedBuilderBid before the external builder is considered to have hit the deadline and the external

or also rename it to BUILDER_BID_PROPOSAL_DELAY_TOLERANCE?

this way it is clear the assumption that the fallback is no more an option once validator sign a blind block made with the bid.


**WARNING**: Validators must be careful to not get slashed when orchestrating the duplicate building pathways.
See the [section on slashing](#proposer-slashing) for more information.

## How to avoid slashing

### Proposer slashing

Validators must take care to not publish signatures for two distinct blocks even if there is a failure with the external
builder network. A `ProposerSlashing` can be formed in this event from the competing beacon block headers which results
in getting slashed.

To avoid slashing when using the external builder network, a validator should begin the external build process for an
`ExecutionPayloadHeader` along with the local build process for an `ExecutionPayload` as soon as they know the required
parameters to do so. Regardless of which process completes in time, the validator should cancel the other
process as soon as they have produced a signature for a beacon block, either a `BeaconBlock` **or** a
`BlindedBeaconBlock`. Producing distinct signatures for the validator's proposal slot, for example because the
transactions list of the `BeaconBlockBody` are different, is the slashable offense.

[builder-spec]: ./builder.md
[builder-spec-apis]: ./builder.md#endpoints
[register-validator-with-builder]: https://ethereum.github.io/builder-specs/#/Builder/registerValidator
[validator-registration-v1]: ./builder.md#validatorregistrationv1
[register-validator-api]: https://ethereum.github.io/beacon-APIs/#/Validator/registerValidator
[beacon-node-apis]: https://ethereum.github.io/beacon-APIs
[bellatrix-specs]: https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix
[bellatrix-validator-specs]: https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/validator.md