Cortex

<h1 align="center">Cortex</h1>

<p align="center">
  <img src="docs/assets/cortex-hero.png" alt="Cortex: miners, challenge containers, a sealing gateway and validators on Bittensor subnet 100" width="100%">
</p>

<p align="center">
  <b>An autonomous research network on Bittensor subnet 100.</b> Miners compete in challenges, a master seals each epoch into one bundle, and validators verify that bundle and submit the weights on-chain.
</p>

<p align="center">
  <a href="LICENSE"><img alt="license Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-6aa84f"></a>
  <img alt="python 3.12" src="https://img.shields.io/badge/python-3.12-1f6feb">
  <img alt="status research" src="https://img.shields.io/badge/status-research-e07b39">
  <img alt="netuid 100" src="https://img.shields.io/badge/netuid-100-8957e5">
  <img alt="Bittensor" src="https://img.shields.io/badge/Bittensor-subnet-555555">
</p>

<p align="center">
  <a href="docs/index.md">Documentation</a> ·
  <a href="https://cortex.foundation">Website</a> ·
  <a href="docs/validator-quickstart.md">Validator guide</a> ·
  <a href="docs/external-miner/README.md">Miner guides</a> ·
  <a href="docs/ARCHITECTURE.md">Architecture</a> ·
  <a href="docs/CHALLENGES.md">Challenges</a> ·
  <a href="docs/THREAT_MODEL.md">Threat model</a> ·
  <a href="LICENSE">License</a>
</p>

> [!WARNING]
> **Research software.** Cortex is experimental. Interfaces, wire formats and emission shares can change. Offline tests exercise submission, scoring, sealing and validator dispatch through fake external boundaries, and a passing test is not proof of a live deployment or of on-chain payment. Don't use it to manage funds you can't afford to lose.

---

## What is Cortex

Cortex is the subnet that runs research competitions. Each competition is a **challenge**: a container with its own rules, its own miners and its own scoring. Miners submit work, the challenge scores it, and Cortex turns the scores into emission.

Two roles keep that honest:

- The **master** runs the gateway, Proof and every challenge container. At the end of each epoch it collects one score leaf per miner and seals the epoch into an unsigned bundle.
- A **validator** runs none of that. It downloads the sealed bundle, checks its hashes, Merkle root and the gateway-served challenge profile against the chain, and submits the weights.

The challenge profile (`config/challenges.toml`, served at `GET /v1/trust`) sets each challenge's emission share. If a challenge earns less than its share, the shortfall burns to UID 0. It never moves to another challenge.

Challenges today:

| Challenge | What miners do | Repository |
| --- | --- | --- |
| `bounty` | Report vulnerabilities in products | [CortexLM/bounty](https://github.com/CortexLM/bounty) |
| `hypertrain` | Decentralized, verifiable LLM pretraining (research stage) | [CortexLM/hypertrain](https://github.com/CortexLM/hypertrain) |

A further challenge, Sentinel, is planned and is not live. See [docs/ecosystem.md](docs/ecosystem.md).

## The Cortex ecosystem

<p align="center">
  <img src="docs/assets/cortex-ecosystem.png" alt="Cortex architecture: challenges feed the Cortex network, which powers the Cortex apps" width="100%">
</p>

Cortex is the engine behind a family of products. Miners improve models and detectors through challenges, and the apps are where those improvements are meant to ship.

| App | What the challenges give it | Status |
| --- | --- | --- |
| Cortex Chat | Models from Hypertrain | Hypertrain is research stage; monetization is PLANNED |
| Cortex Decisions | Models from Hypertrain | Hypertrain is research stage; monetization is PLANNED |
| Cortex Security Cloud | Vulnerability findings from Bounty today; Sentinel is PLANNED to improve it | Sentinel is PLANNED, not live |
| Cortex Code | Models from Hypertrain | Hypertrain is research stage; monetization is PLANNED |
| Cortex Bot | Models from Hypertrain | Hypertrain is research stage; monetization is PLANNED |

Sentinel is planned as a miner-improved competitor to CodeRabbit and Greptile, positioned inside Cortex Security Cloud. None of it exists yet. Monetizing Hypertrain models in the apps is also a plan, not a shipped feature. Details are in [docs/ecosystem.md](docs/ecosystem.md).

## How it works

### 1. One epoch

```mermaid
flowchart LR
    M["Miner"] --> C["Challenge container"] --> L["Score leaf"] --> G["Gateway seals epoch"] --> V["Validators verify"] --> N["Weights on chain"]
```

A miner submits work to a challenge. The challenge scores it and the master records a leaf for that miner. When the epoch ends, the gateway seals all leaves into one bundle. Validators fetch the bundle from `GET https://chain.joinbase.ai/v1/weights/latest`, recompute the weights from the leaves and submit them to Bittensor.

### 2. Who runs what

```mermaid
flowchart LR
    subgraph Master["Master operator machine"]
        GW["Gateway"]
        P["Proof"]
        CH["Challenge containers"]
        SUP["Challenge supervisor"]
    end
    subgraph Val["Any validator"]
        VAL["cortex validator"]
    end
    GW -->|"sealed bundle"| VAL
    VAL -->|"weights"| CHAIN["Bittensor"]
```

| Role | Runs | Command |
| --- | --- | --- |
| master | gateway, Proof, [challenge containers](docs/CHALLENGES.md), auto-updater | `cortex master` and `cortex challenge-supervisor` |
| validator | verification and weight submission, nothing else | `cortex validator` |

Validators never run challenge containers or Proof evaluation, rent GPUs or hold miner provider credentials.

## Run a validator in one command

The master runs only on the master operator's machine. Any operator with a registered hotkey can run a validator, and a script does the setup. Miners use the miner CLI instead.

```bash
sudo apt-get install libsodium23
uv sync --locked --extra chain

export WALLET_NAME=validator WALLET_HOTKEY=default

scripts/run-validator.sh --verify-only   # one verification, never submits
scripts/run-validator.sh