Aurelius

# Aurelius Protocol — subnet 37 miner

Aurelius is Bittensor subnet **37**. Miners build tools that help explain and work with language
models, submit them for evaluation, and compete for rewards based on their usefulness. Each tool
type has its own **lane** with its own evaluation rules. Sparse autoencoders (SAEs) are the first
lane; probes, steering vectors and other tools can follow as their rules are published.

This repository contains the miner, the SAE submission tools and the shared protocol they need.

- **Incentives are in open beta** and change frequently. Rewards depend on winning your lane's
  evaluation, scaled by the subnet 37 alpha you hold. Read [INCENTIVES.md](INCENTIVES.md) before
  you start; the miner asks you to confirm you have.
- **Lane guides:** competition rules, training and submission live in the
  [lanes folder](lanes/README.md). Start with [Lane 1: SAEs](lanes/lane1.md).

## What you need

- Linux with Git, curl, Bash, Python **3.11 or 3.12** and [uv](https://docs.astral.sh/uv/)
- A publicly reachable IPv4 address and persistent disk
- A Bittensor wallet with a hotkey **registered on subnet 37**, and TAO for fees
- Subnet 37 alpha for evaluation fees (1 WT per alpha; one SAE evaluation costs 10 WT)
- A trained SAE bundle. Serving and checks run on CPU; training needs your own GPU compute.

## 1. Install

```sh
git clone https://github.com/Aurelius-Protocol/Aurelius-Protocol.git
cd Aurelius-Protocol
uv python install 3.12
uv sync --all-packages --extra bt --no-dev --frozen --python 3.12
source .venv/bin/activate
```

## 2. Prepare your wallet

The serving machine needs only your hotkey, never your private coldkey. If you don't have a
registered hotkey yet, follow the [Bittensor mining guide](https://www.bittensor.com/docs/guides/mining).

On your wallet machine, create a hotkey-only copy of the wallet:

```sh
python scripts/prepare_wallet_view.py --source "$HOME/.bittensor/wallets" \
  --output "$PWD/miner-wallets" --wallet miner --hotkey default \
  --hotkey-ss58 YOUR_REGISTERED_HOTKEY_SS58
```

Use your own wallet and hotkey names. Copy the generated `miner-wallets` directory to the serving
machine, keeping its permissions (`0700` directories, `0600` files), and set
`AURELIUS_BT_WALLET_PATH` to its absolute path.

## 3. Configure and serve

```sh
cp .env.example .env
# Edit .env: replace every REPLACE_WITH value.
set -a
. ./.env
set +a
umask 077
mkdir -p "$AURELIUS_MINER_DATA" "$AURELIUS_AXON_PUBLISH_STATE_DIR" \
  "$(dirname "$AURELIUS_BITTENSOR_NONCE_DB")" "$(dirname "$AURELIUS_MINER_JOURNAL")"
chmod 700 "$AURELIUS_AXON_PUBLISH_STATE_DIR"
aurelius-miner serve --netuid "$NETUID" --port 8091
```

- Allow inbound **TCP 8091**. Behind NAT, forward your advertised port to it. Keep port **8092**
  (local health check) private.
- The first `serve` or `fund` shows the [incentive terms](INCENTIVES.md) and asks you to confirm
  you have read and agree to them. Under a process supervisor or Docker with no terminal, set
  `AURELIUS_ACCEPT_INCENTIVES=yes` or pass `--accept-incentives`.
- `serve` runs in the foreground. Leave it running and use a second terminal, with the same
  `.env` exported, for everything else. Run it under a supervisor in production.
- Keep the wallet and state directories across restarts. Never delete the journals to force a
  resubmission.

Check that it is up:

```sh
curl --fail http://127.0.0.1:8092/health                 # on the miner
curl --fail http://YOUR_PUBLIC_IPV4:8091/health          # from another machine
```

Expect HTTP 200, `status: "ok"` and your hotkey. Until you stage a candidate, the miner serves an
idle response; a healthy miner alone earns nothing.

## 4. Fund evaluations

`fund` supports reviewed mainnet runtime 488 and retained 475/477/479/481 profiles. It checks
the exact code and metadata against the server's funding terms before unlocking or sending.
Unknown runtimes refuse.
A successful chain transfer alone does not establish WT credit; wait for the signed receipt.

Evaluations are paid in work-tokens (WT), bought with subnet 37 alpha. Run `fund` on your
**wallet machine**; the coldkey must own your registered hotkey.

```sh
aurelius-miner fund --alpha 10 --wallet-name miner \
  --wallet-path "$HOME/.bittensor/wallets" --intent-dir "$PWD/funding/purchase-001"
# Review the amount, destination and fee, then rerun the same command with --execute.
```

- Credit is confirmed by a signed WT receipt, not by the chain transfer alone.
- If the result is lost or pending, rerun the same command with the same `--intent-dir` to check
  it. Use a new directory only for a new purchase.
- Check your balance with `aurelius-miner economics --netuid 37`.

Buying WT does not improve your score, and the alpha you spend no longer counts toward your
payout multiplier. See [INCENTIVES.md](INCENTIVES.md#work-tokens).

## 5. Build and submit

Follow [Lane 1](lanes/lane1.md) to train a compatible SAE, check the bundle, upload it and stage
it for the next window. No pretrained bundle is included. **Uploading alone is not submitting:**
the evaluator pulls your staged candidate, and the WT charge commits it to the epoch.

After the epoch closes, check your result and charges:

```sh
aurelius-sae status --refresh --accounting --netuid 37
```

This shows your verdict and its explanation, measured scores, your ladder rank, and whether a
charge or refund was recorded.

## Optional automatic winner renewal

The standard miner does not renew just because it is online or has WT. You can opt in to
`aurelius-sae renew` below. Keep `aurelius-miner serve` running separately.

**Holding the incumbent title is free:** empty epochs retain it until a challenger wins under
the comparison rules. Reference comparisons do not charge the incumbent. **Earning rewards
requires eligibility:** the current paid result stays fresh for 3,600 blocks (about 12 hours
at 12 seconds/block). There is a conditional, bounded 48-hour payout grace; it is not a new
paid result or a pr