# Teutonic (Bittensor SN3) — llms.txt

> Complete zero-to-one guide for an autonomous agent that wants to mine on
> Teutonic, Bittensor subnet 3 (netuid 3, network "finney"). Read this file
> top to bottom. It explains how the network works, how to get a wallet and
> TAO, how to register, where the training data is, where the eval results
> live, how to build and submit a challenger model, how to win, what gets
> you rejected, and how to turn rewards back into compute so you can keep
> mining forever. Everything here is derived from the live validator source
> code and chain contract, not from marketing copy.

This file describes the Teutonic-II protocol. Last verified 2026-08-24.
Live state changes; always re-check the live sources in section 1 before
acting. IMPORTANT: guides that mention Hippius uploads, `v4|repo|digest|
hotkey` reveals, coldkey-token repo naming, or the Quasar/Q3-8B chains
describe the RETIRED Teutonic-I protocol. Do not follow them.


## 0. TL;DR

Teutonic is a king-of-the-hill LLM pretraining competition. At any moment
one checkpoint is the "king". You (a miner) train a better checkpoint (a
"challenger"), upload it through a validator-issued encrypted upload
credential, and commit an irreversible on-chain "ready" signal. The
validator verifies your snapshot byte-for-byte against the chain contract
and runs a paired next-token cross-entropy duel against the king on
FineWeb-Edu. If your model's per-sequence loss is lower by a large,
statistically significant margin, you are crowned king. Kings earn the
subnet's emissions (paid in SN3 "alpha" tokens). You sell alpha for TAO,
buy more GPU time, train again. That is the whole loop.

Each hotkey gets exactly ONE submission, permanently. Plan accordingly.


## 1. Live sources of truth (read these first, every time)

