workflow-escrow

Automated escrow agent that facilitates secure transactions.

Table of contents

• Clone and run locally
• Using Supabase Cloud
• Using Replit
• Project Structure

Clone and run locally

1. Clone the repository and install dependencies:

   git clone https://github.com/[username]/workflow-escrow.git
   cd workflow-escrow
   npm install

2. Rename .env.example to .env.local and update the following:

   # Deployment URL (e.g., http://localhost:3000)
   VERCEL_URL=http://localhost:3000
   NEXT_PUBLIC_VERCEL_URL=http://localhost:3000
   
   # Supabase configuration (https://app.supabase.com/project/_/settings/api)
   NEXT_PUBLIC_SUPABASE_URL=
   NEXT_PUBLIC_SUPABASE_ANON_KEY=
   
   # USDC Smart Contract configuration
   NEXT_PUBLIC_USDC_CONTRACT_ADDRESS=
   
   # Agent Wallet configuration
   NEXT_PUBLIC_AGENT_WALLET_ID=<leave blank>
   NEXT_PUBLIC_AGENT_WALLET_ADDRESS=<leave blank>
   
   # Circle API configuration (https://console.circle.com/apikeys)
   CIRCLE_API_KEY=
   CIRCLE_ENTITY_SECRET=
   CIRCLE_BLOCKCHAIN=<leave blank>
   
   # OpenAI API configuration (https://platform.openai.com/api-keys)
   OPENAI_API_KEY=
   

   • VERCEL_URL and NEXT_PUBLIC_VERCEL_URL is the base URL of the project (i.e. http://localhost:3000/ when developing locally).

   • NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY can be found in your Supabase project's API settings.

   • CIRCLE_API_KEY can be found in the API Keys section of Circle's console, while CIRCLE_ENTITY_SECRET must be shared, or rotated here in case it's lost.

   • OPENAI_API_KEY can be found in the Settings of your OpenAI account (Settings > API keys), while OPENAI_ASSISTANT_ID is located on the Assistants page, after selecting the desired assistant, the ID can be seen right below the "Name" input.

   • NEXT_PUBLIC_USDC_CONTRACT_ADDRESS is documented here alongside other blockchain test networks, like Polygon PoS Amoy (the one used in the project). This is used for the USDC approval function, which gives permission for a dapp to access and move a specific type of token from your wallet. The address for Polygon PoS Amoy is 0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582.

   Leave the follwing vars blank. These variables will be automatically generated by the generate-wallet.mjs script ins step 3:

   • CIRCLE_BLOCKCHAIN can be left blank. This is the blockchain network the escrow contracts will be deployed to.

   • NEXT_PUBLIC_AGENT_WALLET_ID and NEXT_PUBLIC_AGENT_WALLET_ADDRESS can be left blank. This is the wallet used by the escrow agent to interact with the escrow contracts.

3. Run the generate-wallet.mjs script to craete the agent wallet and updated the environment variables:

   npm run generate-wallet

4. Then start a local instance of the Supabase server:

   npx supabase start

5. Initialize the database schema:

   npx supabase migration up

6. You can now run the Next.js local development server:

   npm run dev

   The starter kit should now be running on localhost:3000.

7. With the project up and running, open an ngrok tunnel on the same port as of the local development server:

   ngrok http 3000

8. Configure the Circle webhook:

   1. Go to Circle Webhooks Dashboard
   2. Click "Add Webhook"
   3. Configure the following settings:
      • URL: Your ngrok URL + /api/webhooks/circle (e.g., https://9940-170-239-106-57.ngrok-free.app/api/webhooks/circle)
      • Limit to specific events: Disabled
   4. Save the webhook configuration

   Note: The webhook is essential for processing transaction status updates. Ensure it's properly configured before testing transactions.

9. This template comes with the default shadcn/ui style initialized. If you instead want other ui.shadcn styles, delete components.json and re-install shadcn/ui

Check out the docs for Local Development to also run Supabase locally.

Using Supabase Cloud

If you prefer to use Supabase Cloud instead of running Supabase locally:

1. Clone the repository and install dependencies:

   git clone https://github.com/[username]/workflow-escrow.git
   cd workflow-escrow
   npm install

2. Rename .env.example to .env.local and update the following:

   # Deployment URL (e.g., http://localhost:3000)
   VERCEL_URL=http://localhost:3000
   NEXT_PUBLIC_VERCEL_URL=http://localhost:3000
   
   # Supabase configuration (https://app.supabase.com/project/_/settings/api)
   NEXT_PUBLIC_SUPABASE_URL=
   NEXT_PUBLIC_SUPABASE_ANON_KEY=
   
   # USDC Smart Contract configuration
   NEXT_PUBLIC_USDC_CONTRACT_ADDRESS=
   
   # Agent Wallet configuration
   NEXT_PUBLIC_AGENT_WALLET_ID=<leave blank>
   NEXT_PUBLIC_AGENT_WALLET_ADDRESS=<leave blank>
   
   # Circle API configuration (https://console.circle.com/apikeys)
   CIRCLE_API_KEY=
   CIRCLE_ENTITY_SECRET=
   CIRCLE_BLOCKCHAIN=<leave blank>
   
   # OpenAI API configuration (https://platform.openai.com/api-keys)
   OPENAI_API_KEY=
   

   • VERCEL_URL and NEXT_PUBLIC_VERCEL_URL is the base URL of the project (i.e. http://localhost:3000/ when developing locally).

   • NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY can be found in your Supabase project's API settings.

   • CIRCLE_API_KEY can be found in the API Keys section of Circle's console, while CIRCLE_ENTITY_SECRET must be shared, or rotated here in case it's lost.

   • OPENAI_API_KEY can be found in the Settings of your OpenAI account (Settings > API keys), while OPENAI_ASSISTANT_ID is located on the Assistants page, after selecting the desired assistant, the ID can be seen right below the "Name" input.

   • NEXT_PUBLIC_USDC_CONTRACT_ADDRESS is documented here alongside other blockchain test networks, like Polygon PoS Amoy (the one used in the project). This is used for the USDC approval function, which gives permission for a dapp to access and move a specific type of token from your wallet. The address for Polygon PoS Amoy is 0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582.

   Leave the follwing vars blank. These variables will be automatically generated by the generate-wallet.mjs script in step 3:

   • CIRCLE_BLOCKCHAIN can be left blank. This is the blockchain network the escrow contracts will be deployed to.

   • NEXT_PUBLIC_AGENT_WALLET_ID and NEXT_PUBLIC_AGENT_WALLET_ADDRESS can be left blank. This is the wallet used by the escrow agent to interact with the escrow contracts.

3. Run the generate-wallet.mjs script to craete the agent wallet and updated the environment variables:

   npm run generate-wallet

4. Create a new project on Supabase

5. Set up authentication:

   • Go to Authentication > Providers
   • Enable Email provider
   • Disable "Confirm Email" to allow immediate sign-ins

6. Link your local project to your Supabase cloud project and push the database schema:

   # Install Supabase CLI if you haven't already
   npm install supabase --save-dev
   
   # Link to your remote project - you'll need your project ID and database password
   npx supabase link --project-ref <project-id>
   
   # Push the database schema
   npx supabase db push

   Note: You can find your project ID in your Supabase project settings under Project Settings > General

7. You can now run the Next.js development server:

   npm run dev

8. With the project up and running, open an ngrok tunnel on the same port as of the local development server:

   ngrok http 3000

9. Configure the Circle webhook:

   1. Go to Circle Webhooks Dashboard
   2. Click "Add Webhook"
   3. Configure the following settings:
      • URL: Your ngrok URL + /api/webhooks/circle (e.g., https://9940-170-239-106-57.ngrok-free.app/api/webhooks/circle)
      • Limit to specific events: Disabled
   4. Save the webhook configuration

   Note: The webhook is essential for processing transaction status updates. Ensure it's properly configured before testing transactions.

Using Replit

If you prefer to use Replit and Supabase Cloud instead of running it locally:

1. Set up your Replit project.

2. Click on the "Secrets" tool in the Tools panel and add the following environment variables (same as in .env.example):

      `VERCEL_URL`
      `NEXT_PUBLIC_VERCEL_URL`
      `NEXT_PUBLIC_SUPABASE_URL`
      `NEXT_PUBLIC_SUPABASE_ANON_KEY`
      `NEXT_PUBLIC_USDC_CONTRACT_ADDRESS`
      `NEXT_PUBLIC_AGENT_WALLET_ID` (generated in step 3)
      `NEXT_PUBLIC_AGENT_WALLET_ADDRESS` (generated in step 3)
      `CIRCLE_API_KEY`
      `CIRCLE_ENTITY_SECRET`
      `CIRCLE_BLOCKCHAIN`
      `OPENAI_API_KEY`
   

   • VERCEL_URL and NEXT_PUBLIC_VERCEL_URL is the base URL of the Replit server when you run it (i.e. https://<your-replit-url>.replit.dev/ when using Replit).

   • NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY can be found in your Supabase project's API settings.

   • CIRCLE_API_KEY can be found in the API Keys section of Circle's console, while CIRCLE_ENTITY_SECRET must be shared, or rotated here in case it's lost.

   • CIRCLE_BLOCKCHAIN can be set to MATIC-AMOY for development purposes

   • OPENAI_API_KEY can be found in the Settings of your OpenAI account (Settings > API keys), while OPENAI_ASSISTANT_ID is located on the Assistants page, after selecting the desired assistant, the ID can be seen right below the "Name" input.

   • NEXT_PUBLIC_USDC_CONTRACT_ADDRESS is documented here alongside other blockchain test networks, like Polygon PoS Amoy (the one used in the project). This is used for the USDC approval function, which gives permission for a dapp to access and move a specific type of token from your wallet. The address for Polygon PoS Amoy is 0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582.

   • NEXT_PUBLIC_AGENT_WALLET_ID and NEXT_PUBLIC_AGENT_WALLET_ADDRESS are the id and address of the developer controlled wallets generated in step 3.

3. Run the generate-wallet.mjs script to create the agent wallet id and address. Update the Replit Secrets with these values:

   npm run generate-wallet

4. Create a new project on Supabase

5. Set up authentication:

   • Go to Authentication > Providers
   • Enable Email provider
   • Disable "Confirm Email" to allow immediate sign-ins

6. Link your local project to your Supabase cloud project and push the database schema:

   # Install Supabase CLI if you haven't already
   npm install supabase --save-dev
   
   # Link to your remote project - you'll need your project ID and database password
   npx supabase link --project-ref <project-id>
   
   # Push the database schema
   npx supabase db push

   Note: You can find your project ID in your Supabase project settings under Project Settings > General

7. Click the "Run" button at the top of the page. Replit will start the development server.

8. Configure the Circle webhook:

   1. Go to Circle Webhooks Dashboard
   2. Click "Add Webhook"
   3. Configure the following settings:
      • URL: Your ngrok URL + /api/webhooks/circle (e.g., https://https://<your-replit-url>.replit.dev/api/webhooks/circle)
      • Limit to specific events: Disabled
      • Note: When using Replit, you'll need to use the Replit-provided URL for your webhook configurations instead of localhost or ngrok.
   4. Save the webhook configuration

   Note: The webhook is essential for processing transaction status updates. Ensure it's properly configured before testing transactions.

Project Structure

.
├── app/                    # Next.js 13+ app directory (main application code)
│   ├── actions/           # Server actions for form handling and data mutations
│   ├── api/               # API routes and endpoints
│   │   ├── contracts/     # Contract-related endpoints (analyze, escrow, validate)
│   │   ├── usdc/         # USDC token operations (buy, sell)
│   │   ├── wallet/       # Wallet operations (balance, transactions)
│   │   ├── wallet-set/   # Wallet set configuration
│   │   └── webhooks/     # Webhook handlers (Circle notifications)
│   ├── auth/             # Authentication core functionality
│   │   ├── auth-error/   # Error handling for auth failures
│   │   └── callback/     # OAuth and auth callback handling
│   ├── (auth-pages)/     # Authentication-related pages
│   │   ├── forgot-password/  # Password reset request
│   │   ├── sign-in/      # Login page
│   │   └── sign-up/      # Registration page
│   └── dashboard/        # Protected dashboard routes
│       ├── reset-password/  # Password reset form
│       └── transaction/   # Transaction details view
│
├── components/            # Reusable React components
│   ├── ui/               # Core UI components
│   │   ├── alert-dialog/ # Alert and confirmation dialogs
│   │   ├── button/      # Button components
│   │   ├── card/        # Card layout components
│   │   ├── dialog/      # Modal dialog components
│   │   └── form/        # Form input components
│   ├── agreement/       # Agreement-related components
│   │   ├── delete/      # Agreement deletion dialogs
│   │   ├── details/     # Agreement details views
│   │   └── table/       # Agreement listing components
│   └── wallet/          # Wallet-related components
│       ├── balance/     # Balance display components
│       └── transactions/# Transaction history components
│
├── contracts/              # Smart contract definitions and ABIs
│   ├── escrow_smart_contract/  # Escrow contract implementation
│   └── example_agreement/      # Example agreement with good and bad submission examples
│
├── lib/                    # Library code and utilities
│   ├── supabase/           # Supabase client configuration
│   └── utils/              # Utility functions and helpers
│
├── supabase/               # Supabase-specific configuration
│   └── migrations/         # Database migration files
│
└── types/                  # TypeScript type definitions

Key Directories

• app/: Core application code using Next.js 13+ app directory structure

  • actions/: Server-side actions for authentication and data mutations
  • api/: Backend API endpoints organized by functionality:
    • contracts/: Smart contract interactions and document analysis
    • usdc/: USDC token purchase and sale operations
    • wallet/: Digital wallet management and transactions
    • webhooks/: External service webhook handlers
  • auth/: Authentication system implementation
  • (auth-pages)/: Authentication-related pages (login, signup, password reset)
  • dashboard/: Protected application routes and features

• components/: Reusable React components organized by function

  • ui/: Core UI component library

• contracts/: Smart contract related files

  • escrow_smart_contract/: Contains the EscrowWithAgent.sol contract, which implements the escrow system with agent functionality
  • example_agreement/: Contains an example agreement and examples of good and bad submissions

• lib/: Utility functions and external service configurations

  • supabase/: Database client configuration for browser and server
  • utils/: Helper functions for amounts, dates, and API clients

• types/: TypeScript type definitions

  • Database schema types
  • Agreement and escrow-related type definitions
  • Component prop types

• supabase/: Database configuration and management

  • migrations/: SQL migration files for schema changes
  • Configuration files for Supabase setup

This structure follows a modular architecture that separates concerns between the frontend, backend APIs, smart contracts, and database layers while maintaining a clear organization for scaling the application.