API Reference

Scope. The interfaces that exist today are the CLI, the agent contract, and the on-chain record formats — all documented below and all runnable. The HTTP API is design-stage and is marked as such at the bottom.

Agent contract

The one interface a miner implements. Your source file must define:

def build_agent(weights: bytes) -> Callable[[str, CallModel], str]: ...

Symbol	Type	Meaning
`weights`	`bytes`	Opaque; whatever you serialised into `weights.bin`
`agent(prompt, call_model)`	`(str, CallModel) -> str`	Returns the answer, graded against public gold
`call_model(model, messages, params)`	`(str, list[dict], dict) -> str`	Your only channel to the pool; metered

call_model raises UnpinnedModelError if model is not on the owner's allow-list.

CLI

Mainnet is Subnet 99: pass --netuid 99 --network finney. The --network default below is test (the offline/testnet path); --netuid is always required.

`orchestra-koth-dev` — score an artifact locally

Runs the exact validator scoring (calls verify_proof directly).

Flag	Default	Meaning
`--source`	reference router	Path to your `build_agent` source
`--weights`	—	Path to your `weights.bin`
`--model`	`strong`	Reference router's pool model
`--n-per-bench`	`8`	Tasks sampled per benchmark
`--budget`	`0.5`	Eligibility cost ceiling (USD)

`orchestra-koth-miner` — the miner daemon

Flag	Default	Meaning
`--netuid`	required	Subnet netuid
`--wallet`	required	Bittensor wallet name
`--network`	`test`	Substrate network
`--repo`	required	Your own HF repo, e.g. `you/koth-miner`
`--source`	reference router	Your `build_agent` source
`--weights`	—	Your `weights.bin`
`--model`	`openai/gpt-4o-mini`	Reference router's model (if no `--source`)
`--pool`	owner allow-list	Comma-separated pinned models
`--n-per-bench`	`8`	Tasks per benchmark
`--poll`	`12.0`	Chain poll interval (s)
`--confine`	off	Run the agent in the no-egress namespace (production)

`orchestra-koth-validator` — the validator daemon

Flag	Default	Meaning
`--netuid`	required	Subnet netuid
`--wallet`	required	Validator wallet name
`--network`	`test`	Substrate network
`--n-per-bench`	`8`	Tasks per benchmark
`--poll`	`12.0`	Chain poll interval (s)
`--probe-bank`	—	Switch the memorisation backstop to the opt-in re-execution probe (`audit_mode="probe"`); the owner's secret held-out bank (JSON) matching the on-chain `probe_commit`. Omit ⇒ default grounding check.
`--commit-window`	`None` (off)	F7 anti-grind: require each proof committed on-chain within N blocks of the epoch open
`--grace-blocks`	`0`	F2: score an epoch only N blocks after it opens (keep N < 100)
`--state`	`koth_validator_state.json`	Persisted reign + king baseline (restart-safety)
`--insecure`	off	Disable the hardware gate. Testnet only — no security.

Without --insecure, governance_ready() refuses to start until the owner has published the approved-measurement set on-chain. The default memorisation backstop is the grounding check (proof-inspection, no re-execution) — no probe bank needed.

`orchestra-koth-owner` — publish the governance record

Flag	Default	Meaning
`--mrtd`	required	Approved image MRTD(s), hex (accepts several)
`--rtmr1`	required	Approved boot RTMR1 (GRUB/shim), hex
`--rtmr2`	required	Approved boot RTMR2 (kernel + cmdline), hex
`--pool`	required	Comma-separated pinned model allow-list
`--tcb-accept`	`UpToDate,SWHardeningNeeded`	Accepted TCB levels
`--version`	`1`	Rotation counter — bump to supersede
`--probe-bank`	—	Secret probe bank; its commit hash is published
`--netuid`	—	Omit for a dry run (prints the record)
`--wallet`	`owner`	Owner wallet
`--network`	`test`	Substrate network

Simulators

Command	What it does
`orchestra-koth-sim`	Full offline competition with the adversary cast
`orchestra-koth-local`	Decoupled 2-neuron demo (miner ⇄ store ⇄ validator)
`thirtyspokes measure --pool curated`	The Phase-0 routing oracle-gap gate on RouterBench

On-chain records

Commit string

koth1|<hf_repo>|<revision>|sha256(source_hash|weights_hash|hotkey)

Published via set_reveal_commitment. Four pipe-separated parts; the prefix is always koth1.

Owner governance record

Read by every validator, every epoch.

