AdTAO

<div align="center">

# **SN21 — Impact Prediction Subnet**

### Predict ad campaign outcomes. Earn from accuracy alone.

> **Daily stream (from 4 Aug 2026).** SN21 has moved from weekly epochs to a
> **daily** stream: you ship a **container image**, the subnet runs it against a
> fresh basket of real account changes every day, and settled outcomes feed a
> rolling standing that drives emissions. Weekly `hope-miner` prediction
> bundles are obsolete. Why we moved: [docs/SN21_WHY_DAILY.md](docs/SN21_WHY_DAILY.md).
>
> **Miners start here:** [Why daily](docs/SN21_WHY_DAILY.md) →
> [Quickstart](docs/miner_quickstart.md) → [Training](docs/SN21_TRAINING.md) →
> [Model spec](docs/MINER_MODEL_SPEC.md) → [Verifying your score](docs/SN21_VERIFYING.md)
>
> **Validators start here:** [Why daily](docs/SN21_WHY_DAILY.md) →
> [Validator setup](docs/validator_setup.md) → [Scoring](docs/SN21_SCORING.md) →
> [Rewards](docs/SN21_REWARDS.md) → [Verifying](docs/SN21_VERIFYING.md)

Every prediction is sealed on chain before the outcome is knowable.
Every score is reproducible by anyone with a chain reader.
No one — including the operator — can rewrite the record after the fact.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/ippcteam/SN21-adtao/actions/workflows/test.yml/badge.svg)](https://github.com/ippcteam/SN21-adtao/actions/workflows/test.yml)

---

Bittensor Subnet 21 · Mainnet `finney` · Testnet `test` (netuid 466)

[Miner quickstart](docs/miner_quickstart.md) · [Validator setup](docs/validator_setup.md) · [Scoring](docs/SN21_SCORING.md) · [Rewards](docs/SN21_REWARDS.md)
</div>

---

- [Documentation](#documentation)
- [Overview](#overview)
- [How it works](#how-it-works)
- [Architecture](#architecture)
- [What you predict](#what-you-predict)
- [How scoring works](#how-scoring-works)
- [How emissions work](#how-emissions-work)
- [Repository structure](#repository-structure)
- [Hardware requirements](#hardware-requirements)
- [Running a miner](#running-a-miner)
- [Running a validator](#running-a-validator)
- [Verifying your score (daily stream)](#verifying-your-score-daily-stream)
- [Verifying any epoch (weekly era)](#verifying-any-epoch-weekly-era)
- [Development](#development)
- [License](#license)

---

## Documentation

**Current system = daily stream (from 4 August 2026).** Anything marked
*weekly era* or under `docs/archive/weekly/` describes the previous protocol
(last weekly epoch scored 3 August 2026). Do not follow weekly commands for
live mining or validation.

### For miners

| Doc | What it is |
|-----|------------|
| [docs/SN21_WHY_DAILY.md](docs/SN21_WHY_DAILY.md) | Why the subnet moved to daily |
| [docs/SN21_TRANSITION_PLAN.md](docs/SN21_TRANSITION_PLAN.md) | Cutover dates and bridge rules |
| [docs/miner_quickstart.md](docs/miner_quickstart.md) | **Start here** — register, build container, commit digest |
| [docs/SN21_TRAINING.md](docs/SN21_TRAINING.md) | Train → package → smoke test |
| [docs/MINER_MODEL_SPEC.md](docs/MINER_MODEL_SPEC.md) | Container I/O contract the subnet enforces |
| [docs/SN21_SCORING.md](docs/SN21_SCORING.md) | How daily settle and standings work |
| [docs/SN21_REWARDS.md](docs/SN21_REWARDS.md) | Weight curve, emissions, champion rule |
| [docs/SN21_STAKING.md](docs/SN21_STAKING.md) | Alpha-hold ladder |
| [docs/SN21_VERIFYING.md](docs/SN21_VERIFYING.md) | Rerun any day's receipt and reproduce your score |

You ship a **digest-pinned container**. The subnet runs it against each daily
basket. You do **not** POST daily predictions. Weekly `hope-miner --epoch WR-…`
commands are obsolete.

### For validators

| Doc | What it is |
|-----|------------|
| [docs/SN21_WHY_DAILY.md](docs/SN21_WHY_DAILY.md) | Why the subnet moved to daily |
| [docs/validator_setup.md](docs/validator_setup.md) | **Start here** — daily loop, API, heartbeat, env |
| [docs/SN21_SCORING.md](docs/SN21_SCORING.md) | Settle / standing / weight curve (authoritative) |
| [docs/SN21_REWARDS.md](docs/SN21_REWARDS.md) | How standings map to emissions |
| [docs/SN21_VERIFYING.md](docs/SN21_VERIFYING.md) | Public receipts and `verify_day.py` |
| [docs/validator_daemon.md](docs/validator_daemon.md) | Consolidated supervisor — **weekly-era scoring step**; heartbeat/reg-index still useful |
| [docs/operator_runbook.md](docs/operator_runbook.md) | Operator cutover playbook (weekly sections historical; daily points to setup §2) |

**Daily validator processes (current):**

1. `hope-validator-api` — long-lived HTTP (episodes + `/v1/daily/*` receipts)
2. `scripts/run_daily_loop.py` — once per day: settle, standings, publish, weight intent
3. `hope-validator-heartbeat` — every 3–4 hours: re-assert weights for ActivityCutoff

`hope-validator --release WR-…` scores **weekly-era** history only. It is not
the daily scoring path.

---

## Overview

SN21 is a verifiable prediction market for Google Ads campaign
outcomes, running on Bittensor. Miners ship a **digest-pinned model
container**; the subnet runs it each day against a fresh basket of real
account changes. Models output P10/P50/P90 distributions over **7-, 14-,
and 28-day** campaign deltas. Settled outcomes feed a rolling standing
that drives emissions. Why daily: [docs/SN21_WHY_DAILY.md](docs/SN21_WHY_DAILY.md).

Protocol background (weekly-era sections historical): [Whitepaper](docs/whitepaper.md).

### Two core guarantees

1. **Predictions lock before outcomes exist.** Your on-chain commitment pins the container digest the subnet will run; each day's basket is scored from that run, before outcomes for that basket are knowable.
2. **Scoring is open and reproducible.** Settle logic lives in `hope/scoring/`; standings and weights follow the published curve. Daily accuracy / receipt feeds and the public site mirror the operator's scored record — see [docs/SN21_SCORING.md](docs/SN21_SCORING.md) and [docs/SN21_REWARDS.md](docs/SN21_REWARDS.md). (Weekly-era epochs remain audi