From c3749954c68a5eff2f79571d6bca58e3fa0a939a Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 21 Apr 2022 13:00:44 +0200 Subject: [PATCH 01/41] add builder api spec --- src/builder/README.md | 7 ++ src/builder/specification.md | 217 +++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 src/builder/README.md create mode 100644 src/builder/specification.md diff --git a/src/builder/README.md b/src/builder/README.md new file mode 100644 index 000000000..7a81c9474 --- /dev/null +++ b/src/builder/README.md @@ -0,0 +1,7 @@ +# Builder JSON-RPC API + +The Builder JSON-RPC API is a collection of methods that all execution clients implement. +This interface allows the communication between the consensus layer and external builders. + +This API is in *active development* and currently [specified as a markdown document](./specification.md). +A schema will follow once the specification stabilizes. diff --git a/src/builder/specification.md b/src/builder/specification.md new file mode 100644 index 000000000..6d9bc4f09 --- /dev/null +++ b/src/builder/specification.md @@ -0,0 +1,217 @@ +# Version 0.2.1 + +This document specifies the Builder API methods that the Consensus Layer uses to interact with external block builders. + +```mermaid +sequenceDiagram + participant consensus + participant mev_boost + participant relays + Title: Block Proposal + Note over consensus: sign fee recipient announcement + consensus->>mev_boost: builder_setFeeRecipient + mev_boost->>relays: builder_setFeeRecipient + Note over consensus: wait for allocated slot + consensus->>mev_boost: builder_getHeader + mev_boost->>relays: builder_getHeader + relays-->>mev_boost: builder_getHeader response + Note over mev_boost: verify response matches expected + Note over mev_boost: select best payload + mev_boost-->>consensus: builder_getHeader response + Note over consensus: sign the block + consensus->>mev_boost: builder_getPayload + Note over mev_boost: identify payload source + mev_boost->>relays: builder_getPayload + Note over relays: validate signature + relays-->>mev_boost: builder_getPayload response + Note over mev_boost: verify response matches expected + mev_boost-->>consensus: builder_getPayload response +``` + +## Structures + +### `ExecutionPayloadV1` + +Mirror of [`ExecutionPayloadV1`][execution-payload]. + +### `ExecutionPayloadHeaderV1` + +Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `transactionsRoot`. +- `parentHash`: `DATA`, 32 Bytes +- `feeRecipient`: `DATA`, 20 Bytes +- `stateRoot`: `DATA`, 32 Bytes +- `receiptsRoot`: `DATA`, 32 Bytes +- `logsBloom`: `DATA`, 256 Bytes +- `prevRandao`: `DATA`, 32 Bytes +- `blockNumber`: `QUANTITY`, 64 Bits +- `gasLimit`: `QUANTITY`, 64 Bits +- `gasUsed`: `QUANTITY`, 64 Bits +- `timestamp`: `QUANTITY`, 64 Bits +- `extraData`: `DATA`, 0 to 32 Bytes +- `baseFeePerGas`: `QUANTITY`, 256 Bits +- `blockHash`: `DATA`, 32 Bytes +- `transactionsRoot`: `DATA`, 32 Bytes + +#### SSZ Objects + +Consider the following definitions supplementary to the definitions in [`consensus-specs`][consensus-specs]. + +##### `builder_setFeeRecipientV1` Request + +```python +class SetFeeRecipientRequestV1(Container): + feeRecipient: Bytes20 + timestamp: uint64 +``` + +##### `builder_getPayloadV1` Response + +```python +class GetPayloadResponseV1(Container): + payload: ExecutionPayloadHeader + value: uint256 +``` + +##### `builder_getPayloadV1` Request + +###### `SignedBlindBeaconBlock` + +```python +class SignedBlindBeaconBlock(Container): + message: BlindBeaconBlock + signature: BLSSignature +``` + +###### `BlindBeaconBlock` + +```python +class BlindBeaconBlock(Container): + slot: Slot + proposer_index: ValidatorIndex + parent_root: Root + state_root: Root + body: BlindBeaconBlockBody +``` + +###### `BlindBeaconBlockBody` + +```python +class BlindBeaconBlockBody(Container): + randao_reveal: BLSSignature + eth1_data: Eth1Data + graffiti: Bytes32 + proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS] + attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS] + attestations: List[Attestation, MAX_ATTESTATIONS] + deposits: List[Deposit, MAX_DEPOSITS] + voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS] + sync_aggregate: SyncAggregate + execution_payload: ExecutionPayloadHeader +``` + +## Errors + +The list of error codes introduced by this specification can be found below. + +| Code | Message | Meaning | +| - | - | - | +| -32000 | Server error | Generic client error while processing request. | +| -32001 | Unknown hash | No block with the provided hash is known. | +| -32002 | Unknown validator | No known mapping between validator and feeRecipient. | +| -32003 | Invalid SSZ | Unable to decode SSZ. | +| -32004 | Unknown block | Block does not match the provided header. | +| -32005 | Invalid signature | Provided signature is invalid. | +| -32006 | Invalid timestamp | Provided timestamp was invalid. | +| -32600 | Invalid request | The JSON sent is not a valid Request object. | +| -32601 | Method not found | The method does not exist / is not available. | +| -32602 | Invalid params | Invalid method parameter(s). | +| -32603 | Internal error | Internal JSON-RPC error. | +| -32700 | Parse error | Invalid JSON was received by the server. | + +## Routines + +### Signing + +All signature operations should follow the [standard BLS operations][bls] interface defined in `consensus-specs`. + +There are two types of data to sign over in the Builder API: +* In-protocol messages, e.g. [`BlindBeaconBlock`](#blindbeaconblock), which should compute the signing root using [`computer_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. +* Builder API messages, e.g. [`builder_setFeeRecipientV1`](#builder_setFeeRecipientV1) and the response to [`builder_getHeader`](#response-2), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and the domain `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). + +As `compute_signing_root` takes `SSZObject` as input, client software should convert in-protocol messages to their SSZ representation to compute the signing root and Builder API messages to the SSZ representations defined [above](#sszobjects). + +## Methods + +### `builder_setFeeRecipientV1` + +#### Request + +- method: `builder_setFeeRecipientV1` +- params: + 1. `message`: `object` + 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. + 2. `timestamp`: `QUANTITY`, uint64 - Unix timestamp of announcement. + 2. `publicKey`: `DATA`, 48 Bytes - Public key of validator. + 3. `signature`: `DATA`, 96 Bytes - Signature over `feeRecipient` and `timestamp`. + +#### Response + +- result: `null` +- error: code and message set in case an exception happens while getting the payload. + +#### Specification +1. Builder software **MUST** verify `signature` is valid under `publicKey`. +2. Builder software **MUST** respond to requests where `timestamp` is before the latest announcement from the validator with `-32006: Invalid timestamp`. +3. Builder software **MUST** store `feeRecipient` in a map keyed by `publicKey`. + +### `builder_getHeaderV1` + +#### Request + +- method: `builder_getHeaderV1` +- params: + 1. `hash`: `DATA`, 32 Bytes - Hash of Execution Layer block which the validator intends to use as the parent for its proposal. + +#### Response + +- result: `object` + - `message`: `object` + - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). + - `value`: `DATA`, 32 Bytes - the payment in wei that will be directed to the `feeRecipient` account. + - `publicKey`: `DATA`, 48 Bytes - the public key associated with the builder. + - `signature`: `DATA`, 96 Bytes - BLS signature of the builder over `payload` and `value`. +- error: code and message set in case an exception happens while getting the payload. + +#### Specification +1. Builder software **SHOULD** respond immediately with the `header` that increases the `feeRecipient`'s balance by the most. +2. Builder software **MUST** return `-32001: Unknown hash` if the block identified by `hash` does not exist. +3. Builder software **MUST** return `-32002: Unknown validator` if the validator the builder expects to propose in the current slot has not been mapped to a `feeRecipient`. +4. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. + +### `builder_getPayloadV1` + +#### Request + +- method: `builder_getPayloadV1` +- params: + 1. `block`: `DATA`, arbitray length - SSZ encoded [`SignedBlindBeaconBlock`](#blindbeaconblock). + +#### Response + +- result: [`ExecutionPayloadV1`](#executionpayloadv1). +- error: code and message set in case an exception happens while proposing the payload. + +#### Specification +1. Builder software **MUST** verify that `block` is an SSZ encoded [`SignBlindBeaconBlock`](#blindbeaconblock). If the block is encoded incorrectly, the builder **MUST** return `-32003: Invalid SSZ`. If the block is encoded correctly, but does not include a matching `ExecutionPayloadHeaderV1` provided from `builder_getHeaderV1`, the builder **SHOULD** return `-32004: Unknown block`. +2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the given slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. + +[consensus-specs]: https://github.com/ethereum/consensus-specs +[bls]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#bls-signatures +[compute-signing-root]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#compute_signing_root +[bytes20]: https://github.com/ethereum/consensus-specs/blob/dev/ssz/simple-serialize.md#aliases +[uint256]: https://github.com/ethereum/consensus-specs/blob/dev/ssz/simple-serialize.md#basic-types +[execution-payload-header]: https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/beacon-chain.md#executionpayloadheader +[execution-payload]: https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md#executionpayloadv1 +[hash-tree-root]: https://github.com/ethereum/consensus-specs/blob/dev/ssz/simple-serialize.md#merkleization +[beacon-block]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#beaconblock +[verify-block-signature]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#beacon-chain-state-transition-function From e28576a8cdc779d5c4af76f4353063d4ff4f8d9b Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 21 Apr 2022 23:13:26 +0200 Subject: [PATCH 02/41] add bls and ssz to word list --- wordlist.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/wordlist.txt b/wordlist.txt index e9e86cb1d..c1790db6d 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -1,5 +1,6 @@ apis attributesv +bls bytecode configurationv eip @@ -21,9 +22,10 @@ rlp rpc schemas secp +sha +ssz statev statusv -sha uint updatedv url From 075a2bb455921422c14448d393765b6ed121fff5 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 21 Apr 2022 23:33:05 +0200 Subject: [PATCH 03/41] fix typo Co-authored-by: Alex Stokes --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 6d9bc4f09..f99e9b4e8 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -135,7 +135,7 @@ The list of error codes introduced by this specification can be found below. All signature operations should follow the [standard BLS operations][bls] interface defined in `consensus-specs`. There are two types of data to sign over in the Builder API: -* In-protocol messages, e.g. [`BlindBeaconBlock`](#blindbeaconblock), which should compute the signing root using [`computer_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. +* In-protocol messages, e.g. [`BlindBeaconBlock`](#blindbeaconblock), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. * Builder API messages, e.g. [`builder_setFeeRecipientV1`](#builder_setFeeRecipientV1) and the response to [`builder_getHeader`](#response-2), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and the domain `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). As `compute_signing_root` takes `SSZObject` as input, client software should convert in-protocol messages to their SSZ representation to compute the signing root and Builder API messages to the SSZ representations defined [above](#sszobjects). From 8d869f49bc27ea0559a009cf165a380d59f1ef3a Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 21 Apr 2022 23:49:59 +0200 Subject: [PATCH 04/41] remove version from builder api spec --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index f99e9b4e8..487d5a195 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -1,4 +1,4 @@ -# Version 0.2.1 +# Builder API This document specifies the Builder API methods that the Consensus Layer uses to interact with external block builders. From 305d33e52e621e17e746c7fda39ffc5b425b03ec Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:41:23 +0200 Subject: [PATCH 05/41] address feedback from workshop --- src/builder/specification.md | 140 +++++++++++++++++++++++++++++------ 1 file changed, 116 insertions(+), 24 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 487d5a195..a1f911fda 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -9,8 +9,8 @@ sequenceDiagram participant relays Title: Block Proposal Note over consensus: sign fee recipient announcement - consensus->>mev_boost: builder_setFeeRecipient - mev_boost->>relays: builder_setFeeRecipient + consensus->>mev_boost: builder_registerValidator + mev_boost->>relays: builder_registerValidator Note over consensus: wait for allocated slot consensus->>mev_boost: builder_getHeader mev_boost->>relays: builder_getHeader @@ -35,7 +35,6 @@ sequenceDiagram Mirror of [`ExecutionPayloadV1`][execution-payload]. ### `ExecutionPayloadHeaderV1` - Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `transactionsRoot`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -52,16 +51,105 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `blockHash`: `DATA`, 32 Bytes - `transactionsRoot`: `DATA`, 32 Bytes +### `BlindBeaconBlockV1` +- `slot`: `QUANTITY`, 64 Bits +- `proposerIndex`: `QUANTITY`, 64 Bits +- `parentRoot`: `DATA`, 32 Bytes +- `stateRoot`: `DATA`, 32 Bytes +- `body`: `object`, `BlindBeaconBlockBodyV1` + +### `BlindBeaconBlockBodyV1` +- `randaoReveal`: `DATA`, 96 Bytes +- `eth1Data`: `object`, `Eth1DataV1` +- `graffiti`: `DATA`, 32 Bytes +- `proposerSlashings`: `object`, `ProposerSlashingV1` +- `attesterSlashings`: `object`, `AttesterSlashingV1` +- `attestations`: `Array`, `AttestationV1` +- `deposits`: `Array`, `DespositV1` +- `voluntaryExits`: `Array`, `SignedVoluntaryExitV1` +- `syncAggregate`: `object`, `SyncAggregateV1` +- `executionPayload`: `object`, `ExecutionPayloadHeaderV1` + +### `Eth1DataV1` +- `depositRoot`: `DATA`, 32 Bytes +- `depositCount`: `QUANTITY`, 64 Bits +- `blockHash`: `DATA`, 32 Bytes + +### `ProposerSlashing` +- `signedHeader1`: `object`, `SignedBeaconBlockBlockHeaderV1` +- `signedHeader2`: `object`, `SignedBeaconBlockBlockHeaderV1` + +### `BeaconBlockHeaderV1` +- `slot`: `QUANTITY`, 64 Bits +- `proposerIndex`: `QUANTITY`, 64 Bits +- `parentRoot`: `DATA`, 32 Bytes +- `stateRoot`: `DATA`, 32 Bytes +- `bodyRoot`: `DATA`, 32 Bytes + +### `AttesterSlashingV1` +- `attestation1`: `object`, `IndexedAttestationV1` +- `attestation2`: `object`, `IndexedAttestationV1` + +### `IndexedAttestationV1` +- `attestingIndices`: `Array`, `QUANTITY`, 64 Bits +- `data`: `object`, `AttestationDataV1` +- `signature`: `DATA`, 96 Bytes + +### `AttestationDataV1` +- `slot`: `QUANTITY`, 64 Bits +- `index`: `QUANTITY`, 64 Bits +- `beaconBlockRoot`, `DATA`, 32 Bytes +- `source`: `object`, `CheckpointV1` +- `target`: `object`, `CheckpointV1` + +### `CheckpointV1` +- `epoch`: `QUANTITY`, 64 Bits +- `root`: `DATA`, 32 Bytes + +### `AttestationV1` +- `aggregationBits`: `DATA`, 0 to 256 Bytes +- `data`: `object`, `AttestationDataV1` +- `signature`: `DATA`, 96 Bytes + +### `DespositV1` +- `proof`: `Array`, 32 Bytes +- `data`: `object`, `DepositDataV1` + +### `DepositDataV1` +- `pubkey`: `DATA`, 48 Bytes +- `withdrawalCredentials`: `DATA`, 32 Bytes +- `amount`: `QUANTITY`, 64 Bits +- `signature`: `DATA`, 96 Bytes + +### `VoluntaryExitV1` +- `epoch`: `QUANTITY`, 64 Bits +- `ValidatorIndex`: `QUANTITY`, 64 Bits + +### `SyncAggregateV1` +- `syncCommitteeBits`: `DATA`, 0 to 64 Bytes +- `syncCommitteeSignature`: `DATA`, 96 Bytes + +#### Signed Containers + +### `SignedBeaconBlockBlockHeaderV1` +- `message`: `object`, BeaconBlockHeader +- `signature`: `DATA`, 96 Bytes + +### `SignedVoluntaryExitV1` +- `message`: `object`, `VoluntaryExitV1` +- `signature`: `DATA`, 96 Bytes + #### SSZ Objects Consider the following definitions supplementary to the definitions in [`consensus-specs`][consensus-specs]. -##### `builder_setFeeRecipientV1` Request +##### `builder_registerValidatorV1` Request ```python -class SetFeeRecipientRequestV1(Container): +class RegisterValidatorV1(Container): feeRecipient: Bytes20 timestamp: uint64 + pubkey: BLSPubkey ``` ##### `builder_getPayloadV1` Response @@ -117,8 +205,8 @@ The list of error codes introduced by this specification can be found below. | - | - | - | | -32000 | Server error | Generic client error while processing request. | | -32001 | Unknown hash | No block with the provided hash is known. | -| -32002 | Unknown validator | No known mapping between validator and feeRecipient. | -| -32003 | Invalid SSZ | Unable to decode SSZ. | +| -32002 | Unknown validator | Unknown validator. | +| -32003 | Unknown fee recipient | No known mapping between validator and fee recipient. | | -32004 | Unknown block | Block does not match the provided header. | | -32005 | Invalid signature | Provided signature is invalid. | | -32006 | Invalid timestamp | Provided timestamp was invalid. | @@ -136,22 +224,22 @@ All signature operations should follow the [standard BLS operations][bls] interf There are two types of data to sign over in the Builder API: * In-protocol messages, e.g. [`BlindBeaconBlock`](#blindbeaconblock), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. -* Builder API messages, e.g. [`builder_setFeeRecipientV1`](#builder_setFeeRecipientV1) and the response to [`builder_getHeader`](#response-2), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and the domain `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). +* Builder API messages, e.g. [`builder_registerValidatorV1`](#builder_registerValidatorV1) and the response to [`builder_getHeader`](#response-2), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and the domain `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). As `compute_signing_root` takes `SSZObject` as input, client software should convert in-protocol messages to their SSZ representation to compute the signing root and Builder API messages to the SSZ representations defined [above](#sszobjects). ## Methods -### `builder_setFeeRecipientV1` +### `builder_registerValidatorV1` #### Request -- method: `builder_setFeeRecipientV1` +- method: `builder_registerValidatorV1` - params: 1. `message`: `object` 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. 2. `timestamp`: `QUANTITY`, uint64 - Unix timestamp of announcement. - 2. `publicKey`: `DATA`, 48 Bytes - Public key of validator. + 3. `pubkey`: `DATA`, 48 Bytes - Public key of validator. 3. `signature`: `DATA`, 96 Bytes - Signature over `feeRecipient` and `timestamp`. #### Response @@ -160,9 +248,9 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while getting the payload. #### Specification -1. Builder software **MUST** verify `signature` is valid under `publicKey`. -2. Builder software **MUST** respond to requests where `timestamp` is before the latest announcement from the validator with `-32006: Invalid timestamp`. -3. Builder software **MUST** store `feeRecipient` in a map keyed by `publicKey`. +1. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. +2. Builder software **MUST** respond to requests where `timestamp` is before the latest announcement from the validator with error `-32007: Invalid timestamp`. +3. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. ### `builder_getHeaderV1` @@ -170,23 +258,26 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getHeaderV1` - params: - 1. `hash`: `DATA`, 32 Bytes - Hash of Execution Layer block which the validator intends to use as the parent for its proposal. + 1. `slot`: `QUANTITY`, 64 Bits - Slot number of the block proposal. + 2. `pubkey`: `QUANTITY`, 64 Bits - Corresponding public key of proposer. + 3. `hash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. #### Response - result: `object` - `message`: `object` - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). - - `value`: `DATA`, 32 Bytes - the payment in wei that will be directed to the `feeRecipient` account. - - `publicKey`: `DATA`, 48 Bytes - the public key associated with the builder. - - `signature`: `DATA`, 96 Bytes - BLS signature of the builder over `payload` and `value`. + - `value`: `DATA`, 32 Bytes - the payment in wei that will be paid to the `feeRecipient` account. + - `pubkey`: `DATA`, 48 Bytes - the public key associated with the builder. + - `signature`: `DATA`, 96 Bytes - BLS signature of the builder over `message`. - error: code and message set in case an exception happens while getting the payload. #### Specification 1. Builder software **SHOULD** respond immediately with the `header` that increases the `feeRecipient`'s balance by the most. -2. Builder software **MUST** return `-32001: Unknown hash` if the block identified by `hash` does not exist. -3. Builder software **MUST** return `-32002: Unknown validator` if the validator the builder expects to propose in the current slot has not been mapped to a `feeRecipient`. -4. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. +2. Builder software **MUST** return `-32001: Unknown hash` if the block identified by `hash` is not known. +3. Builder software **MUST** return `-32002: Unknown validator` if `pubkey` does not map to the validator that is expected to propose at `slot`. +4. Builder software **MUST** return `-32003: Unknown fee recipient` if the builder does not have a `feeRecipient` mapped to the validator. +5. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. ### `builder_getPayloadV1` @@ -194,7 +285,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getPayloadV1` - params: - 1. `block`: `DATA`, arbitray length - SSZ encoded [`SignedBlindBeaconBlock`](#blindbeaconblock). + 1. `message`: [`SignedBlindBeaconBlock`](#signedblindbeaconblockv1). + 2. `signature`: `DATA`, 96 Bytes. #### Response @@ -202,8 +294,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while proposing the payload. #### Specification -1. Builder software **MUST** verify that `block` is an SSZ encoded [`SignBlindBeaconBlock`](#blindbeaconblock). If the block is encoded incorrectly, the builder **MUST** return `-32003: Invalid SSZ`. If the block is encoded correctly, but does not include a matching `ExecutionPayloadHeaderV1` provided from `builder_getHeaderV1`, the builder **SHOULD** return `-32004: Unknown block`. -2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the given slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. +1. Builder software **MUST** verify that the beacon block's exeuction payload is a matching `ExecutionPayloadHeaderV1` provided from `builder_getHeaderV1`, otherwise the return `-32004: Unknown block`. +2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. [consensus-specs]: https://github.com/ethereum/consensus-specs [bls]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#bls-signatures From dc69e00062c2d80810829597f6b95ade1e2ccfc4 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:44:07 +0200 Subject: [PATCH 06/41] additional validity checks on timestamp Co-authored-by: Chris Hager --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index a1f911fda..5ee93d138 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -249,7 +249,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Specification 1. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. -2. Builder software **MUST** respond to requests where `timestamp` is before the latest announcement from the validator with error `-32007: Invalid timestamp`. +2. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. 3. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. ### `builder_getHeaderV1` From e6732a18404872d024ee4931e1d619a66cc4bf90 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:53:45 +0200 Subject: [PATCH 07/41] add link refs to stuct defs --- src/builder/specification.md | 42 ++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 5ee93d138..b0c2cae6a 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -56,19 +56,19 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `proposerIndex`: `QUANTITY`, 64 Bits - `parentRoot`: `DATA`, 32 Bytes - `stateRoot`: `DATA`, 32 Bytes -- `body`: `object`, `BlindBeaconBlockBodyV1` +- `body`: `object`, [`BlindBeaconBlockBodyV1`](#blindbeaconblockbodyv1) ### `BlindBeaconBlockBodyV1` - `randaoReveal`: `DATA`, 96 Bytes -- `eth1Data`: `object`, `Eth1DataV1` +- `eth1Data`: `object`, [`Eth1DataV1`](#eth1datav1) - `graffiti`: `DATA`, 32 Bytes -- `proposerSlashings`: `object`, `ProposerSlashingV1` -- `attesterSlashings`: `object`, `AttesterSlashingV1` -- `attestations`: `Array`, `AttestationV1` -- `deposits`: `Array`, `DespositV1` -- `voluntaryExits`: `Array`, `SignedVoluntaryExitV1` -- `syncAggregate`: `object`, `SyncAggregateV1` -- `executionPayload`: `object`, `ExecutionPayloadHeaderV1` +- `proposerSlashings`: `object`, [`ProposerSlashingV1`](#proposerslashingv1) +- `attesterSlashings`: `object`, [`AttesterSlashingV1`](#attesterslashingv1) +- `attestations`: `Array`, [`AttestationV1`](#attestationv1) +- `deposits`: `Array`, [`DespositV1`](#depositv1) +- `voluntaryExits`: `Array`, [`SignedVoluntaryExitV1`](#signedvoluntaryexitv1) +- `syncAggregate`: `object`, [`SyncAggregateV1`](#syncaggregatev1) +- `executionPayload`: `object`, [`ExecutionPayloadHeaderV1`](#executionpayloadheader) ### `Eth1DataV1` - `depositRoot`: `DATA`, 32 Bytes @@ -76,8 +76,8 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `blockHash`: `DATA`, 32 Bytes ### `ProposerSlashing` -- `signedHeader1`: `object`, `SignedBeaconBlockBlockHeaderV1` -- `signedHeader2`: `object`, `SignedBeaconBlockBlockHeaderV1` +- `signedHeader1`: `object`, [`SignedBeaconBlockBlockHeaderV1`](#signedbeaconblockheaderv1) +- `signedHeader2`: `object`, [`SignedBeaconBlockBlockHeaderV1`](#signedbeaconblockheaderv1) ### `BeaconBlockHeaderV1` - `slot`: `QUANTITY`, 64 Bits @@ -87,20 +87,20 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `bodyRoot`: `DATA`, 32 Bytes ### `AttesterSlashingV1` -- `attestation1`: `object`, `IndexedAttestationV1` -- `attestation2`: `object`, `IndexedAttestationV1` +- `attestation1`: `object`, [`IndexedAttestationV1`](#indexedattestationv1) +- `attestation2`: `object`, [`IndexedAttestationV1`](#indexedattestationv1) ### `IndexedAttestationV1` - `attestingIndices`: `Array`, `QUANTITY`, 64 Bits -- `data`: `object`, `AttestationDataV1` +- `data`: `object`, [`AttestationDataV1`](#attestationdatav1) - `signature`: `DATA`, 96 Bytes ### `AttestationDataV1` - `slot`: `QUANTITY`, 64 Bits - `index`: `QUANTITY`, 64 Bits - `beaconBlockRoot`, `DATA`, 32 Bytes -- `source`: `object`, `CheckpointV1` -- `target`: `object`, `CheckpointV1` +- `source`: `object`, [`CheckpointV1`](#checkpointv1) +- `target`: `object`, [`CheckpointV1`](#checkpointv1) ### `CheckpointV1` - `epoch`: `QUANTITY`, 64 Bits @@ -108,12 +108,12 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran ### `AttestationV1` - `aggregationBits`: `DATA`, 0 to 256 Bytes -- `data`: `object`, `AttestationDataV1` +- `data`: `object`, [`AttestationDataV1`](#attestationdatav1) - `signature`: `DATA`, 96 Bytes ### `DespositV1` - `proof`: `Array`, 32 Bytes -- `data`: `object`, `DepositDataV1` +- `data`: `object`, [`DepositDataV1`](#depositdatav1) ### `DepositDataV1` - `pubkey`: `DATA`, 48 Bytes @@ -132,11 +132,11 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran #### Signed Containers ### `SignedBeaconBlockBlockHeaderV1` -- `message`: `object`, BeaconBlockHeader +- `message`: `object`, [`BeaconBlockHeader`](#beaconblockheaderv1) - `signature`: `DATA`, 96 Bytes ### `SignedVoluntaryExitV1` -- `message`: `object`, `VoluntaryExitV1` +- `message`: `object`, [`VoluntaryExitV1`](#voluntaryexitv1) - `signature`: `DATA`, 96 Bytes #### SSZ Objects @@ -294,7 +294,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while proposing the payload. #### Specification -1. Builder software **MUST** verify that the beacon block's exeuction payload is a matching `ExecutionPayloadHeaderV1` provided from `builder_getHeaderV1`, otherwise the return `-32004: Unknown block`. +1. Builder software **MUST** verify that the beacon block's exeuction payload is a matching [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) provided from [`builder_getHeaderV1`](#buildergetheaderv1), otherwise the return `-32004: Unknown block`. 2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. [consensus-specs]: https://github.com/ethereum/consensus-specs From 40d5b448a45e4237ba101556bc6e8aa48d8137cc Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:55:07 +0200 Subject: [PATCH 08/41] fix typo --- src/builder/specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index b0c2cae6a..a60d075cb 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -76,8 +76,8 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `blockHash`: `DATA`, 32 Bytes ### `ProposerSlashing` -- `signedHeader1`: `object`, [`SignedBeaconBlockBlockHeaderV1`](#signedbeaconblockheaderv1) -- `signedHeader2`: `object`, [`SignedBeaconBlockBlockHeaderV1`](#signedbeaconblockheaderv1) +- `signedHeader1`: `object`, [`SignedBeaconBlockHeaderV1`](#signedbeaconblockheaderv1) +- `signedHeader2`: `object`, [`SignedBeaconBlockHeaderV1`](#signedbeaconblockheaderv1) ### `BeaconBlockHeaderV1` - `slot`: `QUANTITY`, 64 Bits @@ -131,7 +131,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran #### Signed Containers -### `SignedBeaconBlockBlockHeaderV1` +### `SignedBeaconBlockHeaderV1` - `message`: `object`, [`BeaconBlockHeader`](#beaconblockheaderv1) - `signature`: `DATA`, 96 Bytes From 7a27240790e3f3e9d2c21a143c9a13172a02632c Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:57:29 +0200 Subject: [PATCH 09/41] missing v1 on proposer slashing def --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index a60d075cb..9668da020 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -75,7 +75,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `depositCount`: `QUANTITY`, 64 Bits - `blockHash`: `DATA`, 32 Bytes -### `ProposerSlashing` +### `ProposerSlashingV1` - `signedHeader1`: `object`, [`SignedBeaconBlockHeaderV1`](#signedbeaconblockheaderv1) - `signedHeader2`: `object`, [`SignedBeaconBlockHeaderV1`](#signedbeaconblockheaderv1) From 069b2c403817e64881a230824e29cd10d37c0611 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 17:58:52 +0200 Subject: [PATCH 10/41] another typo --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 9668da020..dc5a1a9b7 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -111,7 +111,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `data`: `object`, [`AttestationDataV1`](#attestationdatav1) - `signature`: `DATA`, 96 Bytes -### `DespositV1` +### `DepositV1` - `proof`: `Array`, 32 Bytes - `data`: `object`, [`DepositDataV1`](#depositdatav1) From 79ea26e1472e84cc2c7783d96dbd0306e9981be6 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 18:00:20 +0200 Subject: [PATCH 11/41] missing v1 --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index dc5a1a9b7..8f9047296 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -68,7 +68,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `deposits`: `Array`, [`DespositV1`](#depositv1) - `voluntaryExits`: `Array`, [`SignedVoluntaryExitV1`](#signedvoluntaryexitv1) - `syncAggregate`: `object`, [`SyncAggregateV1`](#syncaggregatev1) -- `executionPayload`: `object`, [`ExecutionPayloadHeaderV1`](#executionpayloadheader) +- `executionPayload`: `object`, [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) ### `Eth1DataV1` - `depositRoot`: `DATA`, 32 Bytes From 49c742d05c655e40d245336820c9b813a78529e8 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sun, 24 Apr 2022 18:03:14 +0200 Subject: [PATCH 12/41] fix some errors in ssz defs --- src/builder/specification.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 8f9047296..62ab88bc6 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -152,12 +152,13 @@ class RegisterValidatorV1(Container): pubkey: BLSPubkey ``` -##### `builder_getPayloadV1` Response +##### `builder_getHeaderV1` Response ```python -class GetPayloadResponseV1(Container): +class GetHeaderResponseV1(Container): payload: ExecutionPayloadHeader value: uint256 + pubkey: BLSPubkey ``` ##### `builder_getPayloadV1` Request From 4c44494cb00075732ffd20ca38a103d3b20b92c9 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Mon, 25 Apr 2022 10:52:07 +0200 Subject: [PATCH 13/41] add status check to builder --- src/builder/specification.md | 42 ++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 62ab88bc6..e0f6af01a 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -217,6 +217,28 @@ The list of error codes introduced by this specification can be found below. | -32603 | Internal error | Internal JSON-RPC error. | | -32700 | Parse error | Invalid JSON was received by the server. | +Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered. + +For example: + +``` +$ curl https://localhost:8550 \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params": ["0x1"],"id":1}' +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32000, + "message": "Server error", + "data": { + "err": "Database corrupted" + } + } +} +``` + ## Routines ### Signing @@ -231,6 +253,22 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con ## Methods +### `builder_status` + +#### Request + +- method: `builder_status` +- params: `null` + +#### Response + +- result: `null` +- error: code and message set in case the builder is not operating normally. + +#### Specification + +1. Builder software **SHOULD** return `-32000: Server error` if it is unable to respond to requests. `err` **MUST** be set explaining the issue. + ### `builder_registerValidatorV1` #### Request @@ -246,7 +284,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Response - result: `null` -- error: code and message set in case an exception happens while getting the payload. +- error: code and message set in case an exception happens while registering the validator. #### Specification 1. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. @@ -271,7 +309,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - `value`: `DATA`, 32 Bytes - the payment in wei that will be paid to the `feeRecipient` account. - `pubkey`: `DATA`, 48 Bytes - the public key associated with the builder. - `signature`: `DATA`, 96 Bytes - BLS signature of the builder over `message`. -- error: code and message set in case an exception happens while getting the payload. +- error: code and message set in case an exception happens while getting the header. #### Specification 1. Builder software **SHOULD** respond immediately with the `header` that increases the `feeRecipient`'s balance by the most. From b402f04861b5a761a63330923a295ab61f44ac87 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Mon, 25 Apr 2022 11:02:19 +0200 Subject: [PATCH 14/41] don't return null in happy case --- src/builder/specification.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index e0f6af01a..f10824456 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -262,12 +262,12 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Response -- result: `null` +- result: `enum`, `"OK" | null` - error: code and message set in case the builder is not operating normally. #### Specification -1. Builder software **SHOULD** return `-32000: Server error` if it is unable to respond to requests. `err` **MUST** be set explaining the issue. +1. Builder software **MUST** return `-32000: Server error` if it is unable to respond to requests. `err` **SHOULD** be set explaining the issue and `result` **MUST** be `null`. ### `builder_registerValidatorV1` @@ -283,13 +283,14 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Response -- result: `null` +- result: `enum`, `"OK" | null` - error: code and message set in case an exception happens while registering the validator. #### Specification 1. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. 2. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. 3. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. +4. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. ### `builder_getHeaderV1` From b006213fe787b5b06136c935ba3caa6dd015592b Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Mon, 25 Apr 2022 11:11:06 +0200 Subject: [PATCH 15/41] rework signature defs a bit --- src/builder/specification.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index f10824456..27090ae90 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -143,25 +143,25 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran Consider the following definitions supplementary to the definitions in [`consensus-specs`][consensus-specs]. -##### `builder_registerValidatorV1` Request +##### `ValidatorRegistrationV1` ```python -class RegisterValidatorV1(Container): +class ValidatorRegistrationV1(Container): feeRecipient: Bytes20 timestamp: uint64 pubkey: BLSPubkey ``` -##### `builder_getHeaderV1` Response +##### `BuilderReceiptV1` ```python -class GetHeaderResponseV1(Container): +class BuilderReceiptV1(Container): payload: ExecutionPayloadHeader value: uint256 pubkey: BLSPubkey ``` -##### `builder_getPayloadV1` Request +##### `SignedBlindBeaconBlock ###### `SignedBlindBeaconBlock` @@ -278,8 +278,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con 1. `message`: `object` 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. 2. `timestamp`: `QUANTITY`, uint64 - Unix timestamp of announcement. - 3. `pubkey`: `DATA`, 48 Bytes - Public key of validator. - 3. `signature`: `DATA`, 96 Bytes - Signature over `feeRecipient` and `timestamp`. + 3. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. + 3. `signature`: `DATA`, 96 Bytes - BLS signature over [`ValidatorRegistrationV1`](#validatorregistrationv1). #### Response @@ -299,7 +299,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getHeaderV1` - params: 1. `slot`: `QUANTITY`, 64 Bits - Slot number of the block proposal. - 2. `pubkey`: `QUANTITY`, 64 Bits - Corresponding public key of proposer. + 2. `pubkey`: `QUANTITY`, 64 Bits - BLS public key of proposer. 3. `hash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. #### Response @@ -307,9 +307,9 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - result: `object` - `message`: `object` - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). - - `value`: `DATA`, 32 Bytes - the payment in wei that will be paid to the `feeRecipient` account. - - `pubkey`: `DATA`, 48 Bytes - the public key associated with the builder. - - `signature`: `DATA`, 96 Bytes - BLS signature of the builder over `message`. + - `value`: `DATA`, 32 Bytes - Payment in wei that will be paid to the `feeRecipient` account. + - `pubkey`: `DATA`, 48 Bytes - BLS public key associated with the builder. + - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderReceiptV1`](#builderreceiptv1). - error: code and message set in case an exception happens while getting the header. #### Specification @@ -326,7 +326,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getPayloadV1` - params: 1. `message`: [`SignedBlindBeaconBlock`](#signedblindbeaconblockv1). - 2. `signature`: `DATA`, 96 Bytes. + 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`SignedBlindBeaconBlock`](#signedblindbeaconblockv1). #### Response From 4338877554fae7eb3ac28e73d1e1a685ca891c16 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Mon, 25 Apr 2022 13:06:30 +0200 Subject: [PATCH 16/41] missing closing backtick --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 27090ae90..d22c2393d 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -161,7 +161,7 @@ class BuilderReceiptV1(Container): pubkey: BLSPubkey ``` -##### `SignedBlindBeaconBlock +##### `SignedBlindBeaconBlock` ###### `SignedBlindBeaconBlock` From 25764b8f02dc4b561fb16bb3b90d5cdd91b92884 Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Wed, 27 Apr 2022 09:25:55 +0200 Subject: [PATCH 17/41] Update src/builder/specification.md Co-authored-by: terence tsao --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index d22c2393d..056dc99f6 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -126,7 +126,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `ValidatorIndex`: `QUANTITY`, 64 Bits ### `SyncAggregateV1` -- `syncCommitteeBits`: `DATA`, 0 to 64 Bytes +- `syncCommitteeBits`: `DATA`, 64 Bytes - `syncCommitteeSignature`: `DATA`, 96 Bytes #### Signed Containers From c81487292029b158169712aadedef97a73166dff Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Wed, 27 Apr 2022 09:26:31 +0200 Subject: [PATCH 18/41] Update src/builder/specification.md Co-authored-by: terence tsao --- src/builder/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 056dc99f6..33b8370f7 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -62,8 +62,8 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `randaoReveal`: `DATA`, 96 Bytes - `eth1Data`: `object`, [`Eth1DataV1`](#eth1datav1) - `graffiti`: `DATA`, 32 Bytes -- `proposerSlashings`: `object`, [`ProposerSlashingV1`](#proposerslashingv1) -- `attesterSlashings`: `object`, [`AttesterSlashingV1`](#attesterslashingv1) +- `proposerSlashings`: `Array`, [`ProposerSlashingV1`](#proposerslashingv1) +- `attesterSlashings`: `Array`, [`AttesterSlashingV1`](#attesterslashingv1) - `attestations`: `Array`, [`AttestationV1`](#attestationv1) - `deposits`: `Array`, [`DespositV1`](#depositv1) - `voluntaryExits`: `Array`, [`SignedVoluntaryExitV1`](#signedvoluntaryexitv1) From d0ae0d191b6767cd23d93793bc64b9d0cd041457 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Wed, 27 Apr 2022 11:05:17 +0200 Subject: [PATCH 19/41] fix wrong message in get payload --- src/builder/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 33b8370f7..c742e313e 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -325,8 +325,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getPayloadV1` - params: - 1. `message`: [`SignedBlindBeaconBlock`](#signedblindbeaconblockv1). - 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`SignedBlindBeaconBlock`](#signedblindbeaconblockv1). + 1. `message`: [`BlindBeaconBlock`](#blindbeaconblockv1). + 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`BlindBeaconBlock`](#blindbeaconblockv1). #### Response From f666d350a8165f636f6ed0f9b489b62604961c9e Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Wed, 27 Apr 2022 15:48:28 +0200 Subject: [PATCH 20/41] Update src/builder/specification.md Co-authored-by: Chris Hager --- src/builder/specification.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index c742e313e..edb9657a1 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -161,16 +161,6 @@ class BuilderReceiptV1(Container): pubkey: BLSPubkey ``` -##### `SignedBlindBeaconBlock` - -###### `SignedBlindBeaconBlock` - -```python -class SignedBlindBeaconBlock(Container): - message: BlindBeaconBlock - signature: BLSSignature -``` - ###### `BlindBeaconBlock` ```python From bd6546751054f14ce80711f5dc66508ef3f447c7 Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Thu, 28 Apr 2022 11:07:29 +0200 Subject: [PATCH 21/41] Update src/builder/specification.md Co-authored-by: Chris Hager --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index edb9657a1..3e6433efd 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -289,7 +289,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getHeaderV1` - params: 1. `slot`: `QUANTITY`, 64 Bits - Slot number of the block proposal. - 2. `pubkey`: `QUANTITY`, 64 Bits - BLS public key of proposer. + 2. `pubkey`: `QUANTITY`, 48 Bytes - BLS public key of validator. 3. `hash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. #### Response From 6e73da23901d961c9e097054b6e21abee1654d49 Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Thu, 28 Apr 2022 17:52:15 +0200 Subject: [PATCH 22/41] Apply suggestions from code review Co-authored-by: Alex Stokes Co-authored-by: Mikhail Kalinin --- src/builder/specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 3e6433efd..7e43f10ff 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -155,8 +155,8 @@ class ValidatorRegistrationV1(Container): ##### `BuilderReceiptV1` ```python -class BuilderReceiptV1(Container): - payload: ExecutionPayloadHeader +class BuilderBidV1(Container): + header: ExecutionPayloadHeader value: uint256 pubkey: BLSPubkey ``` @@ -185,7 +185,7 @@ class BlindBeaconBlockBody(Container): deposits: List[Deposit, MAX_DEPOSITS] voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS] sync_aggregate: SyncAggregate - execution_payload: ExecutionPayloadHeader + execution_payload_header: ExecutionPayloadHeader ``` ## Errors @@ -324,7 +324,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while proposing the payload. #### Specification -1. Builder software **MUST** verify that the beacon block's exeuction payload is a matching [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) provided from [`builder_getHeaderV1`](#buildergetheaderv1), otherwise the return `-32004: Unknown block`. +1. Builder software **MUST** verify that the beacon block's execution payload is a matching [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) provided from [`builder_getHeaderV1`](#buildergetheaderv1), otherwise the return `-32004: Unknown block`. 2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. [consensus-specs]: https://github.com/ethereum/consensus-specs From 989c3bfd5b4c73ae4c9614020b21bd81b215130c Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 28 Apr 2022 17:55:04 +0200 Subject: [PATCH 23/41] remove diagram --- src/builder/specification.md | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 7e43f10ff..ad912a46b 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -2,32 +2,6 @@ This document specifies the Builder API methods that the Consensus Layer uses to interact with external block builders. -```mermaid -sequenceDiagram - participant consensus - participant mev_boost - participant relays - Title: Block Proposal - Note over consensus: sign fee recipient announcement - consensus->>mev_boost: builder_registerValidator - mev_boost->>relays: builder_registerValidator - Note over consensus: wait for allocated slot - consensus->>mev_boost: builder_getHeader - mev_boost->>relays: builder_getHeader - relays-->>mev_boost: builder_getHeader response - Note over mev_boost: verify response matches expected - Note over mev_boost: select best payload - mev_boost-->>consensus: builder_getHeader response - Note over consensus: sign the block - consensus->>mev_boost: builder_getPayload - Note over mev_boost: identify payload source - mev_boost->>relays: builder_getPayload - Note over relays: validate signature - relays-->>mev_boost: builder_getPayload response - Note over mev_boost: verify response matches expected - mev_boost-->>consensus: builder_getPayload response -``` - ## Structures ### `ExecutionPayloadV1` From dfc10b6ff29f6c9624b7fb2d94951a67243868eb Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 28 Apr 2022 17:57:29 +0200 Subject: [PATCH 24/41] soften requirement for ELs to implement interface --- src/builder/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/builder/README.md b/src/builder/README.md index 7a81c9474..fa721abb8 100644 --- a/src/builder/README.md +++ b/src/builder/README.md @@ -1,7 +1,7 @@ # Builder JSON-RPC API -The Builder JSON-RPC API is a collection of methods that all execution clients implement. -This interface allows the communication between the consensus layer and external builders. +The Builder JSON-RPC API is a collection of methods that external block building software must +implement. This interface allows the communication between the consensus layer and external builders. This API is in *active development* and currently [specified as a markdown document](./specification.md). A schema will follow once the specification stabilizes. From 3614eec1f5225c5e4e58e3379feac993cc846e0c Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Thu, 28 Apr 2022 17:58:00 +0200 Subject: [PATCH 25/41] Apply suggestions from code review Co-authored-by: Mikhail Kalinin --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index ad912a46b..421f1ff26 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -42,7 +42,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `deposits`: `Array`, [`DespositV1`](#depositv1) - `voluntaryExits`: `Array`, [`SignedVoluntaryExitV1`](#signedvoluntaryexitv1) - `syncAggregate`: `object`, [`SyncAggregateV1`](#syncaggregatev1) -- `executionPayload`: `object`, [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) +- `executionPayloadHeader`: `object`, [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) ### `Eth1DataV1` - `depositRoot`: `DATA`, 32 Bytes From a90e003ac1c557734f650a5666e7e868b7ebce50 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Thu, 28 Apr 2022 18:59:03 +0200 Subject: [PATCH 26/41] change builder receipt to builder bid --- src/builder/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 421f1ff26..f7f69b089 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -126,7 +126,7 @@ class ValidatorRegistrationV1(Container): pubkey: BLSPubkey ``` -##### `BuilderReceiptV1` +##### `BuilderBidV1` ```python class BuilderBidV1(Container): @@ -273,7 +273,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). - `value`: `DATA`, 32 Bytes - Payment in wei that will be paid to the `feeRecipient` account. - `pubkey`: `DATA`, 48 Bytes - BLS public key associated with the builder. - - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderReceiptV1`](#builderreceiptv1). + - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderBid1`](#builderbidv1). - error: code and message set in case an exception happens while getting the header. #### Specification From e249cb396abe414180665e11237170aa2133b724 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 29 Apr 2022 08:48:31 +0200 Subject: [PATCH 27/41] blind -> blinded --- src/builder/specification.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index f7f69b089..7270ac91c 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -25,14 +25,14 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran - `blockHash`: `DATA`, 32 Bytes - `transactionsRoot`: `DATA`, 32 Bytes -### `BlindBeaconBlockV1` +### `BlindedBeaconBlockV1` - `slot`: `QUANTITY`, 64 Bits - `proposerIndex`: `QUANTITY`, 64 Bits - `parentRoot`: `DATA`, 32 Bytes - `stateRoot`: `DATA`, 32 Bytes -- `body`: `object`, [`BlindBeaconBlockBodyV1`](#blindbeaconblockbodyv1) +- `body`: `object`, [`BlindedBeaconBlockBodyV1`](#blindedbeaconblockbodyv1) -### `BlindBeaconBlockBodyV1` +### `BlindedBeaconBlockBodyV1` - `randaoReveal`: `DATA`, 96 Bytes - `eth1Data`: `object`, [`Eth1DataV1`](#eth1datav1) - `graffiti`: `DATA`, 32 Bytes @@ -135,21 +135,21 @@ class BuilderBidV1(Container): pubkey: BLSPubkey ``` -###### `BlindBeaconBlock` +###### `BlindedBeaconBlock` ```python -class BlindBeaconBlock(Container): +class BlindedBeaconBlock(Container): slot: Slot proposer_index: ValidatorIndex parent_root: Root state_root: Root - body: BlindBeaconBlockBody + body: BlindedBeaconBlockBody ``` -###### `BlindBeaconBlockBody` +###### `BlindedBeaconBlockBody` ```python -class BlindBeaconBlockBody(Container): +class BlindedBeaconBlockBody(Container): randao_reveal: BLSSignature eth1_data: Eth1Data graffiti: Bytes32 @@ -210,7 +210,7 @@ $ curl https://localhost:8550 \ All signature operations should follow the [standard BLS operations][bls] interface defined in `consensus-specs`. There are two types of data to sign over in the Builder API: -* In-protocol messages, e.g. [`BlindBeaconBlock`](#blindbeaconblock), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. +* In-protocol messages, e.g. [`BlindedBeaconBlock`](#blindedbeaconblock), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and use the domain specified for beacon block proposals. * Builder API messages, e.g. [`builder_registerValidatorV1`](#builder_registerValidatorV1) and the response to [`builder_getHeader`](#response-2), which should compute the signing root using [`compute_signing_root`][compute-signing-root] and the domain `DomainType('0xXXXXXXXX')` (TODO: get a proper domain). As `compute_signing_root` takes `SSZObject` as input, client software should convert in-protocol messages to their SSZ representation to compute the signing root and Builder API messages to the SSZ representations defined [above](#sszobjects). @@ -289,8 +289,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getPayloadV1` - params: - 1. `message`: [`BlindBeaconBlock`](#blindbeaconblockv1). - 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`BlindBeaconBlock`](#blindbeaconblockv1). + 1. `message`: [`BlindedBeaconBlock`](#blindedbeaconblockv1). + 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`BlindedBeaconBlock`](#blindedbeaconblockv1). #### Response From 66afd7fe38cb63c513b97314e35698027bb4c3d6 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 29 Apr 2022 08:52:32 +0200 Subject: [PATCH 28/41] verify registered validator --- src/builder/specification.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 7270ac91c..3585aa330 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -251,10 +251,11 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while registering the validator. #### Specification -1. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. -2. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. -3. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. -4. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. +1. Builder software **MUST** verify `pubkey` corresponds to an active or pending validator, otherwise return error `-32003: Unknown validator`. +2. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. +3. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. +4. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. +5. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. ### `builder_getHeaderV1` From 4ae07f35d328909743c6a03b6923bc8aa73de6cd Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 29 Apr 2022 08:53:22 +0200 Subject: [PATCH 29/41] typo fix --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 3585aa330..39c326650 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -274,7 +274,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). - `value`: `DATA`, 32 Bytes - Payment in wei that will be paid to the `feeRecipient` account. - `pubkey`: `DATA`, 48 Bytes - BLS public key associated with the builder. - - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderBid1`](#builderbidv1). + - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderBidV1`](#builderbidv1). - error: code and message set in case an exception happens while getting the header. #### Specification From 280bff1ec51b87e68c44913a6d88dfa626f43c1e Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 29 Apr 2022 08:57:35 +0200 Subject: [PATCH 30/41] relax get payload header assumptions --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 39c326650..547ab2a70 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -299,7 +299,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while proposing the payload. #### Specification -1. Builder software **MUST** verify that the beacon block's execution payload is a matching [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) provided from [`builder_getHeaderV1`](#buildergetheaderv1), otherwise the return `-32004: Unknown block`. +1. Builder software **MUST** be able to un-blind the [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) in `message`, otherwise the return `-32004: Unknown block`. 2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. [consensus-specs]: https://github.com/ethereum/consensus-specs From 40547baaba75c9d81ee77453e32145bd72a4a2b1 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Fri, 29 Apr 2022 08:59:53 +0200 Subject: [PATCH 31/41] competing chains note --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 547ab2a70..d48e93fac 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -300,7 +300,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Specification 1. Builder software **MUST** be able to un-blind the [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1) in `message`, otherwise the return `-32004: Unknown block`. -2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. +2. Builder software **MUST** verify that `signature` is a BLS signature over `block` using [`verify_block_signature`][verify-block-signature] from the validator that is expected to propose in the slot. If the signature is determined to be invalid or from a different validator than expected, the builder **MUST** return `-32005: Invalid signature`. It's possible that competing chains could have different proposer shuffling, causing multiple proposer indexes to be valid for a given slot. [consensus-specs]: https://github.com/ethereum/consensus-specs [bls]: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#bls-signatures From 1cbd4e74d9e7d2797d1e6c5ccad686597a02db6f Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sat, 30 Apr 2022 11:20:17 +0200 Subject: [PATCH 32/41] add gas target to validator registration --- src/builder/specification.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index d48e93fac..93081f013 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -122,6 +122,7 @@ Consider the following definitions supplementary to the definitions in [`consens ```python class ValidatorRegistrationV1(Container): feeRecipient: Bytes20 + gasTarget: uint64 timestamp: uint64 pubkey: BLSPubkey ``` @@ -241,7 +242,8 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - params: 1. `message`: `object` 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. - 2. `timestamp`: `QUANTITY`, uint64 - Unix timestamp of announcement. + 2. `gasTarget`: QUANTITY, 64 bits - Target for block `gasTarget`. + 2. `timestamp`: `QUANTITY`, 64 bits - Unix timestamp of announcement. 3. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. 3. `signature`: `DATA`, 96 Bytes - BLS signature over [`ValidatorRegistrationV1`](#validatorregistrationv1). @@ -283,6 +285,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con 3. Builder software **MUST** return `-32002: Unknown validator` if `pubkey` does not map to the validator that is expected to propose at `slot`. 4. Builder software **MUST** return `-32003: Unknown fee recipient` if the builder does not have a `feeRecipient` mapped to the validator. 5. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. +6. Builder software **MUST** return a header whose `gasLimit` is equal to the validator's registered `gasTarget * 2` or as close as possible under the constraints of the consensus rules. ### `builder_getPayloadV1` From 4bba25c81f4569da3f8ead1ab60e192683c45ed8 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sat, 30 Apr 2022 11:43:28 +0200 Subject: [PATCH 33/41] rename to parent hash in get header --- src/builder/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 93081f013..7b1b295d4 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -267,7 +267,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - params: 1. `slot`: `QUANTITY`, 64 Bits - Slot number of the block proposal. 2. `pubkey`: `QUANTITY`, 48 Bytes - BLS public key of validator. - 3. `hash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. + 3. `parentHash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. #### Response @@ -281,7 +281,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Specification 1. Builder software **SHOULD** respond immediately with the `header` that increases the `feeRecipient`'s balance by the most. -2. Builder software **MUST** return `-32001: Unknown hash` if the block identified by `hash` is not known. +2. Builder software **MUST** return a `header` whose `parentHash` matches the request's `parentHash`. If `parentHash` is not known by the builder, it **MUST** return `-32001: Unknown hash`. 3. Builder software **MUST** return `-32002: Unknown validator` if `pubkey` does not map to the validator that is expected to propose at `slot`. 4. Builder software **MUST** return `-32003: Unknown fee recipient` if the builder does not have a `feeRecipient` mapped to the validator. 5. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. From 572f15044fe6a4a61d7eb440238b358d45eea924 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sat, 30 Apr 2022 15:31:28 +0200 Subject: [PATCH 34/41] fix typo --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 7b1b295d4..8871e0ab9 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -97,7 +97,7 @@ Equivalent to `ExecutionPayloadV1`, except `transactions` is replaced with `tran ### `VoluntaryExitV1` - `epoch`: `QUANTITY`, 64 Bits -- `ValidatorIndex`: `QUANTITY`, 64 Bits +- `validatorIndex`: `QUANTITY`, 64 Bits ### `SyncAggregateV1` - `syncCommitteeBits`: `DATA`, 64 Bytes From 377748659e14518b5865ae21c719a08f190e2768 Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Mon, 2 May 2022 09:36:34 +0200 Subject: [PATCH 35/41] fix numbering Co-authored-by: Chris Hager --- src/builder/specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 8871e0ab9..271c21009 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -243,9 +243,9 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con 1. `message`: `object` 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. 2. `gasTarget`: QUANTITY, 64 bits - Target for block `gasTarget`. - 2. `timestamp`: `QUANTITY`, 64 bits - Unix timestamp of announcement. - 3. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. - 3. `signature`: `DATA`, 96 Bytes - BLS signature over [`ValidatorRegistrationV1`](#validatorregistrationv1). + 3. `timestamp`: `QUANTITY`, 64 bits - Unix timestamp of announcement. + 4. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. + 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`ValidatorRegistrationV1`](#validatorregistrationv1). #### Response From 190b7f3eef580e757f1674fa4b6324ba255c93aa Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Mon, 2 May 2022 09:37:07 +0200 Subject: [PATCH 36/41] fix incorrect error num Co-authored-by: Alex Stokes --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 271c21009..f1ed1828d 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -253,7 +253,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - error: code and message set in case an exception happens while registering the validator. #### Specification -1. Builder software **MUST** verify `pubkey` corresponds to an active or pending validator, otherwise return error `-32003: Unknown validator`. +1. Builder software **MUST** verify `pubkey` corresponds to an active or pending validator, otherwise return error `-32002: Unknown validator`. 2. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. 3. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. 4. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. From 42e1fbe6abaa4b35cb0e27dd4f08d486749b1f5e Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Mon, 2 May 2022 09:37:29 +0200 Subject: [PATCH 37/41] wrong value ident Co-authored-by: Enrico Del Fante --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index f1ed1828d..785b27587 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -266,7 +266,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - method: `builder_getHeaderV1` - params: 1. `slot`: `QUANTITY`, 64 Bits - Slot number of the block proposal. - 2. `pubkey`: `QUANTITY`, 48 Bytes - BLS public key of validator. + 2. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. 3. `parentHash`: `DATA`, 32 Bytes - Hash of execution layer block the proposer will use as the proposal's parent. #### Response From fcddc0d8a76844dad6b8b6a3a866330b1a0da1fb Mon Sep 17 00:00:00 2001 From: lightclient <14004106+lightclient@users.noreply.github.com> Date: Mon, 2 May 2022 09:37:45 +0200 Subject: [PATCH 38/41] better value ident Co-authored-by: Enrico Del Fante --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 785b27587..880cb6d83 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -274,7 +274,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - result: `object` - `message`: `object` - `header`: [`ExecutionPayloadHeaderV1`](#executionpayloadheaderv1). - - `value`: `DATA`, 32 Bytes - Payment in wei that will be paid to the `feeRecipient` account. + - `value`: `QUANTITY`, 256 Bits - Payment in wei that will be paid to the `feeRecipient` account. - `pubkey`: `DATA`, 48 Bytes - BLS public key associated with the builder. - `signature`: `DATA`, 96 Bytes - BLS signature over [`BuilderBidV1`](#builderbidv1). - error: code and message set in case an exception happens while getting the header. From 14963f3ce547ffc2ffc9cff5190359a864a924d5 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Mon, 2 May 2022 14:12:57 +0200 Subject: [PATCH 39/41] use gas limit instead of gas target --- src/builder/specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 880cb6d83..98be17fbe 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -122,7 +122,7 @@ Consider the following definitions supplementary to the definitions in [`consens ```python class ValidatorRegistrationV1(Container): feeRecipient: Bytes20 - gasTarget: uint64 + gasLimit: uint64 timestamp: uint64 pubkey: BLSPubkey ``` @@ -242,7 +242,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con - params: 1. `message`: `object` 1. `feeRecipient`: `DATA`, 20 Bytes - Address of account which should receive fees. - 2. `gasTarget`: QUANTITY, 64 bits - Target for block `gasTarget`. + 2. `gasLimit`: `QUANTITY`, 64 bits - Target gas limit for block. 3. `timestamp`: `QUANTITY`, 64 bits - Unix timestamp of announcement. 4. `pubkey`: `DATA`, 48 Bytes - BLS public key of validator. 2. `signature`: `DATA`, 96 Bytes - BLS signature over [`ValidatorRegistrationV1`](#validatorregistrationv1). @@ -285,7 +285,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con 3. Builder software **MUST** return `-32002: Unknown validator` if `pubkey` does not map to the validator that is expected to propose at `slot`. 4. Builder software **MUST** return `-32003: Unknown fee recipient` if the builder does not have a `feeRecipient` mapped to the validator. 5. Builder software **MAY** set the `feeRecipient` for the block to a different address than the address mapped to the validator so long as a payment equal to `value` is made to `feeRecipient`. -6. Builder software **MUST** return a header whose `gasLimit` is equal to the validator's registered `gasTarget * 2` or as close as possible under the constraints of the consensus rules. +6. Builder software **MUST** return a header whose `gasLimit` is equal to the validator's registered `gasLimit` or as close as possible under the constraints of the consensus rules. ### `builder_getPayloadV1` From d891d16b81af7e742f0235e9dc833854310a5f35 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Tue, 3 May 2022 08:50:44 +0200 Subject: [PATCH 40/41] remove impl detail --- src/builder/specification.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 98be17fbe..0a7398e94 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -256,8 +256,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con 1. Builder software **MUST** verify `pubkey` corresponds to an active or pending validator, otherwise return error `-32002: Unknown validator`. 2. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. 3. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. -4. Builder software **MUST** store `feeRecipient` in a map keyed by `pubkey`. -5. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. +4. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. ### `builder_getHeaderV1` From e7dfb37ffa47688ed3fd2e02abced44f72cebf69 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Tue, 3 May 2022 08:58:23 +0200 Subject: [PATCH 41/41] change validity delta on timestamps to 10 sec --- src/builder/specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/builder/specification.md b/src/builder/specification.md index 0a7398e94..e5a4923f2 100644 --- a/src/builder/specification.md +++ b/src/builder/specification.md @@ -255,7 +255,7 @@ As `compute_signing_root` takes `SSZObject` as input, client software should con #### Specification 1. Builder software **MUST** verify `pubkey` corresponds to an active or pending validator, otherwise return error `-32002: Unknown validator`. 2. Builder software **MUST** verify `signature` is valid under `pubkey`, otherwise return error `-32005: Invalid Signature`. -3. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 1 hour in the future with error `-32007: Invalid timestamp`. +3. Builder software **MUST** respond to requests where `timestamp` is less than or equal to the latest announcement from the validator or more than 10 seconds in the future with error `-32007: Invalid timestamp`. 4. Builder software **MUST** return `result` as `"OK"` if the request succeeds, `null` otherwise. ### `builder_getHeaderV1`