# COR Prover – External Validation Framework

**Status:** Design → Testnet Phase-4 roll-out (Router v2)\
**Surfaces:** REST (now), x402 (edge), MCP (agent runtimes)\
**Trust Rails:** PoI (quantitative), PoUW (qualitative), Attestations (JWS / EIP-712), optional ERC-8004 artifacts\
**Backbone:** Reuses Cortensor **Session / SessionQueue / Validator** with delegated sessions (no core protocol change)

***

### 1) What it does

* **Redundant re-inference (k-redundant)** of a candidate result on Cortensor miners.
* **PoI (Proof of Inference)**: embedding-distance + dispersion to detect inconsistency.
* **PoUW (Proof of Useful Work)**: LLM-verifier rubric to score usefulness/quality.
* **Attestation**: Signed JWS (optional EIP-712) + evidence bundle (IPFS/Arweave).
* **Anchoring (optional)**: Write a `ValidationResponse` to an ERC-8004-compatible registry.

Use it to validate:

* LLM outputs (text/multimodal);
* Structured results (JSON/specs) with rule checks;
* Hybrid flows (rule → LLM rubric).

***

### 2) High-level flow

```
Client → [Edge/x402] → Router v2 /validate
                 │
           (x402 settle)
                 ▼
        Delegated Session (Cortensor)
            ├─ k redundant re-inference
            ├─ PoI (embedding stats)
            ├─ PoUW (LLM-verifier, rubric)
            └─ TaskRoot → SessionRoot update
                 ▼
      Signed Attestation (JWS/EIP-712)
                 ├─ Evidence (IPFS/Arweave)
                 └─ (optional) 8004 Validation write
```

***

### 3) API (REST, v1)

#### 3.1 `POST /v1/prover/validate`

**Purpose:** Submit input + candidate for validation. Optionally pick policies (k, eval rubric).\
**Auth/Payment:**

* **Now:** API key (test) or allowlist; optional 402 stub for sandbox.
* **Phase-4:** **x402** at edge → receipt verified → credit session (direct) or staking pool.
* **MCP:** mirrored tool method (see §8).

**Request (JSON)**

```json
{
  "job": {
    "input": { "prompt": "Explain PoI vs PoUW to a dev." },
    "candidate": { "text": "PoI checks consistency; PoUW checks usefulness." }
  },
  "policy": {
    "k": 5,
    "poi": { "embedding_model": "all-MiniLM-L6-v2", "distance": "cosine", "dispersion_threshold": 0.25 },
    "pouw": {
      "rubric": ["factuality","consistency","relevance","format_adherence"],
      "verifier_model": "gpt-4o-mini-like",
      "score_threshold": 0.75
    },
    "rules": {
      "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] },
      "max_tokens": 2048
    },
    "finalize": { "attestation": "JWS", "anchor_8004": false }
  },
  "metadata": {
    "buyer":"0xabc...","trace_id":"req_123","ttl_sec":120
  }
}
```

**Response (202 Accepted)**

```json
{ "jobId": "job_9f2f...", "status": "queued", "k": 5, "eta_sec": 20 }
```

#### 3.2 `GET /v1/prover/jobs/{jobId}`

Returns state and partial metrics while running. Jobs will be reading from Session Queue module.

```json
{
  "jobId": "job_9f2f...",
  "status": "running",
  "progress": { "assigned": 5, "completed": 3 },
  "poi": { "dispersion": 0.31, "outliers": ["miner_12"] },
  "pouw": { "sampled": 2, "avg_score": 0.78 }
}
```

#### 3.3 `GET /v1/prover/jobs/{jobId}/attestation`

Final results + signed proof. If `anchor_8004=true`, includes registry pointer(s).

