Minos – Decentralized Genomic Variant Calling & Benchmarking Platform

  A---T
 { \ / }
  \ X /
  / X \     __  __ _
 { / \ }   |  \/  (_)_ __   ___  ___
  G---C    | |\/| | | '_ \ / _ \/ __|
 { \ / }   | |  | | | | | | (_) \__ \
  \ X /    |_|  |_|_|_| |_|\___/|___/
  / X \
 { / \ }
  T---A

Minos – Decentralized Genomic Variant Calling & Benchmarking Platform

Minos (SN107) is a subnet for genomic variant calling and benchmarking powered by Bittensor. Every 72 minutes, the platform generates a fresh challenge genome (BAM file) containing hidden synthetic mutations injected using HelixForge at read level. Miners are rewarded for performing hyperparameter search and providing configurations for state-of-the-art variant calling tools that can accurately identify these hidden mutations in the genome. Once the hyperparameter space has been saturated, miners will compete to provide their own custom algorithms to identify mutations. Validators are responsible for downloading miner's hyperparam config and they will run each miner's submitted config, and evaluate the results using industry standard tools and approaches such as hap.py. Miners will never be asked to upload outputs, they submit their variant-calling configuration (and pipelines in later stages), which the validator executes trustlessly.

Subnet 107 on Bittensor mainnet (finney).

Architecture Overview

┌────────────────────────────────────────────────────────────-─┐
│                    MINOS PLATFORM                            │
│              (Task Coordination & File Conveyance)           │
├────────────────────────────────────────────────────────────-─┤
│  • Prepares BAMs with synthetic mutations using HelixForge   │
│  • Presigned URL generation for BAM transfer                 │
│    (Hippius SN75 + Cloudflare R2 + AWS S3 fallback)          │
│  • Continuous 72-minute rounds aligned to Bittensor tempo    │
│  • Lag scoring: miners submit in cycle N, validators score   │
│    cycle N while miners work on cycle N+1                    │
│  • Miner registration & status tracking                      │
└──────────────┬──────────────────────────────┬────────────────┘
               │                              │
    ┌───────────▼────────────────┐      ┌──────▼─────────────────────-------------------┐
    │     VALIDATOR              │      │      MINER                                    │
    │  • Downloads BAMs          │      │  • Download and run variant caller on BAM     │
    │  • Runs miner config       │      │ • Submits hyperparam config from their run    │
    │  • Scores with hap.py      │      │  • Top performer wins                         │
    │  • Sets blockchain weights │      └────────────────────────────-------------------┘
    └────────────────────────────┘
               │
    ┌──────────▼──────────┐
    │     BITTENSOR       │
    │    BLOCKCHAIN       │
    │  • Weight storage   │
    │  • Emission calc    │
    │  • Alpha emissions  │
    └─────────────────────┘

Repository Layout

