Skip to content

feat(api): add ton-validators-rewards-api #1978

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
delovoyhomie wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(api): add ton-validators-rewards-api #1978

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
ee6ccc4
feat(ton-validators-rewards-api): add ton-validators-rewards-api
delovoyhomie Mar 19, 2026
b494399
refactor(ton-validators-rewards-api): refine validator rewards API do…
delovoyhomie Mar 23, 2026
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
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,4 @@ node_modules/
__pycache__

# Generated folders
/stats/
/stats/
8 changes: 8 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,14 @@
}
]
},
{
"group": "Validator rewards API",
"pages": [
"ecosystem/api/validator-rewards/overview",
"ecosystem/api/validator-rewards/run-locally",
"ecosystem/api/validator-rewards/api-reference"
]
},
"ecosystem/api/price"
]
},
Expand Down
195 changes: 195 additions & 0 deletions ecosystem/api/validator-rewards/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
---
title: "Validator rewards API reference"
sidebarTitle: "API reference"
mode: "wide"
---

import { Aside } from "/snippets/aside.jsx";

Self-hosted HTTP endpoints for validator stake, validation round metadata, and
finished round reward distribution.

<Aside type="note">
Replace `<BASE_URL>` with the address of a running deployment, for example
`http://localhost:8080`.
</Aside>

## Formats and conventions

- All balance, stake, and reward fields are decimal strings in nanoTON.
`1 TON = 1,000,000,000 nanoTON`.
- `seqno` and `block` values are masterchain block sequence numbers.
- `election_id` is the validation round `electAt` timestamp.
- `election_id` and `block` are mutually exclusive on endpoints that accept
both parameters.
- Error responses use HTTP `400` for invalid query parameters and HTTP `500`
for service-side failures.

Define placeholders:

- `<BASE_URL>`: base URL of the running service.
- `<SEQNO>`: masterchain block sequence number.
- `<BLOCK>`: masterchain block sequence number inside the target round.
- `<ELECTION_ID>`: election ID of the target round.

## Service routes

| Endpoint | Response | Description |
| ----------------------- | -------- | ----------------------------------------- |
| `GET /health` | JSON | Return `{"status":"ok"}`. |
| `GET /swagger` | HTML | Return the local Swagger UI. |
| `GET /api/openapi.yaml` | YAML | Return the embedded OpenAPI 3.0 document. |

## Common objects

### Validator entry

`validators` in `GET /api/validators` and `GET /api/round-rewards` use the same
object shape.

| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rank` | Position in the validator list, sorted by `effective_stake` in descending order. |
| `pubkey` | Validator public key encoded as lowercase hex. |
| `effective_stake` | Effective stake locked in the elector contract. |
| `weight` | Share of total effective stake in the selected response, from `0` to `1`. |
| `reward` | Reward amount. In `GET /api/validators`, this is the per-block estimate for the target block. In `GET /api/round-rewards`, this is the total reward for the selected finished round. |
| `pool` | Pool smart contract address in bounceable base64url form, when available. |
| `pool_type` | Detected pool type: `nominator-pool-v1.0`, `single-nominator-pool-v1.0`, `single-nominator-pool-v1.1`, or `other`. |
| `validator_address` | Validator wallet or control address, when available. |
| `owner_address` | Owner address for a single nominator pool, when available. |
| `validator_stake` | Validator's own deposited funds. Present for `nominator-pool-v1.0`. |
| `nominators_stake` | Sum of nominator deposits. Present for `nominator-pool-v1.0`. |
| `total_stake` | Total pool funds computed as `effective_stake + credit`, where `credit` is the returned stake still held in the elector contract. |
| `validator_reward_share` | Fraction of rewards kept by the validator, for example `0.3` for `30%`. Present for `nominator-pool-v1.0`. |
| `nominators_count` | Number of nominators. Present for `nominator-pool-v1.0`. |
| `nominators` | Array of nominator entries. Present for `nominator-pool-v1.0`. |

### Nominator entry

| Field | Description |
| ----------------- | --------------------------------------------------------------- |
| `address` | Nominator wallet address in bounceable base64url form. |
| `weight` | Share of total nominator deposits in the pool, from `0` to `1`. |
| `reward` | Reward amount assigned to the nominator. |
| `effective_stake` | Nominator share of the validator's effective stake. |
| `stake` | Raw nominator deposit in the pool contract. |

## `GET /api/validators`

Return the active validator set for a target masterchain block. If `seqno` is
not provided, the service uses the latest masterchain block.

```bash
curl "<BASE_URL>/api/validators?seqno=<SEQNO>"
```

Query parameters:

| Parameter | Type | Description |
| --------- | -------- | --------------------------------------------------- |
| `seqno` | `uint32` | Target masterchain block sequence number. Optional. |

Response fields:

| Field | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_time_ms` | Server-side response time in milliseconds. |
| `block.seqno` | Resolved masterchain block sequence number. |
| `block.time` | Target block time in UTC, RFC 3339 format. |
| `validation_round.start` | Validation round start time for the target block. |
| `validation_round.end` | Validation round end time for the target block. |
| `validation_round.start_block` | First masterchain block of the round, when resolved. |
| `validation_round.end_block` | Last masterchain block of the round, when the round has already finished. |
| `election_id` | Election ID of the round active at the target block. |
| `prev_election_id` | Election ID of the previous round, when resolved. |
| `next_election_id` | Election ID of the next round, when the selected round has already finished. |
| `elector_balance` | Elector contract balance at the target block. |
| `total_stake` | Sum of effective stakes across the active validator set. |
| `reward_per_block` | Estimated total reward for the target block, computed as the change in the elector `bonuses` value between the target block and the previous block. |
| `validators` | Array of validator entries. |

