Gasless Escrow System

A milestone-based escrow platform that enables completely gasless interactions for end users through EIP-2612 permits and ERC-2771 meta-transactions. Built for freelancers and clients who want to use blockchain escrow without crypto complexity.

🌟 Overview

This project demonstrates how to build truly gasless Web3 applications by combining:

EIP-2612 USDC Permits - Gasless token approvals through off-chain signatures
ERC-2771 Meta-Transactions - Gasless contract interactions via trusted forwarders
Sponsor-Paid Gas - Backend pays all transaction fees on behalf of users
Milestone-Based Escrow - Secure payment system with incremental fund release

The Result: Users can interact with smart contracts using only email authentication - no wallets, no ETH, no gas fees, no crypto knowledge required.

💡 Key Innovation

Problem: Traditional Web3 UX requires users to:

Install wallets (MetamMask, etc.)
Buy ETH for gas fees
Understand blockchain concepts
Manage private keys and seed phrases

Solution: This system abstracts away all blockchain complexity:

✅ Sign in with email - No wallet installation
✅ Zero gas fees - Backend sponsors all transactions
✅ Familiar UX - Feels like a traditional web app
✅ Full security - All transactions cryptographically signed by users

🏗️ Technical Architecture

graph TB
    User[👤 User] --> Frontend[🖥️ Next.js Frontend]
    Frontend --> Backend[🐍 FastAPI Backend]
    Backend --> Sponsor[💰 Sponsor Account]
    Backend --> DB[(🗄️ PostgreSQL)]
    
    User --> |EIP-2612 Permit| USDC[💱 USDC Contract]
    User --> |EIP-712 Signature| Forwarder[📡 ERC2771Forwarder]
    
    Sponsor --> |Pays Gas| Forwarder
    Sponsor --> |Pays Gas| USDC
    
    Forwarder --> |Meta-Transaction| Escrow[📝 Escrow Contract]
    USDC --> |Transfer| Escrow
    
    subgraph "Base Sepolia Testnet"
        USDC
        Forwarder
        Escrow
    end

Flow Breakdown

User Action: User wants to fund a milestone
USDC Permit: User signs EIP-2612 permit (gasless approval)
Sponsor Submission: Backend submits permit using sponsor account (pays gas)
Meta-Transaction: User signs EIP-712 meta-transaction for escrow funding
Forwarder Execution: Backend submits meta-transaction via ERC2771Forwarder (pays gas)
Contract Execution: Escrow contract receives original user address via _msgSender()
Token Transfer: USDC transfers from user to escrow contract
Milestone Update: Database updated with funding status

🛠️ Tech Stack

Smart Contracts

Solidity ^0.8.28 - Contract development
Hardhat - Development framework
OpenZeppelin ERC2771Context - Meta-transaction support
OpenZeppelin ERC2771Forwarder - Trusted forwarder implementation
Base Sepolia - L2 testnet deployment

Backend

FastAPI - High-performance Python API
Web3.py - Ethereum interaction
PostgreSQL - Data persistence
eth-account - Cryptographic signing
python-dotenv - Environment management

Frontend

Next.js 15 - React framework with SSR
TypeScript - Type safety
Tailwind CSS - Utility-first styling
NextAuth.js - Authentication
Lucide React - Icon library

Infrastructure

EIP-2612 - USDC permit signatures
EIP-712 - Typed data signing
ERC-2771 - Meta-transaction standard
Base L2 - Low-cost blockchain deployment

📁 Project Structure

stablecoin-poc/
├── contracts/                 # Smart contract development
│   ├── contracts/
│   │   ├── Escrow.sol         # Main escrow contract with ERC2771Context
│   │   └── Forwarder.sol      # ERC2771Forwarder implementation
│   ├── scripts/               # Deployment scripts
│   └── hardhat.config.js      # Hardhat configuration
│
├── backend/                   # FastAPI backend
│   └── app/
│       ├── main.py           # FastAPI application entry
│       ├── routes/           # API endpoints
│       │   ├── escrow.py     # Escrow-related endpoints
│       │   ├── invoice.py    # Invoice management
│       │   └── users.py      # User management
│       ├── services/         # Business logic
│       │   ├── escrow.py     # Meta-transaction orchestration
│       │   └── permit2.py    # EIP-2612 permit handling
│       ├── database/         # Data access layer
│       └── utils/            # Contract ABIs and utilities
│
├── frontend/                 # Next.js frontend
│   ├── components/           # React components
│   ├── pages/               # Next.js pages
│   └── services/            # API client
│
└── shared/                  # Shared Python modules
    ├── constants.py         # Blockchain constants
    └── utils.py            # Utility functions

🚀 Quick Start

Prerequisites

Node.js 18+
Python 3.11+
PostgreSQL
Alchemy API key (for Base Sepolia RPC)

Environment Setup

Clone the repository

git clone https://github.com/yourusername/gasless-escrow-system.git
cd gasless-escrow-system

Set up environment variables

cp .env.example .env

