docs: add ERC-8183 integration guide for Arc Escrow

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to Arc Escrow
+
+Thank you for contributing to Arc Escrow! This guide covers everything you need to know.
+
+## Prerequisites
+
+- Node.js v22+
+- Docker Desktop (for local Supabase)
+- Circle Developer Console account
+- OpenAI API key
+
+## Development Setup
+
+1. Fork and clone the repository
+2. Install dependencies: npm install
+3. Copy environment variables: cp .env.example .env.local
+4. Generate agent wallet: npm run generate-wallet
+5. Start Supabase: npx supabase start
+6. Run migrations: npx supabase migration up
+7. Start dev server: npm run dev
+
+## Branch Naming
+
+- feat/your-feature-name
+- fix/your-bug-fix
+- docs/your-documentation
+- chore/your-chore
+
+## Commit Messages
+
+Follow Conventional Commits:
+- feat: add new feature
+- fix: fix a bug
+- docs: update documentation
+- chore: maintenance tasks
+
+## Pull Request Process
+
+1. Create a branch from master
+2. Make your changes
+3. Test thoroughly
+4. Submit PR with clear description
+5. Reference any related issues
+
+## Code Style
+
+- TypeScript strict mode
+- ESLint configuration in .eslintrc
+- Prettier for formatting
+
+## Testing
+
+- Test all escrow flows end-to-end
+- Verify Circle webhook handling
+- Test AI validation with sample deliverables
+
+## Environment Variables
+
+Never commit .env.local or any secrets.
+Use .env.example as a template.
+
+## Questions?
+
+Open an issue or discussion on GitHub.

docs/ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# Arc Escrow Architecture
+
+## System Overview
+
+Arc Escrow is a Next.js application that enables trustless freelance agreements using USDC on Arc Testnet.
+
+## Components
+
+### Frontend
+- Next.js 14 with App Router
+- Tailwind CSS + shadcn/ui components
+- Supabase Realtime for live updates
+
+### Backend
+- Next.js API routes
+- Supabase for database and auth
+- Circle Developer Controlled Wallets for USDC
+- OpenAI for AI-powered deliverable validation
+
+### Blockchain
+- Arc Testnet (Chain ID: 5042002)
+- Native USDC as gas token
+- EIP-712 Refund Protocol smart contract
+- Circle smart contract platform
+
+## Data Flow
+
+1. Client creates escrow agreement
+2. Client deposits USDC into escrow wallet
+3. Freelancer submits deliverable
+4. AI (OpenAI) validates deliverable against criteria
+5. If approved: USDC released to freelancer
+6. If rejected: USDC refunded to client
+
+## Circle Developer Controlled Wallets
+
+The app uses Circle Developer Controlled Wallets for:
+- Agent wallet: holds USDC escrow funds
+- Transaction signing via Circle API
+- Webhook notifications for payment events
+
+Key contracts:
+- USDC on Arc Testnet: 0x3600000000000000000000000000000000000000
+
+## Supabase Schema
+
+Tables:
+- agreements: escrow contract details
+- users: authenticated users
+- deliverables: submitted work items
+- transactions: payment history
+
+## OpenAI Validation
+
+The AI validation flow:
+1. Freelancer uploads deliverable
+2. App sends deliverable + criteria to OpenAI
+3. OpenAI returns pass/fail with reasoning
+4. Result triggers payment release or refund
+
+## Webhook Architecture
+
+Circle webhooks notify the app of:
+- Deposit confirmations
+- Payment completions
+- Transaction failures
+
+Webhook endpoint: /api/webhooks/circle
+Signature verification: HMAC-SHA256
+
+## Security Model
+
+- Webhook signature verification
+- Environment variables for all secrets
+- Supabase Row Level Security (RLS)
+- Testnet only — not production ready
+
+## ERC-8183 Extension
+
+For native Arc agentic commerce, see docs/erc8183-integration.md.
+ERC-8183 provides trustless escrow with autonomous agent hiring.
+AgenticCommerce: 0x0747EEf0706327138c69792bF28Cd525089e4583

docs/DEPLOYMENT.md

