Conduit UCPI - Escrow Smart Contracts

Time-delayed escrow contracts on Base blockchain with built-in dispute resolution.

Overview

This repository contains the Foundry-based smart contract implementation for Conduit UCPI's trustless escrow system. The contracts enable secure, time-locked transactions with buyer protection and administrator dispute resolution.

Contract Architecture

• EscrowContractFactory: Factory contract that creates individual escrow contracts using CREATE2 for deterministic addresses
• EscrowContract: Immutable escrow contract template for individual transactions

Features

• ⏱️ Time-delayed Release: Funds locked until expiry, protecting buyers
• 🛡️ Dispute Resolution: Built-in mechanism for handling transaction disputes
• 🔒 Immutable Parameters: Contract terms cannot be changed after deployment
• ✅ Battle-tested Security: Built with OpenZeppelin contracts
• 💰 USDC Support: Native USDC token integration
• 🏭 Factory Pattern: Gas-efficient contract deployment
• 🔄 Reentrancy Protection: Comprehensive security measures

Contract Lifecycle

1. Active: Contract deployed, funds locked, can be disputed by buyer
2. Disputed: Buyer raised a dispute, awaiting administrator resolution
3. Expired: Time passed expiry, seller can claim funds
4. Resolved: Dispute resolved by administrator with percentage-based fund distribution
5. Claimed: Funds distributed to final recipient(s)

Quick Start

Prerequisites

• Foundry
• Git

Installation

# Clone the repository
git clone <repository-url>
cd contracts

# Install dependencies
forge install

Configuration

Create a .env file based on .env.example:

cp .env.example .env
# Edit .env with your configuration

Required environment variables:

• RELAYER_WALLET_PRIVATE_KEY: Private key of the deployer wallet
• NETWORK: Target network (e.g., base-sepolia, base)
• CHAIN_ID: Network chain ID (84532 for Base Sepolia, 8453 for Base Mainnet)
• NETWORK_RPC_URL: RPC endpoint URL
• USDC_CONTRACT_ADDRESS: USDC contract address on target network
• VERIFIER_API_KEY: Block explorer API key for contract verification
• VERIFIER_URL: Block explorer API endpoint

Building

forge build

Testing

# Run all tests
forge test -vvv

# Run specific test
forge test --match-contract EscrowContractTest -vvv

# Generate gas report
forge test --gas-report

Deployment

# Deploy to configured network
forge script script/DeploymentScript.s.sol:DeploymentScript \
  --rpc-url $NETWORK_RPC_URL \
  --broadcast \
  --verify

# The deployment script will output:
# - Implementation contract address
# - Factory contract address

Security

Access Controls

• Buyer: Can raise disputes only
• Seller: Can claim funds after expiry (if not disputed)
• Gas Payer (Factory Owner): Can resolve disputes and facilitate claims

Security Features

• OpenZeppelin contracts for proven security patterns
• Reentrancy protection on all state-changing functions
• Comprehensive input validation
• Immutable contract parameters prevent tampering
• No upgrade mechanisms (security by design)

Testing

The test suite includes:

• Unit tests for individual contract functions
• Integration tests for full escrow lifecycle
• Security tests for access controls and edge cases
• Mock ERC20 implementation for comprehensive testing

Network Support

Supported Networks

Network	Chain ID	USDC Address
Base Sepolia (Testnet)	84532	0x036CbD53842c5426634e7929541eC2318f3dCF7e
Base Mainnet	8453	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Avalanche Fuji (Legacy)	43113	0x5425890298aed601595a70AB815c96711a31Bc65
Avalanche Mainnet (Legacy)	43114	TBD

Project Structure

contracts/
├── foundry.toml              # Foundry configuration
├── src/
│   ├── EscrowContract.sol    # Individual escrow contract template
│   └── EscrowContractFactory.sol # Factory for creating escrow contracts
├── script/
│   └── DeploymentScript.s.sol # Deployment script with verification
├── test/
│   ├── EscrowContract.t.sol  # Comprehensive escrow contract tests
│   └── EscrowContractFactory.t.sol # Factory contract tests
└── .env.example              # Environment configuration template

Related Repositories

• Chain Service - Transaction relay service with gas sponsorship
• Web Application - Next.js frontend for escrow management

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details

Deployed Contracts

Base Mainnet (Production)

• Factory: 0x00b1D1A005022D1f140062Ba5aB0A44788089F88
• Implementation: 0xCbfD53842f0ACc885a55b7A0eDb18eF5ac9237f9

Base Sepolia (Testnet)

• Factory: Not yet deployed
• Implementation: Not yet deployed

To update testnet: After testnet deployment, add addresses here.

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation in .claude/CLAUDE.md (for developers)

---

Built with ❤️ for trustless transactions on Base