Validator Guide

Overview

A Phylax validator dispatches typed skill tasks to miners, verifies their submissions, computes consensus across verification groups, and pushes weights on chain. Per round the validator does six things:

Fetch tasks

Up to twelve tasks per round, two per skill type.

Prepare bundles

Inject canaries and derive nonce-based probe events. Concurrent across all twelve tasks.

Select verification group

Three primaries plus two auditors per task. Dispatch concurrently.

Verify each response

Deadline, SSSA structure, sandbox manifest digest, trace bundle hashes, probe presence, semantic subset.

Compute consensus

Full SSSA consensus across the group multiplies each miner’s emission score.

Async sandbox rerun

Pull each primary’s declared Docker image, rerun on the same bundle and nonce, confirm honesty. Result feeds next round’s reputation.

The validator needs Docker on the host for the async miner image rerun.

Requirements

Docker 24+ with the compose plugin (docker compose version must work)
btcli (install guide)
16 GB RAM, 4 or more CPU cores, 100 GB free disk
Outbound HTTPS to the server URL
Outbound HTTPS to container registries miners publish sandbox images to (typically ghcr.io, docker.io)
Your shell user in the docker group: sudo usermod -aG docker $USER && newgrp docker

Setup

Create Wallet, Register, and Stake

btcli wallet create --wallet.name validator --wallet.hotkey default

Fund the coldkey with testnet TAO from the Bittensor Discord #faucet channel. You need TAO for the registration fee and for stake.

btcli subnet register \
  --netuid 486 \
  --subtensor.network test \
  --wallet.name validator \
  --wallet.hotkey default

btcli stake add \
  --netuid 486 \
  --subtensor.network test \
  --wallet.name validator \
  --wallet.hotkey default \
  --amount 1

Verify:

btcli wallet overview --wallet.name validator --subtensor.network test

Get on the Network Allowlist

The network operator maintains an allowlist of validator hotkeys. Your hotkey needs to be on it before you can pull tasks.Send the network operator (reach out via the Phylax community channels):

Your validator hotkey ss58
The source IP your validator will dial from

They reply with the server URL and the server signing key hotkey. You pin that hotkey in .env so a rogue impostor cannot trick you.

Install and Configure

curl -fsSL https://raw.githubusercontent.com/praxi-labs/phylax-subnet/main/scripts/install.sh | bash -s validator

Edit ~/phylax/validator/.env:

Variable	What to set
`PHYLAX_NETUID`	`486`
`SUBTENSOR_NETWORK`	`test`
`WALLET_NAME`	folder name in `~/.bittensor/wallets/`
`WALLET_HOTKEY`	`default` (or the hotkey you registered)
`PHYLAX_SERVER_URL`	server URL
`PHYLAX_SERVER_HOTKEY`	pinned server hotkey
`PHYLAX_VALIDATOR_LABEL`	friendly label for network dashboards

docker compose restart is not enough to pick up .env changes. Use docker compose up -d --force-recreate.

Run

cd ~/phylax/validator
docker compose pull
docker compose up -d
docker compose logs -f

Within about 30 seconds you should see:

registered with phylax-server
starting Phylax validator on netuid=486 hotkey=...

Within a couple of minutes:

round <id> | tasks=12 types={'executable_python','declarative','rag_knowledge',...}
executable_python hk=5FHneW... role=primary Q=0.512 cs=0.85 tier=tier_1_reference ε=0.78
round <id> done | top_score=0.XXX epoch=0
set_weights | block=...

Per Round Verification Pipeline

For each response from a miner the validator runs sequential gates. Each gate either passes (continue to the next) or fails (the submission scores zero and a reputation update is queued).

Gate 1: Deadline

If latency_ms > deadline_s * 1000 the submission is discarded with no score and no reputation update.

Gate 2: SSSA parse

Attestation dict must deserialise into a valid SSSA pydantic model.

Gate 3: SSSA validity

skill.skill_type must match the task’s skill type. If llm_evidence.allowed_use is present it must be finding_enrichment, mitre_owasp_mapping, or cve_explanation. Violations score zero and flag for reputation violation.

