diff --git a/beacon-chain/rpc/prysm/beacon/handlers.go b/beacon-chain/rpc/prysm/beacon/handlers.go index 3a873d7e5423..b55938a1e9bc 100644 --- a/beacon-chain/rpc/prysm/beacon/handlers.go +++ b/beacon-chain/rpc/prysm/beacon/handlers.go @@ -26,6 +26,15 @@ import ( // GetWeakSubjectivity computes the starting epoch of the current weak subjectivity period, and then also // determines the best block root and state root to use for a Checkpoint Sync starting from that point. +// +// @Summary Get weak subjectivity checkpoint +// @Description Computes the weak subjectivity checkpoint for safe checkpoint sync initialization +// @Tags Prysm Beacon +// @Produce json +// @Success 200 {object} structs.GetWeakSubjectivityResponse +// @Failure 500 {object} httputil.DefaultJsonError +// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing" +// @Router /prysm/v1/beacon/weak_subjectivity [get] func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.GetWeakSubjectivity") defer span.End() @@ -79,6 +88,17 @@ func (s *Server) GetWeakSubjectivity(w http.ResponseWriter, r *http.Request) { } // GetIndividualVotes returns a list of validators individual vote status of a given epoch. +// +// @Summary Get individual validator votes +// @Description Returns detailed voting information for specified validators in a given epoch +// @Tags Prysm Beacon +// @Accept json +// @Produce json +// @Param request body structs.GetIndividualVotesRequest true "Validator indices/public keys and epoch" +// @Success 200 {object} structs.GetIndividualVotesResponse +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/beacon/individual_votes [post] func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "validator.GetIndividualVotes") defer span.End() @@ -159,6 +179,14 @@ func (s *Server) GetIndividualVotes(w http.ResponseWriter, r *http.Request) { // GetChainHead retrieves information about the head of the beacon chain from // the view of the beacon chain node. +// +// @Summary Get chain head information +// @Description Returns detailed information about the current head, finalized, and justified checkpoints of the beacon chain +// @Tags Prysm Beacon +// @Produce json +// @Success 200 {object} structs.ChainHead +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/beacon/chain_head [get] func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.GetChainHead") defer span.End() @@ -186,7 +214,20 @@ func (s *Server) GetChainHead(w http.ResponseWriter, r *http.Request) { httputil.WriteJson(w, response) } +// PublishBlobs publishes blob sidecars to the network. // Warning: no longer supported post Fulu blobs +// +// @Summary Publish blob sidecars (DEPRECATED post-Fulu) +// @Description Publishes blob sidecars to the beacon network. Only supported for Deneb through Fulu epochs. +// @Tags Prysm Beacon +// @Accept json +// @Param request body structs.PublishBlobsRequest true "Blob sidecars to publish" +// @Success 200 "Blobs successfully published" +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Failure 503 {object} httputil.DefaultJsonError "Beacon node is currently syncing" +// @Deprecated +// @Router /prysm/v1/beacon/blobs [post] func (s *Server) PublishBlobs(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.PublishBlobs") defer span.End() diff --git a/beacon-chain/rpc/prysm/beacon/ssz_query.go b/beacon-chain/rpc/prysm/beacon/ssz_query.go index 30fbfdf16bdd..05af97a540ac 100644 --- a/beacon-chain/rpc/prysm/beacon/ssz_query.go +++ b/beacon-chain/rpc/prysm/beacon/ssz_query.go @@ -19,6 +19,19 @@ import ( // QueryBeaconState handles SSZ Query request for BeaconState. // Returns as bytes serialized SSZQueryResponse. +// +// @Summary Query beacon state with SSZ path +// @Description Executes an SSZ query on a beacon state and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from large state objects. +// @Tags Prysm Beacon +// @Accept json +// @Produce application/octet-stream +// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)" +// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'validators[0].pubkey')" +// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result" +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 404 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/beacon/states/{state_id}/query [post] func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconState") defer span.End() @@ -110,8 +123,21 @@ func (s *Server) QueryBeaconState(w http.ResponseWriter, r *http.Request) { httputil.WriteSsz(w, responseSsz) } -// QueryBeaconState handles SSZ Query request for BeaconState. +// QueryBeaconBlock handles SSZ Query request for BeaconBlock. // Returns as bytes serialized SSZQueryResponse. +// +// @Summary Query beacon block with SSZ path +// @Description Executes an SSZ query on a beacon block and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from block objects. +// @Tags Prysm Beacon +// @Accept json +// @Produce application/octet-stream +// @Param block_id path string true "Block identifier (head, genesis, finalized, slot number, or hex root)" +// @Param request body structs.SSZQueryRequest true "SSZ query path (e.g., 'body.attestations[0]')" +// @Success 200 {string} binary "SSZ-encoded SSZQueryResponse containing root and result" +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 404 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/beacon/blocks/{block_id}/query [post] func (s *Server) QueryBeaconBlock(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.QueryBeaconBlock") defer span.End() diff --git a/beacon-chain/rpc/prysm/beacon/validator_count.go b/beacon-chain/rpc/prysm/beacon/validator_count.go index 1735aae99426..a3c87de90e74 100644 --- a/beacon-chain/rpc/prysm/beacon/validator_count.go +++ b/beacon-chain/rpc/prysm/beacon/validator_count.go @@ -48,6 +48,19 @@ import ( // } // ] // } +// +// @Summary Get validator count by status +// @Description Returns the total number of validators grouped by their status (active, pending, exited, withdrawal, etc.) for a given state +// @Tags Prysm Beacon +// @Produce json +// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)" +// @Param status query []string false "Validator status filter (can be repeated). If omitted, returns counts for all statuses. Valid values: pending_initialized, pending_queued, active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal" +// @Success 200 {object} structs.GetValidatorCountResponse +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 404 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/beacon/states/{state_id}/validator_count [get] +// @Router /eth/v1/beacon/states/{state_id}/validator_count [get] func (s *Server) GetValidatorCount(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "beacon.GetValidatorCount") defer span.End() diff --git a/beacon-chain/rpc/prysm/doc.go b/beacon-chain/rpc/prysm/doc.go new file mode 100644 index 000000000000..ac2062ba099f --- /dev/null +++ b/beacon-chain/rpc/prysm/doc.go @@ -0,0 +1,18 @@ +// Package prysm provides custom Prysm beacon node API endpoints. +// +// @title Prysm Beacon Node Custom API +// @version 1.0 +// @description Custom Prysm endpoints for beacon node operations, validator metrics, and extended functionality. +// @description These endpoints extend the standard Ethereum Beacon Node API with Prysm-specific features. +// +// @contact.name Prysm Team +// @contact.url https://github.com/OffchainLabs/prysm +// +// @license.name GPL-3.0 +// @license.url https://github.com/OffchainLabs/prysm/blob/develop/LICENSE.md +// +// @host localhost:3500 +// @BasePath / +// +// @schemes http https +package prysm diff --git a/beacon-chain/rpc/prysm/node/handlers.go b/beacon-chain/rpc/prysm/node/handlers.go index 0eaea34be587..8de9c8d93752 100644 --- a/beacon-chain/rpc/prysm/node/handlers.go +++ b/beacon-chain/rpc/prysm/node/handlers.go @@ -19,6 +19,14 @@ import ( ) // ListTrustedPeer retrieves data about the node's trusted peers. +// +// @Summary List trusted peers +// @Description Returns a list of all trusted peers configured on this beacon node, including their connection state, direction, ENR, and last seen address +// @Tags Prysm Node +// @Produce json +// @Success 200 {object} structs.PeersResponse +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/node/trusted_peers [get] func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) { _, span := trace.StartSpan(r.Context(), "node.ListTrustedPeer") defer span.End() @@ -53,6 +61,16 @@ func (s *Server) ListTrustedPeer(w http.ResponseWriter, r *http.Request) { } // AddTrustedPeer adds a new peer into node's trusted peer set by Multiaddr +// +// @Summary Add a trusted peer +// @Description Adds a peer to the beacon node's trusted peer set using its multiaddress. Trusted peers are given priority in peer connections. +// @Tags Prysm Node +// @Accept json +// @Param request body structs.AddrRequest true "Peer multiaddress (e.g., /ip4/127.0.0.1/tcp/13000/p2p/16Uiu2...)" +// @Success 200 "Peer successfully added to trusted set" +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/node/trusted_peers [post] func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) { _, span := trace.StartSpan(r.Context(), "node.AddTrustedPeer") defer span.End() @@ -101,6 +119,14 @@ func (s *Server) AddTrustedPeer(w http.ResponseWriter, r *http.Request) { } // RemoveTrustedPeer removes peer from our trusted peer set but does not close connection. +// +// @Summary Remove a trusted peer +// @Description Removes a peer from the beacon node's trusted peer set by peer ID. Does not disconnect the peer if already connected. +// @Tags Prysm Node +// @Param peer_id path string true "Peer ID to remove from trusted set" +// @Success 200 "Peer successfully removed from trusted set" +// @Failure 400 {object} httputil.DefaultJsonError +// @Router /prysm/node/trusted_peers/{peer_id} [delete] func (s *Server) RemoveTrustedPeer(w http.ResponseWriter, r *http.Request) { _, span := trace.StartSpan(r.Context(), "node.RemoveTrustedPeer") defer span.End() diff --git a/beacon-chain/rpc/prysm/validator/handlers.go b/beacon-chain/rpc/prysm/validator/handlers.go index 6b60b89f2a32..0cc24460bc9a 100644 --- a/beacon-chain/rpc/prysm/validator/handlers.go +++ b/beacon-chain/rpc/prysm/validator/handlers.go @@ -17,6 +17,17 @@ import ( // GetParticipation retrieves the validator participation information for a given epoch, // it returns the information about validator's participation rate in voting on the proof of stake // rules based on their balance compared to the total active validator balance. +// +// @Summary Get validator participation for an epoch +// @Description Returns participation rate information for validators at a given state, including voting statistics and balance information for current and previous epochs +// @Tags Prysm Validator +// @Produce json +// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)" +// @Success 200 {object} structs.GetValidatorParticipationResponse +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 404 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/validators/{state_id}/participation [get] func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "validator.GetParticipation") defer span.End() @@ -62,6 +73,17 @@ func (s *Server) GetParticipation(w http.ResponseWriter, r *http.Request) { // // This data includes any activations, voluntary exits, and involuntary // ejections. +// +// @Summary Get active validator set changes +// @Description Returns validator set changes for a given epoch including activations, voluntary exits, slashings, and ejections with both public keys and indices +// @Tags Prysm Validator +// @Produce json +// @Param state_id path string true "State identifier (head, genesis, finalized, justified, slot number, or hex root)" +// @Success 200 {object} structs.ActiveSetChanges +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 404 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/v1/validators/{state_id}/active_set_changes [get] func (s *Server) GetActiveSetChanges(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "validator.GetActiveSetChanges") defer span.End() diff --git a/beacon-chain/rpc/prysm/validator/validator_performance.go b/beacon-chain/rpc/prysm/validator/validator_performance.go index 29334068a342..f8f8e2417ed1 100644 --- a/beacon-chain/rpc/prysm/validator/validator_performance.go +++ b/beacon-chain/rpc/prysm/validator/validator_performance.go @@ -14,6 +14,17 @@ import ( ) // GetPerformance is an HTTP handler for GetPerformance. +// +// @Summary Get validator performance metrics +// @Description Returns detailed performance metrics for specified validators including voting accuracy, balances before and after epoch transitions, and inactivity scores +// @Tags Prysm Validator +// @Accept json +// @Produce json +// @Param request body structs.GetValidatorPerformanceRequest true "Validator public keys and/or indices to query" +// @Success 200 {object} structs.GetValidatorPerformanceResponse +// @Failure 400 {object} httputil.DefaultJsonError +// @Failure 500 {object} httputil.DefaultJsonError +// @Router /prysm/validators/performance [post] func (s *Server) GetPerformance(w http.ResponseWriter, r *http.Request) { ctx, span := trace.StartSpan(r.Context(), "validator.GetPerformance") defer span.End() diff --git a/changelog/willianpaixao_swagger.md b/changelog/willianpaixao_swagger.md new file mode 100644 index 000000000000..54c62a830dc5 --- /dev/null +++ b/changelog/willianpaixao_swagger.md @@ -0,0 +1,3 @@ +### Added + +- Added Swagger 2.0 documentation for all Prysm API endpoints, including machine-readable OpenAPI specifications (swagger.yaml, swagger.json) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..c78bff794bdb --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Prysm Custom API Documentation + +This directory contains Swagger 2.0 documentation for Prysm's custom beacon node API endpoints. + +## Files + +- `swagger.json` - OpenAPI 2.0 specification in JSON format +- `swagger.yaml` - OpenAPI 2.0 specification in YAML format + +## Viewing the Documentation + +You can view the API documentation using any Swagger UI viewer: + +1. **Online Swagger Editor**: Upload `swagger.json` to [editor.swagger.io](https://editor.swagger.io/) +2. **Swagger UI Docker**: + ```bash + docker run -p 8080:8080 -e SWAGGER_JSON=/docs/swagger.json -v $(pwd)/docs:/docs swaggerapi/swagger-ui + ``` +3. **VS Code Extension**: Use the "OpenAPI (Swagger) Editor" extension + +## Regenerating the Documentation + +The swagger files are generated from Go annotations in the source code using the [swag](https://github.com/swaggo/swag) CLI tool. + +### Prerequisites + +Install swag CLI: + +```bash +go install github.com/swaggo/swag/cmd/swag@latest +``` + +### Generate Swagger Files + +From the repository root: + +```bash +swag init -g beacon-chain/rpc/prysm/doc.go -o docs/ --parseDependency --parseInternal +``` diff --git a/docs/swagger.json b/docs/swagger.json new file mode 100644 index 000000000000..56fb97079f1f --- /dev/null +++ b/docs/swagger.json @@ -0,0 +1,1161 @@ +{ + "schemes": [ + "http", + "https" + ], + "swagger": "2.0", + "info": { + "description": "Custom Prysm endpoints for beacon node operations, validator metrics, and extended functionality.\nThese endpoints extend the standard Ethereum Beacon Node API with Prysm-specific features.", + "title": "Prysm Beacon Node Custom API", + "contact": { + "name": "Prysm Team", + "url": "https://github.com/OffchainLabs/prysm" + }, + "license": { + "name": "GPL-3.0", + "url": "https://github.com/OffchainLabs/prysm/blob/develop/LICENSE.md" + }, + "version": "1.0" + }, + "host": "localhost:3500", + "basePath": "/", + "paths": { + "/eth/v1/beacon/states/{state_id}/validator_count": { + "get": { + "description": "Returns the total number of validators grouped by their status (active, pending, exited, withdrawal, etc.) for a given state", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Get validator count by status", + "parameters": [ + { + "type": "string", + "description": "State identifier (head, genesis, finalized, justified, slot number, or hex root)", + "name": "state_id", + "in": "path", + "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Validator status filter (can be repeated). If omitted, returns counts for all statuses. Valid values: pending_initialized, pending_queued, active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal", + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetValidatorCountResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/node/trusted_peers": { + "get": { + "description": "Returns a list of all trusted peers configured on this beacon node, including their connection state, direction, ENR, and last seen address", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Node" + ], + "summary": "List trusted peers", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.PeersResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + }, + "post": { + "description": "Adds a peer to the beacon node's trusted peer set using its multiaddress. Trusted peers are given priority in peer connections.", + "consumes": [ + "application/json" + ], + "tags": [ + "Prysm Node" + ], + "summary": "Add a trusted peer", + "parameters": [ + { + "description": "Peer multiaddress (e.g., /ip4/127.0.0.1/tcp/13000/p2p/16Uiu2...)", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.AddrRequest" + } + } + ], + "responses": { + "200": { + "description": "Peer successfully added to trusted set" + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/node/trusted_peers/{peer_id}": { + "delete": { + "description": "Removes a peer from the beacon node's trusted peer set by peer ID. Does not disconnect the peer if already connected.", + "tags": [ + "Prysm Node" + ], + "summary": "Remove a trusted peer", + "parameters": [ + { + "type": "string", + "description": "Peer ID to remove from trusted set", + "name": "peer_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "Peer successfully removed from trusted set" + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/blobs": { + "post": { + "description": "Publishes blob sidecars to the beacon network. Only supported for Deneb through Fulu epochs.", + "consumes": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Publish blob sidecars (DEPRECATED post-Fulu)", + "deprecated": true, + "parameters": [ + { + "description": "Blob sidecars to publish", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.PublishBlobsRequest" + } + } + ], + "responses": { + "200": { + "description": "Blobs successfully published" + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "503": { + "description": "Beacon node is currently syncing", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/blocks/{block_id}/query": { + "post": { + "description": "Executes an SSZ query on a beacon block and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from block objects.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/octet-stream" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Query beacon block with SSZ path", + "parameters": [ + { + "type": "string", + "description": "Block identifier (head, genesis, finalized, slot number, or hex root)", + "name": "block_id", + "in": "path", + "required": true + }, + { + "description": "SSZ query path (e.g., 'body.attestations[0]')", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.SSZQueryRequest" + } + } + ], + "responses": { + "200": { + "description": "SSZ-encoded SSZQueryResponse containing root and result", + "schema": { + "type": "string" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/chain_head": { + "get": { + "description": "Returns detailed information about the current head, finalized, and justified checkpoints of the beacon chain", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Get chain head information", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.ChainHead" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/individual_votes": { + "post": { + "description": "Returns detailed voting information for specified validators in a given epoch", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Get individual validator votes", + "parameters": [ + { + "description": "Validator indices/public keys and epoch", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.GetIndividualVotesRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetIndividualVotesResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/states/{state_id}/query": { + "post": { + "description": "Executes an SSZ query on a beacon state and returns the result as SSZ-encoded bytes. Allows efficient extraction of specific fields from large state objects.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/octet-stream" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Query beacon state with SSZ path", + "parameters": [ + { + "type": "string", + "description": "State identifier (head, genesis, finalized, justified, slot number, or hex root)", + "name": "state_id", + "in": "path", + "required": true + }, + { + "description": "SSZ query path (e.g., 'validators[0].pubkey')", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.SSZQueryRequest" + } + } + ], + "responses": { + "200": { + "description": "SSZ-encoded SSZQueryResponse containing root and result", + "schema": { + "type": "string" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/states/{state_id}/validator_count": { + "get": { + "description": "Returns the total number of validators grouped by their status (active, pending, exited, withdrawal, etc.) for a given state", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Get validator count by status", + "parameters": [ + { + "type": "string", + "description": "State identifier (head, genesis, finalized, justified, slot number, or hex root)", + "name": "state_id", + "in": "path", + "required": true + }, + { + "type": "array", + "items": { + "type": "string" + }, + "collectionFormat": "csv", + "description": "Validator status filter (can be repeated). If omitted, returns counts for all statuses. Valid values: pending_initialized, pending_queued, active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal", + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetValidatorCountResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/beacon/weak_subjectivity": { + "get": { + "description": "Computes the weak subjectivity checkpoint for safe checkpoint sync initialization", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Beacon" + ], + "summary": "Get weak subjectivity checkpoint", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetWeakSubjectivityResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "503": { + "description": "Beacon node is currently syncing", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/validators/{state_id}/active_set_changes": { + "get": { + "description": "Returns validator set changes for a given epoch including activations, voluntary exits, slashings, and ejections with both public keys and indices", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Validator" + ], + "summary": "Get active validator set changes", + "parameters": [ + { + "type": "string", + "description": "State identifier (head, genesis, finalized, justified, slot number, or hex root)", + "name": "state_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.ActiveSetChanges" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/v1/validators/{state_id}/participation": { + "get": { + "description": "Returns participation rate information for validators at a given state, including voting statistics and balance information for current and previous epochs", + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Validator" + ], + "summary": "Get validator participation for an epoch", + "parameters": [ + { + "type": "string", + "description": "State identifier (head, genesis, finalized, justified, slot number, or hex root)", + "name": "state_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetValidatorParticipationResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + }, + "/prysm/validators/performance": { + "post": { + "description": "Returns detailed performance metrics for specified validators including voting accuracy, balances before and after epoch transitions, and inactivity scores", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "Prysm Validator" + ], + "summary": "Get validator performance metrics", + "parameters": [ + { + "description": "Validator public keys and/or indices to query", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/structs.GetValidatorPerformanceRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/structs.GetValidatorPerformanceResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httputil.DefaultJsonError" + } + } + } + } + } + }, + "definitions": { + "httputil.DefaultJsonError": { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "message": { + "type": "string" + } + } + }, + "structs.ActiveSetChanges": { + "type": "object", + "properties": { + "activated_indices": { + "type": "array", + "items": { + "type": "string" + } + }, + "activated_public_keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "ejected_indices": { + "type": "array", + "items": { + "type": "string" + } + }, + "ejected_public_keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "epoch": { + "type": "string" + }, + "exited_indices": { + "type": "array", + "items": { + "type": "string" + } + }, + "exited_public_keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "slashed_indices": { + "type": "array", + "items": { + "type": "string" + } + }, + "slashed_public_keys": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "structs.AddrRequest": { + "type": "object", + "properties": { + "addr": { + "type": "string" + } + } + }, + "structs.BeaconBlockHeader": { + "type": "object", + "properties": { + "body_root": { + "type": "string" + }, + "parent_root": { + "type": "string" + }, + "proposer_index": { + "type": "string" + }, + "slot": { + "type": "string" + }, + "state_root": { + "type": "string" + } + } + }, + "structs.BlobSidecars": { + "type": "object", + "properties": { + "sidecars": { + "type": "array", + "items": { + "$ref": "#/definitions/structs.Sidecar" + } + } + } + }, + "structs.ChainHead": { + "type": "object", + "properties": { + "finalized_block_root": { + "type": "string" + }, + "finalized_epoch": { + "type": "string" + }, + "finalized_slot": { + "type": "string" + }, + "head_block_root": { + "type": "string" + }, + "head_epoch": { + "type": "string" + }, + "head_slot": { + "type": "string" + }, + "justified_block_root": { + "type": "string" + }, + "justified_epoch": { + "type": "string" + }, + "justified_slot": { + "type": "string" + }, + "optimistic_status": { + "type": "boolean" + }, + "previous_justified_block_root": { + "type": "string" + }, + "previous_justified_epoch": { + "type": "string" + }, + "previous_justified_slot": { + "type": "string" + } + } + }, + "structs.Checkpoint": { + "type": "object", + "properties": { + "epoch": { + "type": "string" + }, + "root": { + "type": "string" + } + } + }, + "structs.GetIndividualVotesRequest": { + "type": "object", + "properties": { + "epoch": { + "type": "string" + }, + "indices": { + "type": "array", + "items": { + "type": "string" + } + }, + "public_keys": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "structs.GetIndividualVotesResponse": { + "type": "object", + "properties": { + "individual_votes": { + "type": "array", + "items": { + "$ref": "#/definitions/structs.IndividualVote" + } + } + } + }, + "structs.GetValidatorCountResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/structs.ValidatorCount" + } + }, + "execution_optimistic": { + "type": "string" + }, + "finalized": { + "type": "string" + } + } + }, + "structs.GetValidatorParticipationResponse": { + "type": "object", + "properties": { + "epoch": { + "type": "string" + }, + "finalized": { + "type": "boolean" + }, + "participation": { + "$ref": "#/definitions/structs.ValidatorParticipation" + } + } + }, + "structs.GetValidatorPerformanceRequest": { + "type": "object", + "properties": { + "indices": { + "type": "array", + "items": { + "type": "integer" + } + }, + "public_keys": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "integer", + "format": "int32" + } + } + } + } + }, + "structs.GetValidatorPerformanceResponse": { + "type": "object", + "properties": { + "balances_after_epoch_transition": { + "type": "array", + "items": { + "type": "integer" + } + }, + "balances_before_epoch_transition": { + "type": "array", + "items": { + "type": "integer" + } + }, + "correctly_voted_head": { + "type": "array", + "items": { + "type": "boolean" + } + }, + "correctly_voted_source": { + "type": "array", + "items": { + "type": "boolean" + } + }, + "correctly_voted_target": { + "type": "array", + "items": { + "type": "boolean" + } + }, + "current_effective_balances": { + "type": "array", + "items": { + "type": "integer" + } + }, + "inactivity_scores": { + "type": "array", + "items": { + "type": "integer" + } + }, + "missing_validators": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "integer", + "format": "int32" + } + } + }, + "public_keys": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "integer", + "format": "int32" + } + } + } + } + }, + "structs.GetWeakSubjectivityResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/structs.WeakSubjectivityData" + } + } + }, + "structs.IndividualVote": { + "type": "object", + "properties": { + "current_epoch_effective_balance_gwei": { + "type": "string" + }, + "epoch": { + "type": "string" + }, + "inactivity_score": { + "type": "string" + }, + "inclusion_distance": { + "type": "string" + }, + "inclusion_slot": { + "type": "string" + }, + "is_active_in_current_epoch": { + "type": "boolean" + }, + "is_active_in_previous_epoch": { + "type": "boolean" + }, + "is_current_epoch_attester": { + "type": "boolean" + }, + "is_current_epoch_target_attester": { + "type": "boolean" + }, + "is_previous_epoch_attester": { + "type": "boolean" + }, + "is_previous_epoch_head_attester": { + "type": "boolean" + }, + "is_previous_epoch_target_attester": { + "type": "boolean" + }, + "is_slashed": { + "type": "boolean" + }, + "is_withdrawable_in_current_epoch": { + "type": "boolean" + }, + "public_keys": { + "type": "string" + }, + "validator_index": { + "type": "string" + } + } + }, + "structs.Peer": { + "type": "object", + "properties": { + "direction": { + "type": "string" + }, + "enr": { + "type": "string" + }, + "last_seen_p2p_address": { + "type": "string" + }, + "peer_id": { + "type": "string" + }, + "state": { + "type": "string" + } + } + }, + "structs.PeersResponse": { + "type": "object", + "properties": { + "peers": { + "type": "array", + "items": { + "$ref": "#/definitions/structs.Peer" + } + } + } + }, + "structs.PublishBlobsRequest": { + "type": "object", + "properties": { + "blob_sidecars": { + "$ref": "#/definitions/structs.BlobSidecars" + }, + "block_root": { + "type": "string" + } + } + }, + "structs.SSZQueryRequest": { + "type": "object", + "properties": { + "include_proof": { + "type": "boolean" + }, + "query": { + "type": "string" + } + } + }, + "structs.Sidecar": { + "type": "object", + "properties": { + "blob": { + "type": "string" + }, + "index": { + "type": "string" + }, + "kzg_commitment": { + "type": "string" + }, + "kzg_commitment_inclusion_proof": { + "type": "array", + "items": { + "type": "string" + } + }, + "kzg_proof": { + "type": "string" + }, + "signed_block_header": { + "$ref": "#/definitions/structs.SignedBeaconBlockHeader" + } + } + }, + "structs.SignedBeaconBlockHeader": { + "type": "object", + "properties": { + "message": { + "$ref": "#/definitions/structs.BeaconBlockHeader" + }, + "signature": { + "type": "string" + } + } + }, + "structs.ValidatorCount": { + "type": "object", + "properties": { + "count": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "structs.ValidatorParticipation": { + "type": "object", + "properties": { + "current_epoch_active_gwei": { + "type": "string" + }, + "current_epoch_attesting_gwei": { + "type": "string" + }, + "current_epoch_target_attesting_gwei": { + "type": "string" + }, + "eligible_ether": { + "type": "string" + }, + "global_participation_rate": { + "type": "string" + }, + "previous_epoch_active_gwei": { + "type": "string" + }, + "previous_epoch_attesting_gwei": { + "type": "string" + }, + "previous_epoch_head_attesting_gwei": { + "type": "string" + }, + "previous_epoch_target_attesting_gwei": { + "type": "string" + }, + "voted_ether": { + "type": "string" + } + } + }, + "structs.WeakSubjectivityData": { + "type": "object", + "properties": { + "state_root": { + "type": "string" + }, + "ws_checkpoint": { + "$ref": "#/definitions/structs.Checkpoint" + } + } + } + } +} \ No newline at end of file diff --git a/docs/swagger.yaml b/docs/swagger.yaml new file mode 100644 index 000000000000..806624603a10 --- /dev/null +++ b/docs/swagger.yaml @@ -0,0 +1,795 @@ +basePath: / +definitions: + httputil.DefaultJsonError: + properties: + code: + type: integer + message: + type: string + type: object + structs.ActiveSetChanges: + properties: + activated_indices: + items: + type: string + type: array + activated_public_keys: + items: + type: string + type: array + ejected_indices: + items: + type: string + type: array + ejected_public_keys: + items: + type: string + type: array + epoch: + type: string + exited_indices: + items: + type: string + type: array + exited_public_keys: + items: + type: string + type: array + slashed_indices: + items: + type: string + type: array + slashed_public_keys: + items: + type: string + type: array + type: object + structs.AddrRequest: + properties: + addr: + type: string + type: object + structs.BeaconBlockHeader: + properties: + body_root: + type: string + parent_root: + type: string + proposer_index: + type: string + slot: + type: string + state_root: + type: string + type: object + structs.BlobSidecars: + properties: + sidecars: + items: + $ref: '#/definitions/structs.Sidecar' + type: array + type: object + structs.ChainHead: + properties: + finalized_block_root: + type: string + finalized_epoch: + type: string + finalized_slot: + type: string + head_block_root: + type: string + head_epoch: + type: string + head_slot: + type: string + justified_block_root: + type: string + justified_epoch: + type: string + justified_slot: + type: string + optimistic_status: + type: boolean + previous_justified_block_root: + type: string + previous_justified_epoch: + type: string + previous_justified_slot: + type: string + type: object + structs.Checkpoint: + properties: + epoch: + type: string + root: + type: string + type: object + structs.GetIndividualVotesRequest: + properties: + epoch: + type: string + indices: + items: + type: string + type: array + public_keys: + items: + type: string + type: array + type: object + structs.GetIndividualVotesResponse: + properties: + individual_votes: + items: + $ref: '#/definitions/structs.IndividualVote' + type: array + type: object + structs.GetValidatorCountResponse: + properties: + data: + items: + $ref: '#/definitions/structs.ValidatorCount' + type: array + execution_optimistic: + type: string + finalized: + type: string + type: object + structs.GetValidatorParticipationResponse: + properties: + epoch: + type: string + finalized: + type: boolean + participation: + $ref: '#/definitions/structs.ValidatorParticipation' + type: object + structs.GetValidatorPerformanceRequest: + properties: + indices: + items: + type: integer + type: array + public_keys: + items: + items: + format: int32 + type: integer + type: array + type: array + type: object + structs.GetValidatorPerformanceResponse: + properties: + balances_after_epoch_transition: + items: + type: integer + type: array + balances_before_epoch_transition: + items: + type: integer + type: array + correctly_voted_head: + items: + type: boolean + type: array + correctly_voted_source: + items: + type: boolean + type: array + correctly_voted_target: + items: + type: boolean + type: array + current_effective_balances: + items: + type: integer + type: array + inactivity_scores: + items: + type: integer + type: array + missing_validators: + items: + items: + format: int32 + type: integer + type: array + type: array + public_keys: + items: + items: + format: int32 + type: integer + type: array + type: array + type: object + structs.GetWeakSubjectivityResponse: + properties: + data: + $ref: '#/definitions/structs.WeakSubjectivityData' + type: object + structs.IndividualVote: + properties: + current_epoch_effective_balance_gwei: + type: string + epoch: + type: string + inactivity_score: + type: string + inclusion_distance: + type: string + inclusion_slot: + type: string + is_active_in_current_epoch: + type: boolean + is_active_in_previous_epoch: + type: boolean + is_current_epoch_attester: + type: boolean + is_current_epoch_target_attester: + type: boolean + is_previous_epoch_attester: + type: boolean + is_previous_epoch_head_attester: + type: boolean + is_previous_epoch_target_attester: + type: boolean + is_slashed: + type: boolean + is_withdrawable_in_current_epoch: + type: boolean + public_keys: + type: string + validator_index: + type: string + type: object + structs.Peer: + properties: + direction: + type: string + enr: + type: string + last_seen_p2p_address: + type: string + peer_id: + type: string + state: + type: string + type: object + structs.PeersResponse: + properties: + peers: + items: + $ref: '#/definitions/structs.Peer' + type: array + type: object + structs.PublishBlobsRequest: + properties: + blob_sidecars: + $ref: '#/definitions/structs.BlobSidecars' + block_root: + type: string + type: object + structs.SSZQueryRequest: + properties: + include_proof: + type: boolean + query: + type: string + type: object + structs.Sidecar: + properties: + blob: + type: string + index: + type: string + kzg_commitment: + type: string + kzg_commitment_inclusion_proof: + items: + type: string + type: array + kzg_proof: + type: string + signed_block_header: + $ref: '#/definitions/structs.SignedBeaconBlockHeader' + type: object + structs.SignedBeaconBlockHeader: + properties: + message: + $ref: '#/definitions/structs.BeaconBlockHeader' + signature: + type: string + type: object + structs.ValidatorCount: + properties: + count: + type: string + status: + type: string + type: object + structs.ValidatorParticipation: + properties: + current_epoch_active_gwei: + type: string + current_epoch_attesting_gwei: + type: string + current_epoch_target_attesting_gwei: + type: string + eligible_ether: + type: string + global_participation_rate: + type: string + previous_epoch_active_gwei: + type: string + previous_epoch_attesting_gwei: + type: string + previous_epoch_head_attesting_gwei: + type: string + previous_epoch_target_attesting_gwei: + type: string + voted_ether: + type: string + type: object + structs.WeakSubjectivityData: + properties: + state_root: + type: string + ws_checkpoint: + $ref: '#/definitions/structs.Checkpoint' + type: object +host: localhost:3500 +info: + contact: + name: Prysm Team + url: https://github.com/OffchainLabs/prysm + description: |- + Custom Prysm endpoints for beacon node operations, validator metrics, and extended functionality. + These endpoints extend the standard Ethereum Beacon Node API with Prysm-specific features. + license: + name: GPL-3.0 + url: https://github.com/OffchainLabs/prysm/blob/develop/LICENSE.md + title: Prysm Beacon Node Custom API + version: "1.0" +paths: + /eth/v1/beacon/states/{state_id}/validator_count: + get: + description: Returns the total number of validators grouped by their status + (active, pending, exited, withdrawal, etc.) for a given state + parameters: + - description: State identifier (head, genesis, finalized, justified, slot number, + or hex root) + in: path + name: state_id + required: true + type: string + - collectionFormat: csv + description: 'Validator status filter (can be repeated). If omitted, returns + counts for all statuses. Valid values: pending_initialized, pending_queued, + active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, + withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal' + in: query + items: + type: string + name: status + type: array + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetValidatorCountResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get validator count by status + tags: + - Prysm Beacon + /prysm/node/trusted_peers: + get: + description: Returns a list of all trusted peers configured on this beacon node, + including their connection state, direction, ENR, and last seen address + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.PeersResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: List trusted peers + tags: + - Prysm Node + post: + consumes: + - application/json + description: Adds a peer to the beacon node's trusted peer set using its multiaddress. + Trusted peers are given priority in peer connections. + parameters: + - description: Peer multiaddress (e.g., /ip4/127.0.0.1/tcp/13000/p2p/16Uiu2...) + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.AddrRequest' + responses: + "200": + description: Peer successfully added to trusted set + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Add a trusted peer + tags: + - Prysm Node + /prysm/node/trusted_peers/{peer_id}: + delete: + description: Removes a peer from the beacon node's trusted peer set by peer + ID. Does not disconnect the peer if already connected. + parameters: + - description: Peer ID to remove from trusted set + in: path + name: peer_id + required: true + type: string + responses: + "200": + description: Peer successfully removed from trusted set + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Remove a trusted peer + tags: + - Prysm Node + /prysm/v1/beacon/blobs: + post: + consumes: + - application/json + deprecated: true + description: Publishes blob sidecars to the beacon network. Only supported for + Deneb through Fulu epochs. + parameters: + - description: Blob sidecars to publish + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.PublishBlobsRequest' + responses: + "200": + description: Blobs successfully published + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "503": + description: Beacon node is currently syncing + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Publish blob sidecars (DEPRECATED post-Fulu) + tags: + - Prysm Beacon + /prysm/v1/beacon/blocks/{block_id}/query: + post: + consumes: + - application/json + description: Executes an SSZ query on a beacon block and returns the result + as SSZ-encoded bytes. Allows efficient extraction of specific fields from + block objects. + parameters: + - description: Block identifier (head, genesis, finalized, slot number, or hex + root) + in: path + name: block_id + required: true + type: string + - description: SSZ query path (e.g., 'body.attestations[0]') + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.SSZQueryRequest' + produces: + - application/octet-stream + responses: + "200": + description: SSZ-encoded SSZQueryResponse containing root and result + schema: + type: string + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Query beacon block with SSZ path + tags: + - Prysm Beacon + /prysm/v1/beacon/chain_head: + get: + description: Returns detailed information about the current head, finalized, + and justified checkpoints of the beacon chain + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.ChainHead' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get chain head information + tags: + - Prysm Beacon + /prysm/v1/beacon/individual_votes: + post: + consumes: + - application/json + description: Returns detailed voting information for specified validators in + a given epoch + parameters: + - description: Validator indices/public keys and epoch + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.GetIndividualVotesRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetIndividualVotesResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get individual validator votes + tags: + - Prysm Beacon + /prysm/v1/beacon/states/{state_id}/query: + post: + consumes: + - application/json + description: Executes an SSZ query on a beacon state and returns the result + as SSZ-encoded bytes. Allows efficient extraction of specific fields from + large state objects. + parameters: + - description: State identifier (head, genesis, finalized, justified, slot number, + or hex root) + in: path + name: state_id + required: true + type: string + - description: SSZ query path (e.g., 'validators[0].pubkey') + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.SSZQueryRequest' + produces: + - application/octet-stream + responses: + "200": + description: SSZ-encoded SSZQueryResponse containing root and result + schema: + type: string + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Query beacon state with SSZ path + tags: + - Prysm Beacon + /prysm/v1/beacon/states/{state_id}/validator_count: + get: + description: Returns the total number of validators grouped by their status + (active, pending, exited, withdrawal, etc.) for a given state + parameters: + - description: State identifier (head, genesis, finalized, justified, slot number, + or hex root) + in: path + name: state_id + required: true + type: string + - collectionFormat: csv + description: 'Validator status filter (can be repeated). If omitted, returns + counts for all statuses. Valid values: pending_initialized, pending_queued, + active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, + withdrawal_possible, withdrawal_done, active, pending, exited, withdrawal' + in: query + items: + type: string + name: status + type: array + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetValidatorCountResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get validator count by status + tags: + - Prysm Beacon + /prysm/v1/beacon/weak_subjectivity: + get: + description: Computes the weak subjectivity checkpoint for safe checkpoint sync + initialization + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetWeakSubjectivityResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "503": + description: Beacon node is currently syncing + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get weak subjectivity checkpoint + tags: + - Prysm Beacon + /prysm/v1/validators/{state_id}/active_set_changes: + get: + description: Returns validator set changes for a given epoch including activations, + voluntary exits, slashings, and ejections with both public keys and indices + parameters: + - description: State identifier (head, genesis, finalized, justified, slot number, + or hex root) + in: path + name: state_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.ActiveSetChanges' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get active validator set changes + tags: + - Prysm Validator + /prysm/v1/validators/{state_id}/participation: + get: + description: Returns participation rate information for validators at a given + state, including voting statistics and balance information for current and + previous epochs + parameters: + - description: State identifier (head, genesis, finalized, justified, slot number, + or hex root) + in: path + name: state_id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetValidatorParticipationResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "404": + description: Not Found + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get validator participation for an epoch + tags: + - Prysm Validator + /prysm/validators/performance: + post: + consumes: + - application/json + description: Returns detailed performance metrics for specified validators including + voting accuracy, balances before and after epoch transitions, and inactivity + scores + parameters: + - description: Validator public keys and/or indices to query + in: body + name: request + required: true + schema: + $ref: '#/definitions/structs.GetValidatorPerformanceRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/structs.GetValidatorPerformanceResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httputil.DefaultJsonError' + summary: Get validator performance metrics + tags: + - Prysm Validator +schemes: +- http +- https +swagger: "2.0"