```json
{
  "attestation": {
    "format": "JWS",
    "payload": {
      "iss":"cor-prover",
      "sub":"job_9f2f",
      "session_id":"sess_4c7a",
      "task_ids":["t1","t2","t3","t4","t5"],
      "input_hash":"0x....",
      "candidate_hash":"0x....",
      "policy":{"k":5,"poi":{"distance":"cosine"},"pouw":{"rubric":["factuality","..."]}},
      "poi":{"method":"cluster-median","dispersion":0.22,"anomalies":["miner_12"]},
      "pouw":{"score":0.84,"rubric_scores":{"factuality":0.86,"consistency":0.82,"relevance":0.85,"format_adherence":0.82}},
      "task_root":"0xTASKROOT",
      "session_root":"0xSESSIONROOT",
      "evidence":{"ipfs":"ipfs://bafk..."},
      "settlement":{"invoice":"inv_xyz","amount":"0.0002","currency":"ETH","chain_id":"42161"},
      "iat": 1762065600,
      "exp": 1762069200
    },
    "signature":"eyJhbGciOi..."
  },
  "anchors": {
    "erc8004": {
      "validation_tx": null,
      "offchain_ref": "https://registry.example/val/0x..."
    }
  }
}
```

**Errors** (examples)

* `402 Payment Required` (with **x402** headers – Phase-4)
* `422 Unprocessable` (schema mismatch / invalid policy)
* `429 Too Many Requests` (rate-limits / pass quota)
* `504 Timeout` (SLA breach; includes refund token when applicable)

***

### 4) Validation methods

#### 4.1 Quantitative (PoI)

* **What:** Compare k re-inference outputs using **embedding vectors**; compute **pairwise/cluster** stats.
* **Signals:** dispersion (median/IQR), centroid distance, anomaly miners, agreement ratio.
* **Pass/Fail:** policy threshold on dispersion; flag if outliers dominate.
* **Storage:** per-job metrics, plus node-level accumulation into **QuantitativeStats / QuantitativeReputation**.

#### 4.2 Qualitative (PoUW)

* **What:** **LLM-verifier** scores candidate (and/or re-runs) on rubric: factuality, consistency, relevance, format, safety.
* **Sampling:** on all k results or on high-dispersion subsets to save budget.
* **Pass/Fail:** aggregated rubric score ≥ threshold; keep rubric breakdowns.
* **Storage:** **QualitativeStats / QualitativeReputation** with time-series roll-ups.

#### 4.3 Rule checks (optional)

* **Schema/format** (JSON schema), **numeric ranges**, **required fields**, **regex**, **max token length**, **safety keywords**.
* **Order:** rules → (if pass) PoI → (if needed) PoUW → final decision.

***

### 5) Proofs & Merkle roots

* **TaskRoot (per task)**: Merkle root of leaves\
  `H(taskId, minerId, modelId, inputHash, outputHash, meta)`
* **SessionRoot (rolling)**: updates as each **TaskRoot** is sealed — a moving commitment ledger for an open session.
* **Attestation** includes both; **Evidence bundle** (optional) holds anonymized leaf material (hashes, metrics, redactable).

***

### 6) x402 integration (Phase-4 edge)

* **Edge behavior:** If unpaid/underfunded → return `402 Payment Required` with **x-402** challenge:

  ```
  WWW-Authenticate: X402 ver="1"; amount="0.0002"; currency="ETH"; chain_id="42161";
  pay_to="0xCOR_TREASURY"; invoice="inv_..."; scope="POST:/v1/prover/validate#job=<H(input,candidate,policy)>";
  exp="<+60s>"; proof="jws"; callback="https://api.cortensor.dev/x402/webhook"
  ```
* **Client pays** (facilitator/on-chain), retries with receipt; **Receipt Verifier** mints internal credit and forwards.
* **Accounting:** `PaymentReceived(x402, invoice, jobId, amount)` → Indexer/Dashboard.
* **Settlement target:** **SessionPayment** (direct) or **SessionPaymentStaking** pool (stake-to-use).

***

### 7) ERC-8004 alignment (optional in Phase-4)

* **Identity:** Register COR Prover as an agent (Router v2).
* **Validation:** Write `ValidationResponse` entries referencing **TaskRoot/SessionRoot** and evidence URL.
* **Reputation (later):** Feed summary scores to 8004 Reputation; keep node/session-level detail in Cortensor reputation modules.

**Mapping**

* `AgentServerID` ⟶ `SessionID` (aggregates miners internally)
* `AgentValidatorID` ⟶ COR Prover validator service
* `DataHash` ⟶ `TaskRoot` / `SessionRoot`

***

### 8) MCP tool (mirrors REST)

**Server advertises tools:**