{
  "version": 1,
  "runtime_measurements": ["<sha256>"],
  "mrtd": ["<hex>"],
  "rtmr": { "1": "<hex>", "2": "<hex>", "3": "<derived>" },
  "tcb_accept": ["UpToDate", "SWHardeningNeeded"],
  "pool_allow_list": ["openai/gpt-4o-mini", "..."],
  "probe_commit": "<sha256>"
}

Proof

The unit a validator verifies. Uploaded to proofs/<epoch>.json in the miner's own repo.

Proof:
  epoch          int      # block // EPOCH_BLOCKS
  nonce          str      # sha256("koth-epoch|{epoch}|{beacon}")[:16]
  hotkey         str      # bound: a copier cannot resubmit this proof
  source_hash    str      # computed by the RUNTIME from the bytes it ran
  weights_hash   str
  model_id       str
  results        [BenchmarkResult]
  total_cost_usd float    # metered in-enclave
  n_calls        int
  call_log_hash  str      # binds the published trace
  measurement    str      # runtime image hash; must be on the approved list
  quote          Quote    # hardware signature over {measurement, report_data()}

BenchmarkResult:
  benchmark  str          # "math" | "mmlu" | "gpqa" | "swe"
  task_id    str
  answer     str
  cost_usd   float

report_data() = sha256(payload-minus-quote)

The behavioural trace (traces/<epoch>.json) records every pool call as {task_id, model, prompt, response, cost_usd} and hashes to call_log_hash.

Verdict and disqualification reasons

Every string a validator can emit.

Group	Reasons
Attestation	`bad_platform_quote`, `mock_quote_rejected`, `unapproved_runtime`, `tcb_out_of_date`, `tcb_revoked`, `measurement_mismatch`
Fail-closed config	`mrtd_gate_unset`, `rtmr_gate_unset`, `tcb_policy_unset`, `probe_bank_missing`, `probe_bank_mismatch`, `probe_bank_unverified`
Binding	`artifact_binding_mismatch`, `report_data_mismatch`, `bad_commit`, `hotkey_mismatch`, `trace_mismatch`, `unbound_source`
Epoch	`epoch_nonce_mismatch`
Commit window (F7, opt-in)	`no_proof_commit`, `commit_out_of_window`, `commit_mismatch`
Behaviour	`no_pool_call`, `hardcoded_answers`, `ungrounded` (default backstop), `memorization` (opt-in probe), `copy_of:<uid>`, `unexpected_task`, `bad_cost`
Eligibility	`over_budget`, `below_floor:<benchmark>`
Guard (clamp, not DQ)	`regression:<b>`, `no_confident_gain`, `thin_eval:<b>`, `cost_regression`
Operational	`artifact_unavailable`, `no_proof`, `produce_error:`, `audit_error:`

Success is ok.

Parameters

Parameter	Default
`EPOCH_BLOCKS`	`100` (≈ 20 min)
`n_per_bench`	`8`
`budget` / `f_min`	`0.50` USD / `0.10`
`margin` / `tol` / `cost_tol` / `min_tasks`	`0.03` / `0.02` / `0.10` / `5`
`alpha` / `boot` (bootstrap LCB)	`0.05` / `1000`
`dedup_agree`	`0.95`
`z_crit` (memorisation test)	`2.33`
`min_cohort` / `max_probe_drop`	`3` / `0.25`
king-chain size	`5` (king + 4 ex-kings), equal share `20 %` each when full
`eps0` / `eps_floor` / `tau`	`0.02` / `0.002` / `8.0`
`audit_mode`	`grounding` (default) · `probe` (opt-in)
`max_ungrounded` (grounding slack)	`0.15`
`scoring_mode` / `half_life_epochs`	`per_epoch` (default) · `accumulate` / `200`
`commit_window` / `grace_blocks`	off / `0` (opt-in anti-grind)
benchmark weights — full suite (sim/dev)	math/mmlu/gpqa/swe `0.30 / 0.22 / 0.23 / 0.25`
benchmark weights — live loader (daemons)	math/mmlu `0.5 / 0.5`
`tcb_accept`	`{UpToDate, SWHardeningNeeded}`

HTTP API — design only

Not built. api.thirtyspokes.ai does not exist. No endpoints, no keys, no payments.

The intended surface is OpenAI-compatible:

POST /v1/chat/completions      model: "auto" | "<any spoke>"

Streaming, tool use, and structured output are intended to pass through unchanged. Authentication, payment, and who operates the gateway are open questions — see Using the Gateway.