From 7e14ed6b113fc2c7dbe4da7a812550a5dc712c20 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Mon, 10 Jun 2024 11:13:43 +0100 Subject: [PATCH 1/4] Validator identities endpoint. In support of #449. --- apis/beacon/states/validator_identities.yaml | 69 ++++++++++++++++++++ beacon-node-oapi.yaml | 4 ++ types/api.yaml | 14 ++++ 3 files changed, 87 insertions(+) create mode 100644 apis/beacon/states/validator_identities.yaml diff --git a/apis/beacon/states/validator_identities.yaml b/apis/beacon/states/validator_identities.yaml new file mode 100644 index 00000000..4d5ffec6 --- /dev/null +++ b/apis/beacon/states/validator_identities.yaml @@ -0,0 +1,69 @@ +post: + operationId: "postStateValidatorIdentities" + summary: "Get validator identities from state" + description: | + Returns filterable list of validators identities. + + Identities 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 identity will be returned but this will not cause an error. There are no guarantees for the + returned data in terms of ordering. + + Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ. + tags: + - Beacon + parameters: + - name: state_id + in: path + $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId' + requestBody: + description: "An array of either hex encoded public keys (any bytes48 with 0x prefix) or validator indices" + required: false + content: + application/json: + schema: + type: array + uniqueItems: true + items: + description: "Either hex encoded public key (any bytes48 with 0x prefix) or validator index" + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + title: PostStateValidatorIdentitiesResponse + type: object + required: [execution_optimistic, finalized, data] + properties: + 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/ValidatorIdentityResponse' + application/octet-stream: + schema: + description: "SSZ serialized results. Use Accept header to choose this response type" + "400": + description: "Invalid state ID or malformed request" + 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/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index b9640ae3..d29dbd7d 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -75,6 +75,8 @@ paths: $ref: "./apis/beacon/states/validator.yaml" /eth/v1/beacon/states/{state_id}/validator_balances: $ref: "./apis/beacon/states/validator_balances.yaml" + /eth/v1/beacon/states/{state_id}/validator_identities: + $ref: "./apis/beacon/states/validator_identities.yaml" /eth/v1/beacon/states/{state_id}/committees: $ref: "./apis/beacon/states/committee.yaml" /eth/v1/beacon/states/{state_id}/sync_committees: @@ -223,6 +225,8 @@ components: $ref: './types/api.yaml#/ValidatorResponse' ValidatorBalanceResponse: $ref: './types/api.yaml#/ValidatorBalanceResponse' + ValidatorIdentityResponse: + $ref: './types/api.yaml#/ValidatorIdentityResponse' ValidatorStatus: $ref: './types/api.yaml#/ValidatorStatus' Committee: diff --git a/types/api.yaml b/types/api.yaml index 8d1dd9fc..8b577e16 100644 --- a/types/api.yaml +++ b/types/api.yaml @@ -45,6 +45,20 @@ ValidatorBalanceResponse: $ref: "./primitive.yaml#/Gwei" description: "Current validator balance in gwei." +ValidatorIdentityResponse: + type: object + required: [index, pubkey, activation_epoch] + properties: + index: + $ref: './primitive.yaml#/Uint64' + description: "Index of validator in validator registry." + pubkey: + $ref: './primitive.yaml#/Pubkey' + description: "Public key of validator." + activation_epoch: + $ref: "./primitive.yaml#/Uint64" + description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated" + ValidatorStatus: description: | Possible statuses: From 1c4b50406c6185bb87aaf7ebd74130955bc3007c Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Wed, 10 Jul 2024 19:44:42 +0100 Subject: [PATCH 2/4] Add endpoint to changelog. --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index e7639bc4..62286798 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 | | | | | | +| [#452](https://github.com/ethereum/beacon-APIs/pull/452) `POST /eth/v1/beacon/states/{state_id}/validator_identities` added | | | | | | The Following are no longer in the Standard API, removed since the latest version. From 0358c42943f6494cfa2233f49a51cfa2bfae7f48 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Fri, 16 Aug 2024 23:18:17 +0100 Subject: [PATCH 3/4] Update apis/beacon/states/validator_identities.yaml Co-authored-by: Nico Flaig --- apis/beacon/states/validator_identities.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/beacon/states/validator_identities.yaml b/apis/beacon/states/validator_identities.yaml index 4d5ffec6..71616f15 100644 --- a/apis/beacon/states/validator_identities.yaml +++ b/apis/beacon/states/validator_identities.yaml @@ -16,7 +16,7 @@ post: in: path $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId' requestBody: - description: "An array of either hex encoded public keys (any bytes48 with 0x prefix) or validator indices" + description: "An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a validator index." required: false content: application/json: From c3b4b870d039445a769fec266cf0d36db3cefe62 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sun, 15 Sep 2024 08:51:15 +0100 Subject: [PATCH 4/4] Add 406. --- apis/beacon/states/validator_identities.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/apis/beacon/states/validator_identities.yaml b/apis/beacon/states/validator_identities.yaml index 71616f15..4963f5c3 100644 --- a/apis/beacon/states/validator_identities.yaml +++ b/apis/beacon/states/validator_identities.yaml @@ -65,5 +65,7 @@ post: example: code: 404 message: "State not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'