minos_subnet/
├── neurons/                  # Bittensor neuron entrypoints
│   ├── miner.py              # Miner loop: poll, download, call variants, submit config
│   ├── validator.py          # Validator loop: subset scoring, set chain weights
│   ├── status.py             # Health checks and system status
│   └── README.md             # Neurons documentation
├── templates/                # Variant-calling tool templates
│   ├── gatk.py               # GATK HaplotypeCaller template
│   ├── deepvariant.py        # Google DeepVariant template
│   ├── freebayes.py          # FreeBayes template (DEPRECATED 2026-05-09; retained so in-flight pre-cutover rounds can still be scored; will be removed in a follow-up release)
│   ├── bcftools.py           # BCFtools mpileup/call template
│   ├── _common.py            # Shared template utilities
│   └── tool_params.py        # Parameter definitions and validation
├── utils/                    # Genomics utility modules
│   ├── scoring.py            # hap.py Docker runner + AdvancedScorer
│   ├── weight_tracking.py    # Round score tracker + winner-heavy pruning dust weights
│   ├── platform_client.py    # Authenticated API client (miner + validator)
│   ├── subset_scoring.py     # Subset scoring helpers (assignments, deadlines)
│   ├── config_loader.py      # Tool config file parser
│   ├── path_utils.py         # Safe filesystem paths
│   ├── file_utils.py         # SHA256-verified file download + caching
│   └── README.md             # Utils documentation
├── base/                     # Core subnet config
│   └── genomics_config.py    # Central config (Docker images, timeouts, scoring params)
├── configs/                  # Miner-tunable quality parameters
│   ├── gatk.conf
│   ├── deepvariant.conf
│   ├── freebayes.conf        # DEPRECATED 2026-05-09; retained for legacy parsing
│   └── bcftools.conf
├── docs/                     # Architecture and integration docs
│   ├── architecture.md       # System architecture deep dive
│   ├── tuning_guide.md       # Miner tuning reference (scoring, parameters, strategy)
│   ├── hap_py_docker.md      # hap.py Docker image reference
│   └── ai-assistant/         # AI assistant knowledge graph, runtime skills, and persona assets
├── scripts/                  # Developer tools
│   ├── verify.sh             # Pre-flight environment check
│   ├── demo.sh               # End-to-end demo runner
│   ├── minosvm_first_run.sh  # Friendly MinosVM first-run launcher
│   ├── prompt_ai_assistant.sh # First-run Ditto/OpenClaw/Hermes prompt
│   ├── setup_ditto_agent.sh  # Optional Ditto @minos graph subscription
│   ├── setup_ai_assistant.sh # Optional Ditto + Minos MCP + OpenClaw/Hermes setup
│   └── auto_update.sh        # PM2 auto-update worker used by enable_auto_update.sh
├── tests/                    # Unit and integration tests
│   ├── conftest.py
│   └── test_*.py             # Tests for scoring, config, platform client, etc.
├── install.sh                # Installer (full setup or update mode)
├── enable_auto_update.sh     # Enable safe git pull + PM2 restart updates
├── disable_auto_update.sh    # Stop the PM2 auto-updater
├── setup.py                  # Interactive setup wizard
├── start-miner.sh            # Start miner (with inline wallet setup)
├── start-validator.sh        # Start validator (with inline wallet setup)
├── pm2-miner.sh              # Start / restart miner under PM2 (wraps start-miner.sh)
├── pm2-validator.sh          # Start / restart validator under PM2 (wraps start-validator.sh)
├── ecosystem.miner.config.js # PM2 app config (miner)
├── ecosystem.validator.config.js # PM2 app config (validator)
├── min_compute.yml           # Minimal compute requirements
├── requirements.txt          # Python dependencies
├── .env.miner.example        # Miner environment configuration
├── .env.validator.example    # Validator environment configuration
└── README.md                 # This document

System Prerequisites

Component	Requirement	Notes
OS	Linux (Ubuntu 20.04+), macOS 13+	Docker + Bittensor run best on Linux
CPU/RAM (Validator)	≥8 cores / 32 GB RAM	hap.py scoring benefits from cores
CPU/RAM (Miner)	≥4 cores / 8–16 GB RAM	8 GB for BCFtools, 16 GB for DeepVariant
Disk	≥60 GB (miner) / ≥100 GB (validator)	Reference: ~2 GB miner, ~14 GB validator (SDF expands ~6×). Plus per-round BAMs (~6 GB each) until cleaned.
Docker	20.10+ (24.0+ recommended)	Required for GATK, hap.py, bcftools
Python	3.10+	We test on 3.12
Bittensor	Latest pip install	Provides wallet/subtensor/dendrite APIs

Quick Start

git clone https://github.com/minos-protocol/minos_subnet.git
cd minos_subnet
bash install.sh          # First-time: full setup (venv, deps, Docker, reference data, wallet)
bash start-miner.sh      # Start as miner (choose one)
# OR
bash start-validator.sh  # Start as validator (choose one)