Edit .env with your configuration:

# Blockchain Configuration
RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY
USDC_CONTRACT_ADDRESS=0x036CbD53842c5426634e7929541eC2318f3dCF7e
FORWARDER_CONTRACT_ADDRESS=YOUR_DEPLOYED_FORWARDER_ADDRESS
PERMIT2_ADDRESS=0x000000000022D473030F116dDEE9F6B43aC78BA3

# Wallet Configuration (for testnet only!)
SPONSOR_PRIVATE_KEY=your_sponsor_private_key_here

# Application Configuration
ENV=development
PORT=8000
API_URL=http://localhost:8000
SERVER_SECRET=your_server_secret_key_here
NEXTAUTH_SECRET=your_nextauth_secret_here

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/your_database_name

Smart Contract Deployment

Install dependencies

cd contracts
npm install

Deploy contracts

# Deploy forwarder
npx hardhat run scripts/deployForwarder.js --network base_sepolia

# Deploy escrow (using forwarder address)
npx hardhat run scripts/deployEscrow.js --network base_sepolia

Update contract addresses in .env

Backend Setup

Install Python dependencies

cd backend
pip install -r requirements.txt

Set up database

# Create PostgreSQL database
createdb escrowdb

# Tables are auto-created on startup

Run backend

cd backend
PYTHONPATH=/path/to/project uvicorn app.main:app --reload

Frontend Setup

Install dependencies

cd frontend
npm install

Run development server

npm run dev

💰 Gas Sponsorship Model

The system uses a sponsor account that pays gas fees for all user transactions:

# Backend sponsors gas for user transactions
sponsor_account = w3.eth.account.from_key(SPONSOR_PRIVATE_KEY)

# User signs permit (gasless)
permit_signature = generate_usdc_permit_signature(user_account, spender, amount)

# Sponsor submits permit (pays gas)
submit_usdc_permit_via_sponsor(permit_signature, sponsor_account)

# User signs meta-transaction (gasless)  
meta_tx_signature = sign_meta_transaction(user_account, function_call)

# Sponsor executes meta-transaction (pays gas)
execute_meta_transaction(meta_tx_signature, sponsor_account)

Cost Estimation:

Permit transaction: ~50,000 gas
Meta-transaction: ~150,000 gas
Base Sepolia gas price: ~0.001 gwei
Cost per user action: ~$0.0002

🔐 Security Model

User Security

Private keys generated and encrypted server-side
Never exposed to frontend or user
EIP-712 signatures ensure transaction authenticity
Permit expiration limits approval timeframes

Contract Security

OpenZeppelin contracts - battle-tested implementations
ERC2771Context - prevents signature replay attacks
Trusted forwarder - validates meta-transaction signatures
Client authorization - only authorized addresses can fund/release

Backend Security

Environment variables for sensitive data
Database encryption for private keys
API rate limiting (recommended for production)
CORS configuration restricts frontend access

🧪 Testing

Contract Tests

cd contracts
npx hardhat test

Backend Tests

cd backend
python -m pytest tests/

Integration Tests

# Test full gasless flow
python test_contract.py

📊 Gas Optimization

The system achieves gasless UX through several optimizations:

EIP-2612 Permits - Replace approve() + transferFrom() with single permit
Batch Operations - Multiple permits can be signed offline
Meta-Transaction Batching - Single forwarder call for multiple operations
Efficient Contract Design - Minimal storage operations
L2 Deployment - Base L2 offers ~100x cheaper gas than mainnet

🤝 Contributing

This project is open-sourced to demonstrate gasless Web3 UX patterns. Contributions welcome!

Development Setup

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Make changes and test thoroughly
Commit with clear messages (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Areas for Contribution

Additional ERC-20 token support
Enhanced frontend components
Mobile-responsive design
Advanced escrow features (disputes, arbitration)
Gas optimization improvements
Comprehensive test coverage
Documentation improvements

🚀 Deployment

Testnet Deployment

The system is configured for Base Sepolia testnet:

Low gas costs for testing
Faucets available for test tokens
Identical to mainnet Base L2

Production Considerations

For mainnet deployment:

Update contract addresses for mainnet USDC
Deploy to Base mainnet for low gas costs
Implement monitoring for sponsor account balance
Add rate limiting and abuse prevention
Consider multi-sig for sponsor account security

📚 Resources

EIP Standards

Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

OpenZeppelin - For secure, audited smart contract implementations
Base Protocol - For low-cost L2 infrastructure
FastAPI - For high-performance Python web framework
Next.js - For excellent React development experience

Built with ❤️ for the future of gasless Web3 UX

This project demonstrates that blockchain applications can have the same user experience as traditional web applications while maintaining the security and decentralization benefits of Web3.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
backend/app		backend/app
contracts		contracts
frontend		frontend
shared		shared
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
test.py		test.py
test_contract.py		test_contract.py

License

zaw-win/gasless-smart-contract-escrow

Folders and files

Latest commit

History

Repository files navigation