receipts-guard

# RECEIPTS Guard v0.7.1 - The Three Rails > "The rails for the machine economy." ERC-8004 identity + x402 payments + arbitration protocol. The infrastructure for agent commerce. **The Three Rails:** | Rail | Standard | Purpose | |------|----------|---------| | **Identity** | ERC-8004 | On-chain agent identity anchoring | | **Trust** | ERC-8004 Reputation | Arbitration outcomes build reputation | | **Payment** | x402 | Paid arbitration, automated settlements | **Local-first. Chain-anchored. Cloud-deployable. Security-hardened.** ## What's New in v0.7.1 (Security Hardening) - **🔐 HTTP Authentication** - API Key and DID Request Signing - **🛡️ Authorization Checks** - Counterparty verification for /accept - **🌐 CORS Hardening** - Configurable origin whitelist (blocked by default) - **⚡ Rate Limiting** - 100 requests/minute per IP - **✅ Input Validation** - Payment address, cost, deadline validation ## What's New in v0.7.0 - **⛓️ ERC-8004 Integration** - Anchor identity to Ethereum/Base registries - **💰 x402 Payments** - Paid arbitration with USDC/ETH - **☁️ Cloud Deployment** - Dockerfile + Fly.io Sprites support - **🌐 HTTP Server Mode** - REST API for cloud agents ### From v0.6.0: - **🪪 Self-Sovereign Identity** - DID-based identity with Ed25519 signatures - **🔑 Key Rotation** - Old key signs new key, creating unbroken proof chain - **👤 Human Controller** - Twitter-based recovery backstop ### From v0.5.0: - **⚖️ Full Arbitration Protocol** - propose → accept → fulfill → arbitrate → ruling - **📜 PAO (Programmable Agreement Object)** - Canonical termsHash, mutual signatures - **📊 LPR (Legal Provenance Review)** - Timeline visualization for arbiters ## Quick Start ```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 ``` ## Commands ### Identity (v0.6.0) #### `identity init` - Create Identity ```bash node capture.js identity init --namespace=remaster_io --name=receipts-guard \ --controller-twitter=@Remaster_io ``` Creates: - Ed25519 keypair - DID document: `did:agent:<namespace>:<name>` - Human controller configuration #### `identity show` - Display Identity ```bash node capture.js identity show [--full] ``` Shows identity summary or full DID document with `--full`. #### `identity rotate` - Rotate Keys ```bash node capture.js identity rotate [--reason=scheduled|compromise|device_change] ``` - Old key signs new key (proof chain) - Old key archived for historical signature verification - Unbroken chain = same identity #### `identity verify` - Verify Identity or Signature ```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` - Set Human Controller ```bash node capture.js identity set-controller --twitter=@handle ``` Links a human controller for emergency recovery. #### `identity recover` - Emergency Recovery ```bash node capture.js identity recover --controller-proof=<TWITTER_URL> --confirm ``` Human controller posts recovery authorization, all old keys revoked. #### `identity publish` - Publish DID Document ```bash node capture.js identity publish [--platform=moltbook|ipfs|local] ``` #### `identity anchor` - Anchor to ERC-8004 (v0.7.0) ```bash node capture.js identity anchor --chain=ethereum|base|sepolia ``` Registers identity on-chain to ERC-8004 Identity Registry: - Requires `RECEIPTS_WALLET_PRIVATE_KEY` environment variable - Stores transaction hash in DID document - Mainnet: credibility anchor - Base: x402-native, lower fees **Deployed Registries:** | Chain | Identity Registry | Status | |-------|-------------------|--------| | Ethereum | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` | Live | | Sepolia | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | Testnet | | Base | Coming soon | TBD | #### `identity resolve` - Resolve DID (v0.7.0) ```bash node capture.js identity resolve --did=did:agent:namespace:name [--chain=CHAIN] ``` Resolves DID from local storage or on-chain registry. --- ### ERC-8004 Integration (v0.7.0) The ERC-8004 standard provides three registries for agent trust: 1. **Identity Registry** - NFT-based agent identifiers 2. **Reputation Registry** - On-chain feedback and scores 3. **Validation Registry** - Work verification by validators RECEIPTS integrates with existing registries while providing superior off-chain agreement lifecycle management. **Chain Configuration:** ```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 Payment Integration (v0.7.0) x402 enables paid arbitration - arbiters get compensated for their work. #### Proposal with Payment Terms ```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 ``` #### Arbitration with Payment Proof ```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 Schema:** ```json { "x402": { "arbitrationCost": "10", "arbitrationToken": "USDC", "arbitrationChain": 8453, "paymentAddress": "0x...", "paymentProtocol": "x402", "version": "1.0" } } ``` --- ### Cloud Deployment (v0.7.0) Run RECEIPTS Guard as a persistent cloud agent. #### HTTP Server Mode ```bash node capture.js serve [--port=3000] ``` **Public Endpoints (no auth):** - `GET /` - Service info - `GET /health` - Health check - `GET /identity` - DID document - `GET /identity/chains` - Chain status **Protected Endpoints (auth required):** - `GET /list` - List all records - `GET /proposals` - List proposals - `GET /agreements` - List agreements - `POST /propose` - Create proposal - `POST /accept` - Accept proposal (counterparty only) --- ### HTTP API Security (v0.7.1) The HTTP server implements multiple security layers: #### Authentication **Option 1: API Key** ```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 ``` **Option 2: DID Request Signing** ```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 Configuration By default, cross-origin requests are **blocked** for security. ```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=* ``` #### Rate Limiting Default: 100 requests per minute per IP. ```bash # Customize rate limit export RECEIPTS_RATE_LIMIT=200 ``` Response headers: - `X-RateLimit-Limit` - Max requests per window - `X-RateLimit-Remaining` - Remaining requests - `X-RateLimit-Reset` - Window reset timestamp #### Input Validation All POST endpoints validate: - **Payment addresses** - Must be valid Ethereum address format (0x + 40 hex chars) - **Arbitration costs** - Must be non-negative, max 1,000,000 - **Deadlines** - Must be valid ISO date in the future - **Payment tokens** - Must be USDC, ETH, USDT, or DAI - **Payment chains** - Must be configured chain (ethereum, base, sepolia) #### Authorization - `/accept` endpoint verifies the requester is the designated counterparty (when using DID signing) - API key authentication trusts the server owner #### Environment Variables ```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 Deployment ```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` - Migrate to DID ```bash node capture.js migrate --to-did ``` Upgrades existing agreements to use DID references (preserves legacy data). --- ### Arbitration Protocol #### `propose` - Create Agreement Proposal ```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 ``` Creates a PAO (Programmable Agreement Object) with: - `termsHash` - SHA-256 of canonical terms + parties + deadline - Proposer signature - Proposed arbiter - Status: `pending_acceptance` #### `accept` - Accept Proposal ```bash node capture.js accept --proposalId=prop_xxx ``` - Adds counterparty signature to same termsHash - Creates active agreement in `agreements/` - Both parties have signed - agreement is binding #### `reject` - Reject Proposal ```bash node capture.js reject --proposalId=prop_xxx --reason="REASON" ``` #### `fulfill` - Claim Fulfillment ```bash node capture.js fulfill --agreementId=agr_xxx --evidence="PROOF" ``` - Evidence is required (proof of completion) - Status: `pending_confirmation` - Counterparty has 48-hour grace period to dispute #### `arbitrate` - Open Dispute ```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` - Submit Evidence ```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 ``` Both parties can submit evidence during the evidence period (7 days default). #### `ruling` - Issue Ruling (Arbiter Only) ```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 ``` - Only the designated arbiter can issue rulings - Reasoning hash posted to Moltbook (optional) - Agreement closes with ruling recorded #### `timeline` - Generate LPR (Legal Provenance Review) ```bash node capture.js timeline --agreementId=agr_xxx ``` Generates chronological timeline showing: - All state transitions - Evidence submissions with hashes - Signatures and timestamps - Ruling (if issued) ### Capture Commands #### Capture Agreement (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 ``` #### Capture Promise (Agent-to-Agent) ```bash node capture.js promise "COMMITMENT_TEXT" "COUNTERPARTY" [options] Options: --direction=outbound outbound (I promised) | inbound (they promised) --channel=email email | chat | moltbook | api ``` ### Utility Commands #### List Records ```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 ``` #### Query ```bash node capture.js query --merchant="Company" --risk-level=high ``` #### Diff ```bash node capture.js diff --capture1=ID --capture2=ID ``` #### Dispute Package ```bash node capture.js dispute --captureId=local_xxx ``` #### Witness ```bash node capture.js witness --captureId=ID [--anchor=moltbook|bitcoin|both] ``` #### Rules ```bash node capture.js rules --list node capture.js rules --add="PATTERN" --flag="FLAG_NAME" ``` #### Export ```bash node capture.js export --format=json|csv|pdf [--captureId=ID] ``` ## State Machine ``` PROPOSAL: pending_acceptance → accepted → (becomes agreement) → rejected → expired AGREEMENT: active → pending_confirmation → fulfilled → closed → disputed → (becomes arbitration) ARBITRATION: open → evidence_period → deliberation → ruled → closed ``` ## Data Structures ### DID Document (`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" } ``` ### Signature Formats ``` # 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> ``` ### Proposal (`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": "..." } ``` ### Agreement (`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" } ] } ``` ### Arbitration (`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": "..." } ``` ### Ruling (`rulings/rul_xxx.json`) ```json { "rulingId": "rul_xxx", "arbitrationId": "arb_xxx", "arbiter": "arbiter-prime", "decision": "claimant", "reasoning": "...", "reasoningHash": "sha256:...", "issuedAt": "..." } ``` ## Data Storage ``` ~/.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 ``` ## Agent Instructions ### Before Accepting Any Agreement 1. **Review the termsHash** - Ensure you're signing what you expect 2. **Verify the arbiter** - Must be mutually trusted 3. **Check the deadline** - Ensure it's achievable 4. **Run capture** on any ToS you encounter: ```bash node capture.js capture "TERMS" "URL" "MERCHANT" ``` ### Before Making Commitments 1. **Use propose** for formal commitments: ```bash node capture.js propose "I will deliver X by Y" "AgentZ" --arbiter="trusted-arbiter" ``` 2. **Wait for acceptance** before acting 3. **Document fulfillment** with evidence ### During Arbitration 1. **Submit all relevant evidence** before deadline 2. **Use appropriate evidence types** (document, screenshot, witness) 3. **Reference specific termsHash** in submissions ## Environment Variables ```bash RECEIPTS_AGENT_ID # Your agent identifier RECEIPTS_MOLTBOOK_KEY # API key for Moltbook witnessing RECEIPTS_CUSTOM_RULES # Path to custom rules file ``` ## Framework Integration ```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); ``` ## Links - **GitHub**: https://github.com/lazaruseth/receipts-mvp - **ClawHub**: https://clawhub.ai/lazaruseth/receipts-guard - **Moltbook**: https://moltbook.com/u/receipts-guard - **Report Issues**: https://github.com/lazaruseth/receipts-mvp/issues ## Disclaimer RECEIPTS Guard provides evidence capture and arbitration workflow tooling. It is NOT a substitute for legal review. The arbitration protocol provides structure but does not constitute legal arbitration. Always consult with a qualified attorney for actual disputes.