**Problem.** A Southeast Asian exporter or agency invoices an overseas buyer and waits 30–90 days to be paid. Buyers don't want to pay upfront with no recourse; sellers can't wait. Trade finance exists but is slow, paper-based and closed to small businesses. **Solution.** Two contracts, both denominated in Paxos **USDG** (MAS-supervised, issued in Singapore):
## 📋 Overview Invoice Escrow is a decentralized, Web3-enabled invoice escrow and instant-advance protocol. It bridges decentralized finance (DeFi) with real-world business transactions by providing: 1. Milestone-Based Invoice Escrow: Multi-party escrow for buyers and sellers ensuring funds are released securely as project milestones are completed. 2. Receivables Financing (Instant Advance): Sellers can sell or factor pending invoices at a calculated discount to get immediate liquidity. 3. Liquidity Pools: Liquidity Providers (LPs) deposit stablecoins (USDG) into pools to fund invoice advances and earn yield from interest/discount fees. 4. Decentralized Dispute Resolution: Approved arbiters resolve contested milestone payments fairly on-chain. 5. On-Chain Reputation & Credit Scoring: Track seller reliability, fulfillment history, and risk metrics dynamically. ────── ## 🎯 Core Features & Capabilities ### 1. Milestone Invoice Escrow • Role-Gated Actions: Buyers lock payment in escrow; sellers submit completed milestones; buyers approve releases. • Auto-Release & Reclaim: Automated timelocks allow buyers to auto-release funds after deadlines or sellers to reclaim unsubmitted funds if unattended. • Custom Milestone Split: Split invoices into flexible milestone percentages or fixed amounts. ### 2. Instant Advance Marketplace (Factoring) • Immediate Liquidity: Sellers can list eligible, undisputed invoices for instant advance from the AdvancePool. • Dynamic Pricing & Quotes: Automated quote generation based on invoice risk, seller reputation score, and time to maturity. ### 3. Liquidity Pools (LPs) • Yield Generation: LPs deposit stablecoins (USDG) to mint pool shares and earn returns when advances mature. • Risk Parameters: Real-time visibility into total pool assets, idle capital, outstanding face value, and max withdrawal limits. ### 4. Arbiter & Dispute Resolution • Contested Milestones: If a buyer disputes a milestone, the invoice enters a disputed state. • Arbiter Ruling: Appointed arbiters review proof of work and execute resolveDispute or resolveExpiredDispute to distribute locked funds proportionally. ### 5. Reputation & Governance • Seller Credit Limits: Governance controls for setting max allowable advance limits per seller based on on-chain reputation. • Protocol Administration: Owner capabilities for approving arbiters, setting fee percentages, and pausing/unpausing protocol functions in emergency scenarios. ────── ## 🏗 System Architecture & Stack Invoice-Escrow Workspace ├── artifacts/ │ ├── invoice-escrow/ # React + Vite Web3 Frontend App │ └── api-server/ # Express API Server ├── lib/ │ ├── api-client-react/ # Generated React Query hooks │ ├── api-spec/ # OpenAPI specs & codegen definitions │ ├── api-zod/ # Zod validation schemas │ └── db/ # PostgreSQL database schemas (Drizzle ORM) └── scripts/ # Utility & deployment scripts ### Technology Stack • Frontend Framework: React 19, Vite 7, Tailwind CSS v4, Framer Motion • Web3 Integration: Wagmi v2, Viem v2, RainbowKit v2 • Monorepo Management: pnpm workspaces • Smart Contracts: Solidity (InvoiceEscrow, AdvancePool, USDG token) • State & Data Fetching: @tanstack/react-query ────── ## 🌐 Supported Blockchain Networks The protocol interacts directly with verified smart contract deployments across testnets: Network | Chain ID | RPC Endpoint | Block Explorer ----------------|----------|----------------|---------------- Arbitrum | 421614 | https://sepoli | Blockscout[1] Sepolia | | a- | | | rollup.arbitru | | | m.io/rpc | Robinhood | 46630 | https://rpc.te | Blockexplorer[ Chain Testnet | | stnet.chain.ro | 2] | | binhood.com | [1]: Blockscout https://arbitrum-sepolia.blockscout.com [2]: Blockexplorer https://explorer.testnet.chain.robinhood.… │ Token Standard: Transactions use USDG (6 decimals) on both │ supported networks. ────── ## 🗺 Application Routes & Navigation Route | Purpose | Key Operations --------------|---------------------|------------------------ / | Protocol Overview | Live metrics: total | | escrowed value, active | | pool assets, share | | price, recent events. /dashboard | Personal Dashboard | View invoices where | | connected wallet is | | Seller, Buyer, or | | Arbiter. /create | Create Invoice | Draft new milestone | | invoices, set | | buyer/arbiter | | addresses and | | deadlines. /market | Advance Marketplace | Browse eligible | | invoices and request | | instant liquidity | | advances. /pool | Liquidity Pool | Deposit USDG to mint | | pool shares or | | withdraw assets. /arbiter | Dispute Portal | View and resolve | | active disputes for | | assigned arbiters. /reputation | Reputation Score | Inspect seller | | completion stats, | | dispute rates, and | | pricing multipliers. /admin | Protocol Admin | Adjust fee structure, | | approve arbiters, | | configure credit | | limits, pause | | contracts. /activity | On-Chain Audit Feed | Decoded contract logs, | | transaction history, | | and event streams. /invoice/:id | Invoice Detail | Comprehensive view of | | milestones, role-gated | | payment actions, and | | disputes. ────── ## 🚀 Local Development & Deployment ### Quick Start # 1. Install dependencies from workspace root pnpm install # 2. Run frontend development server cd artifacts/invoice-escrow pnpm run dev # Starts app at http://localhost:5173 # 3. Build for production pnpm run build # Outputs production build to dist/public ### Vercel Deployment Settings When deploying artifacts/invoice-escrow to Vercel: • Root Directory: artifacts/invoice-escrow • Framework Preset: Vite • Output Directory: dist/public (configured in vercel.json)