Merge remote-tracking branch 'upstream/master' into eip_rename

ethereum · Feb 8, 2023 · 09ca1dd · 09ca1dd
2 parents fd02cd2 + 181575d
commit 09ca1dd
Show file tree

Hide file tree

Showing 20 changed files with 304 additions and 71 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 .idea
 deploy
+node_modules
diff --git a/CHANGES.md b/CHANGES.md
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ API browser: [https://ethereum.github.io/beacon-APIs/](https://ethereum.github.i
 ## Outline
 
 This document outlines an application programming interface (API) which is exposed by a beacon node implementation
- which aims to facilitate [Phase 0](https://github.com/ethereum/consensus-specs#phase-0) of the Etheruem consensus layer.
+ which aims to facilitate [Phase 0](https://github.com/ethereum/consensus-specs#phase-0) of the Ethereum consensus layer.
 
 The API is a REST interface, accessed via HTTP. The API should not, unless protected by additional security layers, be exposed to the public Internet as the API includes multiple endpoints which could open your node to denial-of-service (DoS) attacks through endpoints triggering heavy processing.
  Currently, the only supported return data type is JSON.

diff --git a/apis/beacon/light_client/bootstrap.yaml b/apis/beacon/light_client/bootstrap.yaml
@@ -2,10 +2,10 @@ get:
   operationId: getLightClientBootstrap
   summary: Get `LightClientBootstrap` structure for a requested block root
   description: |
-    Requests the [`LightClientBootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientbootstrap) structure corresponding to a given post-Altair beacon block root.
+    Requests the [`LightClientBootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#lightclientbootstrap) structure corresponding to a given post-Altair beacon block root.
     Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
 
-    Servers SHOULD provide results as defined in [`create_light_client_bootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_bootstrap). To fulfill a request, the requested block's post state needs to be known.
+    Servers SHOULD provide results as defined in [`create_light_client_bootstrap`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/full-node.md#create_light_client_bootstrap). To fulfill a request, the requested block's post state needs to be known.
   tags:
     - Beacon
   parameters:
@@ -28,7 +28,9 @@ get:
               version:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
               data:
-                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap'
+                oneOf:
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap'
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientBootstrap'
         application/octet-stream:
           schema:
             description: "SSZ serialized `LightClientBootstrap` bytes. Use Accept header to choose this response type"

diff --git a/apis/beacon/light_client/finality_update.yaml b/apis/beacon/light_client/finality_update.yaml
@@ -2,10 +2,10 @@ get:
   operationId: getLightClientFinalityUpdate
   summary: Get the latest known `LightClientFinalityUpdate`
   description: |
-    Requests the latest [`LightClientFinalityUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientfinalityupdate) known by the server.
+    Requests the latest [`LightClientFinalityUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#lightclientfinalityupdate) known by the server.
     Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
 
-    Servers SHOULD provide results as defined in [`create_light_client_finality_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_finality_update).
+    Servers SHOULD provide results as defined in [`create_light_client_finality_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/full-node.md#create_light_client_finality_update).
   tags:
     - Beacon
   responses:
@@ -23,7 +23,9 @@ get:
               version:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
               data:
-                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate'
+                oneOf:
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate'
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientFinalityUpdate'
         application/octet-stream:
           schema:
             description: "SSZ serialized `LightClientFinalityUpdate` bytes. Use Accept header to choose this response type"

diff --git a/apis/beacon/light_client/optimistic_update.yaml b/apis/beacon/light_client/optimistic_update.yaml
@@ -2,10 +2,10 @@ get:
   operationId: getLightClientOptimisticUpdate
   summary: Get the latest known `LightClientOptimisticUpdate`
   description: |
-    Requests the latest [`LightClientOptimisticUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate) known by the server.
+    Requests the latest [`LightClientOptimisticUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate) known by the server.
     Depending on the `Accept` header it can be returned either as JSON or SSZ-serialized bytes.
 
-    Servers SHOULD provide results as defined in [`create_light_client_optimistic_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_optimistic_update).
+    Servers SHOULD provide results as defined in [`create_light_client_optimistic_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/full-node.md#create_light_client_optimistic_update).
   tags:
     - Beacon
   responses:
@@ -23,7 +23,9 @@ get:
               version:
                 $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
               data:
-                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate'
+                oneOf:
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate'
+                  - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientOptimisticUpdate'
         application/octet-stream:
           schema:
             description: "SSZ serialized `LightClientOptimisticUpdate` bytes. Use Accept header to choose this response type"

diff --git a/apis/beacon/light_client/updates.yaml b/apis/beacon/light_client/updates.yaml
@@ -2,10 +2,10 @@ get:
   operationId: getLightClientUpdatesByRange
   summary: Get `LightClientUpdate` instances in a requested sync committee period range
   description: |
-    Requests the [`LightClientUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#lightclientupdate) instances in the sync committee period range `[start_period, start_period + count)`, leading up to the current head sync committee period as selected by fork choice.
+    Requests the [`LightClientUpdate`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#lightclientupdate) instances in the sync committee period range `[start_period, start_period + count)`, leading up to the current head sync committee period as selected by fork choice.
     Depending on the `Accept` header they can be returned either as JSON or SSZ-serialized bytes.
 
-    Servers SHOULD provide results as defined in [`create_light_client_update`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/full-node.md#create_light_client_update). They MUST respond with at least the earliest known result within the requested range, and MUST send results in consecutive order (by period). The response MUST NOT contain more than [`min(MAX_REQUEST_LIGHT_CLIENT_UPDATES, count)`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/p2p-interface.md#configuration) results.
+    Servers SHOULD provide results as defined in [`create_light_client_update`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/full-node.md#create_light_client_update). They MUST respond with at least the earliest known result within the requested range, and MUST send results in consecutive order (by period). The response MUST NOT contain more than [`min(MAX_REQUEST_LIGHT_CLIENT_UPDATES, count)`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/p2p-interface.md#configuration) results.
   tags:
     - Beacon
   parameters:
@@ -33,7 +33,9 @@ get:
                 version:
                   $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
                 data:
-                  $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate'
+                  oneOf:
+                    - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate'
+                    - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientUpdate'
         application/octet-stream:
           schema:
             description: |
@@ -53,10 +55,11 @@ get:
 
               Per `context = compute_fork_digest(fork_version, genesis_validators_root)`:
 
-              | `fork_version`                               | Response chunk SSZ type              |
-              | -------------------------------------------- | ------------------------------------ |
-              | `GENESIS_FORK_VERSION`                       | n/a                                  |
-              | <nobr>`ALTAIR_FORK_VERSION` and later</nobr> | `altair.LightClientUpdate`           |
+              | `fork_version`                                                      | Response chunk SSZ type               |
+              | ------------------------------------------------------------------- | ------------------------------------- |
+              | `GENESIS_FORK_VERSION`                                              | n/a                                   |
+              | <nobr>`ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION`</nobr> | `altair.LightClientUpdate`            |
+              | <nobr>`CAPELLA_FORK_VERSION` and later</nobr>                       | `capella.LightClientUpdate`           |
     "400":
       description: Malformed or missing request parameter
       content:

diff --git a/apis/beacon/rewards/attestations.yaml b/apis/beacon/rewards/attestations.yaml
@@ -38,9 +38,7 @@ post:
               finalized:
                 $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
               data:
-                type: array
                 $ref: "../../../beacon-node-oapi.yaml#/components/schemas/AttestationsRewards"
-
     "400":
       description: "Invalid get attestations rewards request"
       content:

diff --git a/apis/node/syncing.yaml b/apis/node/syncing.yaml
@@ -33,6 +33,9 @@
                       allOf:
                         - type: boolean
                         - description: "Set to true if the node is optimistically tracking head."
-
+                    el_offline:
+                      allOf:
+                        - type: boolean
+                        - description: "Set to true if the execution client is offline."
       "500":
         $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
diff --git a/apis/validator/beacon_committee_selections.yaml b/apis/validator/beacon_committee_selections.yaml
@@ -0,0 +1,43 @@
+post:
+  operationId: "submitBeaconCommitteeSelections"
+  summary: Determine if a distributed validator has been selected to aggregate attestations
+  description: |
+    This endpoint should be used by a validator client running as part of a distributed validator cluster, and is 
+    implemented by a distributed validator middleware client. This endpoint is used to exchange partial 
+    selection proofs for combined/aggregated selection proofs to allow a validator client 
+    to correctly determine if one of its validators has been selected to perform an aggregation duty in this slot. 
+    Consensus clients need not support this endpoint and may return a 501.
+  tags:
+    - Validator
+  requestBody:
+    content:
+      application/json:
+        schema:
+          title: BeaconCommitteeSelectionRequest
+          type: array
+          items:
+            $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconCommitteeSelection'
+
+  responses:
+    "200":
+      description: |
+        Returns the threshold aggregated beacon committee selection proofs.
+      content:
+        application/json:
+          schema:
+            title: BeaconCommitteeSelectionResponse
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '../../beacon-node-oapi.yaml#/components/schemas/BeaconCommitteeSelection'
+
+    "400":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest'
+    "500":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
+    "501":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/NotImplementedError'
+    "503":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'
diff --git a/apis/validator/sync_committee_selections.yaml b/apis/validator/sync_committee_selections.yaml
@@ -0,0 +1,41 @@
+post:
+  operationId: "submitSyncCommitteeSelections"
+  summary: Determine if a distributed validator has been selected to make a sync committee contribution
+  description: |
+    Submit sync committee selections to a DVT middleware client. It returns the threshold aggregated sync 
+    committee selection. This endpoint should be used by a validator client running as part of a distributed 
+    validator cluster, and is implemented by a distributed validator middleware client. This endpoint is 
+    used to exchange partial selection proof slot signatures for combined/aggregated selection proofs to 
+    allow a validator client to correctly determine if one of its validators has been selected to perform 
+    a sync committee contribution (sync aggregation) duty in this slot. Consensus clients need not support 
+    this endpoint and may return a 501.
+  tags:
+    - Validator
+  requestBody:
+    content:
+      application/json:
+        schema:
+          title: SyncCommitteeSelectionRequest
+          type: array
+          items:
+            $ref: '../../beacon-node-oapi.yaml#/components/schemas/SyncCommitteeSelection'
+  responses:
+    "200":
+      description: |
+        Returns the threshold aggregated sync committee selection proofs.
+      content:
+        application/json:
+          schema:
+            title: SyncCommitteeSelectionResponse
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: '../../beacon-node-oapi.yaml#/components/schemas/SyncCommitteeSelection'
+    "400":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest'
+    "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
@@ -58,7 +58,7 @@ tags:
     description: Endpoints to query rewards and penalties for validators.
   - name: Experimental
     description: Endpoints that are not stable or fully implemented by each client.
-    
+
 paths:
 
   /eth/v1/beacon/genesis:
@@ -177,8 +177,12 @@ paths:
     $ref: "./apis/validator/beacon_committee_subscriptions.yaml"
   /eth/v1/validator/sync_committee_subscriptions:
     $ref: "./apis/validator/sync_committee_subscriptions.yaml"
+  /eth/v1/validator/beacon_committee_selections:
+    $ref: "./apis/validator/beacon_committee_selections.yaml"
   /eth/v1/validator/sync_committee_contribution:
     $ref: "./apis/validator/sync_committee_contribution.yaml"
+  /eth/v1/validator/sync_committee_selections:
+    $ref: "./apis/validator/sync_committee_selections.yaml"
   /eth/v1/validator/contribution_and_proofs:
     $ref: "./apis/validator/sync_committee_contribution_and_proof.yaml"
   /eth/v1/validator/prepare_beacon_proposer:
@@ -232,6 +236,10 @@ components:
       $ref: './types/attestation.yaml#/Attestation'
     AttestationData:
       $ref: './types/attestation.yaml#/AttestationData'
+    BeaconCommitteeSelection:
+      $ref: './types/selection.yaml#/BeaconCommitteeSelection'
+    SyncCommitteeSelection:
+      $ref: './types/selection.yaml#/SyncCommitteeSelection'
     Fork:
       $ref: './types/misc.yaml#/Fork'
     Checkpoint:
@@ -272,6 +280,10 @@ components:
       $ref: './types/http.yaml#/ErrorMessage'
     IndexedErrorMessage:
       $ref: './types/http.yaml#/IndexedErrorMessage'
+    Altair.BeaconBlock:
+      $ref: './types/altair/block.yaml#/Altair/BeaconBlock'
+    Altair.SignedBeaconBlock:
+      $ref: './types/altair/block.yaml#/Altair/SignedBeaconBlock'
     Altair.LightClientBootstrap:
       $ref: './types/altair/light_client.yaml#/Altair/LightClientBootstrap'
     Altair.LightClientUpdate:
@@ -280,10 +292,6 @@ components:
       $ref: './types/altair/light_client.yaml#/Altair/LightClientFinalityUpdate'
     Altair.LightClientOptimisticUpdate:
       $ref: './types/altair/light_client.yaml#/Altair/LightClientOptimisticUpdate'
-    Altair.SignedBeaconBlock:
-      $ref: './types/altair/block.yaml#/Altair/SignedBeaconBlock'
-    Altair.BeaconBlock:
-      $ref: './types/altair/block.yaml#/Altair/BeaconBlock'
     Altair.BeaconState:
       $ref: './types/altair/state.yaml#/Altair/BeaconState'
     Altair.SyncCommitteeSignature:
@@ -325,6 +333,14 @@ components:
       $ref: './types/capella/block.yaml#/Capella/BlindedBeaconBlock'
     Capella.SignedBlindedBeaconBlock:
       $ref: './types/capella/block.yaml#/Capella/SignedBlindedBeaconBlock'
+    Capella.LightClientBootstrap:
+      $ref: './types/capella/light_client.yaml#/Capella/LightClientBootstrap'
+    Capella.LightClientUpdate:
+      $ref: './types/capella/light_client.yaml#/Capella/LightClientUpdate'
+    Capella.LightClientFinalityUpdate:
+      $ref: './types/capella/light_client.yaml#/Capella/LightClientFinalityUpdate'
+    Capella.LightClientOptimisticUpdate:
+      $ref: './types/capella/light_client.yaml#/Capella/LightClientOptimisticUpdate'
     Deneb.BeaconState:
       $ref: './types/deneb/state.yaml#/Deneb/BeaconState'
     Deneb.BeaconBlock:
@@ -363,6 +379,8 @@ components:
       $ref: './types/http.yaml#/UnsupportedMediaType'
     InternalError:
       $ref: './types/http.yaml#/InternalError'
+    NotImplementedError:
+      $ref: './types/http.yaml#/NotImplementedError'
     CurrentlySyncing:
       $ref: './types/http.yaml#/CurrentlySyncing'
 

diff --git a/types/altair/light_client.yaml b/types/altair/light_client.yaml
@@ -3,21 +3,21 @@ Altair:
     type: array
     items:
       $ref: '../primitive.yaml#/Root'
-      description: "Merkle proof consisting of [`log2trunc(FINALIZED_ROOT_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
+      description: "Merkle proof consisting of [`log2trunc(FINALIZED_ROOT_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#constants) roots"
     minItems: 6
     maxItems: 6
   CurrentSyncCommitteeBranch:
     type: array
     items:
       $ref: '../primitive.yaml#/Root'
-      description: "Merkle proof consisting of [`log2trunc(CURRENT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
+      description: "Merkle proof consisting of [`log2trunc(CURRENT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#constants) roots"
     minItems: 5
     maxItems: 5
   NextSyncCommitteeBranch:
     type: array
     items:
       $ref: '../primitive.yaml#/Root'
-      description: "Merkle proof consisting of [`log2trunc(NEXT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/altair/light-client/sync-protocol.md#constants) roots"
+      description: "Merkle proof consisting of [`log2trunc(NEXT_SYNC_COMMITTEE_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/altair/light-client/sync-protocol.md#constants) roots"
     minItems: 5
     maxItems: 5