Skip to content

Update info endpoint with validator summaries #5

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

Draft
Ganthology wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Update info endpoint with validator summaries #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e47c1c
feat: Add validator summaries endpoint to API
cursoragent Sep 12, 2025
399cb2d
Add validatorSummaries endpoint to OpenAPI spec
cursoragent Sep 12, 2025
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
6 changes: 3 additions & 3 deletions index.html
View file
Open in desktop

Large diffs are not rendered by default.

154 changes: 153 additions & 1 deletion info/info.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1851,4 +1851,156 @@ paths:
totalAmount: "0.73117184"
- time: 1736726400073
source: "commission"
totalAmount: "130.76445876"
totalAmount: "130.76445876"

# validatorSummaries
/info:
post:
summary: Get validator summaries
description: Retrieve summaries of all validators including their details, stake information, and performance statistics
requestBody:
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum: [validatorSummaries]
required:
- type
example:
type: validatorSummaries
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: object
properties:
validator:
type: string
description: Validator address in 42-character hexadecimal format
signer:
type: string
description: Signer address in 42-character hexadecimal format
name:
type: string
description: Validator name
description:
type: string
description: Validator description
nRecentBlocks:
type: integer
description: Number of recent blocks produced
stake:
type: integer
description: Total stake amount in smallest unit
isJailed:
type: boolean
description: Whether the validator is currently jailed
unjailableAfter:
type: [integer, "null"]
description: Timestamp when the validator can be unjailed, null if not jailed
isActive:
type: boolean
description: Whether the validator is currently active
commission:
type: string
description: Commission rate as a decimal string (e.g., "0.04" for 4%)
stats:
type: array
description: Performance statistics for different time periods
items:
type: array
minItems: 2
maxItems: 2
items:
oneOf:
# First item: time period
- type: string
enum: ["day", "week", "month"]
# Second item: statistics object
- type: object
properties:
uptimeFraction:
type: string
description: Uptime as a decimal fraction (e.g., "1.0" for 100%)
predictedApr:
type: string
description: Predicted annual percentage rate as a decimal string
nSamples:
type: integer
description: Number of samples used for statistics
required:
- uptimeFraction
- predictedApr
- nSamples
required:
- validator
- signer
- name
- description
- nRecentBlocks
- stake
- isJailed
- unjailableAfter
- isActive
- commission
- stats
example:
- validator: "0x000000000056f99d36b6f2e0c51fd41496bbacb8"
signer: "0x0000000008b0b558419582041f85740344ae8fde"
name: "ValiDAO"
description: "The People's Validator. Zero seed oils. Yours truly. https://validao.xyz"
nRecentBlocks: 6
stake: 629361369497189
isJailed: false
unjailableAfter: null
isActive: true
commission: "0.04"
stats:
- ["day", {
"uptimeFraction": "1.0",
"predictedApr": "0.0216167826",
"nSamples": 1440
}]
- ["week", {
"uptimeFraction": "1.0",
"predictedApr": "0.0216167826",
"nSamples": 10080
}]
- ["month", {
"uptimeFraction": "1.0",
"predictedApr": "0.0216167826",
"nSamples": 43190
}]
- validator: "0x15458aed3c7a49b215fbfa863c6ff550c31e1a31"
signer: "0x21d50a1c2e70b2b4b25516c744da7f1de760b2ec"
name: "B-Harvest"
description: "Provides secure validation services for dPoS networks(https://bharvest.io)"
nRecentBlocks: 6
stake: 567706292364350
isJailed: false
unjailableAfter: null
isActive: true
commission: "0.05"
stats:
- ["day", {
"uptimeFraction": "1.0",
"predictedApr": "0.0213916078",
"nSamples": 1440
}]
- ["week", {
"uptimeFraction": "1.0",
"predictedApr": "0.0213916078",
"nSamples": 10080
}]
- ["month", {
"uptimeFraction": "0.9992127807",
"predictedApr": "0.0213747679",
"nSamples": 43190
}]
101 changes: 101 additions & 0 deletions openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ paths:
- `metaAndAssetCtxs`: Retrieve perps universe and per-asset contexts (funding, OI, prices).
- `clearinghouseState`: Retrieve a user's perps clearinghouse account state and summaries.
- `gossipRootIps`: Retrieve recently available seed peer IP addresses to bootstrap gossip.
- `validatorSummaries`: Retrieve comprehensive summaries of all validators including stake, commission, and performance statistics.
requestBody:
required: true
content:
Expand Down Expand Up @@ -75,6 +76,7 @@ paths:
- $ref: "#/components/schemas/PerpMetaAndAssetCtxsResponse"
- $ref: "#/components/schemas/PerpClearinghouseStateResponse"
- $ref: "#/components/schemas/GossipRootIpsResponse"
- $ref: "#/components/schemas/ValidatorSummariesResponse"
"400":
description: Bad request
"429":
Expand Down Expand Up @@ -192,6 +194,7 @@ components:
metaAndAssetCtxs,
clearinghouseState,
gossipRootIps,
validatorSummaries,
]
x-enumNames:
[
Expand All @@ -212,6 +215,7 @@ components:
PerpMetaAndAssetCtxs,
PerpClearinghouseState,
GossipRootIps,
ValidatorSummaries,
]
x-enumDescriptions:
[
Expand All @@ -232,6 +236,7 @@ components:
"Retrieve perps universe and asset contexts",
"Retrieve a user's perps clearinghouse state",
"Retrieve recent seed peer IPs for gossip",
"Retrieve summaries of all validators including their details, stake information, and performance statistics",
]
oneOf:
- const: allMids
Expand Down Expand Up @@ -285,6 +290,9 @@ components:
- const: gossipRootIps
title: Gossip Root IPs
description: Recently available seed peer IPs for gossip
- const: validatorSummaries
title: Validator Summaries
description: Retrieve summaries of all validators including their details, stake information, and performance statistics
required: [type]
oneOf:
- $ref: "#/components/schemas/AllMidsRequest"
Expand All @@ -304,6 +312,7 @@ components:
- $ref: "#/components/schemas/PerpMetaAndAssetCtxsRequest"
- $ref: "#/components/schemas/PerpClearinghouseStateRequest"
- $ref: "#/components/schemas/GossipRootIpsRequest"
- $ref: "#/components/schemas/ValidatorSummariesRequest"
discriminator:
propertyName: type
mapping:
Expand All @@ -324,6 +333,7 @@ components:
metaAndAssetCtxs: "#/components/schemas/PerpMetaAndAssetCtxsRequest"
clearinghouseState: "#/components/schemas/PerpClearinghouseStateRequest"
gossipRootIps: "#/components/schemas/GossipRootIpsRequest"
validatorSummaries: "#/components/schemas/ValidatorSummariesRequest"
# ---------- /exchange: Request & Action union ----------
ExchangeRequest:
type: object
Expand Down Expand Up @@ -1002,6 +1012,19 @@ components:
type: string
enum: [gossipRootIps]