The start-*.sh scripts handle wallet setup on first run and automatically repair missing required runtime assets before launch, including reference data and Docker images. Run with --help to see all options, or --setup to re-run the setup wizard. If you already ran install.sh before, running it again will only update dependencies and download any new reference data (use --fresh to redo everything).

The installer automatically installs required runtime pieces where supported, including Python packages, Docker on Linux, Node/npm for PM2, missing Docker images, and reference data. It only pauses for choices that should stay under your control, such as wallet/registration, existing .env overwrite, and optional AI assistant/runtime setup.

Try mining without registering

Want to verify your variant-calling pipeline works before bonding TAO or registering a hotkey? Run the miner with --demo:

bash start-miner.sh --demo            # ephemeral keypair, no wallet needed
# or, with PM2 / systemd:
MINER_DEMO=true bash start-miner.sh   # equivalent — env var works the same as --flag
bash pm2-miner.sh --demo              # PM2 launcher with the flag

In demo mode the miner skips the chain entirely, generates an ephemeral keypair, downloads a static sandbox BAM from the platform's /v2/demo/* endpoints, runs your variant caller, and submits the result for acknowledgement. Nothing is persisted, no score is computed, no TAO is earned — it's purely a pipeline smoke test. When it prints DEMO COMPLETE, you know your Docker setup, reference data, variant caller, and platform connectivity all work end-to-end.

Switching from demo to live: the demo run creates a template .env with MINER_DEMO=true and placeholder WALLET_NAME=default / WALLET_HOTKEY=default. To switch to real mining: edit .env to set your real wallet name/hotkey, change MINER_DEMO=true → MINER_DEMO=false (or delete the line), and re-run bash start-miner.sh. Alternatively, run bash start-miner.sh --setup to redo the wallet wizard.

MinosVM: If using the MinosVM image, everything is pre-installed. Just SSH in and run:

bash scripts/minosvm_first_run.sh

The MinosVM first-run menu can start a demo miner, set up live mining, set up a validator, or launch the Minos Miner AI Assistant flow. You can still run bash start-miner.sh or bash start-validator.sh directly.

Optional Minos Miner AI Assistant

Minos includes an optional miner onboarding assistant so new miners can ask Minos-specific questions from a local runtime instead of starting with a blank generic agent. The assistant helps with demo mode, PM2/Docker issues, scoring/eligibility, public endpoint checks, safe paste-back rules, variant-calling concepts, and basic config-tuning.

The general setup menu offers:

OpenClaw runtime with Ditto skill, Minos MCP live data, and local Minos skill/persona files. This is the recommended path.
Hermes runtime with Ditto skill, Minos MCP live data, and local Minos skill/persona files.
Ditto account setup only, subscribed read-only to the public @minos knowledge graph.
Skip for now.

On MinosVM, Ditto is baseline infrastructure and the first-run prompt only asks whether to enable OpenClaw, enable Hermes, or skip the local runtime.

During a fresh miner install, bash install.sh offers to set this up after the setup wizard finishes. You can also subscribe Ditto to the public @minos graph later:

bash start-miner.sh --setup-ditto
# or directly:
bash scripts/setup_ditto_agent.sh

If you also want a local agent runtime, use the guided AI assistant setup:

bash start-miner.sh --setup-ai-assistant
# or directly:
bash scripts/setup_ai_assistant.sh

That flow defaults to OpenClaw because it gives miners a local runtime plus the @minos graph and Minos MCP live data from https://mcp.theminos.ai. If you choose OpenClaw or Hermes from the menu, it installs that runtime's Ditto skill, configures the minos MCP connection for current round/leaderboard/miner-history data, and installs a local minos-miner skill/persona bundle so the agent understands Minos setup, monitoring, variant calling, public endpoints, and safe tuning even before a Ditto lookup. OpenClaw and Hermes are installed noninteractively by default, so miners stay inside the Minos setup flow. Ditto-only remains available outside MinosVM for miners who only want the public graph subscription and no local runtime yet.

