Update attestation APIs to support EIP-7549 (#448)

* update attestation APIs to support EIP-7549 * fix attestations array shcema * fix one of array item schemas * use anyOf instead of oneOf * bump attestations apis to v2 * add change log entries * refactoring * add consensus version header to POST apis parameters * update spec version * fix typos * rebase master * update indexed attestation spec link * update changes log * add new line * Review PR * fixing reviews * Fix Attestation field order * Correct committee_bits example * Fix required properties ordering --------- Co-authored-by: Nico Flaig <[email protected]>
ethereum · Jul 4, 2024 · 41cc574 · 41cc574
1 parent 5152163
commit 41cc574
Show file tree

Hide file tree

Showing 12 changed files with 297 additions and 27 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -10,6 +10,11 @@ There are likely to be descriptions etc outside of the list below, but new query
 | Endpoint                                                                                                            | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) |
 |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------|
 | [#447](https://github.com/ethereum/beacon-APIs/pull/447) `GET /eth/v2/validator/aggregate_attestation` added         |                                                  |                                                   |                                                    |                                                 |                                           |
+| [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/blocks/{block_id}/attestations` added  |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/pool/attestations` added               |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attestations` added              |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/pool/attester_slashings` added         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attester_slashings` added        |                                                  |                                                  |                                                    |                                                 |                                           |
 
 
 The Following are no longer in the Standard API, removed since the latest version.

diff --git a/apis/beacon/blocks/attestations.v2.yaml b/apis/beacon/blocks/attestations.v2.yaml
@@ -0,0 +1,60 @@
+get:
+  operationId: getBlockAttestationsV2
+  summary: Get block attestations
+  description: Retrieves attestation included in requested block.
+  tags:
+    - Beacon
+  parameters:
+    - name: block_id
+      in: path
+      required: true
+      $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId'
+  responses:
+    "200":
+      description: Success
+      headers:
+        Eth-Consensus-Version:
+          $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
+      content:
+        application/json:
+          schema:
+            title: GetBlockAttestationsV2Response
+            type: object
+            required: [version, execution_optimistic, finalized, data]
+            properties:
+              version:
+                type: string
+                enum: [phase0, altair, bellatrix, capella, deneb, electra]
+                example: "phase0"
+              execution_optimistic:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic"
+              finalized:
+                $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
+              data:
+                anyOf:
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Attestation'
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.Attestation'
+    "400":
+      description: "The block ID supplied could not be parsed"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid block ID: current"
+    "404":
+      description: "Block not found"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 404
+            message: "Block not found"
+    "500":
+      $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"
diff --git a/apis/beacon/blocks/attestations.yaml b/apis/beacon/blocks/attestations.yaml
@@ -1,6 +1,7 @@
 get:
   operationId: getBlockAttestations
   summary: Get block attestations
+  deprecated: true
   description: Retrieves attestation included in requested block.
   tags:
     - Beacon

diff --git a/apis/beacon/pool/attestations.v2.yaml b/apis/beacon/pool/attestations.v2.yaml
@@ -0,0 +1,96 @@
+get:
+  operationId: getPoolAttestationsV2
+  summary: Get attestations from operations pool
+  description: Retrieves attestations known by the node but not necessarily incorporated into any block
+  parameters:
+    - name: slot
+      in: query
+      required: false
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64'
+    - name: committee_index
+      in: query
+      required: false
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64'
+  tags:
+    - Beacon
+  responses:
+    "200":
+      description: Successful response
+      headers:
+        Eth-Consensus-Version:
+          $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
+      content:
+        application/json:
+          schema:
+            title: GetPoolAttestationsV2Response
+            type: object
+            required: [version, data]
+            properties:
+              version:
+                type: string
+                enum: [phase0, altair, bellatrix, capella, deneb, electra]
+                example: "phase0"
+              data:
+                anyOf:
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Attestation'
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.Attestation'
+    "400":
+      description: "The slot or committee index could not be parsed"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid slot: current"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
+
+post:
+  operationId: submitPoolAttestationsV2
+  summary: Submit Attestation objects to node
+  description: |
+    Submits Attestation objects to the node. Each attestation in the request body is processed individually.
+    
+    If an attestation is validated successfully, the node MUST publish that attestation on the appropriate subnet.
+
+    If one or more attestations fail validation, the node MUST return a 400 error with details of which attestations have failed, and why.
+  parameters:
+    - in: header
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+      required: true
+      name: Eth-Consensus-Version
+      description: "Version of the attestations being submitted."
+  tags:
+    - Beacon
+    - ValidatorRequiredApi
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          anyOf:
+            - type: array
+              items:
+                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Attestation'
+            - type: array
+              items:
+                $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.Attestation'
+  responses:
+    "200":
+      description: Attestations are stored in pool and broadcast on the appropriate subnet
+    "400":
+      description: "Errors with one or more attestations"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
diff --git a/apis/beacon/pool/attestations.yaml b/apis/beacon/pool/attestations.yaml
@@ -1,6 +1,7 @@
 get:
   operationId: getPoolAttestations
   summary: Get Attestations from operations pool
+  deprecated: true
   description: Retrieves attestations known by the node but not necessarily incorporated into any block
   parameters:
     - name: slot
@@ -44,6 +45,7 @@ get:
 post:
   operationId: submitPoolAttestations
   summary: Submit Attestation objects to node
+  deprecated: true
   description: |
     Submits Attestation objects to the node.  Each attestation in the request body is processed individually.
     

diff --git a/apis/beacon/pool/attester_slashings.v2.yaml b/apis/beacon/pool/attester_slashings.v2.yaml
@@ -0,0 +1,69 @@
+get:
+  operationId: getPoolAttesterSlashingsV2
+  summary: Get attester slashings from operations pool
+  description: Retrieves attester slashings known by the node but not necessarily incorporated into any block
+  tags:
+    - Beacon
+  responses:
+    "200":
+      description: Successful response
+      headers:
+        Eth-Consensus-Version:
+          $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
+      content:
+        application/json:
+          schema:
+            title: GetPoolAttesterSlashingsV2Response
+            type: object
+            required: [version, data]
+            properties:
+              version:
+                type: string
+                enum: [phase0, altair, bellatrix, capella, deneb, electra]
+                example: "phase0"
+              data:
+                anyOf:
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/AttesterSlashing'
+                  - type: array
+                    items:
+                      $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.AttesterSlashing'
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
+
+post:
+  operationId: submitPoolAttesterSlashingsV2
+  summary: Submit AttesterSlashing object to node's pool
+  description: Submits AttesterSlashing object to node's pool. Upon successful validation the node MUST broadcast it to network.
+  parameters:
+    - in: header
+      schema:
+        $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+      required: true
+      name: Eth-Consensus-Version
+      description: "Version of the attester slashing being submitted."
+  tags:
+    - Beacon
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          anyOf:
+           - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/AttesterSlashing'
+           - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.AttesterSlashing'
+  responses:
+    "200":
+      description: Success
+    "400":
+      description: "Invalid attester slashing"
+      content:
+        application/json:
+          schema:
+            $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid attester slashing, it will never pass validation so it's rejected"
+    "500":
+      $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
diff --git a/apis/beacon/pool/attester_slashings.yaml b/apis/beacon/pool/attester_slashings.yaml
@@ -1,6 +1,7 @@
 get:
   operationId: getPoolAttesterSlashings
   summary: Get AttesterSlashings from operations pool
+  deprecated: true
   description: Retrieves attester slashings known by the node but not necessarily incorporated into any block
   tags:
     - Beacon
@@ -24,6 +25,7 @@ get:
 post:
   operationId: submitPoolAttesterSlashings
   summary: Submit AttesterSlashing object to node's pool
+  deprecated: true
   description: Submits AttesterSlashing object to node's pool and if passes validation node MUST broadcast it to network.
   tags:
     - Beacon

diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml
@@ -99,6 +99,8 @@ paths:
     $ref: "./apis/beacon/blocks/root.yaml"
   /eth/v1/beacon/blocks/{block_id}/attestations:
     $ref: "./apis/beacon/blocks/attestations.yaml"
+  /eth/v2/beacon/blocks/{block_id}/attestations:
+    $ref: "./apis/beacon/blocks/attestations.v2.yaml"
   /eth/v1/beacon/blob_sidecars/{block_id}:
     $ref: "./apis/beacon/blob_sidecars/blob_sidecars.yaml"
   /eth/v1/beacon/rewards/sync_committee/{block_id}:
@@ -121,8 +123,12 @@ paths:
     $ref: "./apis/beacon/light_client/optimistic_update.yaml"
   /eth/v1/beacon/pool/attestations:
     $ref: "./apis/beacon/pool/attestations.yaml"
+  /eth/v2/beacon/pool/attestations:
+    $ref: "./apis/beacon/pool/attestations.v2.yaml"
   /eth/v1/beacon/pool/attester_slashings:
     $ref: "./apis/beacon/pool/attester_slashings.yaml"
+  /eth/v2/beacon/pool/attester_slashings:
+    $ref: "./apis/beacon/pool/attester_slashings.v2.yaml"
   /eth/v1/beacon/pool/proposer_slashings:
     $ref: "./apis/beacon/pool/proposer_slashings.yaml"
   /eth/v1/beacon/pool/sync_committees:
@@ -248,7 +254,7 @@ components:
     Attestation:
       $ref: './types/attestation.yaml#/Attestation'
     AttestationData:
-      $ref: './types/attestation.yaml#/AttestationData'
+      $ref: './types/attestation_data.yaml#/AttestationData'
     BeaconCommitteeSelection:
       $ref: './types/selection.yaml#/BeaconCommitteeSelection'
     SyncCommitteeSelection:
@@ -331,7 +337,7 @@ components:
       $ref: './types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock'
     ConsensusVersion:
       type: string
-      enum: [phase0, altair, bellatrix, capella, deneb]
+      enum: [phase0, altair, bellatrix, capella, deneb, electra]
       example: "phase0"
     SignedValidatorRegistration:
       $ref: './types/registration.yaml#/SignedValidatorRegistration'
@@ -375,6 +381,8 @@ components:
       $ref: './types/deneb/blob_sidecar.yaml#/Deneb/BlobSidecars'
     Electra.Attestation:
       $ref: './types/electra/attestation.yaml#/Electra/Attestation'
+    Electra.AttesterSlashing:
+      $ref: './types/electra/attester_slashing.yaml#/Electra/AttesterSlashing'
     Node:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:

diff --git a/types/attestation.yaml b/types/attestation.yaml
@@ -1,32 +1,33 @@
 IndexedAttestation:
   type: object
   description: "The [`IndexedAttestation`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/phase0/beacon-chain.md#indexedattestation) object from the CL spec."
+  required: [attesting_indices, data, signature]
   properties:
     attesting_indices:
       type: array
       maxItems: 2048
       description: "Attesting validator indices"
       items:
         $ref: "./primitive.yaml#/Uint64"
+    data:
+      $ref: './attestation_data.yaml#/AttestationData'
     signature:
       $ref: './primitive.yaml#/Signature'
       description: "The BLS signature of the `IndexedAttestation`, created by the validator of the attestation."
-    data:
-      $ref: './attestation.yaml#/AttestationData'
 
 Attestation:
   type: object
   description: "The [`Attestation`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/phase0/beacon-chain.md#attestation) object from the CL spec."
-  required: [aggregation_bits, signature, data]
+  required: [aggregation_bits, data, signature]
   properties:
     aggregation_bits:
       $ref: "./primitive.yaml#/BitList"
       description: "Attester aggregation bits."
+    data:
+      $ref: './attestation_data.yaml#/AttestationData'
     signature:
       $ref: './primitive.yaml#/Signature'
       description: "BLS aggregate signature."
-    data:
-      $ref: './attestation.yaml#/AttestationData'
 
 PendingAttestation:
   type: object
@@ -37,25 +38,8 @@ PendingAttestation:
       $ref: "./primitive.yaml#/BitList"
       description: "Attester aggregation bits."
     data:
-      $ref: '#/AttestationData'
+      $ref: './attestation_data.yaml#/AttestationData'
     inclusion_delay:
       $ref: "./primitive.yaml#/Uint64"
     proposer_index:
       $ref: "./primitive.yaml#/Uint64"
-
-AttestationData:
-  type: object
-  description: "The [`AttestationData`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/phase0/beacon-chain.md#attestationdata) object from the CL spec."
-  required: [slot, index, beacon_block_root, source, target]
-  properties:
-    slot:
-      $ref: "./primitive.yaml#/Uint64"
-    index:
-      $ref: "./primitive.yaml#/Uint64"
-    beacon_block_root:
-      $ref: './primitive.yaml#/Root'
-      description: "LMD GHOST vote."
-    source:
-      $ref: "./misc.yaml#/Checkpoint"
-    target:
-      $ref: "./misc.yaml#/Checkpoint"