Receipts Guard

# RECEIPTS Guard v0.7.1 - The Three Rails

> “机器经济的轨道。”

ERC-8004 身份 + x402 支付 + 仲裁协议。用于智能体商业的基础设施。

**三大支柱：** | 支柱 | 标准 | 目的 | |------|----------|---------| | **身份** | ERC-8004 | 链上智能体身份锚定 | | **信任** | ERC-8004 声誉 | 仲裁结果构建声誉 | | **支付** | x402 | 有偿仲裁，自动结算 |

**本地优先。链上锚定。云端部署。安全加固。**

## v0.7.1 新增内容（安全加固）

- **🔐 HTTP 身份验证** - API 密钥和 DID 请求签名 - **🛡️ 授权检查** - 针对对 /accept 的对手方验证 - **🌐 CORS 加固** - 可配置的源白名单（默认阻止） - **⚡ 速率限制** - 每个 IP 每分钟 100 次请求 - **✅ 输入验证** - 支付地址、费用、截止日期验证

## v0.7.0 新增内容

- **⛓️ ERC-8004 集成** - 将身份锚定到以太坊/Base 注册表 - **💰 x402 支付** - 使用 USDC/ETH 进行有偿仲裁 - **☁️ 云端部署** - Dockerfile + Fly.io Sprites 支持 - **🌐 HTTP 服务器模式** - 面向云端智能体的 REST API

### 来自 v0.6.0： - **🪪 自主身份** - 基于 DID 的身份，采用 Ed25519 签名 - **🔑 密钥轮换** - 旧密钥签署新密钥，建立不间断的证明链 - **👤 人类控制者** - 基于 Twitter 的恢复后盾

### 来自 v0.5.0： - **⚖️ 完整仲裁协议** - 提议 → 接受 → 履行 → 仲裁 → 裁决 - **📜 PAO (可编程协议对象)** - 规范化的 termsHash，相互签名 - **📊 LPR (法律溯源审查)** - 仲裁员的时间线可视化

## 快速开始

```bash # === ARBITRATION FLOW ===

# 1. Create proposal node capture.js propose "I will deliver API docs by Friday" "AgentX" \ --arbiter="arbiter-prime" --deadline="2026-02-14"

# 2. Accept proposal (as counterparty) node capture.js accept --proposalId=prop_abc123

# 3. Fulfill agreement node capture.js fulfill --agreementId=agr_xyz789 \ --evidence="Docs delivered at https://docs.example.com"

# --- OR if there's a dispute ---

# 4. Open arbitration node capture.js arbitrate --agreementId=agr_xyz789 \ --reason="non_delivery" --evidence="No docs received by deadline"

# 5. Submit evidence (both parties) node capture.js submit --arbitrationId=arb_def456 \ --evidence="Screenshot of empty inbox" --type=screenshot

# 6. Issue ruling (as arbiter) node capture.js ruling --arbitrationId=arb_def456 \ --decision=claimant --reasoning="Evidence shows non-delivery past deadline"

# 7. View timeline node capture.js timeline --agreementId=agr_xyz789 ```

## 命令

### 身份 (v0.6.0)

#### `identity init` - 创建身份 ```bash node capture.js identity init --namespace=remaster_io --name=receipts-guard \ --controller-twitter=@Remaster_io ```

创建： - Ed25519 密钥对 - DID 文档：`did:agent:<namespace>:<name>` - 人类控制者配置

#### `identity show` - 显示身份 ```bash node capture.js identity show [--full] ```

显示身份摘要或使用 `--full` 显示完整 DID 文档。

#### `identity rotate` - 轮换密钥 ```bash node capture.js identity rotate [--reason=scheduled|compromise|device_change] ```

- 旧密钥签署新密钥（证明链） - 旧密钥存档用于历史签名验证 - 不间断的链 = 同一身份

#### `identity verify` - 验证身份或签名 ```bash # Verify DID key chain node capture.js identity verify --did=did:agent:acme:trade-bot

# Verify signature node capture.js identity verify \ --signature="ed25519:xxx:timestamp" \ --termsHash="sha256:abc123..." ```

#### `identity set-controller` - 设置人类控制者 ```bash node capture.js identity set-controller --twitter=@handle ```

关联人类控制者以进行紧急恢复。

