Configuration Schema

BlockZero uses YAML configuration files for both miners and validators. This page documents every field for MinerConfig and ValidatorConfig.

MinerConfig

Example

model_path: Qwen/Qwen3-VL-30B-Instruct
expert_group: 0
chain_endpoint: wss://entrypoint-finney.opentensor.ai:443
netuid: 42
wallet:
  name: my-wallet
  hotkey: my-hotkey
checkpoint_dir: ./checkpoints
data_path: /data/expert-group-0/train.jsonl
batch_size: 4
gradient_accumulation_steps: 4
learning_rate: 3e-5
warmup_steps: 100
max_steps: 500
fp16: true
wandb: false
wandb_project: blockzero-miner
checkpoint_keep_top_k: 3
num_workers: 4
seed: 42

Field Reference

Field	Type	Default	Description
model_path	string	required	Path to base model directory or HuggingFace model ID (e.g., Qwen/Qwen3-VL-30B-Instruct)
expert_group	integer	required	Expert group ID assigned to this miner (0-indexed). Each miner trains only the experts belonging to this group.
chain_endpoint	string	wss://entrypoint-finney.opentensor.ai:443	Bittensor chain WebSocket endpoint
netuid	integer	required	BlockZero subnet UID
wallet.name	string	default	Bittensor coldkey wallet name
wallet.hotkey	string	default	Bittensor hotkey name
checkpoint_dir	string	./checkpoints	Checkpoint storage path. Supports local paths, s3:// URIs, and ipfs:// URIs.
data_path	string	required	Path to the training dataset for this expert group (JSONL format)
batch_size	integer	4	Per-GPU batch size during training
gradient_accumulation_steps	integer	4	Number of gradient accumulation steps. Effective batch size = batch_size × gradient_accumulation_steps.
learning_rate	float	3e-5	AdamW optimizer learning rate
warmup_steps	integer	100	Number of linear LR warmup steps at the start of each training cycle
max_steps	integer	500	Maximum number of training steps per cycle before the miner submits its checkpoint
fp16	boolean	true	Enable FP16 mixed-precision training
wandb	boolean	false	Enable Weights & Biases run logging
wandb_project	string	blockzero-miner	W&B project name. Only used when wandb: true.
checkpoint_keep_top_k	integer	3	Number of local checkpoints to retain by lowest validation loss
num_workers	integer	4	Number of DataLoader worker processes
seed	integer	42	Global random seed for reproducibility

---

ValidatorConfig

Example

model_path: ./models/Qwen3-VL-30B-Instruct
chain_endpoint: wss://entrypoint-finney.opentensor.ai:443
netuid: 42
wallet:
  name: my-wallet
  hotkey: my-validator-hotkey
checkpoint_cache_dir: ./validator-cache
server_port: 8080
server_host: 0.0.0.0
# auth_token: set via BZ_AUTH_TOKEN environment variable
eval_dataset_path: /data/validation/held-out.jsonl
eval_batch_size: 8
score_ema_alpha: 0.9
consensus_timeout: 60
max_checkpoints_cached: 50

Field Reference

Field	Type	Default	Description
model_path	string	required	Path to the base model directory for serving to miners and for evaluation
chain_endpoint	string	wss://entrypoint-finney.opentensor.ai:443	Bittensor chain WebSocket endpoint
netuid	integer	required	BlockZero subnet UID
wallet.name	string	default	Bittensor coldkey wallet name
wallet.hotkey	string	default	Bittensor hotkey name
checkpoint_cache_dir	string	./validator-cache	Local directory where downloaded miner checkpoints are stored for evaluation
server_port	integer	8080	Port the FastAPI model server binds to
server_host	string	0.0.0.0	Network interface the FastAPI server listens on
auth_token	string	env: BZ_AUTH_TOKEN	Bearer token for API auth. Set via environment variable, not config file.
eval_dataset_path	string	required	Path to the held-out validation dataset for Proof-of-Loss scoring
eval_batch_size	integer	8	Batch size used during miner checkpoint evaluation
score_ema_alpha	float	0.9	EMA smoothing for MinerScoreAggregator. Higher = more weight on recent scores.
consensus_timeout	integer	60	Seconds to wait for inter-validator merging before timing out
max_checkpoints_cached	integer	50	Max miner checkpoints to retain in checkpoint_cache_dir

Auth token security

Never set auth_token directly in the config file. Use the BZ_AUTH_TOKEN environment variable to avoid storing secrets in version-controlled configuration files.