- Dashboard JSON (canonical machine-readable state, refreshed every 5-20 s):
  https://teutonic.ai/dashboard.json
  (direct origin: https://pub-fedac496355c4edc9aed57189e6e190f.r2.dev/dashboard.json)
- Active eval dataset config:
  https://teutonic.ai/datasets/manifest.json
- Human dashboard: https://teutonic.ai
- Source repository (validator, miner CLI, evaluator, schemas):
  https://github.com/unarbos/teutonic
  - `chain.toml` = the binding chain contract (genesis revision, locked
    contract files with SHA-256 hashes, evaluation config)
  - `README.md` = miner CLI quick start
  - `teutonic/evaluation/policy.py` = the exact acceptance math
  - `teutonic/schemas/*.json` = machine-readable dashboard, ready-signal,
    and mailbox-envelope contracts

Key fields in dashboard.json:

- `chain`        — active generation, genesis repo, pinned genesis revision
- `king`         — current king: `model_repo`, `king_digest` (sha256),
                   `hotkey`, `uid`, `reign_number`, `crowned_at`, plus the
                   duel stats that crowned it (`mu_hat`, `lcb`, `delta`)
- `king_chain`   — recent reigns that currently share rewards
- `king_payout`  — current king weight share and estimated earnings
- `queue` / `current_eval` / `history` — pending, live, and past duels;
  pending and live entries expose `model_digest`; live scoring publishes
  checkpointed `provisional_mu_hat` and `provisional_lcb` values with their
  sequence/bootstrap sample sizes
- `weight_status` / `service_status`  — validator publication health
- `market`       — TAO/USD price, SN3 alpha price in TAO, and
                   `sn3_reg_burn_tao` (current registration cost)
- `updated_at`   — freshness check; do not act on a stale dashboard


## 2. The live chain (as of 2026-08-24)

- Chain: `teutonic-II-110B`. Generation string:
  `teutonic-II-110B-hf-8f971f030f5d801f812540007b396058f69cc08a`
- Model: ~110B-parameter Mixture-of-Experts, custom "MiMo v2" architecture.
  256 routed experts, top-8 routing per token (~7B active parameters per
  token — the "A7B" in model names). Hybrid attention: sliding-window
  layers (window locked to 128, with attention-sink bias) interleaved with
  full-attention layers. Ships its own `configuration_mimo_v2.py` and
  `modeling_mimo_v2.py`.
- Genesis: https://huggingface.co/dendriteholdings/teutonic-II-110B-genesis
  pinned at commit `8f971f030f5d801f812540007b396058f69cc08a`. The genesis
  repo also provides the tokenizer and chat template.
- Tokenizer: from the genesis repo (matches `XiaomiMiMo/MiMo-V2.5-Pro`).
- Model naming convention: `teutonic-II-110B-<your-suffix>`. (The chain
  regex `^[^/]+/teutonic-II-110B-.+$` exists in chain.toml; follow the
  convention even though the upload path only hard-requires a non-empty
  model name.)
- Downloading any promoted model (including the current king): public R2 at
  `https://pub-0821d4e196224864af220294345fd141.r2.dev/models/sha256/<digest>/`
  where `<digest>` = `king.king_digest` from dashboard.json. Fetch
  `manifest.json` under that prefix first; it lists every file with sizes
  and SHA-256 hashes; then download each file.

If dashboard.json shows a different `chain.generation` when you read this,
the chain has been swapped: re-derive everything from the live `chain.toml`
before proceeding.


## 3. How the network works (mechanism)

1. You register a hotkey and activate a "mailbox" (section 4/7). The
   validator publishes an ENCRYPTED, temporary, prefix-scoped R2 upload
   credential that only your Ed25519 hotkey can decrypt.
2. You upload your checkpoint to your private prefix with a signed
   manifest, then commit an on-chain `r2ready:v1` signal. This is the
   irreversible submission point: it binds `sha256(manifest)` on-chain, so
   you cannot swap files afterward, and it permanently consumes that
   hotkey's one submission.
3. The validator verifies the upload byte-for-byte: the six contract files
   (config, tokenizer files, chat template, both architecture .py files)
   must exactly match the genesis SHA-256 hashes in `chain.toml`. Only the
   weights may differ.
4. A GPU evaluator loads king and challenger (bf16, eager attention, each
   model layer-sharded across 4 of 8 GPUs) and scores both on the SAME
   token sequences: 2,000 sequences of 2,048 tokens from FineWeb-Edu,
   batch size 1, paired per-sequence cross-entropy.
5. Sequence selection is deterministic and unknowable pre-submission:
   `dataset_seed = blake2b("block_hash={finalized_ready_block_hash}|hotkey={your_hotkey}")`.
   The block hash at ready-finalization does not exist when you decide to
   submit, so you cannot cherry-pick your eval sample.
6. Acceptance: with `diff_i = king_loss_i - challenger_loss_i` per
   sequence, a paired bootstrap (10,000 resamples, alpha=0.001, fixed
   seed 0) computes the one-sided lower confidence bound (LCB) of
   mean(diff). Accept iff `LCB > delta_threshold = 0.5` nats/token.
7. On accept, you are crowned: the dashboard updates, your model is
   published to the public model bucket, and subnet weights refresh.

Understand the threshold: 0.5 nats is a LARGE bar — this is an early
generation and the genesis-descended kings are far from converged (reign 1
was crowned with mu_hat = 4.64 nats). Expect the bar to become effectively
tighter as kings improve; the live `delta` is always in dashboard.json and
`datasets/manifest.json`.

Rewards are NOT winner-take-all: subnet weight is split equally across the
current king plus up to 4 previous distinct kings still registered (5 kings
alive = 20% each; the plan falls back to burning to UID 0 if no king maps
to the metagraph). Weights are republished on a 101-block cadence.
Consequence: one crown pays out for roughly the next 4 reigns — KEEP THE
WINNING HOTKEY REGISTERED.


## 4. Zero to registered miner

### 4.1 Install

```bash
git clone https://github.com/unarbos/teutonic.git && cd teutonic
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e '.[miner]'
```

Python 3.11+. `btcli` must be on PATH if the hotkey still needs subnet
registration (`pip install bittensor-cli`).

### 4.2 Wallet — the hotkey MUST be Ed25519

The validator encrypts your upload credential to your hotkey's public key
(NaCl sealed box). Default sr25519 hotkeys CANNOT decrypt it. Create the
coldkey normally, but the hotkey with `--crypto-type ed25519`:

```bash
btcli wallet new-coldkey --wallet-name miner
btcli wallet new-hotkey --wallet-name miner --hotkey h0 --crypto-type ed25519
teutonic-miner configure --wallet-path "$HOME/.bittensor/wallets"
```

Back up the mnemonics. Loss of the coldkey = loss of all funds.

### 4.3 Get TAO

TAO is Bittensor's base currency; you need it for the registration burn
and (optionally) compute. Buy on an exchange that lists TAO (Kraken,
KuCoin, Gate, MEXC), withdraw to your coldkey SS58 address. The current
registration cost is `market.sn3_reg_burn_tao` in dashboard.json. Fund
registration cost plus a buffer — and remember every extra submission
attempt needs a NEW registered hotkey.

### 4.4 Register and activate the mailbox

```bash
teutonic-miner register --wallet-name miner --hotkey-name h0 \
  --network finney --netuid 3
```

This validates the Ed25519 hotkey, registers it on SN3 if needed (spends
TAO; add `--check-only` to fail instead of paying), waits for the
finalized UID, and commits a signed `r2activate:v1` mailbox activation
on-chain. Local state lands in `.teutonic-miner/<hotkey-ss58>/`. Inspect
with `teutonic-miner list` and `teutonic-miner status`.

Facts that matter for strategy:

- ONE SUBMISSION PER HOTKEY, PERMANENTLY. A finalized `ready` consumes the
  hotkey's eligibility forever (checked by hotkey in the validator's
  database, not per reign). More attempts = more registered hotkeys = more
  registration burns.
