From 60ee6dfbe6ce552dfd904d845e723acb8420b508 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 29 May 2024 21:13:59 +0100 Subject: [PATCH 1/4] Add validators v2. --- apis/beacon/states/validators.v2.yaml | 83 +++++++++++++++++++++++++++ apis/beacon/states/validators.yaml | 1 + beacon-node-oapi.yaml | 4 ++ types/api.yaml | 13 +++++ 4 files changed, 101 insertions(+) create mode 100644 apis/beacon/states/validators.v2.yaml diff --git a/apis/beacon/states/validators.v2.yaml b/apis/beacon/states/validators.v2.yaml new file mode 100644 index 00000000..436f872b --- /dev/null +++ b/apis/beacon/states/validators.v2.yaml @@ -0,0 +1,83 @@ +post: + operationId: "postStateValidatorsV2" + summary: "Get validators from state" + description: | + Returns filterable list of validators with their index. + + Information will be returned for all indices or public keys that match known validators. If an index or public key does not + match any known validator, no information will be returned but this will not cause an error. There are no guarantees for the + returned data in terms of ordering; both the index and public key are returned for each validator, and can be used to confirm + for which inputs a response has been returned. + tags: + - Beacon + parameters: + - name: state_id + in: path + $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId' + requestBody: + description: "The lists of validator IDs and statuses to filter on. Either or both may be `null` to signal that no filtering on that attribute is desired." + required: true + content: + application/json: + schema: + type: object + required: [] + properties: + ids: + type: array + uniqueItems: true + items: + description: "Either hex encoded public key (any bytes48 with 0x prefix) or validator index" + type: string + statuses: + type: array + uniqueItems: true + items: + oneOf: + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorStatus' + - enum: ["active", "pending", "exited", "withdrawal"] + responses: + "200": + description: Success + content: + application/json: + schema: + title: PostStateValidatorsV2Response + type: object + required: [version, execution_optimistic, finalized, data] + properties: + version: + type: string + enum: [ phase0, altair, bellatrix, capella, deneb ] + example: "phase0" + execution_optimistic: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" + data: + type: array + items: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorV2Response' + application/octet-stream: + schema: + description: "SSZ serialized array of the returned data. Use Accept header to choose this response type" + "400": + description: "Invalid state or validator ID, or status" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid state ID: current" + "404": + description: "State not found" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "State not found" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index 81ec2a1a..1a2b300e 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -1,6 +1,7 @@ get: operationId: "getStateValidators" summary: "Get validators from state" + deprecated: true description: | Returns filterable list of validators with their balance, status and index. diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index b9640ae3..03184330 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -71,6 +71,8 @@ paths: $ref: "./apis/beacon/states/finality_checkpoints.yaml" /eth/v1/beacon/states/{state_id}/validators: $ref: "./apis/beacon/states/validators.yaml" + /eth/v2/beacon/states/{state_id}/validators: + $ref: "./apis/beacon/states/validators.v2.yaml" /eth/v1/beacon/states/{state_id}/validators/{validator_id}: $ref: "./apis/beacon/states/validator.yaml" /eth/v1/beacon/states/{state_id}/validator_balances: @@ -221,6 +223,8 @@ components: $ref: './types/block.yaml#/SignedBeaconBlockHeader' ValidatorResponse: $ref: './types/api.yaml#/ValidatorResponse' + ValidatorV2Response: + $ref: './types/api.yaml#/ValidatorV2Response' ValidatorBalanceResponse: $ref: './types/api.yaml#/ValidatorBalanceResponse' ValidatorStatus: diff --git a/types/api.yaml b/types/api.yaml index 8d1dd9fc..898aa993 100644 --- a/types/api.yaml +++ b/types/api.yaml @@ -34,6 +34,19 @@ ValidatorResponse: validator: $ref: "./validator.yaml#/Validator" +ValidatorV2Response: + type: object + required: [index, balance, validator] + properties: + index: + $ref: './primitive.yaml#/Uint64' + description: "Index of validator in validator registry." + balance: + $ref: "./primitive.yaml#/Gwei" + description: "Current validator balance in gwei." + validator: + $ref: "./validator.yaml#/Validator" + ValidatorBalanceResponse: type: object required: [index, balance] From 022436039fec1cacdd66cb159c0869ca3133e32a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 29 May 2024 21:19:32 +0100 Subject: [PATCH 2/4] Tidy-ups. --- apis/beacon/states/validators.v2.yaml | 3 +++ apis/beacon/states/validators.yaml | 1 + 2 files changed, 4 insertions(+) diff --git a/apis/beacon/states/validators.v2.yaml b/apis/beacon/states/validators.v2.yaml index 436f872b..f7e4bafa 100644 --- a/apis/beacon/states/validators.v2.yaml +++ b/apis/beacon/states/validators.v2.yaml @@ -39,6 +39,9 @@ post: responses: "200": description: Success + headers: + Eth-Consensus-Version: + $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' content: application/json: schema: diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index 1a2b300e..c892cd5d 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -88,6 +88,7 @@ get: post: operationId: "postStateValidators" summary: "Get validators from state" + deprecated: true description: | Returns filterable list of validators with their balance, status and index. From 07491625bd5d0a194b2b4da3f14ec1c427d2e054 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Fri, 31 May 2024 10:55:42 +0100 Subject: [PATCH 3/4] Add electra to consensus version for validators v2. --- apis/beacon/states/validators.v2.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/beacon/states/validators.v2.yaml b/apis/beacon/states/validators.v2.yaml index f7e4bafa..5b0681b1 100644 --- a/apis/beacon/states/validators.v2.yaml +++ b/apis/beacon/states/validators.v2.yaml @@ -51,7 +51,7 @@ post: properties: version: type: string - enum: [ phase0, altair, bellatrix, capella, deneb ] + enum: [ phase0, altair, bellatrix, capella, deneb, electra ] example: "phase0" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" From aa1cba3098e62c0217c611f35fdd48b88b1e56c7 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 10 Jul 2024 19:47:14 +0100 Subject: [PATCH 4/4] Add endpoint to changelog. --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index e7639bc4..0817536d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -15,6 +15,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#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 | | | | | | +| [#449](https://github.com/ethereum/beacon-APIs/pull/449) `POST /eth/v2/beacon/states/{state_id}/validators` added | | | | | | The Following are no longer in the Standard API, removed since the latest version.