From 07d97529716d573150804c303a16e8ee308c6359 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sun, 16 Jul 2023 11:05:38 +0100 Subject: [PATCH 1/5] Add block v3 endpoint. --- apis/validator/block.v2.yaml | 1 + apis/validator/block.v3.yaml | 92 ++++++++++++++++++++++++++++++++++++ beacon-node-oapi.yaml | 13 +++++ types/primitive.yaml | 3 ++ 4 files changed, 109 insertions(+) create mode 100644 apis/validator/block.v3.yaml diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index 403d4ffb..29ac4cc9 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -4,6 +4,7 @@ get: - Validator operationId: "produceBlockV2" summary: "Produce a new block, without signature." + deprecated: true description: | Requests a beacon node to produce a valid block, which can then be signed by a validator. diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml new file mode 100644 index 00000000..262f3640 --- /dev/null +++ b/apis/validator/block.v3.yaml @@ -0,0 +1,92 @@ +get: + tags: + - ValidatorRequiredApi + - Validator + operationId: "produceBlockV3" + summary: "Produce a new block, without signature." + description: | + Requests a beacon node to produce a valid block, which can then be signed by a validator. The + returned block may be blinded or unblinded, depending on the current state of the network as + decided by the execution and beacon nodes. + + The beacon node must return an unblinded block if it obtains the execution payload from its + paired execution node. It must only return a blinded block if it obtains the execution payload + header from an MEV relay. + + Metadata in the response indicates the type of block produced, and the supported types of block + will be added to as forks progress. + parameters: + - name: slot + in: path + required: true + description: "The slot for which the block should be proposed." + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" + - name: randao_reveal + in: query + required: true + description: "The validator's randao reveal value." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Signature' + - name: graffiti + in: query + required: false + description: "Arbitrary data validator wants to include in block." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Graffiti' + - name: skip_randao_verification + in: query + required: false + description: | + Skip verification of the `randao_reveal` value. If this flag is set then the + `randao_reveal` must be set to the point at infinity (`0xc0..00`). This query parameter + is a flag and does not take a value. + schema: {} + allowEmptyValue: true + responses: + "200": + description: Success response + headers: + Eth-Consensus-Version: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + Eth-Blinded-Payload: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Blinded-Payload' + Eth-Payload-Value: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Payload-Value' + content: + application/json: + schema: + title: ProduceBlockV3Response + type: object + properties: + version: + type: string + enum: [ phase0, altair, bellatrix, capella, deneb ] + example: "phase0" + data: + oneOf: + - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconBlock' + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBlockContents" + application/octet-stream: + schema: + description: "SSZ serialized block or blinded block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and block type in `Eth-Blinded-Payload`." + "400": + description: "Invalid block production request" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + examples: + InvalidRequest: + value: + code: 400 + message: "Invalid request to produce a block" + "500": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' + "503": + $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index c63c6df4..a2fbfb65 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -174,6 +174,8 @@ paths: $ref: "./apis/validator/duties/sync.yaml" /eth/v2/validator/blocks/{slot}: $ref: "./apis/validator/block.v2.yaml" + /eth/v3/validator/blocks/{slot}: + $ref: "./apis/validator/block.v3.yaml" /eth/v1/validator/blinded_blocks/{slot}: $ref: "./apis/validator/blinded_block.yaml" /eth/v1/validator/attestation_data: @@ -330,6 +332,7 @@ components: Bellatrix.SignedBlindedBeaconBlock: $ref: './types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock' ConsensusVersion: + type: string enum: [phase0, altair, bellatrix, capella, deneb] example: "phase0" SignedValidatorRegistration: @@ -421,3 +424,13 @@ components: required: true schema: $ref: '#/components/schemas/ConsensusVersion' + Eth-Blinded-Payload: + description: Required in response so client can deserialize returned json or ssz data to the correct object. + required: true + schema: + type: boolean + Eth-Payload-Value: + description: Required in response so client can determine relative value of execution payloads. + required: true + schema: + $ref: './types/primitive.yaml#/Wei' diff --git a/types/primitive.yaml b/types/primitive.yaml index 65fe7dde..f87a4718 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -23,6 +23,9 @@ GenesisTime: - example: "1590832934" - description: "The genesis_time configured for the beacon node, which is the unix time in seconds at which the Eth2.0 chain began." +Wei: + $ref: "./primitive.yaml#/Uint256" + Gwei: $ref: "./primitive.yaml#/Uint64" From 7d11c256df24592918679ba1b69ad43c3e1aa9e9 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sun, 16 Jul 2023 11:08:17 +0100 Subject: [PATCH 2/5] Deprecate blinded block request. --- apis/validator/blinded_block.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index 52edf072..20c2d42b 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -4,6 +4,7 @@ get: - Validator operationId: "produceBlindedBlock" summary: "Produce a new blinded block, without signature." + deprecated: true description: | Requests a beacon node to produce a valid blinded block, which can then be signed by a validator. A blinded block is a block with only a transactions root, rather than a full transactions list. From 8766d92e10bdd6737ed2974a30ea50df0e994e33 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Fri, 21 Jul 2023 15:28:52 +0100 Subject: [PATCH 3/5] Add JSON metadata. --- apis/validator/block.v3.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 262f3640..0de1a805 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -59,10 +59,16 @@ get: title: ProduceBlockV3Response type: object properties: - version: + consensus-version: type: string enum: [ phase0, altair, bellatrix, capella, deneb ] example: "phase0" + blinded-payload: + type: boolean + example: false + payload-value: + type: string + example: "12345" data: oneOf: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconBlock' From d3b9cce76ab94be9aabe4b516839acb5e662ad76 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sat, 22 Jul 2023 16:40:43 +0100 Subject: [PATCH 4/5] Clearer metadata names. --- apis/validator/block.v3.yaml | 12 ++++++------ beacon-node-oapi.yaml | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 0de1a805..b93ebe9a 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -49,10 +49,10 @@ get: headers: Eth-Consensus-Version: $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' - Eth-Blinded-Payload: - $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Blinded-Payload' - Eth-Payload-Value: - $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Payload-Value' + Eth-Execution-Payload-Blinded: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Blinded' + Eth-Execution-Payload-Value: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Value' content: application/json: schema: @@ -63,10 +63,10 @@ get: type: string enum: [ phase0, altair, bellatrix, capella, deneb ] example: "phase0" - blinded-payload: + execution-payload-blinded: type: boolean example: false - payload-value: + execution-payload-value: type: string example: "12345" data: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index a2fbfb65..01560874 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -424,12 +424,12 @@ components: required: true schema: $ref: '#/components/schemas/ConsensusVersion' - Eth-Blinded-Payload: + Eth-Execution-Payload-Blinded: description: Required in response so client can deserialize returned json or ssz data to the correct object. required: true schema: type: boolean - Eth-Payload-Value: + Eth-Execution-Payload-Value: description: Required in response so client can determine relative value of execution payloads. required: true schema: From fca70b2fdde4f32b1a6074f433717b6868bc8342 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Mon, 24 Jul 2023 23:40:39 +0100 Subject: [PATCH 5/5] Use standard name for metadata. --- apis/validator/block.v3.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index b93ebe9a..632863a3 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -59,7 +59,7 @@ get: title: ProduceBlockV3Response type: object properties: - consensus-version: + version: type: string enum: [ phase0, altair, bellatrix, capella, deneb ] example: "phase0"