Add block v3 endpoint. (#339)

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.

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.
 

apis/validator/block.v3.yaml

@@ -0,0 +1,98 @@
+get:
+  tags:
+    - ValidatorRequiredApi
+    - Validator
+  operationId: "produceBlockV3"
+  summary: "Produce a new block, without signature."
+  description: |
+    Requests a beacon node to produce a valid block, which can then be signed by a validator. The
+    returned block may be blinded or unblinded, depending on the current state of the network as
+    decided by the execution and beacon nodes.
+
+    The beacon node must return an unblinded block if it obtains the execution payload from its
+    paired execution node. It must only return a blinded block if it obtains the execution payload
+    header from an MEV relay.
+
+    Metadata in the response indicates the type of block produced, and the supported types of block
+    will be added to as forks progress.
+  parameters:
+    - name: slot
+      in: path
+      required: true
+      description: "The slot for which the block should be proposed."
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+    - name: randao_reveal
+      in: query
+      required: true
+      description: "The validator's randao reveal value."
+      schema:
+        $ref: '../../beacon-node-oapi.yaml#/components/schemas/Signature'
+    - name: graffiti
+      in: query
+      required: false
+      description: "Arbitrary data validator wants to include in block."
+      schema:
+        $ref: '../../beacon-node-oapi.yaml#/components/schemas/Graffiti'
+    - name: skip_randao_verification
+      in: query
+      required: false
+      description: |
+        Skip verification of the `randao_reveal` value. If this flag is set then the
+        `randao_reveal` must be set to the point at infinity (`0xc0..00`). This query parameter
+        is a flag and does not take a value.
+      schema: {}
+      allowEmptyValue: true
+  responses:
+    "200":
+      description: Success response
+      headers:
+        Eth-Consensus-Version:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
+        Eth-Execution-Payload-Blinded:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Blinded'
+        Eth-Execution-Payload-Value:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Value'
+      content:
+        application/json:
+          schema:
+            title: ProduceBlockV3Response
+            type: object
+            properties:
+              version:
+                type: string
+                enum: [ phase0, altair, bellatrix, capella, deneb ]
+                example: "phase0"
+              execution-payload-blinded:
+                type: boolean
+                example: false
+              execution-payload-value:
+                type: string
+                example: "12345"
+              data:
+                oneOf:
+                 - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconBlock'
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Altair.BeaconBlock"
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconBlock"
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconBlock"
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock"
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents"
+                 - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBlockContents"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized block or blinded block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and block type in `Eth-Blinded-Payload`."
+    "400":
+      description: "Invalid block production request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Invalid request to produce a block"
+    "500":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
+    "503":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

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-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-Execution-Payload-Value:
+      description: Required in response so client can determine relative value of execution payloads.
+      required: true
+      schema:
+        $ref: './types/primitive.yaml#/Wei'

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"