OpenClaw/Hermes still need a model provider. For 1.0.0, Minos does not install or tune local open-source models. During setup, Minos checks whether the selected runtime already has a usable provider; if not, it offers a short provider menu. OpenClaw users can choose OpenAI/Codex, Claude/Anthropic, OpenRouter, OpenClaw guided setup, or skip. Hermes users can choose Hermes/Nous Portal, full Hermes setup, or skip. Provider credentials stay inside OpenClaw, Hermes, or the provider OAuth flow; Minos does not read, log, or store model API keys.

The setup script uses the Ditto CLI to initialize or use your Ditto account, then subscribes it read-only to the public @minos knowledge graph. The launch graph is Minos SN107 Public Knowledge Graph version 1.0.0, and subscribed search results should show subscribed_graph:minos-public-knowledge-graph-1.0.0 with @minos / Minos SN107 - ... source context. On MinosVM, the default is public-graph-only: private fallback seeding is disabled unless explicitly overridden. Outside MinosVM, the script can save the same public memory-pack files into that Ditto account as a private fallback copy only if graph subscription/search cannot be verified or fallback seeding is explicitly requested. That fallback is only public Minos docs, never miner secrets, and the preferred source remains the shared @minos graph. If you choose OpenClaw or Hermes, setup installs the heyditto command globally so runtime skills can read Ditto knowledge directly. It also writes the Ditto API key into the runtime's own env file without printing it: ~/.openclaw/.env for OpenClaw and ~/.hermes/.env for Hermes. If you do not already have Ditto CLI auth, it creates a Ditto agent account, prints the private claim URL at the end of setup, and saves the same URL locally with private file permissions. Open that claim URL yourself and do not paste it into public channels, screenshots, or logs before claiming it. The setup does not upload your Minos .env, wallet files, miner configs, logs, presigned URLs, model API keys, or private validator data.

Minos MCP is configured only for public live subnet tools such as current round, leaderboard, recent rounds, miner history, subnet overview, incentives, and emissions. Ditto explains stable setup and troubleshooting concepts; MCP provides current subnet data.

For OpenClaw on headless/container VMs, Minos runs the foreground gateway under PM2 as openclaw-gateway because systemctl --user is often unavailable. Check it with openclaw gateway status or pm2 logs openclaw-gateway --lines 80. Start the local OpenClaw terminal UI with bash scripts/openclaw-tui.sh; the wrapper reads the local gateway token without printing it so miners do not hit an extra pairing prompt.

Requirements: Ditto setup needs either heyditto or Node/npm for npx -y @heyditto/cli. bash install.sh installs Node/npm where supported. OpenClaw/Hermes are only needed if you choose a runtime. They still need a model provider configured in that runtime. The recommended assistant path is:

bash scripts/setup_ai_assistant.sh --with-ditto --openclaw

Advanced runtime flags such as --openclaw, --hermes, --skip-ditto, and --dry-run are available on scripts/setup_ai_assistant.sh directly.

If OpenClaw or Hermes says it cannot use Ditto because heyditto is missing or DITTO_API_KEY is not configured, rerun the matching setup:

bash scripts/setup_ai_assistant.sh --with-ditto --openclaw
bash scripts/setup_ai_assistant.sh --with-ditto --hermes

After setup, try asking Ditto:

PM2 says my Minos miner is online but I have 0 weight. What should I check?

In normal operation, agents subscribe to the shared public @minos graph. Private fallback seeding is only for cases where graph retrieval cannot be verified or the operator explicitly requests a local fallback copy.

Running with PM2 (optional)

PM2 keeps the miner or validator running with restarts and log management. This repo runs the same start-miner.sh / start-validator.sh entrypoints under PM2 (so your venv, .env, and prerequisite checks stay identical to a manual start).

