Attestation and Sync Committee aggregation selection (#224)

Co-authored-by: xenowits <[email protected]> Co-authored-by: Dhruv Bodani <[email protected]> Co-authored-by: Abhishek Kumar <[email protected]>
ethereum · Jan 31, 2023 · 3945797 · 3945797
1 parent 4a2d70b
commit 3945797
Show file tree

Hide file tree

Showing 7 changed files with 154 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 .idea
 deploy
+node_modules
diff --git a/CHANGES.md b/CHANGES.md
@@ -11,6 +11,8 @@ There are likely to be descriptions etc outside of the list below, but new query
 |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------|
 | [#131](https://github.com/ethereum/beacon-APIs/pull/131) [#254](https://github.com/ethereum/beacon-APIs/pull/254) NEW `/eth/v1/validator/liveness/{epoch}`            |                                                  |                                                   |                                                    |                                                 |                                           |
 | [#221](https://github.com/ethereum/beacon-APIs/pull/221) `/eth/v1/validator/blinded_blocks/{slot}` added header `ethConsensusVersion`                                 |                                                  |                                                   |                                                    |                                                 |                                           |
+| [#224](https://github.com/ethereum/beacon-APIs/pull/224) NEW `/eth/v1/validator/beacon_committee_selections                                 |                                                  |                                                   |                                                    |                                                 |                                           |
+| [#224](https://github.com/ethereum/beacon-APIs/pull/224) NEW `/eth/v1/validator/sync_committee_selections                                 |                                                  |                                                   |                                                    |                                                 |                                           |
 | [#232](https://github.com/ethereum/beacon-APIs/pull/232) NEW `/eth/v1/debug/fork_choice`                                                                              |                                                  |                                                   |                                                    |                                                 |                                           |
 | [#241](https://github.com/ethereum/beacon-APIs/pull/241) NEW `/eth/v1/beacon/blinded_blocks/{block_id}`                                                               |                                                  |                                                   |                                                    |                                                 |                                           |
 | [#242](https://github.com/ethereum/beacon-APIs/pull/242) NEW `/eth/v1/beacon/states/{state_id}/randao`                                                                |                                                  |                                                   |                                                    |                                                 |                                           |

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
@@ -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:
@@ -361,6 +369,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/http.yaml b/types/http.yaml
@@ -39,6 +39,28 @@ InternalError:
       example:
         code: 500
         message: "Internal server error"
+NotImplementedError:
+  description: "Endpoint not implemented."
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          code:
+            description: "Either specific error code in case of invalid request or http status code"
+            type: number
+            example: 501
+          message:
+            description: "Message describing error"
+            type: string
+          stacktraces:
+            description: "Optional stacktraces, sent when node is in debug mode"
+            type: array
+            items:
+              type: string
+      example:
+        code: 501
+        message: "Endpoint not implemented"
 CurrentlySyncing:
   description: "Beacon node is currently syncing, try again later."
   content:

diff --git a/types/selection.yaml b/types/selection.yaml
@@ -0,0 +1,35 @@
+BeaconCommitteeSelection:
+  type: object
+  properties:
+    validator_index:
+      allOf:
+        - $ref: './primitive.yaml#/Uint64'
+        - description: "Index of the validator"
+    slot:
+      allOf:
+        - $ref: './primitive.yaml#/Uint64'
+        - description: "The slot at which a validator is assigned to attest"
+    selection_proof:
+      allOf:
+        - $ref: './primitive.yaml#/Signature'
+        - description: "The `slot_signature` calculated by the validator for the upcoming attestation slot"
+
+SyncCommitteeSelection:
+  type: object
+  properties:
+    validator_index:
+      allOf:
+        - $ref: './primitive.yaml#/Uint64'
+        - description: "Index of the validator"
+    slot:
+      allOf:
+        - $ref: './primitive.yaml#/Uint64'
+        - description: "The slot at which validator is assigned to produce a sync committee contribution"
+    subcommittee_index:
+      allOf:
+        - $ref: './primitive.yaml#/Uint64'
+        - description: "SubcommitteeIndex to which the validator is assigned"
+    selection_proof:
+      allOf:
+        - $ref: './primitive.yaml#/Signature'
+        - description: "The `slot_signature` calculated by the validator for the upcoming sync committee slot"