* `cortensor.prover.validate(input, candidate, policy?) → jobId`
* `cortensor.prover.attestation(jobId) → attestation`

**Payment over MCP:** First call emits **x402 challenge event**; client returns receipt in `tool/use` metadata. **Passes/quotas** supported post-Testnet.

***

### 9) Policies & tuning

* **k-redundancy:** default 3; tiers (1/3/5) by SLA/price.
* **Dispersion threshold:** default 0.25 cosine; adjustable per domain.
* **Rubric:** default 4-criteria; domain packs (code, math, support).
* **Sampling:** `eval=auto|always|never`; `auto` triggers PoUW when PoI dispersion high.
* **Time budget:** commit/reveal windows per task; global **job TTL**.
* **Privacy:** hash inputs; store raw evidence off-chain; role-gated bundle access.

***

### 10) Security, rate limits, and abuse controls

* **Single-use receipts** (Redis), **short TTL** (≤60s), **scope** bound to `jobHash`.
* **DPoP/cnf** binding for agent callers (post-Testnet).
* **Payload caps** (input size, model hints), **min/max k** per buyer.
* **Refund tokens** for timeouts/SLA violations.
* **Audit**: all decisions + hashes + pricing version recorded.

***

### 11) Minimal data model (sketch)

* **jobs**: `job_id, job_hash, buyer, session_id, k, policy_json, status, created_at, completed_at`
* **metrics\_poi**: `job_id, dispersion, centroid, outliers[]`
* **metrics\_pouw**: `job_id, score, rubric_scores{}`, `verifier_model`
* **attestations**: `job_id, jws, eip712?, evidence_uri, task_root, session_root`
* **invoices**: `invoice_id, scope_hash, amount, currency, chain_id, pay_to, tx_hash, status, used_at`

***

### 12) Example: hybrid validation (rule → PoI → PoUW)

**Request**

```json
{
  "job": {
    "input": {"prompt":"Summarize our privacy key-exchange methods."},
    "candidate": {"text":"Method 1 uses ECDH with commitments; Method 2 uses a coordinator."}
  },
  "policy": {
    "k": 3,
    "rules": {
      "schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},
      "max_tokens": 1000
    },
    "poi":{"embedding_model":"text-embed-lite","distance":"cosine","dispersion_threshold":0.3},
    "pouw":{"verifier_model":"gpt-4o-mini-like","rubric":["factuality","relevance"],"score_threshold":0.8},
    "finalize":{"attestation":"JWS","anchor_8004":false}
  }
}
```

**Final (attestation payload excerpt)**

```json
{
  "poi":{"dispersion":0.21,"anomalies":[]},
  "pouw":{"score":0.86,"rubric_scores":{"factuality":0.88,"relevance":0.84}},
  "decision":{"valid":true,"reasons":["rules_pass","poi_low_dispersion","pouw_score>=0.8"]}
}
```

***

### 13) Operational notes

* **SLA tiers (example):**
  * k=1 (cheap/fast, no eval): p50 5–10s
  * k=3 (balanced, eval on high dispersion): p50 15–25s
  * k=5 (critical, eval always): p50 ≤30s
* **Gas/L2 optimization:** minimize on-chain writes; batch anchors; compress event logs; prefer off-chain bundles with anchored roots.
* **Observability:** job timelines, miner dispersion histograms, verifier latency, receipt-verify success.

***

### 14) Roadmap fit

* **Testnet Phase-4:** Ship Router v2 `/validate` with x402 edge, delegated sessions, PoI+PoUW, JWS attestation, optional 8004 off-chain write.
* **Post-Testnet (Integration Phases 2–3):** Passes/quotas, default 8004 writes, agent-bound flows, Router v3 (inference + validation), MCP first-class.

***

#### TL;DR for integrators

* Call **`POST /v1/prover/validate`** with `{input, candidate, policy}`.
* Handle **402/x402** (Phase-4) or use test key.
* Poll **`/jobs/{id}`**, then fetch **`/jobs/{id}/attestation`**.
* Verify **JWS**; (optionally) look up **ERC-8004** validation reference.
* Trust the numbers: **PoI** (consistency) + **PoUW** (quality) + **TaskRoot/SessionRoot** (proof).