Add execution_optimistic flag to responses

apis/beacon/blocks/attestations.yaml

@@ -18,6 +18,8 @@ get:
             title: GetBlockAttestationsResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/beacon/blocks/block.v2.yaml

@@ -26,6 +26,8 @@ get:
                 type: string
                 enum: [phase0, altair]
                 example: "phase0"
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 oneOf:
                   - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/SignedBeaconBlock"

apis/beacon/blocks/header.yaml

@@ -17,6 +17,8 @@ get:
             title: GetBlockHeaderResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: object
                 properties:

apis/beacon/blocks/headers.yaml

@@ -29,6 +29,8 @@ get:
             title: GetBlockHeadersResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/beacon/blocks/root.yaml

@@ -17,6 +17,8 @@ get:
             type: object
             title: GetBlockRootResponse
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: object
                 properties:

apis/beacon/states/committee.yaml

@@ -42,6 +42,8 @@ get:
             title: GetEpochCommitteesResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/beacon/states/finality_checkpoints.yaml

@@ -19,6 +19,8 @@ get:
             title: GetStateFinalityCheckpointsResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: object
                 properties:

apis/beacon/states/fork.yaml

@@ -18,6 +18,8 @@ get:
             title: GetStateForkResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Fork'
 

apis/beacon/states/root.yaml

@@ -17,6 +17,8 @@ get:
             title: GetStateRootResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: object
                 properties:

apis/beacon/states/sync_committees.yaml

@@ -26,6 +26,8 @@ get:
             title: GetEpochSyncCommitteesResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.SyncCommittee'
 

apis/beacon/states/validator.yaml

@@ -25,6 +25,8 @@ get:
             title: GetStateValidatorResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorResponse'
     "400":

apis/beacon/states/validator_balances.yaml

@@ -35,6 +35,8 @@ get:
             title: GetStateValidatorBalancesResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/beacon/states/validators.yaml

@@ -46,6 +46,8 @@ get:
             title: GetStateValidatorsResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/debug/heads.v2.yaml

@@ -0,0 +1,28 @@
+get:
+  operationId: getDebugChainHeadsV2
+  summary: Get fork choice leaves
+  description: Retrieves all possible chain heads (leaves of fork choice tree).
+  tags:
+    - Debug
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            title: GetDebugChainHeadsResponse
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    root:
+                      $ref: "../../beacon-node-oapi.yaml#/components/schemas/Root"
+                    slot:
+                      $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+                    execution_optimistic:
+                      $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+    "500":
+      $ref: "../beacon-node-oapi.yaml#/components/responses/InternalError"

apis/debug/heads.yaml

@@ -2,6 +2,7 @@ get:
   operationId: getDebugChainHeads
   summary: Get fork choice leaves
   description: Retrieves all possible chain heads (leaves of fork choice tree).
+  deprecated: true
   tags:
     - Debug
   responses:

apis/debug/state.v2.yaml

@@ -27,6 +27,8 @@ get:
                 type: string
                 enum: [ phase0, altair ]
                 example: "phase0"
+              execution_optimistic:
+                $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 oneOf:
                  - $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconState'

apis/eventstream/index.yaml

@@ -42,11 +42,13 @@ get:
               description: The node has finished processing, resulting in a new head. previous_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and current_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`. Both dependent roots use the genesis block root in the case of underflow.
               value: |
                 event: head
+                execution_optimistic: false
                 data: {"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch_transition":false, "previous_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "current_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91"}
             block:
               description: The node has received a valid block (from P2P or API)
               value: |
                 event: block
+                execution_optimistic: false
                 data: {"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf"}
             attestation:
               description: The node has received a valid attestation (from P2P or API)
@@ -62,11 +64,13 @@ get:
               description: Finalized checkpoint has been updated
               value: |
                 event: finalized_checkpoint
+                execution_optimistic: false
                 data: {"block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch":"2" }
             chain_reorg:
               description: The node has reorganized its chain
               value: |
                 event: chain_reorg
+                execution_optimistic: false
                 data: {"slot":"200", "depth":"50", "old_head_block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "new_head_block":"0x76262e91970d375a19bfe8a867288d7b9cde43c8635f598d93d39d041706fc76", "old_head_state":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "new_head_state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch":"2"}
             contribution_and_proof:
               description: The node has received a valid sync committee SignedContributionAndProof (from P2P or API)

apis/validator/block.v2.yaml

@@ -59,4 +59,4 @@ get:
     "500":
       $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
     "503":
-      $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

apis/validator/duties/attester.yaml

@@ -50,6 +50,8 @@ post:
             properties:
               dependent_root:
                 $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot"
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/validator/duties/proposer.yaml

@@ -34,6 +34,8 @@ get:
             properties:
               dependent_root:
                 $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot"
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

apis/validator/duties/sync.yaml

@@ -32,6 +32,8 @@ post:
             title: GetSyncCommitteeDutiesResponse
             type: object
             properties:
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
               data:
                 type: array
                 items:

beacon-node-oapi.yaml

@@ -95,6 +95,8 @@ paths:
     $ref: './apis/debug/state.v2.yaml'
   /eth/v1/debug/beacon/heads:
     $ref: './apis/debug/heads.yaml'
+  /eth/v2/debug/beacon/heads:
+    $ref: './apis/debug/heads.v2.yaml'
 
   /eth/v1/node/identity:
     $ref: "./apis/node/identity.yaml"
@@ -209,6 +211,8 @@ components:
       $ref: './types/primitive.yaml#/ForkVersion'
     DependentRoot:
       $ref: './types/primitive.yaml#/DependentRoot'
+    ExecutionOptimistic:
+      $ref: './types/primitive.yaml#/ExecutionOptimistic'
     Root:
       $ref: './types/primitive.yaml#/Root'
     Hex:

types/primitive.yaml

@@ -33,6 +33,12 @@ DependentRoot:
     - $ref: "./primitive.yaml#/Root"
     - description: "The block root that this response is dependent on."
 
+ExecutionOptimistic:
+  allOf:
+    - type: boolean
+    - example: false
+    - description: "True if the response references an unverified execution payload. Optimistic information may be invalidated at a later time. If the field is not present, assume the False value."
+
 Root:
   type: string
   example: "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"