#### `identity recover` - 紧急恢复 ```bash node capture.js identity recover --controller-proof=<TWITTER_URL> --confirm ```

人类控制者发布恢复授权，所有旧密钥被撤销。

#### `identity publish` - 发布 DID 文档 ```bash node capture.js identity publish [--platform=moltbook|ipfs|local] ```

#### `identity anchor` - 锚定到 ERC-8004 (v0.7.0) ```bash node capture.js identity anchor --chain=ethereum|base|sepolia ```

在链上向 ERC-8004 身份注册表注册身份： - 需要 `RECEIPTS_WALLET_PRIVATE_KEY` 环境变量 - 将交易哈希存储在 DID 文档中 - 主网：可信度锚定 - Base：x402 原生，费用更低

**已部署的注册表：** | 链 | 身份注册表 | 状态 | |-------|-------------------|--------| | Ethereum | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` | 线上 | | Sepolia | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | 测试网 | | Base | 即将推出 | 待定 |

#### `identity resolve` - 解析 DID (v0.7.0) ```bash node capture.js identity resolve --did=did:agent:namespace:name [--chain=CHAIN] ```

从本地存储或链上注册表解析 DID。

---

### ERC-8004 集成 (v0.7.0)

ERC-8004 标准为智能体信任提供了三个注册表：

1. **身份注册表** - 基于 NFT 的智能体标识符 2. **声誉注册表** - 链上反馈和评分 3. **验证注册表** - 验证员的工作验证

RECEIPTS 与现有注册表集成，同时提供卓越的链下协议生命周期管理。

**链配置：** ```bash # Environment variables export ETHEREUM_RPC=https://eth.llamarpc.com export BASE_RPC=https://mainnet.base.org export RECEIPTS_WALLET_PRIVATE_KEY=0x... # Never commit this! ```

---

### x402 支付集成 (v0.7.0)

x402 支持有偿仲裁 - 仲裁员的工作获得报酬。

#### 带有支付条款的提案 ```bash node capture.js propose "Service agreement" "counterparty" \ --arbiter="arbiter-prime" \ --arbitration-cost="10" \ --payment-token="USDC" \ --payment-chain="base" \ --payment-address="0x..." # Arbiter's address ```

#### 带有支付证明的仲裁 ```bash # Without payment proof (fails if x402 required) node capture.js arbitrate --agreementId=agr_xxx --reason="non_delivery" # Error: Payment required: 10 USDC

# With payment proof node capture.js arbitrate --agreementId=agr_xxx --reason="non_delivery" \ --evidence="..." --payment-proof="0x123..." ```

**x402 架构：** ```json { "x402": { "arbitrationCost": "10", "arbitrationToken": "USDC", "arbitrationChain": 8453, "paymentAddress": "0x...", "paymentProtocol": "x402", "version": "1.0" } } ```

---

### 云端部署 (v0.7.0)

将 RECEIPTS Guard 作为持久化云端智能体运行。

#### HTTP 服务器模式 ```bash node capture.js serve [--port=3000] ```

**公开端点（无需认证）：** - `GET /` - 服务信息 - `GET /health` - 健康检查 - `GET /identity` - DID 文档 - `GET /identity/chains` - 链状态

**受保护端点（需要认证）：** - `GET /list` - 列出所有记录 - `GET /proposals` - 列出提案 - `GET /agreements` - 列出协议 - `POST /propose` - 创建提案 - `POST /accept` - 接受提案（仅限对手方）

---

### HTTP API 安全 (v0.7.1)

HTTP 服务器实现了多层安全机制：

#### 身份验证

**选项 1：API 密钥** ```bash # Generate a secure API key export RECEIPTS_API_KEY=$(openssl rand -hex 32)

# Use in requests curl -H "X-API-Key: $RECEIPTS_API_KEY" https://your-agent.fly.dev/list ```

**选项 2：DID 请求签名** ```bash # Sign each request with your Ed25519 key # Headers required: # - X-DID: your DID (e.g., did:agent:namespace:name) # - X-DID-Timestamp: Unix timestamp in milliseconds # - X-DID-Signature: ed25519:BASE64URL_SIGNATURE:TIMESTAMP

# Signed message format: METHOD:PATH:TIMESTAMP # Example: POST:/propose:1707494400000 ```

#### CORS 配置

出于安全考虑，默认情况下跨源请求会被**阻止**。

