Skip to content

feat(api): publish a bounded subnet price-share composition timeline #11550

Description

@JSONbored

Problem

The homepage currently has only a point-in-time economics ranking. Rendering an OpenCode-style historical composition chart from that snapshot would be misleading, while requesting history per series in the browser would add avoidable latency and unstable client-side aggregation.

The original proposed cross-subnet total_stake_alpha stack is invalid: alpha is denominated independently by subnet and must never be summed across netuids.

The historical emission_share column is a legacy economics-artifact normalization: alpha price divided by the sum of reported alpha prices. It includes Root when Root reports a price and does not retain the historical runtime eligibility inputs required to reconstruct v440 Stage 1. It must never be described as runtime Stage 1, stake, market cap, or final TAO emission.

Scope

  • Add a typed, mainnet-only GET /api/v1/chain/subnet-price-share-composition endpoint with up to 56 closed UTC daily points.
  • Read existing subnet_snapshots history in one bounded indexed query. Select a deterministic fixed cohort of up to six netuids from the newest eligible date, with netuid tie-breaking; never reshuffle colors or series identity by day.
  • Use only existing emission_share as an explicitly artifact-normalized moving-price share. Preserve Root in its stored denominator; do not post-hoc filter or re-normalize historical rows where runtime eligibility is unknown.
  • Mark the result estimated_observed_price_set. Legacy daily snapshots have no completed-pass manifest, so a returned day must require one persisted writer timestamp for numeric shares, unique netuids, valid six-decimal share units, and a total within the six-decimal source rounding envelope. This detects certain mixed writes; it is not a source artifact ID or proof of complete chain coverage.
  • Derive Other artifact-normalized price share as the exact six-decimal residual of that normalized unit, never as a persisted bucket, unselected-row sum, or claimed network total.
  • Do not join identity history: a stable series is a netuid, not a claim that a reused netuid is one project throughout the timeline.
  • Omit mixed, malformed, off-grid, partial-normalization, uncaptured, and cap-truncated raw dates rather than inventing zeroes or a complete-looking bar.
  • Use existing worker edge-cache, route-contract, OpenAPI, docs, GraphQL, MCP, and mainnet-addressing patterns. Keep the payload compact for an interactive composition timeline.

Acceptance criteria

  • The response contains a stable ordered netuid series list plus a bounded chronological sequence of real daily points.
  • Every emitted day has selected recorded shares plus an exact six-decimal Other artifact-normalized price share residual within the normalized unit; any selected total above 100% is omitted rather than clamped.
  • A cold or unavailable store returns the repositorys schema-stable empty response; it never substitutes a fake timeline.
  • The endpoint is contract-described, documented, edge-cached, and covered at the same quality bar as analogous analytics routes.
  • Public wording distinguishes artifact-normalized moving-price share from runtime v440 Stage 1, total stake, final TAO emission, source-artifact identity, and completed-pass certification.

Out of scope

Blocks #11544

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

backendmaintainer-onlyOwner-only work — yields no Gittensor points.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions