Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

57 Commits
 
 
 
 
 
 
 
 

Repository files navigation

BizEscrow — Programmatic USDC Settlement & Escrow Protocol

An enterprise-ready settlement framework and developer API infrastructure for milestone-gated B2B trade finance. BizEscrow operates on Arc Testnet using native USDC as gas, enabling sub-second finality, zero-friction capital lockups, and yield-bearing escrow vaults.


Technical & Business Value Proposition

Traditional B2B trade finance relies on slow, expensive letter-of-credit systems and manual bank escrow procedures, which tie up corporate working capital with high overhead. BizEscrow replaces these legacy pipelines with a programmatic trust layer:

+-------------------------------------------------------------------------------+
|                             Legacy Escrow vs BizEscrow                        |
|                                                                               |
|   Legacy Escrow:                                                              |
|   [Buyer] ---> (Bank Intermediary) ---> [3-5 Days Lockup] ---> [Seller]       |
|                * High Fees (1-3%)                                             |
|                * Zero Yield on Locked Funds                                   |
|                * Manual Dispute Resolution                                    |
|                                                                               |
|   BizEscrow:                                                                  |
|   [Buyer] ---> (Isolated SCA Vault) ---> [Sub-Second Yield] ---> [Seller]     |
|                * Ultra-Low Fees (0.1%)                                        |
|                * Split Compound Interest (USDC)                               |
|                * Automated AI/Oracle Milestones                               |
+-------------------------------------------------------------------------------+

1. System Topology & Architecture

BizEscrow utilizes a multi-tier decentralized design to isolate user execution, protect transaction metadata, and guarantee capital security.

graph TD
    %% Client Interactions
    User[Connected Web3 Wallet] -->|USDC Transfer| GateReceiver[Circle Gateway Receiver]
    GateReceiver -->|Verify Receipt| DB[(Supabase Database)]
    
    %% API / Routing Tier
    User -->|Sign Request| SignatureFilter[x402 Micropayment Filter]
    SignatureFilter -->|Access Granted| AgentSwarm[AI Verification Swarm]
    
    %% On-Chain Core Tier
    AgentSwarm -->|Deploy SCA Vault| BizEscrowContract[BizEscrow Core Contract]
    BizEscrowContract -->|Register Vault Address| Registry[Vault Registry]
    BizEscrowContract -->|Automatic Deposit| YieldPool[MockYieldPool / TokenYield]
    
    %% Settlement & FX Tier
    YieldPool -->|Compound Interest| SplitManager[Yield Split Manager]
    BizEscrowContract -->|Trigger Settlement Swap| StableFX[StableFX Converter]
    StableFX -->|Deliver EURC/USDC| Seller[Seller Wallet]

    classDef contract fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef external fill:#1e293b,stroke:#64748b,stroke-width:1px,color:#cbd5e1;
    class BizEscrowContract,YieldPool,StableFX contract;
    class DB,AgentSwarm external;
Loading

Isolated Smart Escrow Accounts (SCA)

Unlike centralized escrow platforms where all funds are pooled in a single contract, BizEscrow implements a segregated vault pattern:

  • Each deal is assigned an isolated Smart Escrow Account address.
  • Funds are held in individual smart contracts before being deposited into the compound yield pool.
  • Isolation ensures that a compromise or failure of a single vault does not impact the global system state.

2. Core Protocol Mechanics

The Escrow Lifecycle (Finite State Machine)

The BizEscrow.sol contract enforces strict transition guardrails, preventing state-jacking and ensuring deterministic outcomes:

