From ee6ccc49f278a19d268f46eff530f74083411699 Mon Sep 17 00:00:00 2001 From: delovoyhomie Date: Thu, 19 Mar 2026 12:49:27 +0300 Subject: [PATCH 1/2] feat(ton-validators-rewards-api): add ton-validators-rewards-api --- docs.json | 8 + .../api/validator-rewards/api-reference.mdx | 194 ++++++++++++++++++ ecosystem/api/validator-rewards/overview.mdx | 64 ++++++ .../api/validator-rewards/run-locally.mdx | 121 +++++++++++ resources/dictionaries/custom.txt | 2 + ton-validators-rewards-api | 1 + 6 files changed, 390 insertions(+) create mode 100644 ecosystem/api/validator-rewards/api-reference.mdx create mode 100644 ecosystem/api/validator-rewards/overview.mdx create mode 100644 ecosystem/api/validator-rewards/run-locally.mdx create mode 160000 ton-validators-rewards-api diff --git a/docs.json b/docs.json index ea7350a15..30c991ab2 100644 --- a/docs.json +++ b/docs.json @@ -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" ] }, diff --git a/ecosystem/api/validator-rewards/api-reference.mdx b/ecosystem/api/validator-rewards/api-reference.mdx new file mode 100644 index 000000000..bb3514c3a --- /dev/null +++ b/ecosystem/api/validator-rewards/api-reference.mdx @@ -0,0 +1,194 @@ +--- +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. + + + +## 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 of the running service. +``: masterchain block sequence number. +``: masterchain block sequence number inside the target round. +``: 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`. | + +Pool type background: + +- [Nominator pool contracts](/ecosystem/staking/nominator-pools) +- [Single nominator pool contracts](/ecosystem/staking/single-nominator) + +### 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 "/api/validators?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 "/api/validation-rounds?block=" +``` + + + +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 "/api/round-rewards?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. diff --git a/ecosystem/api/validator-rewards/overview.mdx b/ecosystem/api/validator-rewards/overview.mdx new file mode 100644 index 000000000..b7fde8abb --- /dev/null +++ b/ecosystem/api/validator-rewards/overview.mdx @@ -0,0 +1,64 @@ +--- +title: "Validator Rewards API overview" +sidebarTitle: "Overview" +--- + +import { Aside } from "/snippets/aside.jsx"; + +TON Validator Rewards API is a self-hosted HTTP API that reads validator +reward and staking data directly from TON liteservers through `tongo`. + + + +## 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 + `https://ton.org/global-config.json`, caches it in memory for seven days, + and refreshes the lite client after the cache 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. | + +## Related pages + +- [How to run the Validator Rewards API locally](/ecosystem/api/validator-rewards/run-locally) +- [Validator Rewards API reference](/ecosystem/api/validator-rewards/api-reference) +- [Nominator pool contracts](/ecosystem/staking/nominator-pools) +- [Single nominator pool contracts](/ecosystem/staking/single-nominator) diff --git a/ecosystem/api/validator-rewards/run-locally.mdx b/ecosystem/api/validator-rewards/run-locally.mdx new file mode 100644 index 000000000..4aaf6cae4 --- /dev/null +++ b/ecosystem/api/validator-rewards/run-locally.mdx @@ -0,0 +1,121 @@ +--- +title: "Run the Validator Rewards API locally" +sidebarTitle: "Run locally" +--- + +import { Aside } from "/snippets/aside.jsx"; + +## Objective + +Run a local instance of the Validator Rewards API, expose it on an HTTP port, +and verify the main service endpoints. + +## Prerequisites + +- A local checkout of the `ton-validators-rewards-api` source code. +- [Go](https://go.dev/dl/) 1.25.0 or later. +- Optional: [Docker Engine](https://docs.docker.com/engine/install/). + +Audience: Intermediate. Assumes familiarity with Go builds, environment +variables, and HTTP requests. + +## Build and start the binary + +Run the following commands from the project root: + +```bash +go build -o ton-validators-rewards-api . +./ton-validators-rewards-api +``` + +The service listens on port `8080` by default. + +When `-config` is not set, startup downloads +`https://ton.org/global-config.json` and uses the liteservers from that file. + +## Configure the process + +The process loads environment variables from a `.env` file in the working +directory, when present. + +Supported environment variables: + +| Variable | Description | +| ------------- | ------------------------------------------------------------ | +| `PORT` | HTTP port. Default: `8080`. | +| `UPTRACE_DSN` | Uptrace DSN for tracing. If unset, telemetry stays disabled. | + +Use a different port: + +```bash +PORT=3000 ./ton-validators-rewards-api +``` + +Define placeholders: +``: path to a TON global config JSON file. + +Use a custom TON global config file: + +```bash +./ton-validators-rewards-api -config +``` + + + +## Run with Docker + +Build and start the container image: + +```bash +docker build -t ton-validators-rewards-api . +docker run -p 8080:8080 ton-validators-rewards-api +``` + +Use a custom config file in Docker: + +```bash +docker run -p 8080:8080 \ + -v $(pwd)/config.json:/config.json:ro \ + ton-validators-rewards-api -config /config.json +``` + +## Verify + +Check the health endpoint: + +```bash +curl http://localhost:8080/health +``` + +Expected output: + +```json +{"status":"ok"} +``` + +Open the Swagger UI: + +```text +http://localhost:8080/swagger +``` + +Fetch the current validator snapshot: + +```bash +curl http://localhost:8080/api/validators +``` + +The response is JSON and includes `block`, `election_id`, `total_stake`, and +`validators`. + +## Troubleshoot + +- If startup fails while downloading the default config, start the service with + `-config ` and use a local TON global config file. +- If port `8080` is already in use, set `PORT` to a different value. +- If `GET /api/round-rewards` returns an error that the round is not finished, + query an older finished round by `election_id` or by a `block` inside that + round. diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt index b314f0a4b..805389b89 100644 --- a/resources/dictionaries/custom.txt +++ b/resources/dictionaries/custom.txt @@ -236,6 +236,7 @@ DEXes DEXs DHT DHTs +DSN DNAT Diffie dockerize @@ -790,6 +791,7 @@ untyped unvoted updatable Upgradability +Uptrace uptimes URIs USDe diff --git a/ton-validators-rewards-api b/ton-validators-rewards-api new file mode 160000 index 000000000..1c6cd3c14 --- /dev/null +++ b/ton-validators-rewards-api @@ -0,0 +1 @@ +Subproject commit 1c6cd3c14c288525fbea2bafad977a6d940196bd From b49439922212521c9ebeffa15189d153779301a3 Mon Sep 17 00:00:00 2001 From: delovoyhomie Date: Mon, 23 Mar 2026 10:27:57 +0300 Subject: [PATCH 2/2] refactor(ton-validators-rewards-api): refine validator rewards API docs and align wording with source - update overview, run locally, and API reference pages - align descriptions and commands with ton-validators-rewards-api - add source and config links, and clean up related sections - update navigation and custom dictionary entries --- .gitignore | 2 +- docs.json | 2 +- .../api/validator-rewards/api-reference.mdx | 21 ++++++++-------- ecosystem/api/validator-rewards/overview.mdx | 25 +++++++++++-------- .../api/validator-rewards/run-locally.mdx | 9 ++++--- resources/dictionaries/custom.txt | 2 ++ ton-validators-rewards-api | 1 - 7 files changed, 35 insertions(+), 27 deletions(-) delete mode 160000 ton-validators-rewards-api diff --git a/.gitignore b/.gitignore index aad06735e..ee77c0df1 100644 --- a/.gitignore +++ b/.gitignore @@ -22,4 +22,4 @@ node_modules/ __pycache__ # Generated folders -/stats/ +/stats/ \ No newline at end of file diff --git a/docs.json b/docs.json index 30c991ab2..9923694bd 100644 --- a/docs.json +++ b/docs.json @@ -120,7 +120,7 @@ ] }, { - "group": "Validator Rewards API", + "group": "Validator rewards API", "pages": [ "ecosystem/api/validator-rewards/overview", "ecosystem/api/validator-rewards/run-locally", diff --git a/ecosystem/api/validator-rewards/api-reference.mdx b/ecosystem/api/validator-rewards/api-reference.mdx index bb3514c3a..bd4ec4c4c 100644 --- a/ecosystem/api/validator-rewards/api-reference.mdx +++ b/ecosystem/api/validator-rewards/api-reference.mdx @@ -1,5 +1,5 @@ --- -title: "Validator Rewards API reference" +title: "Validator rewards API reference" sidebarTitle: "API reference" mode: "wide" --- @@ -26,10 +26,11 @@ finished round reward distribution. for service-side failures. Define placeholders: -``: base URL of the running service. -``: masterchain block sequence number. -``: masterchain block sequence number inside the target round. -``: election ID of the target round. + +- ``: base URL of the running service. +- ``: masterchain block sequence number. +- ``: masterchain block sequence number inside the target round. +- ``: election ID of the target round. ## Service routes @@ -64,11 +65,6 @@ object shape. | `nominators_count` | Number of nominators. Present for `nominator-pool-v1.0`. | | `nominators` | Array of nominator entries. Present for `nominator-pool-v1.0`. | -Pool type background: - -- [Nominator pool contracts](/ecosystem/staking/nominator-pools) -- [Single nominator pool contracts](/ecosystem/staking/single-nominator) - ### Nominator entry | Field | Description | @@ -192,3 +188,8 @@ Response fields: 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) diff --git a/ecosystem/api/validator-rewards/overview.mdx b/ecosystem/api/validator-rewards/overview.mdx index b7fde8abb..9e0815920 100644 --- a/ecosystem/api/validator-rewards/overview.mdx +++ b/ecosystem/api/validator-rewards/overview.mdx @@ -1,16 +1,17 @@ --- -title: "Validator Rewards API overview" +title: "Validator rewards API overview" sidebarTitle: "Overview" --- import { Aside } from "/snippets/aside.jsx"; -TON Validator Rewards API is a self-hosted HTTP API that reads validator -reward and staking data directly from TON liteservers through `tongo`. +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). ## What the API returns @@ -34,8 +35,9 @@ reward and staking data directly from TON liteservers through `tongo`. - 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 - `https://ton.org/global-config.json`, caches it in memory for seven days, - and refreshes the lite client after the cache TTL expires. + 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 @@ -56,9 +58,12 @@ reward and staking data directly from TON liteservers through `tongo`. | `GET /api/openapi.yaml` | Return the embedded OpenAPI document. | | `GET /swagger` | Open the local Swagger UI. | -## Related pages +## 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 -- [How to run the Validator Rewards API locally](/ecosystem/api/validator-rewards/run-locally) -- [Validator Rewards API reference](/ecosystem/api/validator-rewards/api-reference) - [Nominator pool contracts](/ecosystem/staking/nominator-pools) - [Single nominator pool contracts](/ecosystem/staking/single-nominator) diff --git a/ecosystem/api/validator-rewards/run-locally.mdx b/ecosystem/api/validator-rewards/run-locally.mdx index 4aaf6cae4..4f5e14617 100644 --- a/ecosystem/api/validator-rewards/run-locally.mdx +++ b/ecosystem/api/validator-rewards/run-locally.mdx @@ -1,5 +1,5 @@ --- -title: "Run the Validator Rewards API locally" +title: "How to run the validator rewards API locally" sidebarTitle: "Run locally" --- @@ -7,12 +7,12 @@ import { Aside } from "/snippets/aside.jsx"; ## Objective -Run a local instance of the Validator Rewards API, expose it on an HTTP port, +Run a local instance of the validator rewards API, expose it on an HTTP port, and verify the main service endpoints. ## Prerequisites -- A local checkout of the `ton-validators-rewards-api` source code. +- A local checkout of the [ton-validators-rewards-api source code](https://github.com/the-ton-tech/ton-validators-rewards-api). - [Go](https://go.dev/dl/) 1.25.0 or later. - Optional: [Docker Engine](https://docs.docker.com/engine/install/). @@ -114,7 +114,8 @@ The response is JSON and includes `block`, `election_id`, `total_stake`, and ## Troubleshoot - If startup fails while downloading the default config, start the service with - `-config ` and use a local TON global config file. + `-config ` and use a local copy of the [TON Mainnet global + config](https://ton-blockchain.github.io/global.config.json). - If port `8080` is already in use, set `PORT` to a different value. - If `GET /api/round-rewards` returns an error that the round is not finished, query an older finished round by `election_id` or by a `block` inside that diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt index 805389b89..fbae2dca3 100644 --- a/resources/dictionaries/custom.txt +++ b/resources/dictionaries/custom.txt @@ -737,10 +737,12 @@ TON TON.cx TONCO Toncoin +Tongo toncoin.org Tonkeeper tonlib Tonscan +tongo tonscan.com tonscan.org Tonstakers diff --git a/ton-validators-rewards-api b/ton-validators-rewards-api deleted file mode 160000 index 1c6cd3c14..000000000 --- a/ton-validators-rewards-api +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 1c6cd3c14c288525fbea2bafad977a6d940196bd