Add broadcast_validation to block publishing

Author: michaelsproul

apis/beacon/blocks/blinded_blocks.yaml

@@ -13,8 +13,27 @@ post:
     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`.
+    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.
+
+        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'

apis/beacon/blocks/blocks.yaml

@@ -8,11 +8,30 @@ post:
     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 state, but may broadcast it
+    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.
+    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.
+
+        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'

beacon-node-oapi.yaml

@@ -207,6 +207,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]