Endure Network

# Endure Subnet

> **Release `v0.1.3`, with experimental economics.** See the
> [release notes and soak decision](docs/releases/v0.1.3.md). Alpha Risk serves on
> mainnet only behind the explicit `--endure.serving_stage mainnet`
> acknowledgement, on releases promoted to the `:prod` image channel after the
> owner release decision ([running_on_mainnet.md](docs/running_on_mainnet.md)).
> The current protocol key is `2044` ([contract](endure/protocol/version_contract.py));
> miners and validators upgrade together, and `v0.1.2` images (key `2043`) are superseded.
> Activated and retired leases are tracked in the [version registry](docs/protocol_versions.md).

Endure is a Bittensor risk-intelligence subnet: miners submit falsifiable
assessments, validators resolve and score them, and consumers read signed risk
feeds. The active vertical is **Alpha Risk V1** (`risk.v1.subnet_alpha`):
per-netuid predictions of drawdown, volatility, TWAP price, and liquidity depth.
It does not originate loans, custody collateral, or liquidate positions.

## Contents

- [Alpha Risk incentive loop](#alpha-risk-incentive-loop)
- [Install from source](#install-from-source)
- [Run local mocks](#run-local-mocks)
- [Run a miner](#run-a-miner)
- [Run a validator](#run-a-validator)
- [Register on testnet](#register-on-testnet)
- [Read the API](#read-the-api)
- [Repository history](#repository-history)
- [Contribute and report security issues](#contribute-and-report-security-issues)

## Alpha Risk incentive loop

A miner commits a hash of an assessment bundle, then reveals that exact bundle
and nonce during the reveal window. Validators freeze each round's universe,
resolve observable outcomes, score revealed coordinates, maintain score history,
and emit Bittensor weights. The signed read API publishes the resulting A–E
risk tier. See [mining](docs/mining.md) for the protocol and [the current
scope](docs/specs/2026-07-06-alpha-risk-v1-scope.md) for the product contract.
There is no minimum runtime: a miner enters scoring with its first accepted
round and becomes eligible for earned weights after positive scores resolve,
typically from that round's 5-day horizon. Earned weights follow a decaying
accuracy record rather than single rounds; submission and finalized confirmation
remain separate — see
[eligibility and the earnings timeline](docs/mining.md#eligibility-and-the-earnings-timeline).

Key `2042` adds a standing owner-vote fallback for served Alpha Risk on mainnet
SN30 and Bittensor testnet: whenever a validator's score vector has no positive
entry — at cold start, including when there are no miners, and again after every
scored miner is archived — it submits its whole vote to the UID of the on-chain
subnet owner hotkey. This is a fallback allocation, not earned miner reputation
or proof of model accuracy. As soon as any score is positive the same process
submits earned score-derived weights, with no flag change or restart in either
direction. Mock and local chains keep all-zero abstention. See the
[identity and emission safety gates](docs/running_on_mainnet.md#weights-and-abstention).

Key `2043` adds the owner burn rate. Once a miner scores, a served validator on
SN30 or testnet still gives the owner UID the share that the owner hotkey
publishes as its subnet commitment, `endure.burn_bps=<0..10000>`; miners share
the rest by earned weight, and the chain burns the owner's share. A missing or
malformed commitment burns the whole vote, so miners are paid only on the
owner's explicit instruction. The owner changes the rate with
[`scripts/set_burn_rate.py`](scripts/set_burn_rate.py), and validators apply it
at their next weight attempt; see the [owner burn rate](docs/running_on_mainnet.md#owner-burn-rate).

Key `2044` pools identical forecasts: the hotkeys in one pool share what its
best member would earn alone, and `/miners` reports each hotkey's `pool_size`.
See [identical forecasts](docs/mining.md#identical-forecasts-share-one-payout)
for who is pooled with whom.

Known limitations: this is a testnet soak with one public validator endpoint;
outcomes and feeds can diverge between validators; interfaces and
internals may change before a later release. Source builds are supported on the
environment below. Each qualified `staging` commit also publishes candidate
Linux/amd64 validator and miner images; run the image for your role using the
[container guide](docs/deploy/operator-node.md).

Supported source environment: Python `>=3.12,<3.13` and Bittensor `>=10.5,<11`
(see [pyproject.toml](pyproject.toml)). Endure does not perform GPU computation;
representative miner and validator sizing will be published after the testnet
soak produces enough measurements for an honest recommendation.

## Install from source

The checked-in `uv.lock` is authoritative. Bootstrap the pinned development
tools before any locked command.

Prerequisites:

- A Python 3.12 executable (macOS: `brew install [email protected]` or
  `uv python install 3.12`; Debian: `apt install python3.12 python3.12-venv`).
  If it is not on `PATH` as `python3.12`, pass
  `make bootstrap BOOTSTRAP_PYTHON=/path/to/python3.12`.
- Node.js 22 or newer (`make verify` installs the integrity-locked jscpd toolchain
  with `npm ci --ignore-scripts`).
- Docker, only for the localnet container fast path.

```bash
git clone https://github.com/endure-network/endure-subnet.git
cd endure-subnet
make bootstrap     # installs hash-pinned uv and Gitleaks in the local tool cache
make install       # uv sync --locked --no-dev, creating .venv as needed
# or, for contributors and testnet operators:
make dev-install   # uv sync --locked --extra dev
make verify
```

`make bootstrap` is required even if these tools are already on `PATH`: Endure
uses and verifies the pinned versions from its local user cache. Do not
substitute `pip install` for either Endure install command. The locked
development environment is required before running `make verify`.

## Run local mocks

After `make dev-install`,