Get started

Local harness quickstart

Install the private REAX reference package, run its tests, and run the three-miner loopback harness. The harness exercises the signed serving path and the validator epoch pipeline end to end on your own machine.

Requirements

• Python 3.10 or newer. CI covers Python 3.10 to 3.13.
• Access to the private reax-subnet reference repository.
• An isolated virtual environment. Do not install into a shared or global Python.

Core dependencies are pinned in pyproject.toml: cryptography==50.0.1 for Ed25519, Pillow==12.3.0 and rfc8785==0.1.4 for RFC 8785 canonical JSON. The harness also needs the server extra, which pins uvicorn==0.54.0. The Bittensor SDK (bittensor==11.1.0, extra chain) is not needed for anything on this page.

Install

From the repository root, create a virtual environment and install the package with the server extra:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e '.[server]'

For a fully hash-locked development environment, install from the lock file instead. It pins every package in scope and verifies published wheel SHA-256 values; source distributions are disabled:

python3 -m pip install --only-binary=:all: --require-hashes -r requirements/dev.lock

Run the tests

python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests

The Makefile wraps the same commands as make test and make compile, plus make typecheck (mypy on Python 3.10). Suites cover the protocol, transport, admission, router, gateway, miner, receipts, scoring, validator epoch and chain guards. Three SDK compatibility tests are skipped unless the pinned Bittensor SDK is installed in an isolated environment.

Run the three-miner harness

Pass an absolute output path in a directory that already exists and that you keep private:

PYTHONPATH=src python3 -m reax_subnet.harness --output /path/to/private/evidence/local-harness.json

The wrapper script does the same thing (despite its name, it does not touch testnet):

scripts/testnet_harness.sh --output /path/to/private/evidence/local-harness.json

With --output, the harness writes the full JSON receipt to that file and prints a one-line summary. Without it, the receipt is printed to standard output. The exit code is 0 when the receipt says "passed": true and 1 otherwise.

{"passed": true, "receipt": "/path/to/private/evidence/local-harness.json"}

--output

Receipt path. Its parent directory must already exist.

--count-per-source

Scheduled probes per miner, default 288 (six synthetic epochs of 48). A short cold start such as --count-per-source 1 intentionally produces no weight vector and exits with 1.

What the harness runs

1. Three miners on ephemeral loopback ports, each a real MinerApp behind Uvicorn: two simulated EU miners admitted by a signed local admission fixture (gdpr_eu) and one simulated permissionless miner (global_permissionless). Their engine is a synthetic arithmetic engine, not a model.
2. Three gateway fixtures (one per miner, same ingress identity) serving signed HTTP. Every scored dispatch goes signed gateway HTTP, then signed miner HTTP.
3. One validator with its own caller key. It generates fresh arithmetic tasks with known answers from a registered deterministic checker, balanced across outcomes, and hashes the entire schedule before any output is inspected.
4. Six synthetic ledger epochs of 48 probes per miner: 864 scheduled inference requests in total at the default count. Epoch boundaries are wall-clock, not chain tempos.
5. Scoring and weights through the typed score_epoch and weights_from_epochs pipeline, with signed policy and epoch documents verified against separate ephemeral owner and ingestor keys, and a dry-run weight plan against a mocked chain snapshot.

What a passing receipt shows

• Signed Ed25519 requests and responses work over real loopback HTTP through both hops, with RFC 8785 canonical JSON.
• Replays are rejected at both the gateway and the miner before inference.
• Tier isolation holds: a GDPR-tier request cannot be routed to the permissionless miner, and a cross-tier request to it returns 403.
• Payload-free gateway receipts verify.
• Complete 288-cluster fidelity windows reach support, the first supported epoch applies the half-gain ramp, and operator-capped weights are produced.
• An unsigned policy abstains, a non-local network profile abstains, and the owned-only testnet_mechanics profile is exercised without connecting to any chain.

What it does not prove

• The chain snapshot and commit plan are mocks ("chain_snapshot": "mocked only", "chain_connection_proven": false).
• Reference latency comes from 16 unscored local calls on the host. It is not a reference-hardware or serving-region measurement.
• The capacity prober is not implemented ("capacity_prober_implemented": false); capacity is fixed at 1.
• Probe indistinguishability is not tested: the gateway fixtures prove the signed path, not production routing.
• The receipt's "design_status" states that the known constant-substitute and max-group merge counterexamples are unresolved in the current scoring code.

Receipt fields worth checking

The receipt schema is reax.local-harness.v2. These keys are the quickest way to confirm what was and was not exercised:

Keep receipts private. They contain signed policy and epoch document hashes and per-miner scores from your local run.