ValidatorSummariesRequest:
type: object
title: Validator Summaries
description: |
Request summaries of all validators including their details, stake information,
and performance statistics via the unified /info endpoint.
required: [type]
properties:
type:
type: string
enum: [validatorSummaries]
description: Must be "validatorSummaries"

AllMidsRequest:
type: object
title: All Mids
Expand Down Expand Up @@ -1281,6 +1304,84 @@ components:
type: string
description: IP address (IPv4 or IPv6)

ValidatorSummariesResponse:
type: array
description: |
Array of validator summaries containing detailed information about each validator,
including their stake, commission, performance statistics, and operational status.
items:
type: object
properties:
validator:
type: string
description: Validator address in 42-character hexadecimal format
signer:
type: string
description: Signer address in 42-character hexadecimal format
name:
type: string
description: Validator name
description:
type: string
description: Validator description
nRecentBlocks:
type: integer
description: Number of recent blocks produced
stake:
type: integer
description: Total stake amount in smallest unit
isJailed:
type: boolean
description: Whether the validator is currently jailed
unjailableAfter:
type: [integer, "null"]
description: Timestamp when the validator can be unjailed, null if not jailed
isActive:
type: boolean
description: Whether the validator is currently active
commission:
type: string
description: Commission rate as a decimal string (e.g., "0.04" for 4%)
stats:
type: array
description: Performance statistics for different time periods
items:
type: array
minItems: 2
maxItems: 2
items:
oneOf:
- type: string
enum: ["day", "week", "month"]
description: Time period for the statistics
- type: object
properties:
uptimeFraction:
type: string
description: Uptime as a decimal fraction (e.g., "1.0" for 100%)
predictedApr:
type: string
description: Predicted annual percentage rate as a decimal string
nSamples:
type: integer
description: Number of samples used for statistics
required:
- uptimeFraction
- predictedApr
- nSamples
required:
- validator
- signer
- name
- description
- nRecentBlocks
- stake
- isJailed
- unjailableAfter
- isActive
- commission
- stats

AllMidsResponse:
type: object
additionalProperties:
Expand Down