# Greevils

**Greevils is a Bittensor subnet where miners run autonomous trading agents inside
confidential TEEs and are scored on how their Hyperliquid accounts actually perform.**

You as a miner, an agent is a directory of code you write. You encrypt it, the organizer builds it into a
fixed, attestable Confidential Space image *without ever seeing your plaintext*, and you deploy
that image to a TDX VM **on your own infrastructure**. Inside the TEE a trusted harness holds
the trading key and your agent code reaches it only through a narrow loopback API — so the agent
can trade but can never withdraw, and anyone can cryptographically verify exactly which code is
running. A validator then reads each miner's on-chain account claim, confirms the agent is a
genuine attested workload, scores the account, and sets weights.

This repo is the **map**. Each component documents itself in its own repo — this page exists only
to explain how the pieces fit together and to point you to the right doc. It does not repeat them.

---

## The repositories

| Repo | Role | Who runs it | Visibility |
|---|---|---|---|
| **[greevils-cli](https://github.com/greevils-ai/greevils-cli)** | The participant's command-line tool: package, submit, deploy, claim your account, approve digests. | Miners & validators | public |
| **[greevils-public-harness](https://github.com/greevils-ai/greevils-public-harness)** | The in-TEE workload — the trusted harness + the sandbox your agent runs in. This is exactly what the API builds, published so you can read every line before trusting it with your key. | Built by the organizer, runs in your TEE VM | public |
| **[greevils-validator](https://github.com/greevils-ai/greevils-validator)** | The subnet validator: verifies account claims, classifies agents vs humans, scores, and sets weights. | Validators | public |
| **greevils-api** | Submission + build backend: stores your *ciphertext*, builds it into an attestable image, tracks build status, serves attestation verification. | The organizer only | private |

> **Why is the API private but the harness public?**
> The API is just organizer infrastructure — you never talk to it directly (the CLI does). But the
> code that runs *inside your TEE and decrypts your agent* must be trustworthy, so the exact
> workload the API bakes into every image is published as **greevils-public-harness**. You can
> audit it, confirm it doesn't exfiltrate your agent or key, and then attestation guarantees that
> *that* image — and nothing else — is what's running.

---

## How it all connects

```
        ┌─────────────┐
 you ──▶│ greevils-cli│  package + encrypt your agent dir  (plaintext never leaves your machine)
        └──────┬──────┘
               │ submit ciphertext
               ▼
        ┌─────────────┐   bakes in the
        │ greevils-api│◀── greevils-public-harness ──┐  workload
        │  (private)  │    + your ciphertext          │
        └──────┬──────┘                               │
               │ publishes image digest D             │
               ▼                                      │
        ┌──────────────┐   greevils-cli deploy        │
        │  YOUR TEE VM │◀────────────────────────────┘
        │ (Confidential│   harness decrypts your agent INSIDE the TEE,
        │  Space / TDX)│   runs it, exposes a loopback trading API
        └──────┬───────┘
               │ you claim the agent's Hyperliquid account on-chain (greevils-cli commit)
               ▼
        ┌──────────────┐  reads claims + asks the API "is this a real attested agent?"
        │   validator  │  scores each Hyperliquid account, sets weights on the subnet
        └──────────────┘
```

**Step by step:**

1. **Package** — You write an agent directory (just needs an `entry.py`) and run `greevils package`.
   It zips and encrypts it locally and prints your `AGENT_KEY`. The encryption key never leaves
   your machine. → [greevils-cli](https://github.com/greevils-ai/greevils-cli)

2. **Submit & build** — `greevils submit` uploads only the *ciphertext* to **greevils-api**. The
   API drops your encrypted bundle into a build context together with the
   **greevils-public-harness** workload, builds a Confidential Space image, and publishes its
   content digest **D**. The organizer never sees your plaintext.

3. **Deploy** — `greevils deploy` launches a Confidential Space TDX VM **on your own GCP project**
   running that exact image. Inside the TEE, the harness decrypts your agent with your `AGENT_KEY`,
   provisions a trading key that stays inside the trusted process, and runs your code as a separate,
   keyless user. Your agent trades by making plain HTTP calls to the harness's loopback API — there
   is no SDK to import. → [greevils-public-harness](https://github.com/greevils-ai/greevils-public-harness)

4. **Claim** — `greevils commit` publishes a one-time on-chain commitment proving you control the
   Hyperliquid account, binding it to your subnet hotkey. That's the miner's whole on-chain job.

5. **Score** — The **greevils-validator** reads every miner's commitment, verifies the signature,
   asks greevils-api whether each claimed account is a genuine attested-and-approved agent,
   classifies accounts into the **agent** and **human** arenas, scores each account, and sets
   weights — splitting emissions 90% to agents / 10% to humans.
   → [greevils-validator](https://github.com/greevils-ai/greevils-validator)

---

## The trust model in one paragraph

The whole system rests on the image digest **D**. Because the API builds and publishes D from the
public harness plus your ciphertext, D is a content-addressed fingerprint of *exactly* what runs.
Attestation (checked by `greevils-api`'s verify endpoint and by the validator) proves a deployed VM
is running image D on genuine production TDX hardware — not a debug build, not a tampered image. So
verifying D simultaneously verifies the custody guarantees (your agent can trade but never withdraw)
*and* the agent's identity. The published harness is what lets you confirm what D actually does
before you ever hand it your key.

---

## Where to go next

- **I want to run an agent (miner):** start with **[greevils-cli](https://github.com/greevils-ai/greevils-cli)** — it walks the full package → submit → deploy → commit workflow.
- **I want to understand what runs in the TEE / audit the custody guarantees:** read **[greevils-public-harness](https://github.com/greevils-ai/greevils-public-harness)** (its `ARCHITECTURE.md` has the full threat model and isolation design).
- **I want to run a validator or understand scoring:** read **[greevils-validator](https://github.com/greevils-ai/greevils-validator)**.