Install PM2 — bash install.sh installs or repairs Node.js/npm, then runs npm install -g pm2 automatically. If PM2 installs under an npm global directory that is not on PATH, the installer prints the exact export PATH=... line to add.
Create .env first — Run bash start-validator.sh or bash start-miner.sh once in a normal terminal so wallet/setup can run (PM2 does not provide a TTY for the interactive wizard).
Launch under PM2:

bash pm2-validator.sh   # validator: start, or restart if already registered
bash pm2-miner.sh       # miner: start, or restart if already registered

Or start from the ecosystem files directly:

pm2 start ecosystem.validator.config.js
pm2 start ecosystem.miner.config.js

Useful commands: pm2 status, pm2 logs minos-validator / pm2 logs minos-miner, pm2 save (persist process list after reboot — pair with pm2 startup per PM2 docs). The interactive setup wizard auto-generates ecosystem.<role>.config.js when PM2 is available. Demo or registered nodes are started automatically; unregistered live nodes are registered in PM2 but left stopped until you register the hotkey.

Automatic Updates with PM2

If your miner or validator already runs under PM2, you can enable safe automatic git pulls and PM2 restarts:

./enable_auto_update.sh

The setup script finds likely PM2 miner/validator processes, asks you to confirm the exact process, then starts a small PM2 updater named minos-auto-update.

Safety rules:

Local git changes or untracked files make the updater skip the pull.
Only fast-forward git updates are applied.
Only the PM2 process you confirmed is restarted.
The selected repo, branch, and PM2 process are saved in ~/.minos/auto_update.env.

Useful commands:

pm2 logs minos-auto-update
./disable_auto_update.sh

Updating

Already running Minos? Pull the latest code and run the installer — it detects your existing setup and only downloads new reference data:

git pull
bash install.sh

Your wallet, .env, and existing data are preserved. Use bash install.sh --fresh to redo a full setup if needed.

Manual setup (if you prefer not to use the install script)

1. Setup Environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment

cp .env.miner.example .env    # for miners
cp .env.validator.example .env # for validators

3. Pull Docker Images

docker pull broadinstitute/gatk:4.5.0.0
docker pull google/deepvariant:1.5.0
docker pull genonet/hap-py@sha256:03acabe84bbfba35f5a7234129d524c563f5657e1f21150a2ea2797f8e6d05f2
docker pull quay.io/biocontainers/bcftools:1.20--h8b25389_0
docker pull quay.io/biocontainers/samtools:1.20--h50ea8bc_0
# Validators only — the freebayes image is retained until in-flight
# pre-cutover rounds finish scoring, then removed in a follow-up release:
# docker pull staphb/freebayes:1.3.7

Note: The hap.py image is pinned by SHA256 digest for reproducible scoring. The tag genonet/hap-py:0.3.15 points to the same image, but validators use the pinned digest for consistency.

4. Run Setup Wizard

# Interactive wizard: configures wallet, downloads reference data, sets up .env
python setup.py

Validator Setup

Environment Variables

# Network
NETUID=107

# Wallet
WALLET_NAME=validator
WALLET_HOTKEY=default

# Platform
PLATFORM_URL=https://api.theminos.ai
PLATFORM_TIMEOUT=60

# Storage preference: hippius = Hippius SN75 first (recommended, Bittensor decentralized).
# aws_s3 = R2/AWS first. Both serve the same files; this just controls fetch order.
STORAGE_PRIMARY_BACKEND=hippius

Running the Validator

bash start-validator.sh
bash start-validator.sh --wallet-name validator   # Pre-fill wallet name
bash start-validator.sh --setup                   # Re-run setup wizard

For production-style supervision, use Running with PM2 (optional) (bash pm2-validator.sh).

Or manually:

source .venv/bin/activate
python -m neurons.validator \
  --netuid 107 \
  --subtensor.network finney \
  --wallet.name validator \
  --wallet.hotkey default

