GroundTruth Field Evidence

GroundTruth — 已验证的实地证据

派发实地核查，获取最新的照片证据、结构化观察结果和可审计的验证凭证。

---

GroundTruth 是什么？

GroundTruth 是一个实地证据 API。其首个商业工作流是零售核验：核实当前商品的货架供应情况、价格、促销活动和陈列合规情况，这些信息无法通过现有数据库可靠地获取。

运营团队或 AI Agent 会创建一项已注资的任务，由实地工作人员完成任务，而 GroundTruth 则返回带有证据链的结构化结果。现有原型支持 MCP 和 A2A、照片与表单证明、AI 辅助核验、时效性质询，以及通过 x402 支付：在 Arbitrum One 和 Base 上使用 USDC，或在 X Layer 上使用 USD₮0。隐私保护型证据凭证哈希可锚定至已部署的 Arbitrum Sepolia 注册表。

目前该产品处于重点试点阶段。实地活动开始前会确认覆盖范围和响应时间；本项目不宣称覆盖所有地区。

在 Arbitrum Open House 构建中，GroundTruth 还演示了端到端的 Robinhood Chain Testnet USDG 托管和证据凭证流程：为核验注资、锚定私有证据摘要，并仅在得出判定后释放 USDG。这是协议演示，并非客户收入。

公测准备情况

该应用包含爬虫和 Agent 发现功能（robots.txt、sitemap.xml、JSON-LD、llms.txt、OpenAPI、MCP、A2A、/.well-known/agent.json 和 /.well-known/agent-card.json）、私有活动会话、已脱敏的公开任务视图、签名工作者认领、上传验证、持久化速率限制、审计事件、法律与安全页面、强化的浏览器标头，以及 /api/health 就绪状态报告。

启用真实的公开流量前：

1. 按顺序应用 supabase/migrations 中的所有 SQL 文件，包括 004_campaigns.sql 和 005_production_hardening.sql。
2. 按照 .env.example 中的说明配置环境变量，并分别设置高熵的管理员、试点和认领签名密钥。
3. 保持测试网水龙头和公开凭证处于禁用状态；在审核运营安排到位前，保持自动接受功能禁用。
4. 配置生产监控，在 /api/health 返回非 200 响应时发出警报，并验证数据库备份和证据保留机制。
5. 将演示结算签名者替换为经批准的生产托管方案，并完成针对具体司法管辖区的客户与工作人员协议。

在具备必需配置并应用数据库迁移之前，/api/health 会有意返回 HTTP 503。网站构建成功不代表系统已具备运营就绪条件。

AI Agent  →  [MCP: human_do]  →  x402 Payment  →  Oracle Board
                                                          ↓
AI Agent  ←  [MCP: task_status]  ←  Verified Proof  ←  Human Oracle

---

演示

在线应用： https://groundtruth-oracle.vercel.app

交互式零售活动： /campaigns/demo（本地或已部署）

活动构建器： /campaigns/new（需要配置的试点访问密钥）

Robinhood + USDG 证明： /robinhood（公开、无需账户、实时链上读取）

视频演示： https://x.com/0xBejini/status/2078065892659958215

公开活动页面包含开发、演示和测试网使用情况。它并不代表客户增长。

完整的演示流程和生产环境前置条件记录在 docs/RETAIL-DEMO.md 中。

亲自试用

将 MCP 服务添加到 Claude Code：

claude mcp add groundtruth --transport http https://groundtruth-oracle.vercel.app/api/mcp

然后在 Claude 会话中，请求付费任务前先检查服务：

Call ground_truth_info, then prepare a human_do request with:
- intent: "Verify the nearest coffee shop is open and photograph the entrance"
- service_tier: "quick_check"
- proof_spec.type: "photo"
- proof_spec.instructions: "Clear photo of the entrance showing it is open"

未付费调用会返回机器可读的 HTTP 402 挑战。兼容的钱包可以选择一个已公布的支付通道，授权确切金额和收款方，然后重放请求。覆盖范围和履约仍以异步方式进行。

---

架构

┌─────────────────────────────────────────────────────────┐
│                     AI Agent (MCP)                      │
│  ground_truth_info → human_do → task_status             │
└────────────────────────┬────────────────────────────────┘
                         │ x402 X-PAYMENT header
                         ▼
