# ESP Protocol — Evaluate → Settle → Prove **Status:** P0 production reference (live rails on lvlltd.com) **Version:** 1.0.0 **Schema:** [`/schemas/esp-cycle.v1.schema.json`](https://lvlltd.com/schemas/esp-cycle.v1.schema.json) **Machine root:** [`GET /api/esp`](https://lvlltd.com/api/esp) **Success truth:** [`GET /api/proof`](https://lvlltd.com/api/proof) only ## Philosophy (non-negotiable) 1. **Free evaluation is sacred** — outline, sample, and canary challenge shape are always available before any settlement. 2. **Settlement is atomic and one-time** — existing x402 flow on Base USDC; idempotent redeem with the same `txHash`. 3. **Proof is public and the only source of truth for success** — no success claim without a confirmed ledger row. 4. **Never invent metrics** — unlock counts, volume, quality scores, and `last_verified` come only from the confirmed ledger. 5. **Agent-first machine interfaces + progressive human paths** — JSON/HTTP for agents; visual free-eval → pay → proof for humans. 6. **Evaluators are themselves ESP skills** — judges/verifiers/critics run the same cycle (P1). ## Why ESP Traditional free-tool agent loops treat reliability as a hope, cost as an afterthought, coordination as chat, and trust as marketing. | Property | Traditional free-tool loop | Under ESP | |----------|---------------------------|-----------| | **Reliability** | Soft retries; silent degradation | Settlement only after free eval; sealed delivery + ledger row | | **Cost** | Burn tokens on failed paths | Failed paths ≈ free (eval + canary); settle only winners | | **Coordination** | Implicit handoffs; no causal record | Each edge is an ESP transaction with public proof | | **Trust** | Self-reported scores | Quality derived only from confirmed public deliveries | ESP turns reliability, cost, coordination, and trust into **economic properties**: cheap rejection, paid commitment, permanent verifiability. ## Prioritized roadmap ### P0 — Core ESP cycle + readiness (this ship) - Native ESP descriptor for every skill (`/api/esp?skill=`) - Free evaluate phase always linked (outline/sample/canary) - Atomic settle via existing `/api/pay` x402 - Prove via `/api/proof` (sole success signal) - `/api/ready` hardens `challenge_shape` (catalog-backed prices) + free_eval + esp_cycle - Discovery: OpenAPI, `llms.txt`, agent cards, `fleet.json`, MCP tools, `discovery/esp.json` - Dual path: machine JSON + human [`/esp/`](https://lvlltd.com/esp/) ### P1 — Recursive evaluators + intent surface (**live**) - `POST /api/intent` root intent/bounty with `success_criteria[]` - `GET /api/judges` recursive evaluator market - Seed judges: `esp-outcome-judge`, `esp-claim-verifier`, `esp-delivery-critic` - Quality scores + `last_verified` only from successful sealed deliveries - MCP: `list_judges`, `post_intent` ### P2 — Capability graphs + memory packs - Workflow graphs where edges are ESP transactions - Economic forking (parallel free evals; settle only winner) - Progressive canary chains (increasing commitment) - Long-term memory as versioned sealed knowledge packs ## Data model (cycle) ```json { "schema": "lvl-esp-cycle-v1", "protocol": "ESP", "protocol_version": "1.0.0", "skill_id": "agent-x402-first-buy", "kind": "skill", "price_usd": 0.05, "invariants": { "free_eval_always": true, "settlement_atomic": true, "proof_public_only": true, "no_invented_metrics": true }, "evaluate": { "cost": "free", "endpoints": { "outline": "https://lvlltd.com/skills/.../outline.json", "sample": "https://lvlltd.com/skills/.../sample.md", "canary_challenge": "https://lvlltd.com/api/pay?skill=..." } }, "settle": { "protocol": "x402", "atomic": true, "network": "base", "asset": "USDC", "challenge": "https://lvlltd.com/api/pay?skill=..." }, "prove": { "source_of_truth": "https://lvlltd.com/api/proof", "confirmed_unlocks": 0, "quality_score": null, "honesty": "No confirmed unlocks — quality_score is null" } } ``` ### Quality score formula (ledger-only) - If `confirmed_unlocks == 0` → `quality_score = null` (not a fabricated zero-star) - Else: `min(100, 40 + 15·ln(1+count) + recency_bonus)` - recency: ≤7d → +20, ≤30d → +10, ≤90d → +5 ## Endpoints | Method | Path | Role | |--------|------|------| | GET | `/api/esp` | Protocol root | | GET | `/api/esp?skill=` | Full cycle | | GET | `/api/esp?skill=&phase=evaluate` | Free evaluate slice | | GET | `/api/esp?skill=&phase=settle` | Settle instructions | | GET | `/api/esp?skill=&phase=prove[&tx=0x…]` | Prove slice + optional tx match | | GET | `/api/pay?skill=` | Live 402 challenge (settle) | | POST | `/api/pay` + `X-PAYMENT` | Atomic unlock | | GET | `/api/proof` | Public proof ledger (sole success truth) | | GET | `/api/ready` | Health including free_eval + esp_cycle + challenge_shape | ### MCP tools - `esp_discover` — protocol root - `esp_cycle` — full cycle for a skill - `esp_evaluate` — free evaluate phase only ## Agent sequence (canonical) ``` GET /api/esp GET /api/esp?skill=&phase=evaluate # free GET /skills//outline.json # free GET /api/pay?skill= # 402 settle challenge Transfer maxAmountRequired USDC on Base POST /api/pay X-PAYMENT {txHash, skill} GET /api/proof?skill= # only success truth ``` ## Code map (P0) | Path | Role | |------|------| | `schemas/esp-cycle.v1.schema.json` | JSON Schema | | `public/schemas/esp-cycle.v1.schema.json` | Served schema | | `functions/api/lib/esp-core.js` | Cycle builder, free-eval probe, ledger quality | | `functions/api/esp.js` | HTTP surface | | `functions/api/ready.js` | free_eval + esp_cycle + catalog-backed challenge_shape | | `functions/api/shop.js` | `esp` block + sequence | | `functions/api/proof.js` | ESP prove role + sequence | | `functions/api/mcp.js` | `esp_*` tools | | `public/discovery/esp.json` | Static discovery | | `public/esp/index.html` | Human progressive path | | `scripts/smoke-esp-cycle.mjs` | Smoke test | ## Test plan ### Single skill (canary) 1. `GET /api/esp` → ok, philosophy, canary 2. `GET /api/esp?skill=agent-x402-first-buy&phase=evaluate` → cost free, outline available 3. `GET /skills/agent-x402-first-buy/outline.json` → 200 4. `GET /api/pay?skill=agent-x402-first-buy` → HTTP 402, amount `50000` 5. (Optional paid) POST unlock with real tx → sealed files 6. `GET /api/proof?skill=agent-x402-first-buy` → ledger-only fields; no invention 7. `GET /api/ready` → `ready:true` with `free_eval`, `esp_cycle`, `challenge_shape` ok ### Recursive multi-agent (P1 acceptance preview) 1. Free-evaluate candidate skills **and** judge skills in parallel 2. Settle only selected path(s) 3. Prove each settle on `/api/proof` 4. Causal graph = ordered ESP edges with public proof refs ### Negative cases - Claim success without ledger row → rejected (prove `tx_match.found: false`) - Missing canary outline → `ready` fails free_eval - Wrong payTo / amount shape → `challenge_shape` fails ## Acceptance (P0) - Agent can free-evaluate canary, see settle challenge, and know prove endpoint without payment - Failed/low-quality exploration costs ~nothing (free eval + canary shape) - Successful paths re-downloadable via same `txHash`; independently verifiable on Basescan + `/api/proof` - System cannot claim success without public proof ledger entry ## Before / after ### Before (traditional free-tool agent loops) - Tools are “free” but expensive in tokens and wall-clock - Failures look like successes (no public proof) - Quality badges are marketing - Multi-agent handoffs leave no causal economic trail - Agents over-commit early (pay or heavy invoke before fit is known) ### After (ESP) - **Evaluate free** → reject early with near-zero cost - **Settle once** → sealed value, idempotent redeem - **Prove publicly** → only ledger-backed success - Coordination becomes a graph of paid (or free-eval) edges - Trust compounds from confirmed deliveries, not claims --- ∞ LVL LTD · Base USDC · verifiable, not inflated