Gate 4: Sandbox manifest digest (primaries, runtime types only)

sandbox_manifest.digest must equal the image_hash the miner declared at registration. Mismatch scores zero immediately, without waiting for the async rerun.

Gate 5: Trace bundle verification (primaries, runtime types only)

Total bundle under 30 MB compressed
Each file under its per file cap
All required files for the skill type present
Each file decompresses, parses as JSONL, and hashes (with ts sorted + key sorted + no whitespace normalisation) to exactly the hash the miner declared in their SSSA evidence block

Gate 6: Probe verification

synapse.probe_evidence must contain {file_path, file_content, dns_host, process_echo} derived from the nonce. For runtime types the probe file write must appear in fs.jsonl, the probe DNS host must appear in network.jsonl, and the probe echo must appear in process.jsonl.

Gate 7: Axis scoring

Compute α, ε, π, η plus the type specific axis. Apply the per type composite Q formula. Below ε = 0.10 the composite Q is zero.

Verification Group Selection

For each task the validator selects a five miner group from miners who declared support for the skill type with reputation greater than or equal to 0.2.

Slot	Selection rule
3 primaries	Top three by per type reputation
2 auditors	Random sample of two from the rest of the pool

Auditors who have been in the auditor role for the same skill type three rounds in a row are promoted into the primary slot, pushing the lowest ranked primary into the auditor pool. Miners with collusion flags (three or more accumulated) are excluded entirely.

If the pool has fewer than five miners the group degrades gracefully. Fewer than three miners disables consensus scoring for that task.

Async Sandbox Rerun

The validator does not rerun every primary’s sandbox every round. It triggers async rerun only when needed.

Consensus breakdown
Some primaries diverge
Clean consensus

More than half the group diverges from majority. Rerun all diverging primaries.

Each rerun job is enqueued to a persistent SQLite queue at ~/.phylax/rerun_queue.sqlite3. A background thread pulls jobs one at a time, pulls the miner’s declared Docker image, verifies the pulled digest matches what they declared, runs the image against the same bundle with the same nonce, and compares:

fs_trace_hash must match exactly (canary write is deterministic)
Semantic agreement on network.jsonl, process.jsonl, secrets.jsonl must be at least 0.7

A pass adds +0.02 to that miner’s per type reputation. A fail multiplies it by 0.7. Results feed into the next round.

Collusion Tracking

After each round the validator records per (hotkey, skill_type, round_id) the miner’s agreement with primaries and agreement with auditors. Over the last 30 samples, if a miner’s agreement with primaries exceeds 0.90 while their agreement with random auditors stays below 0.60, the validator accumulates a collusion flag. Three flags eject the miner from group selection until investigated.

Configuration Reference

Required

Variable	What to set
`PHYLAX_NETUID`	`486`
`SUBTENSOR_NETWORK`	`test` or `finney`
`WALLET_NAME`	folder in `~/.bittensor/wallets/`
`WALLET_HOTKEY`	hotkey under that wallet
`PHYLAX_SERVER_URL`	network server URL

Recommended

Variable	What to set
`PHYLAX_SERVER_HOTKEY`	pinned server signing key for impersonation defence
`PHYLAX_VALIDATOR_LABEL`	friendly label for network dashboards

Tunable

Variable	Default	Description
`WEIGHT_UPDATE_INTERVAL`	`360`	Blocks between set_weights pushes (one tempo on netuid 486; the chain rate-limit is 100 blocks so going below ~110 risks `set_weights returned False: too soon to commit`)
`EMA_ALPHA`	`0.2`	Per round EMA blending factor
`QUERY_TIMEOUT`	`150`	Hard ceiling on dendrite call, in seconds
`PHYLAX_RERUN_QUEUE_PATH`	`~/.phylax/rerun_queue.sqlite3`	Persistent queue for async miner image reruns
`PHYLAX_COLLUSION_DB_PATH`	`~/.phylax/collusion.sqlite3`	Persistent store for collusion agreement history
`PHYLAX_INFERENCE_PROXY_URL`	(empty)	Forwarded to miners as `inference_config.proxy_url`
`PHYLAX_ALLOWED_MODELS`	(empty)	Comma separated list forwarded as `allowed_models`
`PHYLAX_COMPOSITION_DEPTH`	`5`	Default `composition_depth` for `agent_composition` ground truth runs

