From 78cbe787fd552ed43b9197dc60cd322105a6ccb1 Mon Sep 17 00:00:00 2001 From: Michael Neuder Date: Tue, 30 May 2023 07:59:56 -0400 Subject: [PATCH 1/3] fixing relay/v1/builder/validators --- specs/capella/builder.md | 164 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 specs/capella/builder.md diff --git a/specs/capella/builder.md b/specs/capella/builder.md new file mode 100644 index 0000000..fae05f9 --- /dev/null +++ b/specs/capella/builder.md @@ -0,0 +1,164 @@ +# Relay specs + +## Table of contents + + + + +- [Introduction](#introduction) +- [Notation](#notation) +- [Custom Types](#custom-types) +- [Constants](#constants) +- [Containers](#containers) + + + + + +## Introduction + +This document presents the `mev-boost` relay specification. + +[`mev-boost`](https://boost.flashbots.net/) is an out-of-protocol mechanism to +connect Ethereum Proof-of-Stake validators to the external block-building market. +The [validator-side](https://github.com/flashbots/mev-boost) API is specified +in the [builder specs](https://github.com/ethereum/builder-specs). The [relay-side](https://github.com/flashbots/mev-boost-relay) API is specified here in the relay specs. + +## Notation + +Code snippets appearing in `this style` are to be interpreted as Python 3 code. + +## Custom types + +We define the following Python custom types for type hinting and readability: + +| Name | SSZ equivalent | Description | +| - | - | - | +| `Slot` | `uint64` | a slot number | +| `ValidatorIndex` | `uint64` | a validator registry index | +| `Gwei` | `uint64` | an amount in Gwei | +| `Hash32` | `Bytes32` | a 256-bit hash | +| `BLSPubkey` | `Bytes48` | a BLS12-381 public key | +| `BLSSignature` | `Bytes96` | a BLS12-381 signature | +| `ExecutionAddress` | `Bytes20` | Address of account on the execution layer | +| `Transaction` | `ByteList[MAX_BYTES_PER_TRANSACTION]` | either a [typed transaction envelope](https://eips.ethereum.org/EIPS/eip-2718#opaque-byte-array-rather-than-an-rlp-array) or a legacy transaction| +| `WithdrawalIndex` | `uint64` | an index of a `Withdrawal` | + + +## Constants + +The following values are (non-configurable) constants used throughout the specification. + + +| Name | Value | +| - | - | +| `BYTES_PER_LOGS_BLOOM` | `uint64(2**8)` (= 256) | +| `MAX_EXTRA_DATA_BYTES` | `2**5` (= 32) | +| `MAX_BYTES_PER_TRANSACTION` | `uint64(2**30)` (= 1,073,741,824) | +| `MAX_TRANSACTIONS_PER_PAYLOAD` | `uint64(2**20)` (= 1,048,576) | +| `MAX_WITHDRAWALS_PER_PAYLOAD` | `uint64(2**4)` (= 16) | + + +## Containers + +*Note*: Fields missing in container instantiations default to their zero value. + +### GET `​/relay​/v1​/builder​/validators` response type + +#### `ProposerDutiesResponse` + +```python +class ProposerDutiesResponse(Container): + data: List[BuilderGetValidatorsResponseEntry] +``` + +#### `BuilderGetValidatorsResponseEntry` + +```python +class BuilderGetValidatorsResponseEntry(Container): + slot: Slot + validator_index: ValidatorIndex + entry: SignedValidatorRegistration +``` + +#### `SignedValidatorRegistration` + +```python +class SignedValidatorRegistration(Container): + message: RegisterValidatorRequestMessage + signature: BLSSignature +``` + + + +Slot uint64 `json:"slot,string"` + ValidatorIndex uint64 `json:"validator_index,string"` + Entry *boostTypes.SignedValidatorRegistration `json:"entry"` + +### POST `​/relay​/v1​/builder​/blocks` request type + +#### `BuilderSubmitNewBlockRequest` + +```python +class BuilderSubmitNewBlockRequest(Container): + capella: SubmitBlockRequest +``` + +#### `SubmitBlockRequest` + +```python +class SubmitBlockRequest(Container): + message: BidTrace + execution_payload: ExecutionPayload + signature: BLSSignature +``` + +#### `BidTrace` + +```python +class BidTrace(Container): + slot: Slot + parent_hash: Hash32 + block_hash: Hash32 + builder_pubkey: BLSPubkey + proposer_pubkey: BLSPubkey + proposer_fee_recipient: ExecutionAddress + gas_limit: uint64 + gas_used: uint64 + value: uint256 +``` + +#### `ExecutionPayload` + +From [capella spec](https://github.com/ethereum/consensus-specs/blob/f7352d18cfb91c58b1addb4ea509aedd6e32165c/specs/capella/beacon-chain.md#executionpayload). + +```python +class ExecutionPayload(Container): + parent_hash: Hash32 + fee_recipient: ExecutionAddress + state_root: Bytes32 + receipts_root: Bytes32 + logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM] + prev_randao: Bytes32 + block_number: uint64 + gas_limit: uint64 + gas_used: uint64 + timestamp: uint64 + extra_data: ByteList[MAX_EXTRA_DATA_BYTES] + base_fee_per_gas: uint256 + block_hash: Hash32 + transactions: List[Transaction, MAX_TRANSACTIONS_PER_PAYLOAD] + withdrawals: List[Withdrawal, MAX_WITHDRAWALS_PER_PAYLOAD] +``` + +#### `Withdrawal` + +From [capella spec](https://github.com/ethereum/consensus-specs/blob/f7352d18cfb91c58b1addb4ea509aedd6e32165c/specs/capella/beacon-chain.md#withdrawal). + +```python +class Withdrawal(Container): + index: WithdrawalIndex + validator_index: ValidatorIndex + address: ExecutionAddress + amount: Gwei +``` \ No newline at end of file From 503be361d150915a1e2a5c930b7ea08b31fde594 Mon Sep 17 00:00:00 2001 From: Michael Neuder Date: Tue, 30 May 2023 08:01:04 -0400 Subject: [PATCH 2/3] fixing relay/v1/builder/validators --- specs/capella/builder.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/specs/capella/builder.md b/specs/capella/builder.md index fae05f9..a4b4c05 100644 --- a/specs/capella/builder.md +++ b/specs/capella/builder.md @@ -63,7 +63,7 @@ The following values are (non-configurable) constants used throughout the specif *Note*: Fields missing in container instantiations default to their zero value. -### GET `​/relay​/v1​/builder​/validators` response type +### `​GET /relay​/v1​/builder​/validators` response type #### `ProposerDutiesResponse` @@ -89,13 +89,17 @@ class SignedValidatorRegistration(Container): signature: BLSSignature ``` +#### `RegisterValidatorRequestMessage` +```python +class RegisterValidatorRequestMessage(Container): + fee_recipient: ExecutionAddress + gas_limit: uint64 + timestamp: uint64 + pubkey: BLSPubkey +``` -Slot uint64 `json:"slot,string"` - ValidatorIndex uint64 `json:"validator_index,string"` - Entry *boostTypes.SignedValidatorRegistration `json:"entry"` - -### POST `​/relay​/v1​/builder​/blocks` request type +### `​POST /relay​/v1​/builder​/blocks` request type #### `BuilderSubmitNewBlockRequest` From 01d856ee0bec3c34a73c907dc73bfc64ec71411c Mon Sep 17 00:00:00 2001 From: Michael Neuder Date: Tue, 30 May 2023 08:04:13 -0400 Subject: [PATCH 3/3] doctoc --- specs/capella/builder.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/specs/capella/builder.md b/specs/capella/builder.md index a4b4c05..5caed3f 100644 --- a/specs/capella/builder.md +++ b/specs/capella/builder.md @@ -7,10 +7,20 @@ - [Introduction](#introduction) - [Notation](#notation) -- [Custom Types](#custom-types) +- [Custom types](#custom-types) - [Constants](#constants) - [Containers](#containers) - + - [`​GET /relay​/v1​/builder​/validators` response type](#%E2%80%8Bget-relay%E2%80%8Bv1%E2%80%8Bbuilder%E2%80%8Bvalidators-response-type) + - [`ProposerDutiesResponse`](#proposerdutiesresponse) + - [`BuilderGetValidatorsResponseEntry`](#buildergetvalidatorsresponseentry) + - [`SignedValidatorRegistration`](#signedvalidatorregistration) + - [`RegisterValidatorRequestMessage`](#registervalidatorrequestmessage) + - [`​POST /relay​/v1​/builder​/blocks` request type](#%E2%80%8Bpost-relay%E2%80%8Bv1%E2%80%8Bbuilder%E2%80%8Bblocks-request-type) + - [`BuilderSubmitNewBlockRequest`](#buildersubmitnewblockrequest) + - [`SubmitBlockRequest`](#submitblockrequest) + - [`BidTrace`](#bidtrace) + - [`ExecutionPayload`](#executionpayload) + - [`Withdrawal`](#withdrawal)