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. diff --git a/apis/beacon/states/validators.v2.yaml b/apis/beacon/states/validators.v2.yaml new file mode 100644 index 00000000..5b0681b1 --- /dev/null +++ b/apis/beacon/states/validators.v2.yaml @@ -0,0 +1,86 @@ +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 + headers: + Eth-Consensus-Version: + $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + content: + application/json: + schema: + title: PostStateValidatorsV2Response + 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: + 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..c892cd5d 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. @@ -87,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. diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index f90691d1..50253e40 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: @@ -229,6 +231,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]