## `GET /api/validation-rounds`

Return metadata for the round selected by `election_id`, `block`, or the latest
masterchain block.

```bash
curl "<BASE_URL>/api/validation-rounds?block=<BLOCK>"
```

<Aside type="note">
The current implementation returns one selected round inside the `rounds`
array, even though the route name is plural.
</Aside>

Query parameters:

| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `election_id` | `int64` | Return the round that matches this election ID. Optional. Mutually exclusive with `block`. |
| `block` | `uint32` | Return the round that contains this masterchain block. Optional. Mutually exclusive with `election_id`. |

Response fields:

| Field | Description |
| ------------------ | ----------------------------------------------------------------- |
| `response_time_ms` | Server-side response time in milliseconds. |
| `rounds` | Array of validation round entries. |
| `error` | Optional top-level error string when round traversal stops early. |

Validation round entry fields:

| Field | Description |
| ------------------ | -------------------------------------------------------------------- |
| `election_id` | Election ID of the selected round. |
| `start` | Validation round start time in UTC, RFC 3339 format. |
| `end` | Validation round end time in UTC, RFC 3339 format. |
| `start_block` | First masterchain block of the round. |
| `end_block` | Last masterchain block of the round, when the round has finished. |
| `finished` | `true` when the round has finished. |
| `prev_election_id` | Election ID of the previous round, when resolved. |
| `next_election_id` | Election ID of the next round, when the selected round has finished. |
| `error` | Optional per-round error string. |

## `GET /api/round-rewards`

Return per-validator and per-nominator reward distribution for a finished
validation round.

```bash
curl "<BASE_URL>/api/round-rewards?election_id=<ELECTION_ID>"
```

Exactly one of `election_id` or `block` is required.

Query parameters:

| Parameter | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `election_id` | `int64` | Election ID of a finished round. Optional. Mutually exclusive with `block`. |
| `block` | `uint32` | Masterchain block sequence number inside a finished round. Optional. Mutually exclusive with `election_id`. |

Response fields:

| Field | Description |
| ------------------ | ------------------------------------------------------- |
| `response_time_ms` | Server-side response time in milliseconds. |
| `election_id` | Election ID of the selected finished round. |
| `prev_election_id` | Election ID of the previous round, when resolved. |
| `next_election_id` | Election ID of the next round. |
| `round_start` | Validation round start time in UTC, RFC 3339 format. |
| `round_end` | Validation round end time in UTC, RFC 3339 format. |
| `start_block` | First masterchain block of the round. |
| `end_block` | Last masterchain block of the round. |
| `total_bonuses` | Total bonuses paid by the elector for the round. |
| `total_stake` | Total stake recorded for the round in `past_elections`. |
| `validators` | Array of validator entries. |

If the selected round has not finished yet, the service returns HTTP `500` with
an error message in the response body.

## See also

- [Nominator pool contracts](/ecosystem/staking/nominator-pools)
- [Single nominator pool contracts](/ecosystem/staking/single-nominator)
69 changes: 69 additions & 0 deletions ecosystem/api/validator-rewards/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: "Validator rewards API overview"
sidebarTitle: "Overview"
---

import { Aside } from "/snippets/aside.jsx";

Validator rewards API is a self-hosted HTTP API that reads validator
reward and staking data directly from TON liteservers through the
[tongo library](https://github.com/tonkeeper/tongo).

<Aside type="note">
The OpenAPI spec defines `localhost` as the server for local development. The
source does not list a public hosted deployment.
</Aside>

## What the API returns

- Current validator data for a target masterchain block, including effective
stake, per-block reward estimates, pool addresses, and optional nominator
breakdowns.
- Validation round metadata for the round selected by `election_id`, `block`,
or the latest masterchain block.
- Reward distribution for a finished validation round.
- Local service routes for Swagger UI and the embedded OpenAPI document.

## How the service resolves data

- It reads the active validator set from config param `34`.
- It reads the elector contract to resolve `past_elections`, total stake,
bonuses, and returned stake.
- It inspects pool contract code hashes to classify pools as
`nominator-pool-v1.0`, `single-nominator-pool-v1.0`,
`single-nominator-pool-v1.1`, or `other`.
- It creates one lite client connection per available liteserver and
distributes requests across those connections in round-robin order.
- When no custom config is provided, it downloads
the [TON Mainnet global config](https://ton.org/global-config.json), caches
it in memory for seven days, and refreshes the lite client after the cache
time to live (TTL) expires.

## When to use it

- Build validator dashboards that need current effective stake and pool
composition.
- Compute reward splits for a finished validation round.
- Inspect nominator pool balances and validator reward shares.
- Compare the elector's locked stake with pool balances and returned stake.

## Endpoints

| Endpoint | Purpose |
| ---------------------------- | ----------------------------------------------------------- |
| `GET /health` | Return service status. |
| `GET /api/validators` | Return current validators for a target masterchain block. |
| `GET /api/validation-rounds` | Return metadata for the selected validation round. |
| `GET /api/round-rewards` | Return reward distribution for a finished validation round. |
| `GET /api/openapi.yaml` | Return the embedded OpenAPI document. |
| `GET /swagger` | Open the local Swagger UI. |

## Next steps

- [How to run the validator rewards API locally](/ecosystem/api/validator-rewards/run-locally)
- [Validator rewards API reference](/ecosystem/api/validator-rewards/api-reference)

## See also

- [Nominator pool contracts](/ecosystem/staking/nominator-pools)
- [Single nominator pool contracts](/ecosystem/staking/single-nominator)
Loading
Loading