https://github.com/circlefin/arc-escrow
This sample app demonstrates an end-to-end escrow workflow — from contract creation and deposit, through AI-validated deliverable submission, to fund release or refund on Arc.
https://github.com/circlefin/arc-escrow
Last synced: 4 months ago
JSON representation
This sample app demonstrates an end-to-end escrow workflow — from contract creation and deposit, through AI-validated deliverable submission, to fund release or refund on Arc.
- Host: GitHub
- URL: https://github.com/circlefin/arc-escrow
- Owner: circlefin
- License: apache-2.0
- Created: 2026-03-10T02:22:46.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-03-27T07:01:51.000Z (4 months ago)
- Last Synced: 2026-03-27T19:06:42.787Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.64 MB
- Stars: 10
- Watchers: 0
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Workflow Escrow Refund Protocol
Automate escrow-backed freelance agreements with AI-powered work validation using USDC on Arc testnet. This sample application uses Next.js, Supabase, Circle Developer Controlled Wallets, and OpenAI to demonstrate an end-to-end escrow workflow — from contract creation and deposit, through AI-validated deliverable submission, to fund release or refund.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [How It Works](#how-it-works)
- [Environment Variables](#environment-variables)
- [User Accounts](#user-accounts)
## Prerequisites
- **Node.js v22+** — Install via [nvm](https://github.com/nvm-sh/nvm)
- **Supabase CLI** — Install via `npm install -g supabase` or see [Supabase CLI docs](https://supabase.com/docs/guides/cli/getting-started)
- **Docker Desktop** (only if using the local Supabase path) — [Install Docker Desktop](https://www.docker.com/products/docker-desktop/)
- **[ngrok](https://ngrok.com/)** — For local webhook testing
- Circle Developer Controlled Wallets **[API key](https://console.circle.com/signin)** and **[Entity Secret](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)**
- **[OpenAI API key](https://platform.openai.com/api-keys)** — Used for AI-powered work validation
## Getting Started
1. Clone the repository and install dependencies:
```bash
git clone git@github.com:akelani-circle/workflow-escrow-refund-protocol.git
cd workflow-escrow-refund-protocol
npm install
```
2. Set up environment variables:
```bash
cp .env.example .env.local
```
Then edit `.env.local` and fill in all required values (see [Environment Variables](#environment-variables) section below). Leave `NEXT_PUBLIC_AGENT_WALLET_ID`, `NEXT_PUBLIC_AGENT_WALLET_ADDRESS`, and `CIRCLE_BLOCKCHAIN` blank — they will be auto-generated in the next step.
3. Generate the agent wallet:
```bash
npm run generate-wallet
```
This creates a Circle developer-controlled wallet and writes the wallet ID, address, and blockchain values into your `.env.local`.
4. Set up the database — Choose one of the two paths below:
Path 1: Local Supabase (Docker)
Requires Docker Desktop installed and running.
```bash
npx supabase start
npx supabase migration up
```
The output of `npx supabase start` will display the Supabase URL and API keys needed for your `.env.local`.
Path 2: Remote Supabase (Cloud)
Requires a [Supabase](https://supabase.com/) account and project.
```bash
npx supabase link --project-ref
npx supabase db push
```
Retrieve your project URL and API keys from the Supabase dashboard under **Settings → API**.
5. Start the development server:
```bash
npm run dev
```
The app will be available at `http://localhost:3000`.
6. Set up Circle Webhooks (for local development):
In a separate terminal, expose your local server:
```bash
ngrok http 3000
```
Copy the HTTPS URL from ngrok and configure a webhook in the Circle Console:
- Navigate to [Circle Console → Webhooks](https://console.circle.com/webhooks)
- Add a new webhook endpoint: `https://your-ngrok-url.ngrok.io/api/webhooks/circle`
- Keep ngrok running while developing to receive webhook events
## How It Works
- Built with [Next.js](https://nextjs.org/) and [Supabase](https://supabase.com/)
- Uses [Circle Developer Controlled Wallets](https://developers.circle.com/wallets/dev-controlled) for USDC escrow transactions on Arc testnet
- Smart contracts (EIP-712 Refund Protocol) deployed and managed via `@circle-fin/smart-contract-platform`
- [OpenAI](https://platform.openai.com/) validates submitted work deliverables against agreement criteria using vision models
- Webhook signature verification ensures secure transaction notifications
- Agent wallet automatically initialized via the `generate-wallet` script
- Real-time UI updates powered by Supabase Realtime subscriptions
## Environment Variables
Copy `.env.example` to `.env.local` and fill in the required values:
```bash
# Deployment URL
VERCEL_URL=http://localhost:3000
NEXT_PUBLIC_VERCEL_URL=http://localhost:3000
# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
# USDC Smart Contract
NEXT_PUBLIC_USDC_CONTRACT_ADDRESS=
# Agent Wallet (auto-generated by npm run generate-wallet)
NEXT_PUBLIC_AGENT_WALLET_ID=
NEXT_PUBLIC_AGENT_WALLET_ADDRESS=
# Circle
CIRCLE_API_KEY=
CIRCLE_ENTITY_SECRET=
CIRCLE_BLOCKCHAIN=
# OpenAI
OPENAI_API_KEY=
```
| Variable | Scope | Purpose |
| --- | --- | --- |
| `VERCEL_URL` | Server-side | Base URL of the deployment (e.g., `http://localhost:3000`). |
| `NEXT_PUBLIC_VERCEL_URL` | Public | Public-facing base URL for client-side usage. |
| `NEXT_PUBLIC_SUPABASE_URL` | Public | Supabase project URL. |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Public | Supabase anonymous/public key. |
| `NEXT_PUBLIC_USDC_CONTRACT_ADDRESS` | Public | USDC token contract address on the target blockchain. |
| `NEXT_PUBLIC_AGENT_WALLET_ID` | Public | Circle wallet ID for the escrow agent. Auto-generated. |
| `NEXT_PUBLIC_AGENT_WALLET_ADDRESS` | Public | Wallet address for the escrow agent. Auto-generated. |
| `CIRCLE_API_KEY` | Server-side | Circle API key for wallet and contract operations. |
| `CIRCLE_ENTITY_SECRET` | Server-side | Circle entity secret for signing transactions. |
| `CIRCLE_BLOCKCHAIN` | Server-side | Blockchain network identifier (e.g., `ARC-TESTNET`). Auto-generated. |
| `OPENAI_API_KEY` | Server-side | OpenAI API key for AI-powered work validation. |
## User Accounts
### Default Account
On first visit, sign up with any email and password. The first user created can act as both a depositor (client) and a beneficiary (freelancer) across different agreements.
### Signup Rate Limits
Supabase limits email signups to **2 per hour** by default (unless custom SMTP is configured). If you hit an "email rate limit exceeded" error during testing:
- **Local Supabase (Docker):** Email verification is handled by the built-in [Inbucket](http://127.0.0.1:54324) mail server — check it to confirm signups. The rate limit can be adjusted in `supabase/config.toml` under `[auth.rate_limit]`.
- **Remote Supabase (Cloud):** Use real email addresses (disposable emails may fail verification). If you hit the limit, you can manually add users via the Supabase dashboard under **Authentication → Users**.
## Security & Usage Model
This sample application:
- Assumes testnet usage only
- Handles secrets via environment variables
- Verifies webhook signatures for security
- Is not intended for production use without modification