Terza Inference

# Terza miner

Run a miner for **Terza Inference**, the model API marketplace on the Terza Bittensor
subnet. Buyers use one Terza API key; the Terza gateway routes each request to a miner
that serves the model, meters it and settles payment. Your upstream address, supplier
key and private model mapping never leave your machine.

This repository contains:

- `terza-miner`: a Python CLI that sets up your local miner configuration, signs the
  admission challenge with your hotkey and manages quotes.
- Install instructions for `terza-miner-node`, the miner service, which is published
  as a release binary (Linux x86_64).

The CLI never registers hotkeys, stakes or moves funds, and it only unlocks the
hotkey, never the coldkey.

## Requirements

- Linux x86_64, Python 3.10+
- A hotkey registered on the Terza subnet under your own coldkey (use `btcli`)
- A Terza account and a single-use miner invitation code from the Terza team
- A public HTTPS endpoint that proxies to the miner service (SSE and WebSocket enabled)
- An upstream that serves the models you will offer

## Install

```sh
python3 -m venv ~/.local/share/terza-miner-venv
~/.local/share/terza-miner-venv/bin/pip install .
export PATH="$HOME/.local/share/terza-miner-venv/bin:$PATH"
```

Download `terza-miner-node-linux-x86_64` and `SHA256SUMS` from this repository's
Releases page, then verify and install it:

```sh
sha256sum -c SHA256SUMS
install -m 0755 terza-miner-node-linux-x86_64 ~/.local/bin/terza-miner-node
```

The CLI never downloads or runs an executable it has not been pointed to.

## Initialize and serve

```sh
terza-miner init \
  --endpoint https://miner.example.com \
  --model your-public-model-id \
  --upstream-url https://your-upstream.example.com \
  --upstream-model your-upstream-model-id \
  --input-price 0.30 --output-price 0.90 \
  --wallet-name your-wallet --hotkey your-hotkey

terza-miner login --username your-account
terza-miner apply            # also pins the gateway keys (see below)
terza-miner serve
```

Replace the example names and prices with your own. `init` asks for the upstream key
with hidden input, generates a separate gateway access token and writes mode-0600
files under `~/.config/terza-miner` (directory mode 0700):

- `miner.json`: local bind address, upstream origin, model mapping and key, and the
  gateway access token. This file stays private.
- `submission.json`: public miner endpoint, model metadata, capabilities and quotes.
- `cli.json`: Terza API origin and local wallet name, path and hotkey.
- `session.json`: login cookie for exactly that API origin, after login.

`init` never overwrites existing configuration. Prices are USD per million tokens;
initial quotes expire in seven days. Initial capabilities are text chat only, with
conservative 2048 input / 1024 output token limits. Edit these limits to match your
service before submitting. For several models or media protocols, edit both model
lists and keep the declared capabilities identical.

`serve` replaces the CLI process with `terza-miner-node --miner <private config>`.
Ctrl-C stops it and the exit status is preserved. It listens on loopback port 19190
by default. Put an HTTPS reverse proxy with SSE and WebSocket forwarding in front of
it; `serve` does not configure DNS, TLS, a public listener or a background service.
Restart it after changing `miner.json`. Use `--binary /absolute/path` if the binary
is not on your `PATH`.

### Gateway signatures

`serve` refuses to start until the gateway's signing keys are pinned. Every request
from the Terza gateway carries an Ed25519 signature over the method, path, target
hotkey, timestamp, a single-use nonce and the exact body. The miner rejects anything
else, including bearer-token-only requests, replays, requests older than 60 seconds
and requests addressed to another hotkey. `apply` pins the keys from
`/api/public/gateway-identity` and sets `audience` to your bound hotkey. After a key
rotation, run `terza-miner trust-gateway` (signed in) and restart `serve`. Check the
key IDs it prints against the values Terza publishes.

## Apply

```sh
terza-miner login --username your-account
terza-miner apply
terza-miner status
```

If account registration is open, `terza-miner register --username your-account`
creates the account and signs in. Account and hotkey passwords are entered at
hidden prompts, never as command-line flags.

`apply` asks for the invitation code (hidden input) when the account has no miner
binding yet and never saves it. Later quote updates need no new invitation.

Before signing, `apply` checks the challenge origin, account, hotkey, nonce, expiry
and its no-spending purpose. It then submits the signature, your public model quotes
and the gateway access token. It never sends the upstream key or upstream origin.
An account binds one hotkey permanently; a different configured hotkey is rejected.
An interrupted application can be retried safely.

Submissions carry the server revision, so concurrent changes from the Console and the
CLI produce a conflict instead of a silent overwrite. Editing an approved
application returns it to review and removes it from new routing until approved.
`status` reports the application status, revision, review note and chain membership
separately: approved does not mean registered or healthy.

## Quotes and lifecycle

```sh
terza-miner quote update --model your-public-model-id \
  --input-price 0.25 --output-price 0.75 --valid-days 7
terza-miner pause
terza-miner resume
terza-miner logout
```

`quote update` saves the local draft and submits the whole model list for review. On a
network error the draft stays local: check `status` and retry `apply`. Renew other
models' expired quotes as well. A suspended miner cannot resume itself.

```sh
terza-miner exit --yes
```

Exit permanently removes this account and hotkey binding from new requests. It does
not deregister the hotkey or move funds.

Put `--config-dir /private/directory` **before** the subcommand to use