```bash # Allow specific origins export RECEIPTS_ALLOWED_ORIGINS=https://app.example.com,https://dashboard.example.com

# Allow all origins (not recommended for production) export RECEIPTS_ALLOWED_ORIGINS=* ```

#### 速率限制

默认值：每个 IP 每分钟 100 次请求。

```bash # Customize rate limit export RECEIPTS_RATE_LIMIT=200 ```

响应头： - `X-RateLimit-Limit` - 每个时间窗口的最大请求数 - `X-RateLimit-Remaining` - 剩余请求数 - `X-RateLimit-Reset` - 时间窗口重置时间戳

#### 输入验证

所有 POST 端点验证： - **支付地址** - 必须是有效的以太坊地址格式（0x + 40 个十六进制字符） - **仲裁费用** - 必须是非负数，最大 1,000,000 - **截止日期** - 必须是未来的有效 ISO 日期 - **支付代币** - 必须是 USDC、ETH、USDT 或 DAI - **支付链** - 必须是已配置的链（ethereum、base、sepolia）

#### 授权

- `/accept` 端点验证请求者是指定的对手方（使用 DID 签名时） - API 密钥身份验证信任服务器所有者

#### 环境变量

```bash # Security RECEIPTS_API_KEY= # API key for authentication (generate with: openssl rand -hex 32) RECEIPTS_ALLOWED_ORIGINS= # Comma-separated CORS origins (default: none/blocked) RECEIPTS_RATE_LIMIT= # Requests per minute (default: 100)

# Existing RECEIPTS_WALLET_PRIVATE_KEY= # For on-chain transactions RECEIPTS_AGENT_ID= # Agent identifier ETHEREUM_RPC= # Ethereum RPC endpoint BASE_RPC= # Base RPC endpoint ```

---

#### Fly.io Sprites 部署 ```bash # Deploy fly launch fly deploy

# Configure secrets fly secrets set RECEIPTS_WALLET_PRIVATE_KEY=... fly secrets set ETHEREUM_RPC=...

# Create persistent volume fly volumes create receipts_data --size 1 ```

#### Docker ```bash docker build -t receipts-guard . docker run -p 3000:3000 -v receipts-data:/data receipts-guard ```

---

#### `migrate` - 迁移到 DID ```bash node capture.js migrate --to-did ```

将现有协议升级为使用 DID 引用（保留旧版数据）。

---

### 仲裁协议

#### `propose` - 创建协议提案 ```bash node capture.js propose "TERMS" "COUNTERPARTY" --arbiter="ARBITER" [options]

Options: --arbiter=AGENT Required: mutually agreed arbiter --deadline=ISO_DATE Fulfillment deadline --value=AMOUNT Agreement value (for reference) --channel=CHANNEL Communication channel ```

创建一个 PAO（可编程协议对象），包含： - `termsHash` - 规范化条款 + 当事方 + 截止日期的 SHA-256 哈希 - 提案方签名 - 提议的仲裁员 - 状态：`pending_acceptance`

#### `accept` - 接受提案 ```bash node capture.js accept --proposalId=prop_xxx ```

- 将对手方签名添加到同一个 termsHash - 在 `agreements/` 中创建活跃协议 - 双方均已签署 - 协议具有约束力

#### `reject` - 拒绝提案 ```bash node capture.js reject --proposalId=prop_xxx --reason="REASON" ```

#### `fulfill` - 声明履行 ```bash node capture.js fulfill --agreementId=agr_xxx --evidence="PROOF" ```

- 需要证据（完成证明） - 状态：`pending_confirmation` - 对手方有 48 小时的宽限期提出异议

#### `arbitrate` - 开启争议 ```bash node capture.js arbitrate --agreementId=agr_xxx --reason="BREACH_TYPE" --evidence="PROOF"

Valid reasons: non_delivery - Counterparty didn't deliver partial_delivery - Delivery was incomplete quality - Delivery didn't meet specs deadline_breach - Missed deadline repudiation - Counterparty denies agreement other - Other breach ```

#### `submit` - 提交证据 ```bash node capture.js submit --arbitrationId=arb_xxx --evidence="PROOF" [--type=TYPE]