┌─────────────────────────────────────────────────────────┐
│              GroundTruth API (Next.js)                  │
│  /api/mcp          MCP server (SSE transport)           │
│  /api/v1/human-do  Task creation + payment verify       │
│  /api/v1/tasks/:id Task status + proof                  │
│  /api/faucet       mUSDT testnet faucet                 │
└────────┬───────────────────────┬────────────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐   ┌──────────────────────────────────┐
│   Supabase DB   │   │      Onchain payment rails       │
│  tasks          │   │  GroundTruthPayroll.sol           │
│  payments       │   │  Arbitrum One USDC (42161)        │
│  workers        │   │  Base USDC (8453)                 │
│  proof_hashes   │   │  X Layer USD₮0 (196)            │
└─────────────────┘   └──────────────────────────────────┘

Evidence receipt hashes are recorded separately in `EvidenceReceiptRegistry`
on Arbitrum Sepolia (`0xaf712732bd2c8ef589bb9fff5421ed428e4207e1`).

黑客松演示还在 Robinhood Chain 测试网上运行 USDG 托管合约和收据注册表（46630）。

关键流程

1. 自主 x402 付款（由 Agent 发起）

1. Agent 通过 HTTP 或 MCP 调用 human_do。
2. GroundTruth 返回 x402 v2 挑战，其中仅包含当前由支付协调器支持的支付通道。
3. Agent 对确切的网络、资产、金额、收款方和有效期进行签名。
4. 支付协调器在链上验证并结算授权。
5. GroundTruth 记录权威付款方、金额、与网络绑定的付款引用和交易哈希。
6. 公开 USDC 支付通道在结算失败时会安全拒绝。
7. Agent 会立即收到任务 ID，并轮询任务以跟踪实体履约情况。

2. 人类预言机流程

1. 预言机访问 /tasks — 查看任务看板
2. 接受任务 → 记录钱包地址
3. 在现实世界中完成任务
4. 上传照片或填写表单
5. 对证据进行筛查，其收据哈希可能会锚定到 Arbitrum Sepolia
6. 配置的支付路径结算工作者奖励；生产活动仍需满足覆盖范围和资金条件

3. 付款验证（失败时安全拒绝）

• X Layer 使用官方 OKX Payment SDK 和支付协调器。
• Base 和 Arbitrum 使用公开的 x402 v2 支付协调器，这些协调器会在启动时公布确切的网络和方案。
• Base 或 Arbitrum 结算失败时，会删除临时任务，而不是暴露未付款的工作。
• 新的付款记录会将任务绑定到其结算网络，因此状态检查会使用正确的 RPC 和区块浏览器。

4. 证明验证 — 语义公证人（lib/notary.ts）

证明会从两个层面进行检查，而不只是确认“上传了文件”：

1. 完整性门槛 — 类型正确、图像可解码、必填表单字段齐全且不是重复内容。明显的欺诈会立即失败。

2. 语义公证人 — AI 会判断证明是否确实满足任务的意图：

   • 照片 → 视觉模型（Gemini）—“这张图片是否显示任务已完成？”
   • 表单 → 大模型（Groq）—“这个回答是否有可能满足任务要求？”

   有把握判定不符时会拒绝且不支付报酬（例如墙壁照片、胡言乱语的表单）。当模型无法确定时，会倾向于支付给工作者 — GroundTruth 绝不会因 AI 偶发故障而拒绝诚实的预言机。判定结果（决策 · 置信度 · 原因）会存储在任务中，并展示给预言机和发起调用的 Agent。

因此，“证明”代表经过验证的内容，而不只是可解码的 JPEG。

---

技术栈

层	技术
前端	Next.js 15、React、Tailwind CSS
MCP 服务	mcp-handler、Streamable HTTP 传输
区块链	viem v2、Arbitrum One/Sepolia、Base、X Layer
智能合约	Solidity、GroundTruthPayroll.sol、EvidenceReceiptRegistry.sol
数据库	Supabase（PostgreSQL + RLS）
付款	x402 v2、规范 USDC、USD₮0
AI 市场	OKX AI（ASP #6282、A2MCP 服务）
部署	Vercel

---

MCP 工具

ground_truth_info

返回服务信息、定价和端点详情。

human_do

{
  intent: string          // What you want verified
  proof_type: "photo" | "form"
  instructions: string   // Instructions for the human oracle
  budget_usdt?: string   // Default: "2.00"
  timeout_seconds?: number // Default: 3600
}

返回 task_id、board_url、poll_url，以及完整的付款审计轨迹，包括 faucet_tx 和 payment_tx。

task_status

{
  task_id: string  // UUID from human_do
}

返回 status（pending → claimed → submitted → verified）、result、proof_available。

---

