> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phyi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> The shared plumbing layer, the four track pipelines, and on-chain coordination.

The principle of the architecture is that **the plumbing is generic and the
evaluation is private to each track**. One shared layer carries registration,
custody, rounds, execution, and consensus; four isolated pipelines carry the
per-track analysis.

## The shared plumbing layer

| Component              | Role                                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| Registration service   | Track registration, miner and validator identity, hotkey management                             |
| Agent registry         | Stores hash-pinned agent code, versioned submissions                                            |
| Round manager          | Server-scheduled rounds (block-derived fallback), the round state machine, per-track scheduling |
| Task selector          | Deterministic, reproducible selection from the track corpus                                     |
| Execution orchestrator | Distributes tasks, manages sandboxes, collects results                                          |
| Consensus engine       | Stake-weighted consensus, median aggregation, weight finalization                               |
| Attestation service    | Writes SSSAs on chain, policy and evidence, public verification                                 |
| Marketplace            | Serves verified agents, search and filter, API access                                           |

## The four track pipelines

Each track owns a corpus, a benchmark, and an evaluation pipeline, and never
shares them:

| Track          | Method                                                                                                            |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `skills`       | Detonation: dual-plane analysis, probe-based execution, capability and injection detection, transitive risk       |
| `mcp_servers`  | Detonation + component analysis: tools, resources, handlers, config, cross-component behavior tracking            |
| `packages`     | Lifecycle detonation: install-time execution, import-time behavior, supply-chain analysis (SBOM), dependency risk |
| `repositories` | Static audit: source analysis, vulnerability detection, CWE classification, recall-based scoring                  |

Track isolation is a hard property. A skills miner and a packages miner operate
in what are effectively parallel subnetworks that share only a chain: no
cross-track consensus, no shared finding identifiers, no common evidence
definition. The four tracks run their own independent rounds, in parallel, on
their own schedules, because analysis times differ sharply between artifact
types.

## Coordination: server and chain

The server schedules *when* rounds run and issues each validator the same round id
and seed; the chain is the source of truth for the competition and its reward. The
server never scores or picks a winner, and if it is down validators fall back to a
block-derived seed.

| Primitive          | Source                       | Used for                                               |
| ------------------ | ---------------------------- | ------------------------------------------------------ |
| Round id + seed    | Server (block-hash fallback) | Opening a round and deriving the shared task set       |
| Block hash         | Chain                        | Fallback round seed when no server schedules the round |
| Weight submissions | Chain                        | Each validator's graduated weight vector               |
| Consensus (stakes) | Chain                        | Stake-weighted median with clipping                    |
| Commitments        | Chain                        | SSSA storage and the contributor set                   |
| Final weights      | Chain                        | Emissions per agent                                    |

## Isolation

All agent execution happens inside a strict, network-isolated sandbox: an
instrumented container with no path to the open internet, whose only outbound
route is a metered inference proxy, with hard limits on memory, processor time,
and process count, all capabilities dropped (`cap-drop=ALL`, `no-new-privileges`),
and a non-root user. The image is the **validator's own** hardened sandbox, not one
the miner supplies, so untrusted miner code runs in a trusted runtime rather than
an attacker-chosen one. Untrusted agent code is never run directly on the validator
host; it runs only inside this jail, and if the jail is unavailable the execution
does not proceed. This protects the validator, which holds keys and stake, from a
malicious agent, and it bounds the resource cost of any single run.

Before an agent is admitted to a round, a **screening** stage rejects agents that
are malformed, exceed the size limit, or fail to expose the required entrypoint,
and agents that exhibit signs of abuse: attempts to execute unauthorised system
commands, read secrets, exhaust resources, abuse the inference channel, or
obfuscate their behavior.

## Integrity checks across the round

Two further checks protect the competition continuously:

* **Agent similarity** — token- and code-structure-level detection of an agent
  copied from another and resubmitted, a real risk once agents are published.
* **Benchmark steering** — detection of an agent targeting known answers rather
  than genuinely analysing the artifact.

An agent found to be copied or gaming the benchmark is removed, and when a
top-ranked miner is removed, the next-ranked miner takes its place.

## Eligibility and consensus

Validator eligibility is on-chain and permissionless: a validator permit granted
by stake weight and positive vtrust from actively setting weights. Each validator
sets weights independently, and Yuma consensus aggregates them by stake. There is
no central register and no team approval.