Types: document - Text evidence (default) screenshot - Visual proof witness - Third-party witness statement ```

双方可以在证据提交期内（默认 7 天）提交证据。

#### `ruling` - 发布裁决（仅限仲裁员） ```bash node capture.js ruling --arbitrationId=arb_xxx --decision=DECISION --reasoning="EXPLANATION"

Decisions: claimant - Rule in favor of claimant respondent - Rule in favor of respondent split - Split responsibility ```

- 只有指定的仲裁员可以发布裁决 - 推理哈希发布到 Moltbook（可选） - 协议关闭并记录裁决

#### `timeline` - 生成 LPR (法律溯源审查) ```bash node capture.js timeline --agreementId=agr_xxx ```

生成按时间顺序的时间线，显示： - 所有状态转换 - 带有哈希的证据提交 - 签名和时间戳 - 裁决（如果已发布）

### 捕获命令

#### 捕获协议 (ToS) ```bash node capture.js capture "TERMS_TEXT" "SOURCE_URL" "MERCHANT_NAME" [options]

Options: --consent-type=TYPE explicit | implicit | continued_use --element=SELECTOR DOM element that triggered consent --screenshot=BASE64 Screenshot at time of consent ```

#### 捕获承诺 (智能体对智能体) ```bash node capture.js promise "COMMITMENT_TEXT" "COUNTERPARTY" [options]

Options: --direction=outbound outbound (I promised) | inbound (they promised) --channel=email email | chat | moltbook | api ```

### 实用命令

#### 列出记录 ```bash node capture.js list [--type=TYPE]

Types: all - Everything (default) captures - ToS captures and promises proposals - Pending proposals agreements - Active/closed agreements arbitrations - Open/closed arbitrations rulings - Issued rulings ```

#### 查询 ```bash node capture.js query --merchant="Company" --risk-level=high ```

#### 对比 ```bash node capture.js diff --capture1=ID --capture2=ID ```

#### 争议包 ```bash node capture.js dispute --captureId=local_xxx ```

#### 见证 ```bash node capture.js witness --captureId=ID [--anchor=moltbook|bitcoin|both] ```

#### 规则 ```bash node capture.js rules --list node capture.js rules --add="PATTERN" --flag="FLAG_NAME" ```

#### 导出 ```bash node capture.js export --format=json|csv|pdf [--captureId=ID] ```

## 状态机

``` PROPOSAL: pending_acceptance → accepted → (becomes agreement) → rejected → expired

AGREEMENT: active → pending_confirmation → fulfilled → closed → disputed → (becomes arbitration)

ARBITRATION: open → evidence_period → deliberation → ruled → closed ```

## 数据结构

### DID 文档 (`identity/did.json`) - v0.6.0 ```json { "@context": ["https://www.w3.org/ns/did/v1"], "id": "did:agent:remaster_io:receipts-guard",

"verificationMethod": [{ "id": "did:agent:remaster_io:receipts-guard#key-xxx", "type": "Ed25519VerificationKey2020", "controller": "did:agent:remaster_io:receipts-guard", "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..." }],

"authentication": ["did:agent:remaster_io:receipts-guard#key-xxx"],

"keyHistory": [{ "keyId": "#key-xxx", "activatedAt": "2026-02-09T00:00:00Z", "rotatedAt": null, "rotationProof": null, "publicKeyMultibase": "z6Mkf5rGMoatrSj1f..." }],

"controller": { "type": "human", "platform": "twitter", "handle": "@Remaster_io" },

"created": "2026-02-09T00:00:00Z", "updated": "2026-02-09T00:00:00Z" } ```

### 签名格式 ``` # Ed25519 (v0.6.0) - cryptographically secure ed25519:<base64url-signature>:<timestamp>

# Legacy HMAC (v0.5.0 and earlier) - still supported for backward compatibility sig:<hex-signature>:<timestamp> ```

### 提案 (`proposals/prop_xxx.json`) ```json { "proposalId": "prop_xxx", "termsHash": "sha256:...", "terms": { "text": "...", "canonical": "..." }, "proposer": "agent-a", "counterparty": "agent-b", "proposedArbiter": "arbiter-prime", "deadline": "2026-02-15T00:00:00Z", "value": "100 USD", "proposerSignature": "ed25519:...", "status": "pending_acceptance", "createdAt": "...", "expiresAt": "..." } ```

