Homepay Escrow Platform

A production-ready multi-party escrow smart contract system with a modern web interface. Built with Hardhat, Solidity, and Next.js.

🎯 Overview

A sophisticated escrow platform that supports unlimited buyers and sellers with simultaneous independent transactions. Each transaction can have custom fee percentages and maintains complete isolation from other transactions.

✨ Key Features

Smart Contract

✅ Multi-party transactions - Unlimited buyers and sellers per transaction
✅ Unique transaction IDs - 5-character base-32 slug system
✅ Per-transaction fee configuration - Customizable agent fees (0-10%)
✅ Partial releases - Milestone-based payments with custom splits
✅ Dispute mechanism - Per-transaction dispute handling
✅ Aggregated withdrawals - Pull payment pattern for security
✅ OpenZeppelin security - ReentrancyGuard, Pausable, AccessControl
✅ Recent transactions tracking - Query last N transactions
✅ 56 comprehensive tests - All passing

Web Interface

🔗 MetaMask integration - Auto-reconnect on page reload
👤 Role-based UI - Agent, Buyer, and Seller views
💰 Transaction management - Create, deposit, release, refund
📊 Real-time updates - Balance and transaction status
🔍 Transaction search - Autocomplete with recent transactions
💸 Fee management - Agent fee withdrawal interface
📱 Responsive design - Tailwind CSS with modern UI

Project Structure

solidity_test1/
├── contracts/
│   └── HomepayEscrowMark3.sol     # Multi-party escrow platform
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx           # Main application page
│   │   │   └── layout.tsx         # Layout wrapper
│   │   ├── components/
│   │   │   ├── WalletConnect.tsx  # MetaMask connection
│   │   │   ├── CreateTransaction.tsx
│   │   │   ├── TransactionView.tsx
│   │   │   ├── DepositFunds.tsx
│   │   │   ├── WithdrawFunds.tsx
│   │   │   ├── AgentActions.tsx
│   │   │   └── AgentFeeWithdrawal.tsx
│   │   ├── contracts/
│   │   │   ├── config.ts          # Contract address & types
│   │   │   └── HomepayEscrowMark3.abi.json
│   │   ├── hooks/
│   │   │   └── useContract.ts     # Contract interaction hook
│   │   └── styles/
│   │       └── globals.css        # Tailwind styles
│   └── package.json
├── test/
│   └── HomepayEscrowMark3.test.js # Platform tests (56 tests)
├── scripts/
│   ├── deploy-escrow-mark3.js     # Deployment with sample transactions
│   └── deploy-to-testnet.js       # Testnet deployment
├── README.md                      # This file
├── SETUP.md                       # Setup instructions
└── hardhat.config.js              # Hardhat configuration

Prerequisites

Node.js (v18 or later)
npm
MetaMask browser extension

Quick Start

1. Install Dependencies

npm install
cd frontend && npm install && cd ..

2. Run Tests

npm test                # Run all tests (56 tests)

3. Start Development Environment

Terminal 1 - Blockchain:

npm run node

Terminal 2 - Deploy Contract:

npm run deploy

Copy the deployed contract address and update frontend/src/contracts/config.ts

Terminal 3 - Frontend:

cd frontend
npm run dev

Open http://localhost:3000 and connect MetaMask.

4. Configure MetaMask

Add Hardhat Local Network:

Network Name: Hardhat Local
RPC URL: http://127.0.0.1:8545
Chain ID: 31337
Currency Symbol: ETH

Import test accounts using private keys from the node output.

📖 How It Works

Transaction Lifecycle

Agent creates transaction - Defines buyers, sellers, and fee percentage
Buyers deposit funds - Each buyer deposits their share
Agent releases funds - Full payout or partial releases to sellers
Parties withdraw - Sellers (and buyers if refunded) withdraw their balances

Key Concepts

Transaction IDs: 5-character slugs (e.g., AAAAB, XYZW9) for easy reference

Per-Transaction Fees: Each transaction can have a custom fee (0-10%, default 0.25%)

Aggregated Withdrawals: All funds from multiple transactions accumulate per user

Dispute Mechanism: Agent can raise/resolve disputes, blocking payments

Partial Releases: Agent can release funds incrementally with custom seller splits

🧪 Testing

# Run all 56 tests
npm test

# With gas reporting
REPORT_GAS=true npm test

📚 Smart Contract API

Agent Functions

createTransaction(buyers[], sellers[], feePercentage) → string txId
payout(txId)
partialRelease(txId, sellerAllocations[])
refund(txId)
raiseDispute(txId, reason)
resolveDispute(txId, resolution)
withdrawFees()

Buyer Functions

deposit(txId) payable
withdraw()
getWithdrawableBalance() → uint256

Seller Functions

withdraw()
getWithdrawableBalance() → uint256
getSellerAllocation(txId, address) → uint256

View Functions

getTransaction(txId) → EscrowTransaction
getBuyerContribution(txId, buyer) → uint256
getRecentTransactions(count) → string[]
getTotalAgentFees() → uint256

🎨 Frontend Components

WalletConnect - MetaMask connection with auto-reconnect

CreateTransaction - Agent creates new escrow transactions

TransactionView - View transaction details, contributions, allocations

DepositFunds - Buyers deposit to transactions

AgentActions - Release, refund, and dispute management

AgentFeeWithdrawal - Agent withdraws collected fees

WithdrawFunds - Users withdraw their balances

🔧 Development Scripts

# Compile contracts
npm run compile

# Deploy contract
npm run deploy          # Deploy to localhost with demo transactions

🔒 Security

All contracts implement OpenZeppelin's security standards:

ReentrancyGuard - Prevents reentrancy attacks
Pausable - Emergency stop functionality
AccessControl - Role-based permissions (AGENT_ROLE)
Pull Payment Pattern - Users withdraw their own funds

📊 Contract Statistics

56 tests passing
Supports unlimited buyers/sellers per transaction
Per-transaction fee configuration
Recent transactions tracking
Comprehensive event logging

🚀 Deployment

Local Network

npx hardhat run scripts/deploy-escrow-mark3.js --network localhost

Testnet (e.g., Sepolia)

Update hardhat.config.js with your Infura/Alchemy key
Add your private key to environment
Deploy:

npx hardhat run scripts/deploy-escrow-mark3.js --network sepolia

📁 Project Structure Details

contracts/ - Multi-party escrow smart contract

test/ - Comprehensive test suite using Hardhat & Chai (56 tests)

scripts/ - Deployment scripts for localhost and testnet

frontend/ - Next.js web interface with TypeScript & Tailwind

🐛 Troubleshooting

MetaMask not connecting?

Ensure Hardhat node is running
Check network settings (Chain ID: 31337)
Try disconnecting and reconnecting

Contract address mismatch?

Update frontend/src/contracts/config.ts with deployed address
Restart frontend dev server

Transaction fails?

Check you're using the correct role (Agent/Buyer/Seller)
Verify sufficient ETH balance
Check transaction hasn't already been processed

📄 License

ISC

🤝 Contributing

This is a learning/demonstration project showcasing production-ready smart contract patterns.

Built with Hardhat, Solidity ^0.8.28, OpenZeppelin, Next.js, and TypeScript

Technology Stack

Hardhat: Ethereum development environment
Solidity: Smart contract programming language (v0.8.28)
Ethers.js: Ethereum library for JavaScript
Chai: Testing framework
Hardhat Toolbox: Collection of essential Hardhat plugins

License

MIT

Name		Name	Last commit message	Last commit date
contracts		contracts
frontend		frontend
scripts		scripts
test		test
.env.example		.env.example
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
hardhat.config.js		hardhat.config.js
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation