diff --git a/CHANGES.md b/CHANGES.md index 0e44342e..b8ab9b28 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -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. diff --git a/apis/beacon/states/validator.yaml b/apis/beacon/states/validator.yaml index 2d1850e2..fdd44d41 100644 --- a/apis/beacon/states/validator.yaml +++ b/apis/beacon/states/validator.yaml @@ -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 @@ -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: @@ -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' diff --git a/apis/beacon/states/validator_balances.yaml b/apis/beacon/states/validator_balances.yaml index aa0c3b7d..f91d0f8e 100644 --- a/apis/beacon/states/validator_balances.yaml +++ b/apis/beacon/states/validator_balances.yaml @@ -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: @@ -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: @@ -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: @@ -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: @@ -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: @@ -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' diff --git a/apis/beacon/states/validators.yaml b/apis/beacon/states/validators.yaml index 35483ffe..3ebad034 100644 --- a/apis/beacon/states/validators.yaml +++ b/apis/beacon/states/validators.yaml @@ -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: @@ -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: @@ -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: @@ -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: @@ -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: @@ -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" diff --git a/types/api.yaml b/types/api.yaml index 356fb4e6..220c2d16 100644 --- a/types/api.yaml +++ b/types/api.yaml @@ -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"