From 0132c09a429e530e1f3f05b91ab4c225b356fdca Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 23 Oct 2023 11:59:41 +1100 Subject: [PATCH 1/3] `POST /eth/v1/beacon/states/{state_id}/validators` --- apis/beacon/states/validators.yaml | 87 ++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index b8cba7cd..6c6e1b42 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -83,3 +83,90 @@ get: message: "Too many validator IDs in request" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" +post: + operationId: "postStateValidators" + summary: "Get validators from state" + description: | + Returns filterable list of validators with their balance, status and index. + + Information will be returned for all indices or public key 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. + + The POST variant of this endpoint has the same semantics as the GET endpoint but passes + the lists of IDs and statuses via a POST body in order to enable larger requests. + 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: + allOf: + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorStatus' + - enum: ["active", "pending", "exited", "withdrawal"] + responses: + "200": + description: Success + content: + application/json: + schema: + title: GetStateValidatorsResponse + type: object + 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/ValidatorResponse' + "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" + "414": + description: "Too many validator IDs" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 414 + message: "Too many validator IDs in request" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" From 4728ebbeffcf52b243fc7a338f25fba97457cd16 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 23 Oct 2023 12:33:07 +1100 Subject: [PATCH 2/3] Delete 414 response --- apis/beacon/states/validators.yaml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index 6c6e1b42..b85c829c 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -159,14 +159,5 @@ post: example: code: 404 message: "State not found" - "414": - description: "Too many validator IDs" - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 414 - message: "Too many validator IDs in request" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" From 6e26783e01268415e22ba200c23acd97692803b0 Mon Sep 17 00:00:00 2001 From: Michael Sproul Date: Mon, 6 Nov 2023 10:57:11 +1100 Subject: [PATCH 3/3] Add POST validator_balances and CHANGELOG --- CHANGES.md | 11 ++-- apis/beacon/states/validator_balances.yaml | 60 ++++++++++++++++++++-- 2 files changed, 63 insertions(+), 8 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index b8d4089b..718e04c1 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -7,11 +7,12 @@ 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) | -|---------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| -| [#339](https://github.com/ethereum/beacon-APIs/pull/339) `POST /eth/v3/beacon/blocks` added | | | | | | -| [#350](https://github.com/ethereum/beacon-APIs/pull/350) `blob_sidecar EVENT` added | | | | | | - +| 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) | +|---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| +| [#339](https://github.com/ethereum/beacon-APIs/pull/339) `POST /eth/v3/beacon/blocks` added | | | | | | +| [#350](https://github.com/ethereum/beacon-APIs/pull/350) `blob_sidecar EVENT` added | | | | | | +| [#367](https://github.com/ethereum/beacon-APIs/pull/367) `POST /eth/v1/beacon/states/{state_id}/validators` | | | | | | +| [#367](https://github.com/ethereum/beacon-APIs/pull/367) `POST /eth/v1/beacon/states/{state_id}/validator_balances` | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/beacon/states/validator_balances.yaml b/apis/beacon/states/validator_balances.yaml index 3cbe0cb8..fe7879a9 100644 --- a/apis/beacon/states/validator_balances.yaml +++ b/apis/beacon/states/validator_balances.yaml @@ -4,9 +4,9 @@ get: description: | Returns filterable list of validators balances. - Balances will be returned for all indices or public key that match known validators. If an index or public key does not - match any known validator, no balance will be returned but this will not cause an error. There are no guarantees for the - returned data in terms of ordering; the index and is returned for each balance, and can be used to confirm for which inputs a + Balances will be returned for all indices or public key that match known validators. If an index or public key does not + match any known validator, no balance will be returned but this will not cause an error. There are no guarantees for the + returned data in terms of ordering; the index is returned for each balance, and can be used to confirm for which inputs a response has been returned. tags: - Beacon @@ -63,4 +63,58 @@ get: message: "Too many validator IDs in request" "500": $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' +post: + operationId: "postStateValidatorBalances" + summary: "Get validator balances from state" + description: | + Returns filterable list of validators balances. + Balances will be returned for all indices or public key that match known validators. If an index or public key does not + match any known validator, no balance will be returned but this will not cause an error. There are no guarantees for the + returned data in terms of ordering; the index is returned for each balance, 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: "An array of either hex encoded public key (any bytes48 with 0x prefix) or validator index" + 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: GetStateValidatorBalancesResponse + type: object + 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/ValidatorBalanceResponse' + "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" + "500": + $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'