Set by install.sh

Variable	What it does
`PHYLAX_EVIDENCE_HOST_DIR`	Host side absolute path of evidence bind mount. Required for docker in docker.
`DOCKER_GID`	Host docker group GID. Validator container joins this group to open `/var/run/docker.sock`.
`HOST_UID` / `HOST_GID`	Your shell user UID/GID. Container runs as this user so bind mounts stay writable.

Local State Files

The validator maintains local SQLite state files. Do not delete them while the validator is running.

Path	Purpose
`~/.phylax/rerun_queue.sqlite3`	Persistent queue of pending async miner image reruns. Survives validator restart.
`~/.phylax/collusion.sqlite3`	30 round window of per `(miner, skill_type)` consensus agreement data.
Docker image cache	Per miner sandbox images pulled at rerun time. Docker manages this automatically. Use `docker image prune -af` if it grows too large.

Troubleshooting

Server registration failed: 403 Forbidden

Your hotkey or source IP is not on the allowlist. Contact the network operator.

Server identity mismatch

Server signing key changed or PHYLAX_SERVER_HOTKEY is wrong. Confirm the pinned value with the operator and update .env.

'no dispatchable miners' log line

No miner has declared the skill type, or all declared miners are filtered out by recency, active task, or collusion flag rules. Wait for more miners to register, or check the validator log for the specific exclusion reason.

'trace verification failed' for many miners

Miners are not following the trace bundle contract or the trace normalisation rule. Confirm miners are on a recent miner image version.

'sandbox digest mismatch' for a specific miner

The miner’s PHYLAX_SANDBOX_DIGEST does not match the image_hash they declared at registration. The miner needs to update either their env or their registration so the two agree.

'probe verification failed' for many miners

Miners are not emitting probe events into their fs/network/process traces. Confirm miners are on a recent miner image version.

'docker pull failed' log line during rerun

Validator host cannot reach the miner’s container registry, or the image is not publicly readable. Test pull manually. Miner must publish their image with public read access.

Rerun queue keeps growing

Rerun worker cannot keep up with submissions, or Docker is broken on the host. Check docker info works. Consider raising WEIGHT_UPDATE_INTERVAL to slow rounds.

top_score stuck at 0.000

No miner is returning valid SSSAs that pass all gates. Inspect validator log for the rejection reasons.

set_weights returned False

Stake too low for permit, or chain is congested. btcli stake add more TAO, or wait and try next interval.

What Makes a Validator Run Well

A well functioning validator has:

Reliable server connectivity

The server URL must be reachable every round for task fetching.

Public network egress for image pulls

The async rerun worker pulls miner sandbox images. If your host cannot reach the registries miners publish to, reruns will fail.

Docker as the host user

The rerun worker uses docker run directly. The container user must reach the Docker socket.

Registered hotkey with non-zero stake

Without stake you cannot set weights on-chain. Top up periodically.

If all of these hold, the validator runs rounds continuously, accumulates per-type reputation history, builds collusion detection signal, and converges on a stable weight distribution that rewards honest, high quality miner work.

Verification Groups

Selection rules, rotation, and graceful degradation.

Consensus

The seven component consensus formula in detail.

Sandbox Reruns

Async rerun queue, image pull, digest verification.

Scoring

Full scoring reference.

​Overview

​Requirements

​Setup

​Per Round Verification Pipeline

​Verification Group Selection

​Async Sandbox Rerun

​Collusion Tracking

​Configuration Reference

​Local State Files

​Troubleshooting

​What Makes a Validator Run Well

Reliable server connectivity

Public network egress for image pulls

Docker as the host user

Registered hotkey with non-zero stake

​Next

Verification Groups

Consensus

Sandbox Reruns

Scoring

Overview

Requirements

Setup

Per Round Verification Pipeline

Verification Group Selection

Async Sandbox Rerun

Collusion Tracking

Configuration Reference

Local State Files

Troubleshooting

What Makes a Validator Run Well

Next