@@ -0,0 +1,83 @@
+# Deployment Guide
+
+## Prerequisites
+
+- Vercel account
+- Supabase account (cloud)
+- Circle Developer Console account
+- OpenAI API key
+
+## Vercel Deployment
+
+1. Push your fork to GitHub
+2. Import project in Vercel dashboard
+3. Add all environment variables (see below)
+4. Deploy
+
+## Environment Variables for Production
+
+VERCEL_URL=https://your-app.vercel.app
+NEXT_PUBLIC_VERCEL_URL=https://your-app.vercel.app
+NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+NEXT_PUBLIC_USDC_CONTRACT_ADDRESS=0x3600000000000000000000000000000000000000
+NEXT_PUBLIC_AGENT_WALLET_ID=auto-generated
+NEXT_PUBLIC_AGENT_WALLET_ADDRESS=auto-generated
+CIRCLE_API_KEY=TEST_API_KEY:your-id:your-secret
+CIRCLE_ENTITY_SECRET=your-entity-secret
+CIRCLE_BLOCKCHAIN=ARC-TESTNET
+OPENAI_API_KEY=your-openai-key
+
+## Supabase Production Setup
+
+1. Create project at https://supabase.com
+2. Get project URL and anon key from Settings > API
+3. Link project: npx supabase link --project-ref your-ref
+4. Push schema: npx supabase db push
+5. Enable Row Level Security on all tables
+
+## Circle Webhook Configuration
+
+1. Deploy your app first
+2. Go to Circle Console > Webhooks
+3. Add endpoint: https://your-app.vercel.app/api/webhooks/circle
+4. Copy webhook secret to environment variables
+
+## Agent Wallet Setup
+
+Run locally before deploying:
+npm run generate-wallet
+
+Copy the generated values to Vercel environment variables:
+- NEXT_PUBLIC_AGENT_WALLET_ID
+- NEXT_PUBLIC_AGENT_WALLET_ADDRESS
+- CIRCLE_BLOCKCHAIN
+
+## Arc Testnet Configuration
+
+Network: Arc Testnet
+Chain ID: 5042002
+RPC URL: https://rpc.testnet.arc.network
+USDC Contract: 0x3600000000000000000000000000000000000000
+Explorer: https://testnet.arcscan.app
+Faucet: https://faucet.circle.com
+
+## Security Checklist
+
+- Never expose CIRCLE_ENTITY_SECRET publicly
+- Enable Supabase RLS on all tables
+- Verify Circle webhook signatures
+- Use HTTPS only in production
+- Rotate API keys regularly
+
+## Monitoring
+
+- Vercel dashboard for deployment logs
+- Supabase dashboard for database activity
+- Circle Console for wallet transactions
+- Arc Testnet Explorer: https://testnet.arcscan.app
+
+## Note
+
+This app is designed for testnet use only.
+Do not use real funds or production Circle API keys.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,92 @@
+# Troubleshooting Guide
+
+## Installation Issues
+
+### Node version errors
+Arc Escrow requires Node.js v22+.
+Check your version: node --version
+Install via nvm: nvm install 22 && nvm use 22
+
+### npm vulnerability warnings
+Fresh install shows ~21 vulnerabilities. These are non-critical dev dependencies.
+Run: npm audit fix (avoid --force as it may break things)
+
+### Docker not running
+Supabase local requires Docker Desktop.
+Start Docker Desktop before running: npx supabase start
+
+### Supabase connection refused
+Ensure Docker is running and ports 54321-54329 are free.
+Try: npx supabase stop && npx supabase start
+
+## API Key Issues
+
+### Circle API key errors
+Format: TEST_API_KEY:your-id:your-secret
+Get from: https://console.circle.com/keys
+Must be Testnet key for Arc Testnet
+
+### Entity Secret errors
+Generate once via Circle Console Configurator.
+Store securely - Circle cannot recover it.
+Register at: https://console.circle.com/wallets/dev/configurator
+
+### OpenAI API key errors
+Ensure key has sufficient credits.
+Get from: https://platform.openai.com/api-keys
+
+## Runtime Issues
+
+### Webhook not receiving events
+1. Start ngrok: ngrok http 3000
+2. Copy HTTPS URL from ngrok output
+3. Add to Circle Console webhooks
+4. URL format: https://your-id.ngrok.io/api/webhooks/circle
+
+### Database migration errors
+Try resetting: npx supabase db reset
+Then: npx supabase migration up
+
+### Wallet generation fails
+Check CIRCLE_API_KEY and CIRCLE_ENTITY_SECRET in .env.local
+Run: npm run generate-wallet
+
+### USDC not appearing
+Arc Testnet faucet: https://faucet.circle.com
+Select Arc Testnet and enter your wallet address
+
+## Common Errors
+
+### Error: malformed API key
+Your Circle API key format is wrong.
+Correct format: TEST_API_KEY:xxxxxxxx:xxxxxxxx
+
+### Error: Entity Secret not registered
+Complete the Circle Console Configurator step first.
+
+### Error: insufficient USDC balance
+Get testnet USDC from: https://faucet.circle.com
+
+### Error: webhook signature invalid
+Ensure CIRCLE_WEBHOOK_SECRET matches your Circle Console webhook secret.
+
+## Arc Testnet Info
+
+- Chain ID: 5042002
+- RPC URL: https://rpc.testnet.arc.network
+- Explorer: https://testnet.arcscan.app
+- Faucet: https://faucet.circle.com
+
+## FAQ
+
+Q: Can I use this on mainnet?
+A: No. This is testnet only and not production ready.
+
+Q: Which Node.js version is recommended?
+A: Node.js v22+ (tested on v22.22.3)
+
+Q: How do I reset everything?
+A: npx supabase db reset && npm run generate-wallet
+
+Q: Where do I get testnet USDC?
+A: https://faucet.circle.com - select Arc Testnet