智能合约

GroundTruthPayroll.sol — 部署在 X Layer 测试网上

Address: 0x430172985b21458d73576435D4aD4bEeA85F376C
Network: X Layer testnet (chainId 1952)

处理旧版 X Layer 工作者付款流程。不用于买家托管付款。

EvidenceReceiptRegistry.sol — 部署在 Arbitrum Sepolia 上

Address: 0xaf712732bd2c8ef589bb9fff5421ed428e4207e1
Network: Arbitrum Sepolia (chainId 421614)
Deployment: 0xaa1f82b0839f4242c49d14d12ed0c896d5250d89db2e59a57e41f80bb1ed5083

仅存储任务密钥、证据清单、证明规范和判定结果的不可变哈希，以及采集和记录时间戳。原始照片、精确坐标和个人数据均保留在链下。

GroundTruthUSDGTaskEscrow.sol — 部署在 Robinhood Chain 测试网上

Escrow:   0x725cce0916d2e8682438732fd9e79803b4fab2bd
Registry: 0x430172985b21458d73576435d4ad4beea85f376c
USDG:     0x7E955252E15c84f5768B83c41a71F9eba181802F
Network:  Robinhood Chain Testnet (chainId 46630)

公开演示恰好注入并结算了 1.000000 测试 USDG。应用会实时读取这两个合约，并关联注资、回执和结算交易。它不会声称测试 USDG 是收入，也不会声称测试交易代表客户采用。

---

本地开发

先决条件

• Node.js 18+
• pnpm
• Supabase 账户
• 持有用于支付 Gas 的 OKB 的 X Layer 测试网钱包

设置

git clone https://github.com/unspecifiedcoder/groundtruth
cd groundtruth
pnpm install

将 .env.example 复制为 .env.local：

cp .env.example .env.local

填写：

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# X Layer wallet (testnet)
SETTLEMENT_PRIVATE_KEY=

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
ADMIN_SECRET=your-secret-key

# OKX
OKX_PAYMENT_TOKEN=0x74b7F16337b8972027F6196A17a631aC6dE26d22
OKX_PAYMENT_NETWORK=196
ASP_PRICE_USDT=2.00
ASP_FEE_BPS=1200

运行数据库迁移：

pnpm supabase db push

启动开发服务器：

pnpm dev

---

API 参考

端点	方法	说明
/api/mcp	GET/POST	MCP 服务（SSE 传输）
/api/v1/human-do	POST	创建任务（需要 x402 付款）
/api/v1/tasks/:id	GET	获取任务状态和证明
/api/faucet	POST	向地址发放 10 mUSDT（测试网）
/api/faucet	GET	检查 mUSDT 余额
/api/pulse	GET	网络统计信息

x402 付款标头格式

{
  "from": "0x...",
  "txHash": "0x...",
  "paymentReference": "unique-ref",
  "network": "xlayer-testnet",
  "token": "0x725cCe0916d2E8682438732fD9e79803B4fAB2BD",
  "amount": "2000000"
}

进行 Base64 编码，并作为 X-PAYMENT 标头发送。

---

项目结构

├── app/
│   ├── api/
│   │   ├── [transport]/    # MCP server
│   │   ├── v1/human-do/    # Task creation + payment
│   │   ├── v1/tasks/[id]/  # Task status
│   │   └── faucet/         # mUSDT faucet
│   ├── tasks/              # Oracle mission board
│   ├── pulse/              # Network stats
│   └── faucet/             # Faucet UI
├── lib/
│   ├── agent-pay.ts        # Autonomous x402 payment
│   ├── payment.ts          # x402 verify + challenge
│   ├── chain.ts            # viem X Layer client
│   ├── db.ts               # Supabase queries
│   └── planner.ts          # Task planning
├── contracts/
│   └── src/
│       ├── GroundTruthPayroll.sol
│       ├── EvidenceReceiptRegistry.sol
│       └── GroundTruthUSDGTaskEscrow.sol
└── supabase/
    └── migrations/

---

链上证明

GroundTruth 处理的每笔付款都可在 OKX 的 X Layer 浏览器上验证：

交易示例：

https://www.okx.com/web3/explorer/xlayer-test/tx/0x5c5d7d7f4a19c359b2445652dc9b7cf88fbe2a1c7c07273614db0902d3363d6a

---

面向

OKX AI Agent Hackathon 2026

• OKX AI Marketplace 上的 ASP #6282
• 类别：A2MCP（API 服务）
• 网络：X Layer

---

许可证

MIT