SPEC.md

TrustKit MVP - Trust Score API

Agent 交易信任中间件 — 第一阶段 MVP

一句话

让任何人通过 API 查询任意 ERC-8004 agent 的信誉分，通过 x402 协议收费。

---

目标

构建一个 Trust Score API：

GET /v1/trust/{agentId}
→ {
    "score": 720,
    "grade": "A",  // F/D/C/B/A/S
    "transactions": 156,
    "completion_rate": 0.97,
    "dispute_rate": 0.02,
    "avg_response_time": "2.3s",
    "suggested_escrow": 0.20,  // 建议 escrow 比例
    "confidence": 0.85,  // 置信度（数据量决定）
    "last_updated": "2026-02-25T10:30:00Z"
  }

---

技术栈

• Runtime: Cloudflare Workers（利用 x402 edge 支持）或 Node.js
• Database: PostgreSQL（交易历史）+ Redis（缓存热门查询）
• Blockchain: Base (Ethereum L2) — 读取 ERC-8004 Registry
• Payment: x402 协议 — 每次查询收费 $0.001 USDC

---

核心组件

1. 数据层

数据来源：

• ERC-8004 Reputation Registry（链上）
• ERC-8004 Validation Registry（验证记录）
• 公开的 escrow 合约事件（Moltlaunch 等）

需要索引的数据：

• Agent 的历史交易记录
• 交易完成/取消/争议状态
• 验证通过/失败记录
• 交易金额和时间

2. 评分算法

基于 EigenTrust 的变体：

TrustScore = BaseScore * ReputationMultiplier * TimeDecay

BaseScore = f(completion_rate, dispute_rate, response_time)
ReputationMultiplier = Σ(peerTrust * peerWeight)  // 传递信任
TimeDecay = exp(-λ * daysSinceLastTx)  // 越久越衰减

防刷分机制：

• 最小交易金额门槛：$0.10
• 交易对手多样性：同一对手交易权重递减
• 时间衰减：90 天半衰期
• Sybil 检测：识别批量创建的关联 agent

冷启动：

• 新 agent 从 operator 的 Human Passport 分数继承部分信誉
• 或从 0 分开始，标记为「新手」

3. x402 支付集成

定价：

• 基础查询：$0.001/次
• 详细报告：$0.01/次（含历史趋势）
• 批量查询：$0.0008/次（10+ 查询）

实现：

• 使用 Coinbase x402 facilitator 或 Stripe x402
• 返回 HTTP 402 → 客户端付款 → 验证 → 返回数据

---

API 设计

端点

# 基础查询（$0.001）
GET /v1/trust/{agentId}

# 详细报告（$0.01）
GET /v1/trust/{agentId}/detailed

# 批量查询（$0.0008/个）
POST /v1/trust/batch
Body: { "agent_ids": ["0x...", "0x..."] }

# 健康检查（免费）
GET /health

x402 流程

1. Client: GET /v1/trust/0x123
2. Server: 402 Payment Required
   Headers:
     X-Payment-Address: 0x...
     X-Payment-Amount: 0.001
     X-Payment-Currency: USDC
     X-Payment-Network: base
3. Client: 付款，获得 receipt
4. Client: GET /v1/trust/0x123
   Headers:
     X-Payment-Receipt: <receipt>
5. Server: 200 OK + trust data

---

文件结构

trustkit-mvp/
├── SPEC.md              # 本文件
├── README.md            # 项目介绍
├── docs/                # 上下文文档
│   ├── trust-layer-analysis.md
│   ├── agent-payment-strategy.md
│   ├── x402-protocol-research.md
│   └── usdc-base-integration.md
├── src/
│   ├── index.ts         # 入口
│   ├── api/
│   │   ├── routes.ts    # API 路由
│   │   └── handlers.ts  # 请求处理
│   ├── trust/
│   │   ├── score.ts     # 评分计算
│   │   ├── eigentrust.ts # EigenTrust 算法
│   │   └── decay.ts     # 时间衰减
│   ├── data/
│   │   ├── indexer.ts   # 链上数据索引
│   │   ├── cache.ts     # 缓存层
│   │   └── models.ts    # 数据模型
│   ├── payment/
│   │   ├── x402.ts      # x402 协议处理
│   │   └── verify.ts    # 支付验证
│   └── utils/
│       └── config.ts    # 配置
├── contracts/           # 如果需要部署合约
├── tests/
│   ├── score.test.ts
│   └── api.test.ts
├── wrangler.toml        # Cloudflare Workers 配置
└── package.json

---

分工建议

Team 1: API + 后端框架

• 搭建 Cloudflare Workers / Node.js 项目
• 实现 API 路由和处理器
• 数据库 schema 设计

Team 2: 评分算法

• 实现 EigenTrust 变体
• 时间衰减函数
• 防刷分机制
• 冷启动逻辑

Team 3: x402 支付集成

• 研究 x402 协议实现
• 集成 Coinbase/Stripe facilitator
• 支付验证逻辑

Team 4: 链上数据索引

• ERC-8004 Registry 数据读取
• 事件监听和索引
• 缓存策略

---

成功标准

MVP 完成时应该能：

1. ✅ 启动服务，监听 API 请求
2. ✅ 对任意 agent ID 返回模拟评分（算法可用假数据验证）
3. ✅ x402 支付流程跑通（可用测试网）
4. ✅ 基础测试覆盖

---

参考资料

• docs/trust-layer-analysis.md — 完整机会分析
• docs/x402-protocol-research.md — x402 协议研究
• docs/usdc-base-integration.md — USDC/Base 集成
• ERC-8004: https://eips.ethereum.org/EIPS/eip-8004
• x402: https://www.x402.org/
• OpenRank: https://openrank.com/