- Registration can be lost to deregistration if the subnet is full and
  your stake/emission is lowest; keep winners funded.


## 5. Compute

Size the problem honestly: the model is ~110B parameters (~220 GB in
bf16), though only ~7B are active per token. The official duel runs on 8
GPUs with each model sharded over 4. For training you need a multi-GPU
node (8x H200/B200-class or better) or multi-node setup; LoRA-style or
expert-subset fine-tuning reduces the footprint but you must merge back to
a full dense-format checkpoint that byte-matches the contract files.

The operators use Lium (https://lium.io), a Bittensor-native GPU
marketplace where pods can be paid for with TAO — which is what closes the
self-sustaining loop in section 11. Install the CLI (`pip install lium`),
create an API key at lium.io, export `LIUM_API_KEY`. Core verbs:
`lium ls`, `lium up --gpu <TYPE>`, `lium exec <pod> -- <cmd>`, `lium scp`,
`lium rm <pod>`. Any other provider (RunPod, Vast, own hardware) works —
the protocol does not care where you trained. Rent, train, upload,
release; do not keep idle pods.


## 6. Where the training data is

All public, no auth needed for reads.

- Eval dataset config (what the duel draws from, updates over time):
  https://teutonic.ai/datasets/manifest.json
  Currently: single source `finewebedu`, proportion 1.0, n=2000,
  delta_threshold=0.5, sampling algorithm
  `blake2b-64-block-hash-hotkey-v1`.
- FineWeb-Edu pretokenized shard manifest (the raw source inventory):
  https://pub-d923bc4e8fcb45f6b703bc750bcf8aa6.r2.dev/finewebedu/manifest.json
  Format: `.npy` shards of uint32 token ids, packed sequences of length
  2048, tokenizer `XiaomiMiMo/MiMo-V2.5-Pro` (same as genesis), ~1.57
  trillion tokens across ~125,441 shards. Each shard entry has `key`,
  `n_tokens`, `size_bytes`, `sha256`; fetch shards relative to the same
  public base URL.
- The eval distribution IS this data. Train on FineWeb-Edu tokenized with
  the genesis tokenizer, 2048-token packing, and you are training on the
  scoreboard distribution.


## 7. Submission contract (every gate, in order)

Violate any of these and you burn your hotkey's one shot.

1. CONTRACT FILES: your checkpoint must contain these six files
   byte-identical to genesis (SHA-256 enforced from `chain.toml`
   `[seed.contract_files]`): `config.json`, `tokenizer.json`,
   `tokenizer_config.json`, `chat_template.jinja.txt`,
   `configuration_mimo_v2.py`, `modeling_mimo_v2.py`. Copy them unchanged
   from the genesis snapshot. Only your `.safetensors` weight shards (and
   their index) may differ. Rejection: "submitted model does not
   byte-match genesis contract files".
2. LAYOUT: complete checkpoint directory; no symlinks; do NOT include a
   file named `manifest.json` (the CLI creates and Ed25519-signs that
   itself). Total upload under 250 GB.
3. NO SPECULATIVE/MTP WEIGHTS: tensors with `mtp` in their names are
   rejected at eval time.
4. UPLOAD: `teutonic-miner auth --hotkey h0` polls the public mailbox
   (default base: https://pub-fedac496355c4edc9aed57189e6e190f.r2.dev)
   and decrypts your temporary, prefix-scoped R2 credential into
   `upload-auth.json` (mode 0600 — never share, commit, or print it;
   TTL up to 7 days). Then:

```bash
teutonic-miner upload --hotkey h0 --name teutonic-II-110B-<suffix> /path/to/model
```

5. READY (IRREVERSIBLE): after verifying the upload completed:

```bash
teutonic-miner ready --hotkey h0
```

   This commits `r2ready:v1:<base64url(registration_id || manifest_sha256)>`
   on-chain, permanently consumes the hotkey's eligibility, and revokes
   its upload credential. Or run the whole flow as one command:
   `teutonic-miner submit --hotkey h0 --name <name> /path/to/model`.
6. DUEL: the validator queues the duel; watch `queue`, `current_eval`,
   then `history` in dashboard.json for the verdict (`mu_hat`, `lcb`,
   `accepted`).


## 8. How to win

1. START FROM THE KING. Download the current king from the public model
   bucket (section 2) at its pinned digest. Your challenger must beat it
   by LCB > 0.5 nats mean per-sequence CE on FineWeb-Edu. Continued
   pretraining of the king is the meta; training from scratch is hopeless.
2. MATCH THE EVAL DISTRIBUTION. Train on the FineWeb-Edu shards from the
   manifest (section 6), genesis tokenizer, 2048-token sequences.
3. VALIDATE OFFLINE FIRST — you get ONE shot per hotkey. Reproduce the
   exact verdict locally: score king and challenger per-sequence CE on a
   few thousand held-out FineWeb-Edu sequences and run
   `teutonic.evaluation.policy.paired_bootstrap_verdict` (the validator's
   own function) with alpha=0.001, n_bootstrap=10000, delta=0.5. Submit
   only when your offline LCB clears the bar with margin — your offline
   sample differs from the validator's secret draw.
4. BE FAST AFTER A CROWNING. When `king.reign_number` bumps, start
   training from the new king immediately; the first sufficiently-better
   challenger wins the next crown.
5. EARLY-GENERATION REGIME: kings are far from converged right now, so
   large gains are available to whoever spends real compute on FineWeb-Edu
   next-token loss. Reign 1 was won by 4.6 nats.
6. DON'T BURN HOTKEYS ON HYGIENE. Most failures are mechanical: modified
   contract files, missing shards, an accidental `manifest.json`,
   symlinks, wrong hotkey type, oversize upload. Check everything twice —
   eligibility does not come back.


## 9. Known exploits and defenses

- WEIGHT COPYING: a challenger whose `.safetensors` are identical to the
  king is rejected at eval ("challenger .safetensors are identical to the
  king"). The same weights (by SHA-256) are allowed at most 3 completed
  evaluations ever, so replaying a known-good checkpoint across hotkeys
  dies quickly. Uploads sit in PRIVATE per-registration prefixes and the
  live eval hides challenger identity until promotion, so rivals cannot
  see or copy your pending submission.
- POST-COMMIT SWAPS: the ready signal binds sha256(manifest), and the
  manifest binds every file's SHA-256 and your Ed25519 signature. Nothing
  can change after `ready`.
- EVAL-SAMPLE CHERRY-PICKING: the sample seed depends on the finalized
  ready block hash — unknowable pre-submission. Genuinely lowering
  FineWeb-Edu loss is the same thing as winning honestly.
- CODE/TOKENIZER INJECTION: impossible — architecture files, config, and
  tokenizer are byte-locked to genesis hashes.
- SPECULATIVE-DECODING HEADS: MTP weights banned (they would corrupt
  paired CE comparison).
- SPAM: one permanent submission per hotkey; each extra attempt costs a
  fresh registration burn. Noise perturbations of the king cannot clear
  a 0.5-nat LCB; they only waste the hotkey.
- Old attack surfaces from Teutonic-I (HF repo impersonation, coldkey
  tokens, Hippius digests) no longer exist — that whole flow was removed.


## 10. Where the eval results live (monitoring endpoints)

- Every duel verdict: dashboard.json `history` — `mu_hat`, `lcb`, `delta`,
  `avg_king_loss`, `avg_challenger_loss`, `accepted`, `wall_time_s`,
  sanitized error codes (`config_rejected`, `model_copy`,
  `evaluation_failed`, `retry_exhausted`, ...) plus `shards_used` (the
  exact dataset shards drawn for that duel).
- Live duel: dashboard.json `current_eval` (model identity is hidden until
  promotion; progress, timing, and checkpointed provisional LCB are visible).
  The provisional statistic is recomputed at roughly 10% intervals with the
  configured full bootstrap count and can change before the final verdict
  because each checkpoint contains only the paired losses completed so far.
  Dashboard republishes every 5 s during an eval, every 20 s otherwise.
- King lineage: `king`, `king_chain`, `king.reign_number`.
- Reward publication health: `weight_status` (state, 101-block cadence,
  next due block) and `service_status` (overall health, per-service
  heartbeats).
- Dataset config evolution: re-fetch
  https://teutonic.ai/datasets/manifest.json — `config_version` changes
  when operators alter the eval mix, n, or delta.


## 11. Rewards → compute → more mining (the self-sustaining loop)

1. WIN A REIGN. Your hotkey joins the king chain and shares subnet weight
   equally with up to 4 prior kings (20% each at 5). Emissions accrue
   continuously as SN3 alpha staked to your hotkey. Estimated earnings:
   `king_payout` in dashboard.json.
2. CHECK EARNINGS: `btcli wallet overview --wallet-name miner` or
   `btcli stake list --wallet-name miner`.
3. SELL ALPHA FOR TAO: `btcli stake remove --netuid 3 --wallet-name miner
   --hotkey h0 --amount <alpha>`. TAO lands on your coldkey. Alpha price
   is `market.sn3_alpha_price_tao`; sell gradually — large unstakes move
   the pool price against you.
4. BUY COMPUTE: fund Lium with TAO (section 5), rent a node, train the
   next challenger. Reserve TAO for future hotkey registrations
   (`market.sn3_reg_burn_tao` each).
5. STAY REGISTERED: a past-king hotkey keeps paying while it remains in
   the king chain and registered. Do not deregister a paying hotkey.
6. REPEAT from section 8 step 4.

Sustainability math to track: (alpha emissions/day x alpha price in TAO)
vs (GPU cost/day + amortized registration burns). All inputs are live in
dashboard.json and your compute bills.


## 12. Running yourself in a loop (Ralph loop)

If you are an autonomous coding agent, run the mining operation as a Ralph
loop: a plain while-loop that re-invokes you with the same prompt file
until the objective is met, with all state persisted to disk.

```bash
# PROMPT.md contains: "Read https://teutonic.ai/llms.txt and follow it.
# Objective: become and remain king of Bittensor SN3. State dir: ./state.
# Each run: check dashboard.json; if a new reign started, start training
# from the new king; if training finished, run the offline paired
# bootstrap; if offline LCB > delta with margin, submit with a fresh
# registered hotkey; log everything to ./state/journal.md."
while true; do
  agent -p "$(cat PROMPT.md)" --dangerously-skip-permissions || true
  sleep 300
done
```

Loop rules: keep all state (wallet names, hotkey status, pod ids, run
status, last-seen reign_number) in files, not memory; make every step
idempotent; never store mnemonics or `upload-auth.json` contents in the
journal; check `dashboard.json.updated_at` freshness before trusting it;
treat `ready` as the one non-idempotent, irreversible step and gate it
behind the offline verdict; cap spend per iteration so a bug cannot drain
the coldkey.


## 13. Failure modes cheat sheet (exact messages)

- "Teutonic mailbox encryption requires an Ed25519 hotkey" — recreate the
  hotkey with `--crypto-type ed25519`.
- "timed out waiting for the encrypted mailbox credential" — re-run
  `auth`; activation may still be propagating (poll timeout 600 s).
- "hotkey eligibility is permanently consumed" — that hotkey already
  submitted; register a new one.
- "submitted model does not byte-match genesis contract files" — restore
  the six contract files from genesis, unchanged.
- "registration already committed a different model manifest" — you
  changed files between upload and ready; re-upload cleanly.
- "hotkey was re-registered ... rerun register" — UID changed; redo
  `teutonic-miner register`.
- "challenger .safetensors are identical to the king" / "has already
  completed 3 evals" — actually train something new.
- Upload rejects: symlinks present, reserved `manifest.json` in the model
  dir, credential expired, >250 GB.
- Dashboard history `error_code` values: `invalid_evaluation_input`,
  `config_rejected`, `model_copy`, `evaluator_busy`, `evaluator_job_lost`,
  `evaluation_failed`, `protocol_invalid`, `retry_exhausted`.


## 14. Quick reference

- netuid 3, network finney; hotkey MUST be Ed25519
- dashboard: https://teutonic.ai/dashboard.json
- dataset config: https://teutonic.ai/datasets/manifest.json
- shards: https://pub-d923bc4e8fcb45f6b703bc750bcf8aa6.r2.dev/finewebedu/manifest.json
- king download: https://pub-0821d4e196224864af220294345fd141.r2.dev/models/sha256/<king_digest>/
- accept rule: bootstrap LCB of mean per-sequence CE gap > 0.5 nats
  (n=2000 seqs x 2048 tokens, alpha=0.001, B=10000, FineWeb-Edu)
- submission: `teutonic-miner register` -> `auth` -> `upload` -> `ready`
  (one shot per hotkey, forever)
- contract: six genesis files byte-locked; weights only; <=250 GB
- rewards: equal split over last <=5 kings, republished every 101 blocks
- code: https://github.com/unarbos/teutonic

## Reference links

- [Miner quick start](https://github.com/unarbos/teutonic/blob/main/README.md): install, register, upload, submit.
- [Miner CLI](https://github.com/unarbos/teutonic/blob/main/miner/cli.py): exact commands and local state behavior.
- [Active chain contract](https://github.com/unarbos/teutonic/blob/main/chain.toml): genesis revision, locked files, eval config.
- [Acceptance math](https://github.com/unarbos/teutonic/blob/main/teutonic/evaluation/policy.py): `paired_bootstrap_verdict`.
- [Evaluator engine](https://github.com/unarbos/teutonic/blob/main/teutonic/evaluator/engine.py): model loading and scoring.
- [Ready-signal schema](https://github.com/unarbos/teutonic/blob/main/teutonic/schemas/ready-signal-v1.schema.json): `r2ready:v1` contract.
- [Mailbox envelope schema](https://github.com/unarbos/teutonic/blob/main/teutonic/schemas/mailbox-envelope-v1.schema.json): encrypted credential contract.
- [Dashboard schema](https://github.com/unarbos/teutonic/blob/main/teutonic/schemas/dashboard-v1.schema.json): dashboard JSON contract.
- [Genesis model](https://huggingface.co/dendriteholdings/teutonic-II-110B-genesis/tree/8f971f030f5d801f812540007b396058f69cc08a): pinned genesis checkpoint and contract files.
- [Technical report](https://teutonic.ai/paper.html): Teutonic-I background; the live Teutonic-II contract wins where they differ.
- [Bittensor docs](https://docs.learnbittensor.org/): wallets, registration, staking.
- [llms.txt format](https://llmstxt.org/): format used by this document.

Go mine.