cascade

<p align="center">
  <img src="docs/assets/cascade-logo.png" alt="cascade logo" width="180">
</p>

# Cascade: synthetic data, real forecasting tests

**The ambition is a model that sees the future.** Contributors write synthetic
time-series generators and test whether the patterns they teach transfer to real
series. Checked promotions and accepted expert updates give useful discoveries
a path to become the starting point for later experiments.

Cascade runs this competition on Bittensor. The research question is whether
independent contributions produce sustained forecasting progress. The
[competition introduction](agent.md) explains the idea, gives an illustrative
example, and links actual historical evidence. Implemented features and live
activation are different: inspect the deployment before choosing a lane.

**V2 Lane A is live on mainnet since 30 October 2026.** Paid entries opened
at 09:00 UTC and the first v2 era started at the first era boundary after
12:00 UTC (block 9,399,600). Commitments revealed before the opening are
refused; make a fresh one. Lane A allows one judged submission per hotkey per
round (one 900-block settlement, about 3 h). B and C remain separately
activated. The planned lane order is **A → C → B**: A/C use 75%/25%, then
A/B/C use 50%/25%/25%.

| You are | Start here |
|---|---|
| Exploring the research | [agent.md](agent.md), then [llms.txt](llms.txt) |
| A miner | [Miner guide](docs/MINER.md#quickstart) and [submission interface](docs/INTERFACE.md) |
| A coding agent | [AGENTS.md](AGENTS.md) and [lane-specific walkthrough](docs/AGENT_MINING.md) |
| A validator | [Validator guide](docs/VALIDATOR.md); choose satellite, full evaluator or designated main responsibilities |
| The operator | [Operator runbook](docs/OPERATOR.md) |
| Reviewing implementation | [Architecture](docs/ARCHITECTURE.md) and [decisions](decisions/) |

V2 synthetic generators must emit finite float arrays `(C, L)` with **exactly 32 channels per yield**. One-dimensional and 1–31-channel yields are rejected. Read the effective policy for length and resource limits.

V2 is developed and deployed from `main`; the older `cascade-v2` branch is
not the live code. The live deployment still determines which rules are active.

## Why compete on data

A synthetic generator expresses a hypothesis about patterns a forecaster should
learn: trends, seasonalities, changing regimes, dependencies or noise. Holding
the model and training contract fixed makes that hypothesis testable against
real held-out data. A realistic-looking series alone does not establish value;
the downstream trained model has to satisfy the competition's evaluation rules.

## How it works

The **king** is A's current winner. A **warm start** is the checkpoint used to
begin training, which can differ from the king's trained checkpoint. An **era**
fixes the training rules and starting checkpoint; a **settlement** (round) judges
completed work. A **leg** is one training run.

### The fixed model

The contract is fixed for each comparison, not for the lifetime of the subnet.
Pre-v2 eras use the Toto2 lineage. The v2 candidate is
**Cascade MoE Base - 1.23B**, a pyramid mixture-of-experts model: **1,234,607,520 total parameters,
112,070,048 active per token**, a **21-quantile head**, top-8 routing, and attention across channels.
It starts a fresh lineage; old Toto2 checkpoints cannot initialize it.
The effective era contract and signed checkpoint pointers determine live training.
On mainnet it trains on `8xH100` or `8xH200` pods only; a full 23,841-step leg
measured ≈ 3.5 h on both (2026-11-01/02). See the
[GPU and price table](docs/MINER_V2_INCENTIVE_INTRO.md#gpus).

Implemented [smaller variants](deploy/presets/README.md) are
**Cascade MoE Base - 17.58M, 69.02M and 273.84M**. Names use total parameters;
active counts are listed separately. Use them to improve generators in cheaper local
experiments, then check promising ideas on the live competition model. The 56M
variant remains unspecified. See the [model and recipe](docs/MODEL.md) for exact
counts, masking, output head and training rules. GPU memory has not been
measured for any size, and throughput only for the 1.23B model (above).

For local scoring, use held-out data from the public eval pool
[Tensor-Link/cascade-eval-pool](https://huggingface.co/datasets/Tensor-Link/cascade-eval-pool)
(retired validator snapshots, byte-identical to what was scored; use the
`snapshots/<as_of>-block-<N>/` folders). It is an evaluation set, never
training data; the live private pool is newer and never revealed. See
[MINER.md](docs/MINER.md#held-out-data-the-public-eval-pool).

A mixture-of-experts (MoE) model routes inputs through selected specialist
subnetworks. B improves a limited selection of those experts while the rest
of the model stays frozen.

| Lane | Contribution | Success and destination |
|---|---|---|
| **A — full model** | A deterministic synthetic-data generator | Challenge the era king on the private pool and applicable public benchmark gate; eligible promotions advance the shared init |
| **B — selected experts** | A generator and eligible declared targets | Train selected routed rows; qualify on target gains and guards, then pass warm-start merge acceptance when enabled before merging and earning |
| **C — applications** | An eligible recipe; currently MarketCast | Fine-tune a separately pinned Timestral base, judge on future market observations, and confirm later for a paid slot; no merge into A/B |

B launches independently of the v2 model and has a measured-lineage/routing
gate. C and its competitions have their own activation settings. Miners select
B targets; the current trainer selects expert rows. The [rollout reference](docs/AGENT_MINING.md#v2-rollout-and-compatibility-reference)
contains target limits, migration details and allocation settings.

### Rules at a glance

| Lane | What must pass | What a pass earns |
|---|---|---|
| A | Beat the king by the private test's conf