docs/erc8183-integration.md

@@ -0,0 +1,53 @@
+# ERC-8183 Integration Guide for Arc Escrow
+
+This guide shows how to extend the Arc Escrow app with native ERC-8183 agentic commerce jobs on Arc Testnet.
+
+## Why ERC-8183?
+
+The current Arc Escrow app uses a custom EIP-712 Refund Protocol contract. ERC-8183 is Arc Testnet native standard for agentic commerce that provides:
+
+- Trustless escrow with onchain job lifecycle
+- Autonomous agent hiring (agents can hire sub-agents)
+- Native USDC settlement on Arc Testnet
+- Composable with ERC-8004 agent identity
+
+## ERC-8183 Contract on Arc Testnet
+
+AgenticCommerce: 0x0747EEf0706327138c69792bF28Cd525089e4583
+
+## Job Lifecycle
+
+createJob() -> setBudget() -> approve() -> fund() -> submit() -> complete()
+
+Status values: 0=Open 1=Funded 2=Submitted 3=Completed 4=Rejected 5=Expired
+
+## Integration Example
+
+Replace the custom escrow contract calls with ERC-8183 using Circle Developer Controlled Wallets:
+
+1. Create job: createJob(provider, evaluator, expiredAt, description, hook)
+2. Approve USDC: approve(AgenticCommerce, budgetAmount)
+3. Fund escrow: fund(jobId, optParams)
+4. Submit deliverable: submit(jobId, deliverableHash, optParams)
+5. Complete job: complete(jobId, reasonHash, optParams)
+
+## AI Validation Flow
+
+1. Client creates job with budget
+2. Provider (AI agent) submits deliverable hash
+3. Evaluator (Claude/OpenAI) validates the work offchain
+4. If approved: evaluator calls complete() -> payment released
+5. If rejected: evaluator calls reject() -> refund to client
+
+## Live Example on Arc Testnet
+
+Job ID: 110935 - Status: Completed - Budget: 5 USDC
+Full implementation: https://github.com/consumeobeydie/arc-agent-api
+
+Multi-agent extension: https://github.com/consumeobeydie/arc-multi-agent
+
+## Resources
+
+- Arc ERC-8183 Docs: https://docs.arc.network/arc/tutorials/create-your-first-erc-8183-job
+- Arc Testnet Explorer: https://testnet.arcscan.app
+- AgenticCommerce: https://testnet.arcscan.app/address/0x0747EEf0706327138c69792bF28Cd525089e4583