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

Validator identities endpoint. #452

Merged
merged 8 commits into from
Sep 24, 2024
Merged

Validator identities endpoint. #452

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7e14ed6
Validator identities endpoint.
mcdee Jun 10, 2024
757d29a
Merge branch 'master' into validator-identities
mcdee Jul 10, 2024
1c4b504
Add endpoint to changelog.
mcdee Jul 10, 2024
b8c1792
Merge branch 'master' into validator-identities
rolfyone Jul 28, 2024
0358c42
Update apis/beacon/states/validator_identities.yaml
mcdee Aug 16, 2024
8623ac6
Merge branch 'master' into validator-identities
mcdee Sep 15, 2024
c3b4b87
Add 406.
mcdee Sep 15, 2024
887120e
Merge branch 'master' into validator-identities
rolfyone Sep 23, 2024
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
1 change: 1 addition & 0 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,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 | | | | | |
| [#452](https://github.com/ethereum/beacon-APIs/pull/452) `POST /eth/v1/beacon/states/{state_id}/validator_identities` added | | | | | |
| [#456](https://github.com/ethereum/beacon-APIs/pull/456) `POST /eth/v2/validator/aggregate_and_proofs` added | | | | | |


Expand Down
71 changes: 71 additions & 0 deletions apis/beacon/states/validator_identities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
post:
operationId: "postStateValidatorIdentities"
nflaig marked this conversation as resolved.
Show resolved Hide resolved
summary: "Get validator identities from state"
description: |
Returns filterable list of validators identities.

Identities 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 identity will be returned but this will not cause an error. There are no guarantees for the
returned data in terms of ordering.

Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was wondering if we wanna state this here, seems a bit redundant considering we have a more general note about this now since #457 and it's already implied by the response content type + the Accept header is mentioned there as well.

The reason to add the note is that it seems consistent with other endpoint that support SSZ, however could consider cleaning those up a bit

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'd be happy to just merge and cleanup as a separate task...

tags:
- Beacon
parameters:
- name: state_id
in: path
$ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
requestBody:
description: "An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a 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: PostStateValidatorIdentitiesResponse
type: object
required: [execution_optimistic, finalized, data]
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/ValidatorIdentityResponse'
application/octet-stream:
schema:
description: "SSZ serialized results. Use Accept header to choose this response type"
"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"
"404":
description: "State not found"
content:
application/json:
schema:
$ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
example:
code: 404
message: "State not found"
"406":
$ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"500":
mcdee marked this conversation as resolved.
Show resolved Hide resolved
$ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError'
4 changes: 4 additions & 0 deletions beacon-node-oapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ paths:
$ref: "./apis/beacon/states/validator.yaml"
/eth/v1/beacon/states/{state_id}/validator_balances:
$ref: "./apis/beacon/states/validator_balances.yaml"
/eth/v1/beacon/states/{state_id}/validator_identities:
$ref: "./apis/beacon/states/validator_identities.yaml"
/eth/v1/beacon/states/{state_id}/committees:
$ref: "./apis/beacon/states/committee.yaml"
/eth/v1/beacon/states/{state_id}/sync_committees:
Expand Down Expand Up @@ -239,6 +241,8 @@ components:
$ref: './types/api.yaml#/ValidatorResponse'
ValidatorBalanceResponse:
$ref: './types/api.yaml#/ValidatorBalanceResponse'
ValidatorIdentityResponse:
$ref: './types/api.yaml#/ValidatorIdentityResponse'
ValidatorStatus:
$ref: './types/api.yaml#/ValidatorStatus'
Committee:
Expand Down
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 @@ -45,6 +45,20 @@ ValidatorBalanceResponse:
$ref: "./primitive.yaml#/Gwei"
description: "Current validator balance in gwei."

ValidatorIdentityResponse:
type: object
required: [index, pubkey, activation_epoch]
properties:
index:
$ref: './primitive.yaml#/Uint64'
description: "Index of validator in validator registry."
pubkey:
$ref: './primitive.yaml#/Pubkey'
description: "Public key of validator."
activation_epoch:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why add the activation_epoch? It's a curious in-between of no epoch and all epochs in the validator record

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's in case validator index reuse comes in, it will allow us to use (index,public key, activation epoch) as a unique identifier for a validator across all time regardless of reuse.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Index re-use won't come until years down the line if ever. Is it better to do a v2 in 2030 when that happens?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i was thinking there's no harm having it?

$ref: "./primitive.yaml#/Uint64"
description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated"

ValidatorStatus:
description: |
Possible statuses:
Expand Down