SN Owner Phase API

The subnet owner runs a FastAPI service that acts as the timing oracle for the entire subnet. All miners and validators query this service to determine the current phase, plan upcoming actions, and bootstrap peer-to-peer connections.

Base URL

http://<owner_ip>:<owner_port>

Configured via the owner.app_ip and owner.app_port fields in the owner configuration.

---

GET /

Returns service information and the full phase schedule.

Response — 200 OK

{
  "message": "Phase service is running",
  "cycle_length": 45,
  "phases": [
    { "index": 0, "name": "Distribute", "length": 5 },
    { "index": 1, "name": "Train", "length": 20 },
    { "index": 2, "name": "MinerCommit1", "length": 3 },
    { "index": 3, "name": "MinerCommit2", "length": 3 },
    { "index": 4, "name": "Submission", "length": 3 },
    { "index": 5, "name": "Validate", "length": 3 },
    { "index": 6, "name": "Merge", "length": 3 },
    { "index": 7, "name": "ValidatorCommit1", "length": 3 },
    { "index": 8, "name": "ValidatorCommit2", "length": 2 }
  ]
}

---

GET /get_phase

Returns the current phase based on the latest block height from the Bittensor chain.

Response — 200 OK

{
  "block": 54321,
  "cycle_length": 45,
  "cycle_index": 1207,
  "cycle_block_index": 6,
  "phase_name": "Train",
  "phase_index": 1,
  "phase_start_block": 54320,
  "phase_end_block": 54339,
  "blocks_into_phase": 1,
  "blocks_remaining_in_phase": 18
}

Field	Description
block	Current Bittensor block number
cycle_length	Total blocks in one full cycle
cycle_index	Which cycle we are in (block / cycle_length)
cycle_block_index	Position within the current cycle (0-indexed)
phase_name	Name of the current phase
phase_index	Index of the current phase within the cycle
phase_start_block	Absolute block where the current phase started
phase_end_block	Absolute block where the current phase ends
blocks_into_phase	How many blocks have elapsed in this phase
blocks_remaining_in_phase	How many blocks remain in this phase

Status codes

Code	Meaning
200 OK	Success
400 Bad Request	Invalid block input

---

GET /previous_phase_blocks

Returns the block ranges for all phases from the previous cycle.

Response — 200 OK

{
  "Distribute": [54270, 54274],
  "Train": [54275, 54294],
  "MinerCommit1": [54295, 54297],
  "MinerCommit2": [54298, 54300],
  "Submission": [54301, 54303],
  "Validate": [54304, 54306],
  "Merge": [54307, 54309],
  "ValidatorCommit1": [54310, 54312],
  "ValidatorCommit2": [54313, 54314]
}

Each value is a [start_block, end_block] tuple.

---

GET /blocks_until_next_phase

Returns when each phase will next occur, useful for scheduling wake-ups.

Response — 200 OK

{
  "Distribute": [54315, 54319, 10],
  "Train": [54320, 54339, 15],
  "MinerCommit1": [54340, 54342, 35],
  "MinerCommit2": [54343, 54345, 38],
  "Submission": [54346, 54348, 41],
  "Validate": [54349, 54351, 44],
  "Merge": [54352, 54354, 47],
  "ValidatorCommit1": [54355, 54357, 50],
  "ValidatorCommit2": [54358, 54359, 53]
}

Each value is a [start_block, end_block, blocks_until] tuple.

---

GET /get_init_peer_id

Returns the list of DHT multiaddresses for bootstrapping peer-to-peer connections between validators.

Response — 200 OK

[
  "/ip4/203.0.113.1/tcp/4001/p2p/QmPeerID1...",
  "/ip4/203.0.113.2/tcp/4001/p2p/QmPeerID2..."
]

Validators use these addresses to join the DHT network for inter-validator gradient synchronization.

---

Phase Definitions

The subnet operates on a 45-block cycle (~9 minutes at 12 seconds per block) with nine phases:

Phase	Description
Distribute	Validators publish model; miners download their expert group slice
Train	Miners train assigned expert groups locally
MinerCommit1	Miners commit signed model hash to chain
MinerCommit2	Miners commit model hash (second round)
Submission	Miners submit trained checkpoints to validators
Validate	Validators evaluate miner submissions via Proof-of-Loss
Merge	Validators synchronize gradients and run outer optimizer
ValidatorCommit1	Validators commit signed model hash to chain
ValidatorCommit2	Validators commit model hash (second round)

note

The phase service does not require authentication. All participants (miners, validators, and external clients) can query the current phase.