Agent0 & ERC-8004 Subgraphs

.gitignore

@@ -39,3 +39,4 @@ dist/
 .turbo/
 packages/og-image/vendor/*.wasm
 .wrangler/
+.Rproj.user

website/src/pages/en/subgraphs/guides/agent0.mdx

@@ -0,0 +1,234 @@
+# Agent0 Subgraphs (ERC-8004)
+
+The **Agent0 Subgraphs** index the [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) registries — Identity, Reputation, and Validation — across five major networks. They give developers a single GraphQL interface to discover agents, filter by capability, query reputation, and track validation outcomes in real time.
+
+Built and maintained by [Agent0](https://sdk.ag0.xyz/docs) in partnership with The Graph.
+
+> **Note:** Agent0 Subgraphs are a public good. The schema, mappings, and deployment configs are open-source and available at [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph).
+
+## Supported networks
+
+| Network | Chain ID | Status | Endpoint | Explorer |
+|---------|----------|--------|----------|----------|
+| **Ethereum Mainnet** | 1 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k) | [Explorer](https://thegraph.com/explorer/subgraphs/FV6RR6y13rsnCxBAicKuQEwDp8ioEGiNaWaZUmvr1F8k?view=Query&chain=arbitrum-one) |
+| **Base Mainnet** | 8453 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb) | [Explorer](https://thegraph.com/explorer/subgraphs/43s9hQRurMGjuYnC1r2ZwS6xSQktbFyXMPMqGKUFJojb?view=Query&chain=arbitrum-one) |
+| **BSC Mainnet** | 56 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K) | [Explorer](https://thegraph.com/explorer/subgraphs/D6aWqowLkWqBgcqmpNKXuNikPkob24ADXCciiP8Hvn1K?view=Query&chain=arbitrum-one) |
+| **Polygon Mainnet** | 137 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF) | [Explorer](https://thegraph.com/explorer/subgraphs/9q16PZv1JudvtnCAf44cBoxg82yK9SSsFvrjCY9xnneF?view=Query&chain=arbitrum-one) |
+| **Monad** | 143 | ✅ Deployed | [Endpoint](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) | [Explorer](https://thegraph.com/explorer/subgraphs/4tvLxkczjhSaMiqRrCV1EyheYHyJ7Ad8jub1UUyukBjg?view=Query&chain=arbitrum-one) |
+| **Ethereum Sepolia** | 11155111 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT) | [Explorer](https://thegraph.com/explorer/subgraphs/6wQRC7geo9XYAhckfmfo8kbMRLeWU8KQd3XsJqFKmZLT?view=Query&chain=arbitrum-one) | 
+| **Base Sepolia** | 84532 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u) | [Explorer](https://thegraph.com/explorer/subgraphs/4yYAvQLFjBhBtdRCY7eUWo181VNoTSLLFd5M7FXQAi6u?view=Query&chain=arbitrum-one) |
+| **BSC Chapel** | 97 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z) | [Explorer](https://thegraph.com/explorer/subgraphs/BTjind17gmRZ6YhT9peaCM13SvWuqztsmqyfjpntbg3Z?view=Query&chain=arbitrum-one) |
+| **Monad Testnet** | 10143 | ✅ Deployed | [Endpoint](https://gateway.thegraph.com/api/subgraphs/id/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU) | [Explorer](https://thegraph.com/explorer/subgraphs/8iiMH9sj471jbp7AwUuuyBXvPJqCEsobuHBeUEKQSxhU?view=Query&chain=arbitrum-one) |
+| **Polygon Amoy** | 80002 | ⛔️ Subgraphs not deployed | - | - |
+| **Linea Sepolia** | 59141 | ⛔️ Subgraphs not deployed | - | - |
+| **Hedera Testnet** | 296 | ⛔️ Subgraphs not deployed | - | - |
+| **HyperEVM Testnet** | 998 | ⛔️ Subgraphs not deployed | - | - |
+| **SKALE Base Sepolia** | 1351057110 | ⛔️ Subgraphs not deployed | - | - |
+
+A single GraphQL schema is shared across all available deployments, so the same query works on every chain — only the endpoint URL changes.
+
+## What's indexed
+
+| Domain | Data |
+| --- | --- |
+| **Agent registrations** | Identity (ERC-721 token), owner, operators, registration URI, ENS, DID, agent wallet, x402 support, supported trust models, name, description, image |
+| **Capabilities** | MCP endpoint, version, tools, prompts, resources. A2A endpoint, version, skills. OASF taxonomy tags |
+| **Feedback** | Score (0–100), tags, client address, off-chain feedback file (text, capability, skill, task, proof of payment), revocation status, responses |
+| **Validation** | Validator address, request/response URIs, score, tag, status (pending, completed, expired) |
+| **Aggregates** | Per-agent stats (avg score, score distribution, totals), per-chain protocol entity, global cross-chain rollup |
+
+Off-chain registration and feedback files (IPFS or HTTPS) are fetched and parsed via File Data Sources, so JSON metadata is queryable alongside on-chain events — no separate IPFS round trip required from the client.
+
+## Why use the Subgraph
+
+- **Fast search:** Query thousands of agents in milliseconds. Filter by capability, score, trust model, or chain.
+- **Rich filtering:** Combine on-chain and off-chain fields in a single GraphQL query.
+- **Real-time data:** New registrations, feedback, and validation events are indexed automatically as they're emitted.
+- **No RPC limits:** Skip rate-limited RPC scans and IPFS round-trips. One query, one response.
+
+## Quick start
+
+### 1. Get an API key
+
+Create a free account on [Subgraph Studio](https://thegraph.com/studio) and generate an API key.
+
+### 2. Find your endpoint
+
+Search **agent0** on [Graph Explorer](https://thegraph.com/explorer?search=agent0) and copy the Subgraph ID for the network you want. Endpoints follow this pattern:
+
+```
+https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
+```
+
+### 3. Run a query
+
+**cURL**
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ agents(first: 5) { id registrationFile { name description mcpEndpoint } } }"}' \
+  https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
+```
+
+**TypeScript**
+
+```typescript
+const res = await fetch(
+  `https://gateway.thegraph.com/api/${API_KEY}/subgraphs/id/${SUBGRAPH_ID}`,
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      query: `{
+        agents(first: 5) {
+          id
+          registrationFile { name description mcpEndpoint }
+        }
+      }`,
+    }),
+  }
+);
+const { data } = await res.json();
+```
+
+**Python**
+
+```python
+import requests
+
+url = f"https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}"
+query = """{
+  agents(first: 5) {
+    id
+    registrationFile { name description mcpEndpoint }
+  }
+}"""
+res = requests.post(url, json={"query": query}).json()
+```
+
+> **Tip:** Using the [Agent0 SDK](https://sdk.ag0.xyz/docs)? Subgraph endpoints are wired up by default — you can call `sdk.searchAgents(...)` and `sdk.searchFeedback(...)` without writing GraphQL by hand.
+
+## Common queries
+
+### Find MCP-compatible agents
+
+```graphql
+query GetMCPAgents {
+  agentRegistrationFiles(
+    where: { mcpEndpoint_not: null, active: true }
+    first: 100
+  ) {
+    agentId
+    name
+    description
+    mcpEndpoint
+    mcpVersion
+    mcpTools
+    supportedTrusts
+  }
+}
+```
+
+### Get a complete agent profile
+
+```graphql
+query GetAgent {
+  agent(id: $id) { # example: "8453:0"
+    id
+    chainId
+    agentId
+    owner
+    createdAt
+    totalFeedback
+    registrationFile {
+      name
+      description
+      image
+      mcpEndpoint
+      mcpTools
+      a2aEndpoint
+      a2aSkills
+      supportedTrusts
+      x402Support
+      ens
+      did
+    }
+    feedback(where: { isRevoked: false }, first: 10, orderBy: createdAt, orderDirection: desc) {
+      tag1
+      tag2
+      clientAddress
+      feedbackFile { text }
+    }
+    validations(orderBy: createdAt, orderDirection: desc) {
+      validatorAddress
+      response
+      status
+      tag
+    }
+  }
+}
+```
+
+The agent `id` is formatted as `chainId:agentId` (e.g. `8453:1247` for agent 1247 on Base).
+
+### Filter agents by trust model
+
+```graphql
+query AgentsByTrust($trustModel: String!) {
+  agentRegistrationFiles(
+    where: { supportedTrusts_contains: [$trustModel], active: true }
+    first: 50
+  ) {
+    agentId
+    name
+    description
+    supportedTrusts
+  }
+}
+```
+
+Common values: `"reputation"`, `"cryptoeconomic"`, `"tee-attestation"`.
+
+### Top-rated feedback across the network
+
+```graphql
+query TopFeedback {
+  feedbacks(
+    where: { isRevoked: false, value_gte: 1000 }
+    first: 50
+    orderBy: value
+    orderDirection: desc
+  ) {
+    value
+    tag1
+    tag2
+    agent {
+      id
+      registrationFile { name }
+    }
+    feedbackFile { text }
+  }
+}
+```
+
+## Schema reference
+
+Core entities:
+
+- **`Agent`:** Onchain identity, mutable. Linked to `AgentRegistrationFile`, `Feedback[]`, `Validation[]`, `AgentStats`.
+- **`AgentRegistrationFile`:** Immutable, parsed from the IPFS/HTTPS registration URI. Contains all advertised capabilities.
+- **`Feedback`:** Onchain feedback entry. Linked to optional `FeedbackFile` for off-chain text and proof of payment.
+- **`FeedbackFile`:** Immutable, parsed from the feedback URI.
+- **`Validation`:** Validation request and response lifecycle. Status: `PENDING`, `COMPLETED`, `EXPIRED`.
+- **`protocolAgentStats`:** Per-agent rollup (total feedback, average score, score distribution).
+- **`Protocol`:** Per-chain rollup.
+
+Full schema: [`schema.graphql`](https://github.com/agent0lab/subgraph/blob/main/schema.graphql).
+
+## Resources
+
+- **Agent0 SDK:** TypeScript and Python SDK for ERC-8004 registration, discovery, and reputation: [sdk.ag0.xyz/docs](https://sdk.ag0.xyz/docs)
+- **Subgraph repo:** Open-source mappings, schema, and multi-chain deployment config: [github.com/agent0lab/subgraph](https://github.com/agent0lab/subgraph)
+- **ERC-8004 spec:** The Trustless Agents standard: [eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004)
+- **Graph Explorer:** Browse all Agent0 Subgraphs: [thegraph.com/explorer?search=agent0](https://thegraph.com/explorer?search=agent0)