Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

POST endpoints for validators and validator_balances #367

Merged
merged 4 commits into from
Nov 7, 2023
Merged

POST endpoints for validators and validator_balances #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0132c09
`POST /eth/v1/beacon/states/{state_id}/validators`
michaelsproul Oct 23, 2023
4728ebb
Delete 414 response
michaelsproul Oct 23, 2023
6e26783
Add POST validator_balances and CHANGELOG
michaelsproul Nov 5, 2023
5d5078d
Merge branch 'master' into post-state-validators
rolfyone Nov 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
60 changes: 57 additions & 3 deletions apis/beacon/states/validator_balances.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'
78 changes: 78 additions & 0 deletions apis/beacon/states/validators.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,81 @@ 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"
"500":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError"
Loading