Ormas

# ormas-subnet

> **Ormas: pay for verified receipts, not inference turns.**
> A client describes a change and the test that proves it. Miners with public track records post a firm ask for the passing result. Accepted delivery → the miner is paid exactly its ask; a miss pays nothing.
> The client's acceptance tests are the purchase order; validators re-run them before anyone is paid.

Bittensor subnet 76 · operated by Heron Cove LLC · protocol, thin client, reference miner and reference validator: MIT.

> **Disclosure.** Heron Cove LLC runs a miner and a validator on SN76 and operates the gateway that
> settles work. Until validators gate settlement on the production gateway, acceptance is not
> independent of us; we say so wherever a number appears (`/v1/public/providers` labels our miner
> `operator-run`). Nothing in this repository is an offer of emissions, a payout schedule, or a
> return; the compensation model below is **planned — not yet live** until marked otherwise.

Working on this repo with a coding agent? Start at [`AGENTS.md`](AGENTS.md) (repository map,
authoritative specs, commands, boundaries). Found a vulnerability? [`SECURITY.md`](SECURITY.md).

This package is normative under
[`docs/DECISIONS.md`](docs/DECISIONS.md)
(owner-locked 2026-09-10): **the runner is the miner.** A miner posts a firm bid
("ask") for a whole task and is paid only when its delivery is **accepted** —
never for inference served, tokens spent, or hardware occupied. It is what you
give a third-party miner to connect to the Ormas subnet, local
or SN76.

## What this is

- The **miner wire protocol** (`ormas_subnet/protocol.py`) — the `ormas-runner-v1`
  data types (`RunnerRegistration`, `RepoRegistration`, `TaskDraft`, `TaskLease`,
  `TaskEvent`, `TaskReceipt`, `TaskTerminal`) that cross the wire to
  `/api/runner/v1` on the Ormas gateway.
- A **thin HTTP client** (`ormas_subnet/client.py`, `OrmasMinerClient`) for those
  routes.
- A **reference miner skeleton** (`ormas_subnet/skeleton.py`, `MinerSkeleton`) —
  register → poll for a lease → clone the client's repository fresh with the
  job's `repo_credential` from the draft and check out the base commit →
  call your `solve(draft, workdir) -> SolveResult` → **actually run
  `draft.verify_command`** (bounded, credential-free env, no shell) → push
  the result branch with the same credential → complete. No `bind` step is
  needed; binding a repository you already hold is the fallback
  (`docs/INSTALL.md`). `solve` is the one pluggable step; completion
  itself is honest, not self-declared: the receipt is built only from usage
  `solve` reports (an unknown value is never fabricated as zero), `scope_ok`
  is computed from a real `git diff` against `allowed_paths` (never asserted),
  and `verification_state` comes from the verify command's actual exit code.
  See "Completion is honest" below and `docs/protocol.md`.
- A **trivial reference solver** (`ormas_subnet/reference_solver.py`) that runs a
  shell command and commits the result, so the skeleton runs end to end with no
  model calls at all — and reports its own honest zero-usage receipt fields
  (it truly made no model call).
- The **protocol contract** in [`docs/protocol.md`](docs/protocol.md): every
  route, field, forbidden field, and error code, written so you could implement
  a miner in another language from it alone.
- No token yet? [`docs/QUICKSTART_LOCAL.md`](docs/QUICKSTART_LOCAL.md) runs the whole loop offline against a local stand-in gateway (`ormas_subnet/localnet.py`) — no token, no network host.

## What this is NOT

- **Not our mining logic.** Our own miner — the agentic worker, model routing,
  cost capture, orchestration loop — stays private. It competes on this same
  protocol, on the same terms as every other miner. Nothing about *how* to solve
  a task well lives here.
- **Not an inference endpoint.** A miner never serves completions and gets paid
  per token; it delivers a whole outcome and gets paid on acceptance.
- **Not yet settled by validators on the production gateway.** Today the
  production gateway derives settlement from the miner's own reported
  `verification_state` plus a scope/commit check — acceptable only because our
  own miner is trusted. The **reference validator** — which clones the job's
  repo, independently re-runs the verify command on base and result, checks
  scope from `git diff`, signs, and posts accept/reject — ships here
  (`ormas_subnet/validator.py`, `neurons/validator.py`). The gateway settles a
  third-party miner's delivery only on unanimous validator acceptance and
  refuses its claim until a validator count is configured; our own trusted
  miner still settles by its own verify run. In production one validator is
  configured (operated by Heron Cove) and every third-party delivery is gated
  on it; the validator provisions the packet's declared `toolchain` before it
  re-runs the tests (see `docs/protocol.md`). See "Known gaps" below and the
  decision doc §8.

## Plugging in your own `solve`

```python
from pathlib import Path
from ormas_subnet import MinerConfig, MinerSkeleton, OrmasMinerClient, TaskDraft
from ormas_subnet.skeleton import SolveResult

def solve(draft: TaskDraft, workdir: Path) -> SolveResult:
    # Your mining logic goes here: read draft.brief / draft.verify_command /
    # draft.work_packet, edit files in `workdir`, commit, return the commit sha.
    # The skeleton itself runs draft.verify_command and computes scope_ok from
    # git — you do not declare either. Report real usage if you have it
    # (provider/model/tokens/cost); leave a field None if you don't know it —
    # never fabricate a zero.
    ...
    return SolveResult(
        result_commit=my_commit_sha,
        changed_paths=("src/app.py",),
        provider="acme-model-co", model="acme-large",
        prompt_tokens=123, completion_tokens=45,
        cache_read_input_tokens=0, cache_creation_input_tokens=0,
        reasoning_tokens=0, upstream_cost_usd=0.0021