Attune

<p align="center">
  <img src="assets/header.png" alt="Attune: the open frontier for adaptive robot intelligence" width="100%">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/bittensor-subnet-black.svg" alt="Bittensor subnet">
</p>

<p align="center">
  <a href="#how-it-works">How it works</a> ·
  <a href="#mining">Mining</a> ·
  <a href="#validating">Validating</a> ·
  <a href="#horizon">Horizon</a> ·
  <a href="#development">Development</a>
</p>

---

**Attune** is a Bittensor subnet for robot foundation models, built by [Robotensor](https://www.robotensor.ai). Miners submit policy weights;
validators score them in simulation and set weights on chain. The rest of the emission pays the
people who collect robot data on Attune Horizon: see [Horizon](#horizon).

| Share of miner emission | Goes to |
|---|---|
| 30% | **Vector**, the policy competition below |
| 70% | **Horizon**, Robotensor's data platform: one vault UID, paid out to the people who collect data there |

The first competition is **Vector**: a policy (`vector_v1.1`) is shown one
demonstration of a task and must complete the same task in a different scene.

## How it works

| | |
|---|---|
| **Submission** | A Hugging Face model repo containing only `model.safetensors` (and an optional README). |
| **Commitment** | `vector:<owner>/<repo>@<commit>.<digest>` on chain: the revision and the sha256 of `model.safetensors`, in base64url. `attune miner commit` builds it; repo ids can be up to 49 characters long. |
| **Queue** | The validator queues a commitment as soon as it reads it from the chain, oldest first. **One submission per hotkey**: once a hotkey is queued, its later commitments are refused. |
| **Scoring** | King of the hill. Each queued submission duels the current king on 240 units (16 tasks × 15), seeded from the finalized block when the duel starts. That block must come after the commitment. The challenger takes the crown when its average success rate beats the king's by 3+ points. |
| **Rewards** | The lane's share (30% of miner emission) goes to the 4 most recent champions: 40% / 30% / 20% / 10%, newest first. |

### Repositories and the kings' weights

A miner's repo is gated, with the permitted validator accounts (`hub.PERMITTED_VALIDATORS`) let in
and nobody else. The validator checks it when the entry's turn comes, and downloads the weights then.

- **Challenger not downloadable.** If the validator can't download the challenger's repo at its
  turn (deleted, private, gated without the validator let in, the revision is gone, or the Hub
  errors about it), it tries three times in all, at least 90 seconds apart. Then the entry is
  dropped as `missing` and the validator duels the next one. The hotkey's one submission is used up.
- **Failures on the validator's side.** An entry whose duel keeps failing (three times) goes behind
  the rest of the queue and keeps its submission, so nothing it does can hold the others up.
- **The validator's own problem.** A try only counts while the validator's token works and the Hub
  answers it. If the token is revoked or the Hub is down, the queue waits and nobody loses anything.
- **Kings.** From the download on, the duel runs on the validator's copy, and nothing asks the miner
  to keep the repo up. The four newest crowned models - the four that are paid - are kept by the
  validator (`var/<config name>/vector/kings/`) and mirrored to a public model repo (`kings_repo`), so
  anyone can take the weights a crown was won with. A new king pushes the oldest of the four out. No
  duel starts until the results hold every record and the reigning king's weights are on the validator
  and in the kings repo; the queue waits meanwhile, and a king never forfeits for lack of its weights.

Submissions are weights only. Nothing a miner uploads is executed or unpickled: the safetensors
header is checked against the pinned architecture before any tensor is read. Weights that don't
hash to the committed digest are refused. Weights identical to an earlier commitment's are refused
as duplicates, and the earlier commitment keeps them.

## Components

| Repo | Role |
|---|---|
| [`attune-subnet`](https://github.com/robotensor/attune-subnet) | Chain side: commitments, queue, seeds, weights, validator loop, miner CLI |
| [`vector-orchestrator`](https://github.com/robotensor/vector-orchestrator) | Duel engine, result store, `vector-runtime` and `vector-protocol` |
| [`RoboTwin-Vector`](https://github.com/robotensor/RoboTwin-Vector) | RoboTwin 2.0 fork with the level gate and the benchmark harness |

## Mining

A submission is a `vector_v1.1` weights file: `model.safetensors`, with exactly the tensors the
architecture pins (`vector_runtime/vector_v1.1.json` in the orchestrator).

```bash
pip install robotensor-attune

attune miner check --dir submission/

export HF_TOKEN=...
attune miner submit --dir submission/ --repo <you>/vector-mine \
    --network finney --netuid <N> --wallet.name miner --wallet.hotkey default
```

`submit` makes the repo private and gated (manual approval), lets the permitted validator accounts
in, uploads, commits on chain, then takes the repo out of private, gated still. It stays private until
then because a gated repo still shows anyone its commit and the weights' hash, which is all it takes
to commit them first. Nobody else can download your weights; if you are crowned, the validator
publishes them in its kings repo. The repo must be downloadable by the validator at the one moment
its turn comes: a repo it can't download then is dropped as missing. If `submit` reports the repo is
still private, run `attune miner reveal --repo <you>/vector-mine` at once.

Check your entry with:

```bash
attune miner status --hotkey <ss58> --network finney --netuid <N>
```

##