From 41cc574bded931d94892e579c04521f3d8d7e619 Mon Sep 17 00:00:00 2001 From: Mehdi AOUADI Date: Thu, 4 Jul 2024 12:35:11 +0200 Subject: [PATCH] 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 --- CHANGES.md | 5 ++ apis/beacon/blocks/attestations.v2.yaml | 60 +++++++++++++ apis/beacon/blocks/attestations.yaml | 1 + apis/beacon/pool/attestations.v2.yaml | 96 +++++++++++++++++++++ apis/beacon/pool/attestations.yaml | 2 + apis/beacon/pool/attester_slashings.v2.yaml | 69 +++++++++++++++ apis/beacon/pool/attester_slashings.yaml | 2 + beacon-node-oapi.yaml | 12 ++- types/attestation.yaml | 30 ++----- types/attestation_data.yaml | 16 ++++ types/electra/attestation.yaml | 21 ++++- types/electra/attester_slashing.yaml | 10 +++ 12 files changed, 297 insertions(+), 27 deletions(-) create mode 100644 apis/beacon/blocks/attestations.v2.yaml create mode 100644 apis/beacon/pool/attestations.v2.yaml create mode 100644 apis/beacon/pool/attester_slashings.v2.yaml create mode 100644 types/attestation_data.yaml create mode 100644 types/electra/attester_slashing.yaml diff --git a/CHANGES.md b/CHANGES.md index 215a347b..e7639bc4 100644 --- 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 new file mode 100644 index 00000000..785ed096 --- /dev/null +++ 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 index 7bf1e089..23e165f6 100644 --- 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 new file mode 100644 index 00000000..7a8be747 --- /dev/null +++ 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 index 1748b42f..e047670b 100644 --- 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 new file mode 100644 index 00000000..03b44d56 --- /dev/null +++ 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 index f21591c8..bb0ba62b 100644 --- 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 index d7bcc56f..f90691d1 100644 --- 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 index 747e0e37..d057f4f4 100644 --- a/types/attestation.yaml +++ b/types/attestation.yaml @@ -1,6 +1,7 @@ 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 @@ -8,25 +9,25 @@ IndexedAttestation: 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" diff --git a/types/attestation_data.yaml b/types/attestation_data.yaml new file mode 100644 index 00000000..38675d97 --- /dev/null +++ b/types/attestation_data.yaml @@ -0,0 +1,16 @@ +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" diff --git a/types/electra/attestation.yaml b/types/electra/attestation.yaml index 2ad061b6..60cd3bbb 100644 --- a/types/electra/attestation.yaml +++ b/types/electra/attestation.yaml @@ -1,4 +1,21 @@ Electra: + IndexedAttestation: + type: object + description: "The [`IndexedAttestation`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.3/specs/electra/beacon-chain.md#indexedattestation) object from the CL spec." + required: [attesting_indices, data, signature] + properties: + attesting_indices: + type: array + maxItems: 131072 + 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." + Attestation: type: object description: "The [`Attestation`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.3/specs/electra/beacon-chain.md#attestation) object from the CL spec." @@ -8,11 +25,11 @@ Electra: $ref: "../primitive.yaml#/BitList" description: "Attester aggregation bits." data: - $ref: "../attestation.yaml#/AttestationData" + $ref: "../attestation_data.yaml#/AttestationData" signature: $ref: "../primitive.yaml#/Signature" description: "BLS aggregate signature." committee_bits: $ref: "../primitive.yaml#/Bitvector" description: "Committee bits." - example: "0x0000000000000000000000000000000000000000000000000000000000000001" + example: "0x0000000000000001" diff --git a/types/electra/attester_slashing.yaml b/types/electra/attester_slashing.yaml new file mode 100644 index 00000000..89634285 --- /dev/null +++ b/types/electra/attester_slashing.yaml @@ -0,0 +1,10 @@ +Electra: + AttesterSlashing: + type: object + description: "The [`AttesterSlashing`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.3/specs/electra/beacon-chain.md#attesterslashing) object from the CL spec." + required: [attestation_1, attestation_2] + properties: + attestation_1: + $ref: './attestation.yaml#/Electra/IndexedAttestation' + attestation_2: + $ref: './attestation.yaml#/Electra/IndexedAttestation'