### 协议 (`agreements/agr_xxx.json`) ```json { "agreementId": "agr_xxx", "termsHash": "sha256:...", "parties": ["agent-a", "agent-b"], "arbiter": "arbiter-prime", "signatures": { "agent-a": "ed25519:...", "agent-b": "ed25519:..." }, "status": "active", "timeline": [ { "event": "proposed", "timestamp": "...", "actor": "agent-a" }, { "event": "accepted", "timestamp": "...", "actor": "agent-b" } ] } ```

### 仲裁 (`arbitrations/arb_xxx.json`) ```json { "arbitrationId": "arb_xxx", "agreementId": "agr_xxx", "claimant": "agent-a", "respondent": "agent-b", "arbiter": "arbiter-prime", "reason": "non_delivery", "status": "evidence_period", "evidence": { "claimant": [...], "respondent": [...] }, "evidenceDeadline": "..." } ```

### 裁决 (`rulings/rul_xxx.json`) ```json { "rulingId": "rul_xxx", "arbitrationId": "arb_xxx", "arbiter": "arbiter-prime", "decision": "claimant", "reasoning": "...", "reasoningHash": "sha256:...", "issuedAt": "..." } ```

## 数据存储

``` ~/.openclaw/receipts/ ├── identity/ # v0.6.0 Self-Sovereign Identity │ ├── did.json # DID document (public) │ ├── private/ │ │ ├── key-current.json # Current private key │ │ └── key-archive/ # Rotated keys (for verification) │ ├── key-history.json # Rotation chain with proofs │ ├── controller.json # Human controller config │ └── recovery/ # Recovery records ├── index.json # Fast lookup index ├── proposals/ │ └── prop_xxx.json # Proposal metadata ├── agreements/ │ ├── agr_xxx.json # Agreement metadata │ └── agr_xxx.txt # Terms text ├── arbitrations/ │ └── arb_xxx.json # Arbitration record ├── rulings/ │ └── rul_xxx.json # Ruling record ├── witnesses/ │ └── witness_xxx.json # Witness anchors ├── local_xxx.json # ToS captures ├── promise_xxx.json # Promise captures └── custom-rules.json # Custom rulesets ```

## 智能体说明

### 在接受任何协议之前

1. **审查 termsHash** - 确保您签署的内容符合预期 2. **验证仲裁员** - 必须是双方共同信任的 3. **检查截止日期** - 确保它是可实现的 4. **对遇到的任何 ToS 运行 capture**： ```bash node capture.js capture "TERMS" "URL" "MERCHANT" ```

### 在做出承诺之前

1. **使用 propose** 进行正式承诺： ```bash node capture.js propose "I will deliver X by Y" "AgentZ" --arbiter="trusted-arbiter" ``` 2. 在行动之前**等待接受** 3. 用证据**记录履行情况**

### 仲裁期间

1. 在截止日期前**提交所有相关证据** 2. **使用适当的证据类型**（文档、截图、见证人） 3. 在提交中**引用特定的 termsHash**

## 环境变量

```bash RECEIPTS_AGENT_ID # Your agent identifier RECEIPTS_MOLTBOOK_KEY # API key for Moltbook witnessing RECEIPTS_CUSTOM_RULES # Path to custom rules file ```

## 框架集成

```javascript const receipts = require('./capture.js');

// Generate terms hash for verification const hash = receipts.generateTermsHash( "I will deliver API docs", ["agent-a", "agent-b"], "2026-02-14" );

// Sign terms const signature = receipts.signTerms(hash, "my-agent-id");

// Verify signature const valid = receipts.verifySignature(hash, signature, "my-agent-id");

// Access directories console.log(receipts.PROPOSALS_DIR); console.log(receipts.AGREEMENTS_DIR); console.log(receipts.ARBITRATIONS_DIR); console.log(receipts.RULINGS_DIR); ```

## 链接

- **GitHub**: https://github.com/lazaruseth/receipts-mvp - **ClawHub**: https://clawhub.ai/lazaruseth/receipts-guard - **Moltbook**: https://moltbook.com/u/receipts-guard - **报告问题**: https://github.com/lazaruseth/receipts-mvp/issues

## 免责声明

RECEIPTS Guard 提供证据捕获和仲裁工作流工具。它**不能**替代法律审查。仲裁协议提供了结构，但不构成法律仲裁。对于实际争议，请务必咨询合格的律师。