stateDiagram-v2
    [*] --> CREATED : createEscrow()
    CREATED --> FUNDED : fundEscrow()
    CREATED --> CANCELLED : cancelEscrow()
    
    FUNDED --> DELIVERED : completeMilestone() [All Completed]
    FUNDED --> DISPUTED : disputeEscrow()
    FUNDED --> REFUNDED : refundEscrow() [After Deadline]
    
    DELIVERED --> RELEASED : releaseMilestone() / releaseAll()
    DELIVERED --> DISPUTED : disputeEscrow()
    
    DISPUTED --> RESOLVED : resolveDispute()
    
    RELEASED --> [*]
    RESOLVED --> [*]
    REFUNDED --> [*]
    CANCELLED --> [*]
Loading

Yield Splitting & Math Formulation

While funds are locked in the escrow vault, they earn compound interest via the integrated MockYieldPool. Upon milestone release, the accumulated interest is distributed dynamically according to the predefined base-points splits:

$$\text{Accumulated Yield} = \text{Total Assets Returned} - \text{Milestone Principal}$$

$$\text{Buyer Yield Share} = \frac{\text{Accumulated Yield} \times \text{Buyer Share Bps}}{10,000}$$

$$\text{Seller Yield Share} = \frac{\text{Accumulated Yield} \times \text{Seller Share Bps}}{10,000}$$

$$\text{Platform Fee} = \frac{\text{Milestone Principal} \times \text{Platform Fee Bps}}{10,000}$$

$$\text{Seller Disbursement} = (\text{Milestone Principal} - \text{Platform Fee}) + \text{Seller Yield Share}$$

$$\text{Platform Revenue} = \text{Platform Fee} + (\text{Accumulated Yield} - \text{Buyer Yield Share} - \text{Seller Yield Share})$$


3. Circle Product Surface Integration

BizEscrow leverages Circle's stablecoin stack to build a gas-abstracted B2B experience:

+---------------------------------------------------------------------------------------+
|                                    CIRCLE STACK UTILITY                               |
|                                                                                       |
|   [Developer-Controlled Wallets] ---> Controls agent treasury wallets & on-chain txs. |
|   [Gateway (Unified Balance)]    ---> Multi-chain deposit routing to Arc Testnet.     |
|   [Modular Wallets SDK]          ---> Isolates Smart Escrow Accounts (SCA).           |
|   [App Kit + CCTP]               ---> Cross-chain stablecoin bridging & UX flow.      |
+---------------------------------------------------------------------------------------+
  1. Developer-Controlled Wallets (DCW): Used by autonomous verification agents to pay gas fees in USDC and execute programmatic contract calls (e.g., registerEscrowVault and fundEscrow) without requiring manual private key handling on the frontend.
  2. Gateway (Unified Balance): Consolidates liquidity across EVM chains (Arbitrum, Base, Ethereum) into a single, unified balance on Arc Testnet, removing bridging friction for corporate buyers.
  3. Modular Wallets SDK: Creates isolated smart accounts for each trade transaction, facilitating on-chain audit reports.
  4. App Kit (Send) + CCTP: Drives the on-chain gateway funding interface, allowing users to sign transactions directly from their browser using MetaMask/AppKit.

4. Security Framework & Threat Vector Analysis

To protect corporate capital, BizEscrow implements multiple security defense-in-depth measures:

  • Non-Custodial Architecture: The escrow contract controls the asset lockup period. Neither the platform team nor the AI agents can withdraw locked funds except through verified milestone completions, expiration timeouts, or arbitrator verdicts.
  • EIP-191 Auth Guard (x402 Micropayments): The REST API explorer prevents DDoS attacks by verifying cryptographic signatures off-chain. Users must sign an authorization payload, which is verified using elliptic and standard Ethereum message hashing before API calls are authorized.
  • Reentrancy Guard: Every state-changing and asset-moving contract function (like fundEscrow, releaseMilestone, and resolveDispute) is protected by OpenZeppelin's ReentrancyGuard to prevent recursive reentrancy attacks.
  • Arc Privacy Precompile: The system is prepared for enterprise privacy requirements. The contract implements a hook to staticcall the ARC_PRIVACY_PRECOMPILE at address 0x0000000000000000000000000000000000000088, validating encrypted transfer proofs and protecting counterparty trade volumes from public block explorers.

