GroundTruth Field Evidence

GroundTruth — 検証済みの現場証拠

現場確認を依頼すると、最新の写真証拠、構造化された観察結果、監査可能な検証レシートを受け取れます。

---

GroundTruth とは？

GroundTruth は、現場証拠を提供する API です。最初の商用ワークフローは小売店の検証です。既存のデータベースからは確実に回答できない、現在の棚在庫、価格、プロモーション、陳列基準への準拠状況を確認します。

運用チームまたは AI エージェントが資金を用意したタスクを作成し、現場作業員がそれを完了すると、GroundTruth は証拠の追跡記録とともに構造化された結果を返します。既存のプロトタイプは、MCP と A2A、写真およびフォームによる証明、AI 支援検証、鮮度チャレンジ、Arbitrum One と Base 上の USDC または X Layer 上の USD₮0 による x402 決済に対応しています。プライバシーを保護する証拠レシートのハッシュは、デプロイ済みの Arbitrum Sepolia レジストリに記録できます。

現在、製品は限定的なパイロット運用中です。フィールドキャンペーンの開始前に、対応地域と所要時間を確認します。プロジェクトは、あらゆる地域をカバーできるとは謳っていません。

Arbitrum Open House のビルドでは、GroundTruth は Robinhood Chain Testnet 上で、USDG のエスクローと証拠レシートのエンドツーエンドのフローも実証します。検証に資金を預け、非公開の証拠ダイジェストを記録し、判定後にのみ USDG を解放します。これはプロトコルのデモンストレーションであり、顧客収益ではありません。

パブリックベータへの準備状況

このアプリケーションには、クローラーとエージェント向けのディスカバリー（robots.txt、sitemap.xml、JSON-LD、llms.txt、OpenAPI、MCP、A2A、/.well-known/agent.json、/.well-known/agent-card.json）、非公開のキャンペーンセッション、公開タスクビューの情報削減、署名付き作業員クレーム、アップロード検証、永続的なレート制限、監査イベント、法律・安全性に関するページ、強化されたブラウザーヘッダー、準備状況を報告する /api/health が含まれています。

実際のパブリックトラフィックを有効にする前に、以下を実施してください。

1. 004_campaigns.sql と 005_production_hardening.sql を含め、supabase/migrations 内のすべての 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 チャレンジを返します。互換性のあるウォレットは、提示されたレールのうち1つを選択し、正確な金額と受取人を承認して、リクエストを再送信できます。対象範囲の確認と履行は非同期で行われます。

---

アーキテクチャ

┌─────────────────────────────────────────────────────────┐
│                     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 Testnet（46630）上で USDG エスクローとレシートレジストリも実行します。

主なフロー

1. 自律型 x402 決済（エージェント起点）

1. エージェントが HTTP または MCP 経由で human_do を呼び出します。
2. GroundTruth は、現在ファシリテーターがサポートしているレールのみを含む x402 v2 チャレンジを返します。
3. エージェントは、ネットワーク、資産、金額、受取人、有効期間を正確に指定して署名します。
4. ファシリテーターが承認を検証し、オンチェーンで決済します。
5. GroundTruth は、正式な支払者、金額、ネットワークに紐づく決済参照情報、トランザクションハッシュを記録します。
6. 公開 USDC レールでは、決済に失敗するとフェイルクローズします。
7. エージェントはタスク 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）

証明は「ファイルがアップロードされた」かどうかだけでなく、2つのレベルで確認されます。

1. 整合性ゲート — 正しい形式であること、画像をデコードできること、必須フォーム項目が入力されていること、重複ではないことを確認します。明白な不正は即座に却下されます。

2. セマンティックノータリー — AI が、証明がタスクの意図を実際に満たしているかを判定します。

   • 写真 → ビジョンモデル（Gemini）—「この画像はタスクが実行されている様子を示していますか？」
   • フォーム → LLM（Groq）—「この回答は、タスクを満たすものとして妥当ですか？」

   明確な不一致は、報酬なしで却下されます（壁の写真、意味不明なフォームなど）。モデルが確信を持てない場合は、作業者に報酬を支払う方向で判断します。GroundTruth は AI の一時的な不調を理由に、誠実なオラクルを決して拒否しません。判定（決定・信頼度・理由）はタスクに保存され、オラクルと呼び出し元のエージェントの両方に表示されます。

これにより「証明」は、デコード可能な 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、canonical 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)

公開デモでは、テスト用 USDG で正確に 1.000000 を入金し、決済しました。アプリは両方のコントラクトをリアルタイムで読み取り、入金、レシート、決済のトランザクションをリンクします。テスト用 USDG が収益であるとも、テストトランザクションが顧客の採用を示すとも主張しません。

---

ローカル開発

前提条件

• Node.js 18+
• pnpm
• Supabase アカウント
• ガス代用の 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