Skip to content

Add SSZ response support for validators and validator_balances endpoints #601

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

Open
Zyra-V21 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add SSZ response support for validators and validator_balances endpoints #601

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 5 additions & 0 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ There are likely to be descriptions etc outside of the list below, but new query
| [#568](https://github.com/ethereum/beacon-APIs/pull/568) `GET /eth/v1/node/version` deprecated | | | | | |
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload EVENT` added | | | | | |
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload_gossip EVENT` added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/validators` SSZ response added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/validators` SSZ response added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/validators/{validator_id}` SSZ response added | | | | | |
| `GET /eth/v1/beacon/states/{state_id}/validator_balances` SSZ response added | | | | | |
| `POST /eth/v1/beacon/states/{state_id}/validator_balances` SSZ response added | | | | | |

The Following are no longer in the Standard API, removed since the latest version.

Expand Down
16 changes: 14 additions & 2 deletions apis/beacon/states/validator.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
get:
operationId: "getStateValidator"
summary: "Get validator from state by id"
description: "Returns validator specified by state and id or public key along with status and balance."
description: |
Returns validator specified by state and id or public key along with status and balance.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
- ValidatorRequiredApi
Expand Down Expand Up @@ -32,6 +35,14 @@ get:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized"
data:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorResponse'
application/octet-stream:
schema:
description: |
SSZ serialized `ValidatorResponse` bytes.

`ValidatorResponse` is the SSZ container `{ index: uint64, balance: uint64, status: byte, validator: Validator }`,
where `status` is a single byte encoded according to the table in the `ValidatorStatus` schema and
`Validator` is the consensus spec object. Use `Accept` header to choose this response type.
"400":
description: "Invalid state or validator ID"
content:
Expand All @@ -56,7 +67,8 @@ get:
value:
code: 404
message: Validator not found

"406":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"500":
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'

20 changes: 20 additions & 0 deletions apis/beacon/states/validator_balances.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ get:
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.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
parameters:
Expand Down Expand Up @@ -44,6 +46,12 @@ get:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorBalanceResponse'
application/octet-stream:
schema:
description: |
SSZ serialized `List[ValidatorBalanceResponse, VALIDATOR_REGISTRY_LIMIT]` bytes.

Each `ValidatorBalanceResponse` is the SSZ container `{ index: uint64, balance: uint64 }`. Use `Accept` header to choose this response type.
"400":
description: "Invalid state or validator ID"
content:
Expand All @@ -62,6 +70,8 @@ get:
example:
code: 404
message: "State not found"
"406":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"414":
description: "Too many validator IDs"
content:
Expand All @@ -83,6 +93,8 @@ post:
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.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
parameters:
Expand Down Expand Up @@ -121,6 +133,12 @@ post:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorBalanceResponse'
application/octet-stream:
schema:
description: |
SSZ serialized `List[ValidatorBalanceResponse, VALIDATOR_REGISTRY_LIMIT]` bytes.

Each `ValidatorBalanceResponse` is the SSZ container `{ index: uint64, balance: uint64 }`. Use `Accept` header to choose this response type.
"400":
description: "Invalid state ID or malformed request"
content:
Expand All @@ -139,5 +157,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'
24 changes: 24 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 @@ -8,6 +8,8 @@ get:
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.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
parameters:
Expand Down Expand Up @@ -55,6 +57,14 @@ get:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorResponse'
application/octet-stream:
schema:
description: |
SSZ serialized `List[ValidatorResponse, VALIDATOR_REGISTRY_LIMIT]` bytes.

Each `ValidatorResponse` is the SSZ container `{ index: uint64, balance: uint64, status: byte, validator: Validator }`,
where `status` is a single byte encoded according to the table in the `ValidatorStatus` schema and
`Validator` is the consensus spec object. Use `Accept` header to choose this response type.
"400":
description: "Invalid state or validator ID, or status"
content:
Expand All @@ -73,6 +83,8 @@ get:
example:
code: 404
message: "State not found"
"406":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"414":
description: "Too many validator IDs"
content:
Expand All @@ -97,6 +109,8 @@ post:

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.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
tags:
- Beacon
parameters:
Expand Down Expand Up @@ -150,6 +164,14 @@ post:
type: array
items:
$ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorResponse'
application/octet-stream:
schema:
description: |
SSZ serialized `List[ValidatorResponse, VALIDATOR_REGISTRY_LIMIT]` bytes.

Each `ValidatorResponse` is the SSZ container `{ index: uint64, balance: uint64, status: byte, validator: Validator }`,
where `status` is a single byte encoded according to the table in the `ValidatorStatus` schema and
`Validator` is the consensus spec object. Use `Accept` header to choose this response type.
"400":
description: "Invalid state or validator ID, or status"
content:
Expand All @@ -168,5 +190,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"
14 changes: 14 additions & 0 deletions types/api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,20 @@ ValidatorStatus:
- **withdrawal_possible** - After validator has exited, a while later is permitted to move funds, and is truly out of the system.
- **withdrawal_done** - (not possible in phase0, except slashing full balance) - actually having moved funds away

SSZ encoding (single `byte`, used in `application/octet-stream` responses):
| Value | Status |
| ------ | --------------------- |
| `0x00` | unknown |
| `0x01` | pending_initialized |
| `0x02` | pending_queued |
| `0x03` | active_ongoing |
| `0x04` | active_exiting |
| `0x05` | active_slashed |
| `0x06` | exited_unslashed |
| `0x07` | exited_slashed |
| `0x08` | withdrawal_possible |
| `0x09` | withdrawal_done |

[Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
enum: ["pending_initialized", "pending_queued", "active_ongoing", "active_exiting", "active_slashed", "exited_unslashed", "exited_slashed", "withdrawal_possible", "withdrawal_done"]
example: "active_ongoing"
Expand Down