5. Blockchain Configuration & Contract Addresses

All smart contract resources are deployed and verified on the Arc Testnet:

Parameter / Resource Blockchain Specification
Network Name Arc Testnet
Chain ID 5042002
RPC Endpoint https://rpc.testnet.arc.network
Block Explorer https://testnet.arcscan.app
BizEscrow Core Contract 0x90B187d57bd04fE228e0B89fE430c973e1500705
USDC Native Gas Token 0x3600000000000000000000000000000000000000
EURC Settlement Token 0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a

6. Local Setup & Verification Guide

Follow these guidelines to launch the local BizEscrow node and web client.

System Prerequisites

  • Node.js version 18.x or higher
  • npm or yarn package manager
  • MetaMask web extension or equivalent Web3 provider configured for the Arc Testnet

Step 1: Clone & Install Dependencies

Navigate into the /app folder and install the NPM packages:

cd app
npm install

Step 2: Configure Environment

Create an .env.local configuration file:

cp .env.example .env.local

Fill in the parameters with your details:

NEXT_PUBLIC_BIZESCROW_ADDRESS=0x90B187d57bd04fE228e0B89fE430c973e1500705
CIRCLE_API_KEY=your_circle_api_key
CIRCLE_ENTITY_SECRET=your_circle_entity_secret
DEVELOPER_WALLET_ID=your_circle_developer_wallet_id
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Step 3: Run the Local Dev Server

npm run dev

Open http://localhost:3000 to access the Interactive Escrow Dashboard.


7. Service API Specification

BizEscrow leverages x402 Micropayments to prevent API abuse. Requests must include the payment-signature header containing a signed EIP-191 payload.

Create Escrow Vault API

  • Endpoint: /api/escrows/create
  • Method: POST
  • Headers:
    Content-Type: application/json
    payment-signature: <Base64_EIP191_Signature>
  • Request Body:
    {
      "buyer_address": "0xBuyerWalletAddress",
      "seller": "0xSellerWalletAddress",
      "arbitrator": "0xArbitratorWalletAddress",
      "totalAmount": "10.00",
      "deadlineDays": "30",
      "reference": "PURCHASE-ORDER-99A",
      "milestones": [
        { "description": "Software Architecture Setup", "amount": "4.00" },
        { "description": "Production Build & Launch", "amount": "6.00" }
      ]
    }

Execute Verification Swarm

  • Endpoint: /api/agents/run
  • Method: POST
  • Request Body:
    {
      "sellerAddress": "0xSellerWalletAddress",
      "amount": "1.00"
    }

8. Circle Developer Feedback & Ecosystem Insights

Building on Circle's Arc Testnet platform highlighted several operational strengths and areas for developer experience optimization:

Core Benefits

  • USDC as Native Gas Token: Removing the need to acquire native gas tokens (like ETH) streamlines the onboarding process for traditional corporate treasurers.
  • Predictable Gas Fees: The fixed fee structure on the Arc network makes transaction costs predictable for business transactions.
  • Sub-Second Finality: The rapid block confirmations (~1s) enable real-time state changes on the frontend, comparable to centralized web interfaces.

Suggested Improvements

  • Smart Contract Platform Integration: Providing built-in support for deploying custom Solidity templates via Circle's API would reduce the need for external deployment tools.
  • Gateway Status Callbacks: Adding webhook payload triggers for Gateway transfer statuses would simplify frontend payment monitoring.
  • Enhanced Faucet Limits: Increasing the faucet limit for developer testing would assist when dry-running multiple escrow scenarios.

About

Enterprise-ready milestone-gated escrow & settlement protocol on Arc Testnet. Integrates Circle's DCW, Gateway, Modular Wallets, and App Kit with native USDC gas for sub-second, yield-bearing B2B commerce.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages