Aurelius

# Aurelius Protocol

A Bittensor subnet for moral reasoning alignment. Miners submit structured ethical-dilemma
scenario configurations; validators score them through an 8-stage pipeline and run
accepted scenarios through [Concordia](https://github.com/google-deepmind/concordia)
generative-agent simulations. The resulting transcripts form training data that improves
LLM performance on moral reasoning benchmarks (MoReBench).

---

## Recommended setup: the published Docker image

We publish validator, miner, and simulation images to **public GHCR** — no registry auth
required:

| | Testnet (subnet **455**, `test`) | Mainnet (subnet **37**, `finney`) |
|---|---|---|
| Validator image | `ghcr.io/aurelius-protocol/aurelius-validator:testnet` | `ghcr.io/aurelius-protocol/aurelius-validator:latest` |
| Miner image | `ghcr.io/aurelius-protocol/aurelius-miner:testnet` | `ghcr.io/aurelius-protocol/aurelius-miner:latest` |
| Simulation sidecar | `…/aurelius-concordia:testnet` (pulled automatically) | `…/aurelius-concordia:latest` |

The published image is the supported path for running a validator. The validator's
stage-7 pipeline launches sandboxed Concordia simulation containers via a Docker socket,
so it expects to run inside a container that has access to the host's Docker daemon via
the socket proxy — which the quickstart below sets up for you. Source checkouts are great
for development, CI, and reading the code; for operating a validator, the image is the
path that has working simulation out of the box.

Every push to `main` rebuilds the mainnet `:latest` tag; every push to `testnet` rebuilds
the `:testnet` tag.

---

## Quickstart — Mainnet validator (SN 37)

Prerequisites:

- Docker 20.10+ and `docker compose`
- A Bittensor wallet registered on mainnet `netuid 37`
  (`btcli subnet register --netuid 37 --network finney`) — registration costs TAO
- An OpenAI-compatible LLM API key — [DeepSeek](https://platform.deepseek.com/) is the
  default and cheapest.

### 1. Write a minimal `.env`

These four variables are the full operator-side config. The `ENVIRONMENT` profile
auto-selects subnet, network, Central API URL, simulation resources, and safety flags —
setting any of those directly is almost never necessary.

```bash
cat > .env <<'EOF'
ENVIRONMENT=mainnet
WALLET_NAME=<your-wallet>
WALLET_HOTKEY=<your-hotkey>
LLM_API_KEY=<your-openai-compatible-api-key>
EOF
```

If you're adapting an older `.env` from a previous release, it's easier to start from this
minimal template than to prune the old one — a legacy variable like `CENTRAL_API_URL=` or
`BT_NETUID=` can override the profile default if it's still present. See
[Configuration](#configuration) for the full list and when an override makes sense.

### 2. Docker compose with socket-proxy sidecar

The validator reaches the Docker daemon through
[`tecnativa/docker-socket-proxy`](https://github.com/Tecnativa/docker-socket-proxy), which
restricts the socket to only the API calls the validator actually uses.

```bash
cat > docker-compose.yml <<'EOF'
services:
  aurelius-validator:
    image: ghcr.io/aurelius-protocol/aurelius-validator:latest
    container_name: aurelius-validator
    restart: unless-stopped
    env_file: .env
    environment:
      DOCKER_HOST: tcp://docker-proxy:2375
    cap_add: [NET_ADMIN]
    volumes:
      - ~/.bittensor/wallets:/home/appuser/.bittensor/wallets:ro
      - ./data:/app/data
      - ./simdata:/sim-data
    depends_on: [docker-proxy]
    labels:
      com.centurylinklabs.watchtower.enable: "true"

  docker-proxy:
    image: tecnativa/docker-socket-proxy:0.3.0
    container_name: docker-proxy
    restart: unless-stopped
    environment: { CONTAINERS: 1, IMAGES: 1, POST: 1, NETWORKS: 1 }
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
EOF
```

### 3. Bring it up

```bash
mkdir -p data simdata
docker compose up -d
docker compose logs -f aurelius-validator
```

The first minute of logs should show: `Validator permit confirmed`, `Authenticated with
Central API`, `Clock drift check passed`, `Remote config refreshed`, and a `Config
summary` line ending with `env=mainnet network=finney
api_url=https://new-collector-api-production.up.railway.app llm_model=deepseek-chat …
burn_mode=True`. Cycle summaries then print every few minutes.

If any of those are missing or followed by warnings, see [Troubleshooting](#troubleshooting).

---

## Quickstart — Testnet validator (SN 455)

Identical shape, different tag and environment:

```bash
cat > .env <<'EOF'
ENVIRONMENT=testnet
WALLET_NAME=<your-wallet>
WALLET_HOTKEY=<your-hotkey>
LLM_API_KEY=<your-openai-compatible-api-key>
EOF
```

Register on `netuid 455` on `network test`, and swap `:latest` → `:testnet` in the
compose file. Everything else — socket proxy, volumes, labels — is identical.

---

## Quickstart — Miner

### What the miner does

A miner is a Bittensor axon that serves a **library of operator-authored scenario
configs**. When a validator queries with a `ScenarioConfigSynapse`
([`aurelius/protocol.py`](aurelius/protocol.py)), the miner returns the next config from
its library in round-robin order, stamped with a `work_id` and signed by the miner's
hotkey so the validator can charge the submission against the miner's work-token balance
on acceptance. The validator runs the returned config through an 8-stage pipeline
(schema, rate-limit, novelty, classifier, Concordia simulation, etc.) and sets on-chain
weights based on the outcome. Miners do **not** generate configs at request time — the
library is loaded at startup from a directory on disk.

That shape means two things for an operator: you need to (a) author some scenario JSON
files, and (b) have a work-token balance that validators can spend.

### Prerequisites

- Docker 20.10+
- A Bittensor wallet registered on mainnet `netuid 37`
  (`btcli subnet register --netuid 37 --network finney`)
- A publicly reachable IP and an open inbound TCP port for the axon (default `8091`)
- One or more scenario config