Perturb

# Perturb Subnet

Perturb is a decentralized adversarial robustness network built on Bittensor. Miners compete to find adversarial examples — imperceptible input perturbations that cause state-of-the-art image classifiers to fail — while validators construct challenges from real images, verify every response with mathematical precision, and reward the best attackers with on-chain emissions.

Modern AI models achieve remarkable accuracy on clean data yet remain catastrophically brittle: a perturbation invisible to any human observer can make a production classifier misclassify a tumor scan, a stop sign, or a fraudulent transaction. The tooling to systematically discover these vulnerabilities is fragmented, expensive, and static. Perturb replaces it with a financially incentivized, continuously improving adversarial testing network — every day miners compete, attacks get stronger and the network's outputs get more valuable.

The network produces two commercially valuable outputs:

- **Adversarial training dataset** — a continuously growing corpus of verified adversarial examples, the raw material for adversarial training (the most effective known defense)
- **Model robustness certificates** — on-chain, auditable proof of adversarial evaluation, relevant to EU AI Act conformity and enterprise AI procurement

Why Bittensor: finding an adversarial example is computationally hard, but verifying one is trivially cheap — run the model, compare the prediction, measure the perturbation norm. This verification asymmetry makes the incentive mechanism clean, objective, and manipulation-resistant, while TAO emissions drive a level of continuous attack research no salaried red team can match.

Read the full vision and roadmap in the [Perturb whitepaper](https://www.perturbai.io/whitepaper).

This repository provides:

- validator node implementation (`neurons/validator.py`)
- baseline miner implementation (`neurons/miner.py`)
- miner model-track scripts: fine-tune, evaluate and submit an adversarially trained EfficientNetV2-L (`training/`)
- one-command launchers for validator and miner

Miners are rewarded on two tracks, both scored by validators:

- **Adversarial scanning (80% of miner emissions)**: every two minutes, find an imperceptible perturbation of the current task image that flips EfficientNetV2-L's prediction.
- **Adversarial training (20% of miner emissions)**: commit a fine-tuned EfficientNetV2-L on-chain; once a day validators evaluate every committed model on ImageNet-1k and the latest adversarial dataset, and the best model of the day takes the whole model share.

## Architecture

### Validator responsibilities

- Fetch the current task image (an ImageNet-1k training image published by the task generator) and run the fixed classifier (`EfficientNetV2-L`) on it
- Verify every submitted miner image and compute scanning rewards
- Once a day (00:00 UTC), evaluate all committed miner models and pick the day's model winner
- Report scanning results and model evaluations to the API; set on-chain weights once per epoch from the cross-validator consensus

### Miner responsibilities

- Poll the task API for the current task
- Run baseline PGD-style attack
- Upload the perturbed image and submit its URL
- Optionally, fine-tune EfficientNetV2-L with `training/train.py` and publish it with `training/submit.py`
- Let validator handle all authoritative verification and scoring

### Challenge lifecycle

1. The team task generator samples an ImageNet-1k train image and publishes one API task
2. Miners poll the task API, perturb the task image, upload the result, and submit the image URL
3. Validators read submitted miner images from the API
4. Validators score responses and report the full miner results

## Hardware and System Requirements

### Miner

- Minimum: 4 vCPU, 16 GB RAM, 50 GB SSD, stable 20+ Mbps network
- Recommended: 8 vCPU, 32 GB RAM, NVIDIA GPU with 8+ GB VRAM, 100+ GB SSD

### Validator

- Minimum: 8 vCPU, 32 GB RAM, NVIDIA GPU with 12+ GB VRAM, 100 GB SSD
- Recommended: 16 vCPU, 64 GB RAM, NVIDIA GPU with 24+ GB VRAM, 200 GB SSD

### Common software prerequisites

- Python 3.10+
- Node.js 18+ (includes `npm`) for PM2 installation
- `pip` and virtualenv support (`python -m venv`)
- OS build tools needed by Python wheels
- For GPU usage: correct NVIDIA driver + CUDA stack compatible with installed PyTorch

## Common Installation (Do Once)

Run role-specific setup once before starting nodes:

```bash
git clone https://github.com/0xsigurd/Perturb
cd Perturb
```

For miner setup:

```bash
bash ./scripts/setup_common.sh miner
```

For validator setup:

```bash
bash ./scripts/setup_common.sh validator
```

`setup_common.sh` behavior by role:

- both roles: install PM2, create `.venv`, install Python/Bittensor dependencies

If `npm: command not found`, install Node.js first, then rerun:

macOS (Homebrew):

```bash
brew install node
node --version
npm --version
bash ./scripts/setup_common.sh
```

Ubuntu/Debian:

```bash
sudo apt-get update
sudo apt-get install -y nodejs npm
node --version
npm --version
bash ./scripts/setup_common.sh
```

## Installation and Setup (Validator Side)

This section is specifically for validator operators.

### 1) Configure validator runtime

Create validator env:

```bash
cp scripts/validator.env.example scripts/validator.env
```

Edit required fields in `scripts/validator.env`:

- `WALLET_NAME`
- `WALLET_HOTKEY`
- `PERTURB_API_KEY`
- `HF_TOKEN`: a Hugging Face token whose account has accepted the terms of the gated [`ILSVRC/imagenet-1k`](https://huggingface.co/datasets/ILSVRC/imagenet-1k) dataset. The daily model evaluation streams ImageNet-1k validation samples with it; `python scripts/check_imagenet1k.py` verifies access.

Optional:

- `PERTURB_API_BASE_URL`
- `LOG_LEVEL` (`DEBUG` default, set `INFO`/`WARNING`/`ERROR` for quieter logs)
- `PERTURB_MODEL_EVAL_*` (see *Adversarial training track* below)

### 2) Start validator

```bash
bash ./scripts/run_validator.sh