Add broadcast_validation to block publishing (#317)

* New v2 APIs and explicit equivocation check

apis/beacon/blocks/blinded_blocks.v2.yaml

@@ -0,0 +1,80 @@
+post:
+  tags:
+    - Beacon
+    - ValidatorRequiredApi
+  summary: "Publish a signed block."
+  operationId: "publishBlindedBlockV2"
+  description: |
+    Instructs the beacon node to use the components of the `SignedBlindedBeaconBlock` to construct and publish a 
+    `SignedBeaconBlock` by swapping out the `transactions_root` for the corresponding full list of `transactions`.
+    The beacon node should broadcast a newly constructed `SignedBeaconBlock` to the beacon network,
+    to be included in the beacon chain. The beacon node is not required to validate the signed
+    `BeaconBlock`, and a successful response (20X) only indicates that the broadcast has been
+    successful. The beacon node is expected to integrate the new block into its state, and
+    therefore validate the block internally, however blocks which fail the validation are still
+    broadcast but a different status code is returned (202). Pre-Bellatrix, this endpoint will accept 
+    a `SignedBeaconBlock`. The broadcast behaviour may be adjusted via the `broadcast_validation`
+    query parameter.
+  parameters:
+    - name: broadcast_validation
+      in: query
+      required: false
+      description: |
+        Level of validation that must be applied to a block before it is broadcast.
+
+        Possible values:
+        - **`gossip`** (default): lightweight gossip checks only
+        - **`consensus`**: full consensus checks, including validation of all signatures and
+          blocks fields _except_ for the execution payload transactions.
+        - **`consensus_and_equivocation`**: the same as `consensus`, with an extra equivocation
+          check immediately before the block is broadcast. If the block is found to be an
+          equivocation it fails validation.
+
+        If the block fails the requested level of a validation a 400 status MUST be returned
+        immediately and the block MUST NOT be broadcast to the network.
+
+        If validation succeeds, the block must still be fully verified before it is
+        incorporated into the state and a 20x status is returned to the caller.
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/BroadcastValidation'
+    - in: header
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+      required: false
+      name: Eth-Consensus-Version
+      description: "Version of the block being submitted, if using SSZ encoding."
+  requestBody:
+    description: "The `SignedBlindedBeaconBlock` object composed of `BlindedBeaconBlock` object (produced by beacon node) and validator signature."
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock'
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "200":
+      description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database."
+    "202":
+      description: "The block failed validation, but was successfully broadcast anyway. It was not integrated into the beacon node's database."
+    "400":
+      description: "The `SignedBlindedBeaconBlock` object is invalid"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+            example:
+              code: 400
+              message: "Invalid block: missing signature"
+    "415":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType'
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
+    "503":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

apis/beacon/blocks/blocks.v2.yaml

@@ -0,0 +1,79 @@
+post:
+  tags:
+    - Beacon
+    - ValidatorRequiredApi
+  summary: "Publish a signed block."
+  operationId: "publishBlockV2"
+  description: |
+    Instructs the beacon node to broadcast a newly signed beacon block to the beacon network,
+    to be included in the beacon chain. A success response (20x) indicates that the block
+    passed gossip validation and was successfully broadcast onto the network.
+    The beacon node is also expected to integrate the block into the state, but may broadcast it
+    before doing so, so as to aid timely delivery of the block. Should the block fail full
+    validation, a separate success response code (202) is used to indicate that the block was
+    successfully broadcast but failed integration. The broadcast behaviour may be adjusted via the
+    `broadcast_validation` query parameter.
+  parameters:
+    - name: broadcast_validation
+      in: query
+      required: false
+      description: |
+        Level of validation that must be applied to a block before it is broadcast.
+
+        Possible values:
+        - **`gossip`** (default): lightweight gossip checks only
+        - **`consensus`**: full consensus checks, including validation of all signatures and
+          blocks fields _except_ for the execution payload transactions.
+        - **`consensus_and_equivocation`**: the same as `consensus`, with an extra equivocation
+          check immediately before the block is broadcast. If the block is found to be an
+          equivocation it fails validation.
+
+        If the block fails the requested level of a validation a 400 status MUST be returned
+        immediately and the block MUST NOT be broadcast to the network.
+
+        If validation succeeds, the block must still be fully verified before it is
+        incorporated into the state and a 20x status is returned to the caller.
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/BroadcastValidation'
+    - in: header
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+      required: false
+      name: Eth-Consensus-Version
+      description: "Version of the block being submitted, if using SSZ encoding."
+  requestBody:
+    description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature."
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock'
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Altair.SignedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock"
+            - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "200":
+      description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database."
+    "202":
+      description: "The block could not be integrated into the beacon node's database as it failed validation, but was successfully broadcast."
+    "400":
+      description: "The `SignedBeaconBlock` object is invalid and could not be broadcast"
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+              - example:
+                  code: 400
+                  message: "Invalid block: missing signature"
+    "415":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType'
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
+    "503":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

beacon-node-oapi.yaml

@@ -89,8 +89,12 @@ paths:
     $ref: "./apis/beacon/blocks/header.yaml"
   /eth/v1/beacon/blinded_blocks:
     $ref: "./apis/beacon/blocks/blinded_blocks.yaml"
+  /eth/v2/beacon/blinded_blocks:
+    $ref: "./apis/beacon/blocks/blinded_blocks.v2.yaml"
   /eth/v1/beacon/blocks:
     $ref: "./apis/beacon/blocks/blocks.yaml"
+  /eth/v2/beacon/blocks:
+    $ref: "./apis/beacon/blocks/blocks.v2.yaml"
   /eth/v2/beacon/blocks/{block_id}:
     $ref: "./apis/beacon/blocks/block.v2.yaml"
   /eth/v1/beacon/blocks/{block_id}/root:
@@ -207,6 +211,8 @@ components:
       $ref: './types/state.yaml#/BeaconState'
     BeaconBlock:
       $ref: './types/block.yaml#/BeaconBlock'
+    BroadcastValidation:
+      $ref: './types/api.yaml#/BroadcastValidation'
     DepositSnapshotResponse:
       $ref: './types/api.yaml#/DepositSnapshotResponse'
     SignedBeaconBlock:

types/api.yaml

@@ -81,3 +81,8 @@ Committee:
       description: "List of validator indices assigned to this committee"
       items:
         $ref: './primitive.yaml#/Uint64'
+
+BroadcastValidation:
+  description: Level of validation that must be applied to a block before it is broadcast.
+  type: string
+  enum: [gossip, consensus, consensus_and_equivocation]