From 5b92a9f6c6239679c8fbe1ef2af460880aeefdf2 Mon Sep 17 00:00:00 2001 From: Etan Kissling Date: Sat, 28 Jan 2023 10:47:53 +0100 Subject: [PATCH 1/5] support Capella LC data (#293) Implements the light client data format for Capella: - https://github.com/ethereum/consensus-specs/pull/3151 --- apis/beacon/light_client/bootstrap.yaml | 8 ++- apis/beacon/light_client/finality_update.yaml | 8 ++- .../light_client/optimistic_update.yaml | 8 ++- apis/beacon/light_client/updates.yaml | 17 +++-- beacon-node-oapi.yaml | 18 +++-- types/altair/light_client.yaml | 6 +- types/bellatrix/transactions.yaml | 3 +- types/capella/execution_payload.yaml | 2 +- types/capella/light_client.yaml | 67 +++++++++++++++++++ types/capella/transactions.yaml | 6 -- 10 files changed, 110 insertions(+), 33 deletions(-) create mode 100644 types/capella/light_client.yaml delete mode 100644 types/capella/transactions.yaml diff --git a/apis/beacon/light_client/bootstrap.yaml b/apis/beacon/light_client/bootstrap.yaml index e0dfcab0..0e206ae5 100644 --- 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 index 9b0a1f40..83b42ee2 100644 --- 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 index b3bfc866..45e47755 100644 --- 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 index ab6296bf..19521eab 100644 --- 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 | - | `ALTAIR_FORK_VERSION` and later | `altair.LightClientUpdate` | + | `fork_version` | Response chunk SSZ type | + | ------------------------------------------------------------------- | ------------------------------------- | + | `GENESIS_FORK_VERSION` | n/a | + | `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientUpdate` | + | `CAPELLA_FORK_VERSION` and later | `capella.LightClientUpdate` | "400": description: Malformed or missing request parameter content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index e0812350..78833c46 100644 --- 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: @@ -272,6 +272,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 +284,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 +325,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' Node: $ref: './types/fork_choice.yaml#/Node' ExtraData: diff --git a/types/altair/light_client.yaml b/types/altair/light_client.yaml index 4489433d..5f843000 100644 --- 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 diff --git a/types/bellatrix/transactions.yaml b/types/bellatrix/transactions.yaml index c18bbbc9..3e481317 100644 --- a/types/bellatrix/transactions.yaml +++ b/types/bellatrix/transactions.yaml @@ -2,6 +2,5 @@ Bellatrix: Transactions: type: array items: - allOf: - - $ref: '../primitive.yaml#/Transaction' + $ref: '../primitive.yaml#/Transaction' maxItems: 1048576 diff --git a/types/capella/execution_payload.yaml b/types/capella/execution_payload.yaml index 3f543156..f3214606 100644 --- a/types/capella/execution_payload.yaml +++ b/types/capella/execution_payload.yaml @@ -38,7 +38,7 @@ Capella: - type: object properties: transactions: - $ref: './transactions.yaml#/Capella/Transactions' + $ref: '../bellatrix/transactions.yaml#/Bellatrix/Transactions' withdrawals: $ref: './withdrawals.yaml#/Capella/Withdrawals' diff --git a/types/capella/light_client.yaml b/types/capella/light_client.yaml new file mode 100644 index 00000000..9eb06d3d --- /dev/null +++ b/types/capella/light_client.yaml @@ -0,0 +1,67 @@ +Capella: + ExecutionBranch: + type: array + items: + $ref: '../primitive.yaml#/Root' + description: "Merkle proof consisting of [`log2trunc(EXECUTION_PAYLOAD_INDEX])`](https://github.com/ethereum/consensus-specs/blob/v1.3.0-rc.2/specs/capella/light-client/sync-protocol.md#constants) roots" + minItems: 4 + maxItems: 4 + + LightClientHeader: + type: object + properties: + beacon: + $ref: '../block.yaml#/BeaconBlockHeader' + execution: + $ref: './execution_payload.yaml#/Capella/ExecutionPayloadHeader' + execution_branch: + $ref: '#/Capella/ExecutionBranch' + + LightClientBootstrap: + type: object + properties: + header: + $ref: '#/Capella/LightClientHeader' + current_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + current_sync_committee_branch: + $ref: '../altair/light_client.yaml#/Altair/CurrentSyncCommitteeBranch' + LightClientUpdate: + type: object + properties: + attested_header: + $ref: '#/Capella/LightClientHeader' + next_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + next_sync_committee_branch: + $ref: '../altair/light_client.yaml#/Altair/NextSyncCommitteeBranch' + finalized_header: + $ref: '#/Capella/LightClientHeader' + finality_branch: + $ref: '../altair/light_client.yaml#/Altair/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientFinalityUpdate: + type: object + properties: + attested_header: + $ref: '#/Capella/LightClientHeader' + finalized_header: + $ref: '#/Capella/LightClientHeader' + finality_branch: + $ref: '../altair/light_client.yaml#/Altair/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientOptimisticUpdate: + type: object + properties: + attested_header: + $ref: '#/Capella/LightClientHeader' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' diff --git a/types/capella/transactions.yaml b/types/capella/transactions.yaml deleted file mode 100644 index eafc7d0d..00000000 --- a/types/capella/transactions.yaml +++ /dev/null @@ -1,6 +0,0 @@ -Capella: - Transactions: - type: array - items: - $ref: '../primitive.yaml#/Transaction' - maxItems: 1048576 From 4a2d70b9e351690ec54526ff983bc42b566269cd Mon Sep 17 00:00:00 2001 From: Samuel Laferriere Date: Tue, 31 Jan 2023 02:47:58 -0500 Subject: [PATCH 2/5] fixed typo (#291) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 191f6d71..429b75c3 100644 --- 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. From 39457974195c1e5d6f15e0f7b3a8f5b4c1881171 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ois=C3=ADn=20Kyne?= <4981644+OisinKyne@users.noreply.github.com> Date: Tue, 31 Jan 2023 09:19:22 +0000 Subject: [PATCH 3/5] Attestation and Sync Committee aggregation selection (#224) Co-authored-by: xenowits Co-authored-by: Dhruv Bodani Co-authored-by: Abhishek Kumar <43061995+xenowits@users.noreply.github.com> --- .gitignore | 1 + CHANGES.md | 2 + .../beacon_committee_selections.yaml | 43 +++++++++++++++++++ apis/validator/sync_committee_selections.yaml | 41 ++++++++++++++++++ beacon-node-oapi.yaml | 10 +++++ types/http.yaml | 22 ++++++++++ types/selection.yaml | 35 +++++++++++++++ 7 files changed, 154 insertions(+) create mode 100644 apis/validator/beacon_committee_selections.yaml create mode 100644 apis/validator/sync_committee_selections.yaml create mode 100644 types/selection.yaml diff --git a/.gitignore b/.gitignore index 04b23911..f0c8d015 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .idea deploy +node_modules diff --git a/CHANGES.md b/CHANGES.md index c21f3cc8..8a7b695c 100644 --- 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 new file mode 100644 index 00000000..c906012e --- /dev/null +++ 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 new file mode 100644 index 00000000..0b26fb0b --- /dev/null +++ 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 index 78833c46..eadfa4c1 100644 --- 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 index 116c114a..16221692 100644 --- 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 new file mode 100644 index 00000000..28d67c88 --- /dev/null +++ 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" From 1741560a920615480b7a7e1bc04060428abc469c Mon Sep 17 00:00:00 2001 From: Mehdi AOUADI Date: Thu, 2 Feb 2023 10:03:23 +0100 Subject: [PATCH 4/5] Handle EL offline/unavailable in the Sync API (#290) * Add changes entry --------- Co-authored-by: Paul Harris --- CHANGES.md | 51 +++++++++++++++++++++--------------------- apis/node/syncing.yaml | 5 ++++- 2 files changed, 30 insertions(+), 26 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 8a7b695c..d4d7a228 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -7,31 +7,32 @@ These endpoints have been added or updated since the last release. There are likely to be descriptions etc outside of the list below, but new query parameters, changes to headers, new endpoints should be listed. -| 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) | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| -| [#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` | | | | | | -| [#245](https://github.com/ethereum/beacon-APIs/pull/245) NEW `/eth/v1/beacon/deposit_snapshot` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/bootstrap/{block_root}` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/updates` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/updates` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/beacon/light_client/finality_update` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/beacon/light_client/optimistic_update` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/events:light_client_finality_update` | | | | | | -| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/events:light_client_optimistic_update` | | | | | | -| [#248](https://github.com/ethereum/beacon-APIs/pull/248) [#248](https://github.com/ethereum/beacon-APIs/pull/248) NEW `/eth/v1/beacon/pool/bls_to_execution_changes` | | | | | | -| [#248](https://github.com/ethereum/beacon-APIs/pull/248) add _Capella Types_ | | | | | | -| [#249](https://github.com/ethereum/beacon-APIs/pull/249) `/eth/v1/beacon/blinded_blocks/{block_id}` query parameter `skip_randao_verification` | | | | | | -| [#251](https://github.com/ethereum/beacon-APIs/pull/251) `/eth/v1/node/health` query parameter `syncing_status` | | | | | | -| [#254](https://github.com/ethereum/beacon-APIs/pull/254) add `finalized` to metadata for chain objects | | | | | | -| [#260](https://github.com/ethereum/beacon-APIs/pull/260) NEW `/eth/v1/beacon/rewards/blocks/{block_id}` | | | | | | -| [#260](https://github.com/ethereum/beacon-APIs/pull/260) NEW `/eth/v1/beacon/rewards/attestations/{epoch}` | | | | | | -| [#262](https://github.com/ethereum/beacon-APIs/pull/262) NEW `/eth/v1/beacon/rewards/sync_committee/{block_id}` | | | | | | +| 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) | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| +| [#290](https://github.com/ethereum/beacon-APIs/pull/290) `/eth/v1/node/syncing` added `el_offline` to response | | | | | | +| [#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` | | | | | | +| [#245](https://github.com/ethereum/beacon-APIs/pull/245) NEW `/eth/v1/beacon/deposit_snapshot` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/bootstrap/{block_root}` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/updates` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v2/beacon/light_client/updates` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/beacon/light_client/finality_update` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/beacon/light_client/optimistic_update` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/events:light_client_finality_update` | | | | | | +| [#247](https://github.com/ethereum/beacon-APIs/pull/247) NEW `/eth/v1/events:light_client_optimistic_update` | | | | | | +| [#248](https://github.com/ethereum/beacon-APIs/pull/248) [#248](https://github.com/ethereum/beacon-APIs/pull/248) NEW `/eth/v1/beacon/pool/bls_to_execution_changes` | | | | | | +| [#248](https://github.com/ethereum/beacon-APIs/pull/248) add _Capella Types_ | | | | | | +| [#249](https://github.com/ethereum/beacon-APIs/pull/249) `/eth/v1/beacon/blinded_blocks/{block_id}` query parameter `skip_randao_verification` | | | | | | +| [#251](https://github.com/ethereum/beacon-APIs/pull/251) `/eth/v1/node/health` query parameter `syncing_status` | | | | | | +| [#254](https://github.com/ethereum/beacon-APIs/pull/254) add `finalized` to metadata for chain objects | | | | | | +| [#260](https://github.com/ethereum/beacon-APIs/pull/260) NEW `/eth/v1/beacon/rewards/blocks/{block_id}` | | | | | | +| [#260](https://github.com/ethereum/beacon-APIs/pull/260) NEW `/eth/v1/beacon/rewards/attestations/{epoch}` | | | | | | +| [#262](https://github.com/ethereum/beacon-APIs/pull/262) NEW `/eth/v1/beacon/rewards/sync_committee/{block_id}` | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/node/syncing.yaml b/apis/node/syncing.yaml index 4ca7f6c5..a2f07d71 100644 --- 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' From 181575da112fe6556e48a5b7e0ad4a2154e95da0 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 6 Feb 2023 10:48:21 +1100 Subject: [PATCH 5/5] Remove array from attestation rewards response (#297) --- apis/beacon/rewards/attestations.yaml | 2 -- types/rewards.yaml | 22 +++++++++++----------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/apis/beacon/rewards/attestations.yaml b/apis/beacon/rewards/attestations.yaml index 8bfdd1b7..5644c8d7 100644 --- 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/types/rewards.yaml b/types/rewards.yaml index c091d75a..c07ee90c 100644 --- a/types/rewards.yaml +++ b/types/rewards.yaml @@ -18,18 +18,18 @@ SyncCommitteeRewards: - description: "sync committee reward in gwei for the validator" AttestationsRewards: + type: object description: "Rewards info for attestations" - type: array - items: - properties: - ideal_rewards: - type: array - items: - $ref: ./rewards.yaml#/IdealAttestationRewards - total_rewards: - type: array - items: - $ref: ./rewards.yaml#/AttestationRewards + required: ["ideal_rewards", "total_rewards"] + properties: + ideal_rewards: + type: array + items: + $ref: ./rewards.yaml#/IdealAttestationRewards + total_rewards: + type: array + items: + $ref: ./rewards.yaml#/AttestationRewards AttestationRewards: type: object