Validator Workflow

Fetch Rounds and Assignment: Poll platform for scoring rounds and this validator's primary/secondary miner assignment
Download Round Data: Download the mutated BAM, merged truth VCF, and mutations-only VCF from platform presigned URLs
Run Miner Tools: Execute assigned miners' variant-calling configs via templates, scoring primaries first and secondaries only while enough time remains
Scoring: Validate each generated VCF with hap.py against the platform truth data, then compute the AdvancedScorer result
Submit Scores: Report each per-miner score and audit artifact pointers back to the platform
Backfill and Record Round: After the scoring window closes, fetch peer scores for miners not personally covered and record complete participation
Weight Update: Submit weight history to the platform, then set on-chain weights if the validator is registered

Validator Parallelism

Each round, the validator runs many miners' variant-calling configs concurrently. Concurrency, per-job thread count, and memory ceiling are auto-tuned at startup from host CPU/RAM:

Reserves 4 cores + 16 GB for the OS, Docker daemon, and hap.py
Picks threads_per_job between 2 and 8 (DeepVariant's call_variants is single-threaded past 8)
Pins memory at 16 GB per job (DeepVariant's documented minimum)
concurrency = min(usable_cores // threads_per_job, usable_ram // 16, 8)

Examples:

Host	Auto-tune
8c / 32 GB	1 concurrent × 2 threads × 16 GB
16c / 64 GB	3 concurrent × 3 threads × 16 GB
32c / 128 GB	4 concurrent × 7 threads × 16 GB
64c / 256 GB	7 concurrent × 8 threads × 16 GB

To override, set MINOS_VALIDATOR_CONCURRENCY, SCORING_THREADS, or SCORING_MEMORY_GB in .env. Note SCORING_MEMORY_GB < 16 will OOM-crash DeepVariant submissions.

Miner Setup

Environment Variables

# Network
NETUID=107

# Wallet
WALLET_NAME=miner
WALLET_HOTKEY=default

# Miner
MINER_TEMPLATE=gatk

# Platform
PLATFORM_URL=https://api.theminos.ai
PLATFORM_TIMEOUT=60

# Storage preference: hippius = Hippius SN75 first (recommended, Bittensor decentralized).
# aws_s3 = R2/AWS first. Both serve the same files; this just controls fetch order.
STORAGE_PRIMARY_BACKEND=hippius

Running the Miner

bash start-miner.sh
bash start-miner.sh --wallet-name miner --miner-template deepvariant  # Pre-fill values
bash start-miner.sh --setup                                           # Re-run setup wizard

For production-style supervision, use Running with PM2 (optional) (bash pm2-miner.sh).

Or manually:

source .venv/bin/activate
python -m neurons.miner \
  --netuid 107 \
  --subtensor.network finney \
  --wallet.name miner \
  --wallet.hotkey default

Miner Workflow

Registration: Register with platform via hotkey authentication
Task Poll: Poll platform for pending evaluation tasks
BAM Download: Fetch benchmark BAM from platform via presigned URL
Variant Calling: Run configured variant caller (GATK, DeepVariant, or bcftools — freebayes deprecated 2026-05-09)
Config Submit: Submit tool config you've used (hyperparameters only based on the template)
Reward: Earn alpha based on accuracy score — validators re-run the config to verify

Platform Service

The Minos Platform is a hosted service at https://api.theminos.ai that handles BAM generation and synthetic mutation injection with HelixForge, file transfers via presigned URLs, and round coordination. Validators and miners connect automatically via the PLATFORM_URL environment variable — no self-hosting required.

Key Endpoints

Endpoint	Used by	Description
`POST /v2/round-status`	Miner	Poll for active rounds and presigned BAM URL
`POST /v2/submit-config`	Miner	Submit variant-calling tool config
`POST /v2/get-scoring-rounds`	Validator	Fetch rounds ready for scoring
`POST /v2/get-submissions`	Validator	Fetch all miner configs for a round
`POST /v2/get-assignment`	Validator	Get primary/secondary miner scoring assignment
`POST /v2/submit-score`	Validator	Submit per-miner scores
`POST /v2/get-backfill-scores`	Validator	Fetch peer scores after scoring window closes
`POST /v2/submit-weight-history`	Validator	Submit round scores, eligibility, and weights
`POST /v2/get-validator-state`	Validator	Recover round score state after validator restart

Storage Backends

The platform serves all per-round files (BAMs, truth VCFs, mutations VCFs) via short-lived presigned URLs and a primary + backup pair, so a miner or validator never needs storage credentials of its own. Three backends sit behind the platform:

Backend	Role
Cloudflare R2	Primary for per-round artifacts when enabled platform-side (free egress)
AWS S3	Fallback for per-round artifacts (`genotypenet-platform` bucket)
Hippius (SN75)	Decentralized backup, Bittensor-native (`genotypenet-mutations` bucket)

Reference data (FASTA, FAI, dict, RTG SDF) is served via the indirected URL https://api.theminos.ai/reference/... which 302-redirects to the active backend (currently a public R2 bucket). Setup downloads through this URL only — no direct R2/S3 hostnames are baked into the subnet code.

The STORAGE_PRIMARY_BACKEND env var only controls fetch order on the client side:

hippius (default) — try the Hippius URL first, fall back to the R2/AWS URL.
aws_s3 — try the R2/AWS URL first, fall back to Hippius. (The label says "aws_s3" for backwards compatibility, but the platform may serve either R2 or AWS in this slot — both behave identically from the client's perspective.)

Both URLs always point at the same files. Pick whichever is faster from your network.

Scoring System

hap.py Validation

Validators run each miner's tool config and score the resulting VCF from that against the truth data shared by the platform with them using hap.py. Scores are combined by Minos' developed AdvancedScorer into a scaled 0–100 final score that balances accuracy and precision with the following components:

Component	Weight
Core F1	60%
Completeness	15%
FP Rate	15%
Quality	10%

Round Score Tracking

The raw AdvancedScorer output (0-100) is normalized to a 0-1 scale and used as the miner's score for that round. Winners are selected from the current round's valid Advanced Score only; historical score carryover is not used.

# AdvancedScorer returns 0-100, normalized to 0-1 for round scoring
combined_final = advanced_score / 100.0
current_score = combined_final

Only finite scores where 0 < current_score <= 1.0 are eligible for ranking. Rounds with no valid local or backfilled scores fail closed and do not reuse previous-round scores. The validator and platform also filter the synthetic all-zero input fingerprint around 0.25 so empty or invalid calls cannot become winners.

Weight Distribution

Validators burn 87% of their weight, give the top eligible current-round miner 10%, and split the remaining 3% as ranked pruning dust across eligible ranks #2 through #10 using 0.8 geometric weighting. If fewer dust recipients exist, that 3% is renormalized across the available ranks; if no dust recipients exist, unused dust is sent to burn.

Eligibility requires scoring in at least 10 of the last 20 rounds, including the current round. Miners below the participation threshold receive 0 weight until they qualify. Close current-round ties use deterministic round data from the validator/platform flow; historical scores are not part of the ranking.

Monitoring & Troubleshooting

Common Issues

Symptom	Cause	Fix
`docker: permission denied`	User not in docker group	`sudo usermod -aG docker $USER && newgrp docker`
`GATK timeout`	Insufficient resources	Increase threads/memory or timeout
DeepVariant OOM / killed	<16 GB available to the container	DeepVariant needs ≥16 GB. Free RAM, close other tools, or switch template to GATK/BCFtools
`Platform 401 error`	Invalid sig or unregistered hotkey	Ensure wallet hotkey is registered on the metagraph
`No miners available`	No registered miners	Check metagraph for active miners
`hap.py zero scores`	VCF format issues	Ensure single-sample VCF output
Round skipped, "<10min left"	Submitted too late	Miner needs ≥10 min remaining to start a round. Check clock skew (`timedatectl`) and platform connectivity speed
Reference download stuck/slow	Platform redirect or transient network	Setup retries once automatically. If it still fails, re-run `python setup.py --update-data-only`
Validator: "no scoring rounds"	Round still in submission window	Validators only score AFTER the submission window closes. Wait for the next tempo boundary
Earning 0 weight as miner	Not eligible yet, no valid current score, or outside the top current-round winners	Need >=10 of last 20 rounds participated, then a stronger current-round Advanced Score. See tuning_guide

Logs

# PM2 (recommended)
pm2 logs minos-miner
pm2 logs minos-validator

# systemd (if using systemd service)
journalctl -u minos-miner -f
journalctl -u minos-validator -f

# Direct (if running manually)
# Output streams to terminal

Health Checks

# Platform health
curl https://api.theminos.ai/health

# Metagraph status
btcli subnet metagraph --netuid 107

Additional Documentation

neurons/README.md - Detailed miner/validator documentation
utils/README.md - Utility modules reference
docs/architecture.md - System architecture deep dive
docs/tuning_guide.md - Miner tuning guide (scoring breakdown, parameters, strategy)
docs/hap_py_docker.md - hap.py Docker image reference
docs/ai-assistant/memory-pack/README.md - Public Minos SN107 knowledge source for Ditto and agent runtimes
docs/ai-assistant/README.md - OpenClaw/Hermes local skill, persona, and model setup assets
scripts/verify.sh - Pre-flight environment check (bash scripts/verify.sh --miner)
scripts/demo.sh - Run a single demo round end-to-end (bash scripts/demo.sh)
scripts/minosvm_first_run.sh - Friendly MinosVM first-run menu
scripts/prompt_ai_assistant.sh - One-time AI assistant prompt for installs and VM first run
scripts/setup_ditto_agent.sh - Subscribe Ditto to the public @minos knowledge graph
scripts/setup_ai_assistant.sh - Set up Ditto first, then optionally connect OpenClaw or Hermes

Links

GitHub: github.com/minos-protocol/minos_subnet

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
base		base
configs		configs
docs		docs
neurons		neurons
scripts		scripts
templates		templates
tests		tests
utils		utils
.env.miner.example		.env.miner.example
.env.validator.example		.env.validator.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
disable_auto_update.sh		disable_auto_update.sh
ecosystem.miner.config.js		ecosystem.miner.config.js
ecosystem.validator.config.js		ecosystem.validator.config.js
enable_auto_update.sh		enable_auto_update.sh
install.sh		install.sh
min_compute.yml		min_compute.yml
pm2-miner.sh		pm2-miner.sh
pm2-validator.sh		pm2-validator.sh
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
start-miner.sh		start-miner.sh
start-validator.sh		start-validator.sh

Folders and files

Latest commit

History

Repository files navigation

Minos – Decentralized Genomic Variant Calling & Benchmarking Platform

Table of Contents

Architecture Overview

Repository Layout

System Prerequisites

Quick Start

Try mining without registering

Optional Minos Miner AI Assistant

Running with PM2 (optional)

Automatic Updates with PM2

Updating

1. Setup Environment

2. Configure Environment

3. Pull Docker Images

4. Run Setup Wizard

Validator Setup

Environment Variables

Running the Validator

Validator Workflow

Validator Parallelism

Miner Setup

Environment Variables

Running the Miner

Miner Workflow

Platform Service

Key Endpoints

Storage Backends

Scoring System

hap.py Validation

Round Score Tracking

Weight Distribution

Monitoring & Troubleshooting

Common Issues

Logs

Health Checks

Additional Documentation

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages