FairDeal - Smart Contract Escrow Platform on Stellar

A trustless freelance escrow platform powered by Soroban smart contracts - No backend custody, fully on-chain!

🎉 Smart Contract Deployed: CC67YA4ZKWGNNA2JLS6TUPWFIULCHDWZEHBNQ5G7VDGWJ2TVC7QKWLZ2

🎯 What Makes This Different?

✅ Smart contract holds escrow (not a backend server!)
✅ Automatic fund release via blockchain logic
✅ On-chain reputation (fraud flags immutable)
✅ Deadline enforcement by contract
✅ Zero custody risk - backend can't access funds

🚀 Quick Start

# Install dependencies
npm install

# Run the application
npm run dev

# Open browser
http://localhost:3000

That's it! Everything (frontend + backend) runs on port 3000.

📋 Features

🔐 Trustless Smart Contract Escrow

Soroban Smart Contract: Funds locked in blockchain contract, not backend server
No Custody Risk: Contract enforces rules automatically, no human intervention
Deadline Enforcement: Automatic refunds if deadline passes
Emergency Release: Freelancers protected from indefinite escrow lock
On-chain Reputation: Immutable fraud tracking on blockchain

💼 Platform Features

Split Payments: Initial % to freelancer, remaining locked in smart contract
Encrypted Files: AES-256-CBC encryption for all submitted work
Watermarked Previews: Clients can preview work before approval
Code Execution Sandbox: Auto-preview for code projects (Node.js, Python, Java, HTML)
IPFS Storage: Decentralized file storage via Pinata
Fraud Protection: Smart contract-based fraud flag system
Freighter Wallet: Stellar wallet integration

🛠️ Setup

1. Environment Variables

Create .env.local file in the root directory:

# Stellar Configuration
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_CONTRACT_ID=your_contract_id_here

# Escrow Configuration (Server-side only)
ESCROW_SECRET_KEY=your_escrow_secret_key
ESCROW_PUBLIC_KEY=your_escrow_public_key

# Pinata/IPFS Configuration (Server-side only)
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_API_KEY=your_pinata_secret_api_key

# Optional: Restore from IPFS on startup
RESTORE_FROM_IPFS_CID=your_ipfs_cid_here

2. Install Freighter Wallet

Install Freighter browser extension
Create or import testnet account
Get testnet XLM from friendbot: https://laboratory.stellar.org/#account-creator?network=test

3. Run the Application

npm install
npm run dev

4. Build & Deploy Smart Contract (Optional - for production)

Prerequisites:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

# Install Soroban CLI
cargo install --locked soroban-cli

Build:

# Windows
.\build-contract.ps1

# Linux/Mac
./build-contract.sh

Deploy to Testnet:

# Windows
.\deploy-contract.ps1

# Linux/Mac
./deploy-contract.sh

See CONTRACT_GUIDE.md for detailed smart contract documentation.

📁 Project Structure

FairDeal/
├── app/                        # Next.js App Router
│   ├── api/                    # Backend API routes
│   │   ├── jobs/               # Job management endpoints
│   │   ├── escrow-address/     # Escrow public key
│   │   ├── freelancers/        # Fraud flags
│   │   ├── decrypt-file/       # File decryption
│   │   ├── ipfs/               # IPFS CID tracking
│   │   └── health/             # Health check
│   ├── page.tsx                # Landing + Dashboard
│   ├── login/                  # Wallet connection
│   ├── create-job/             # Job creation
│   ├── jobs/[jobId]/           # Job detail
│   └── submit-work/[jobId]/    # Work submission
├── components/                 # React components
│   ├── WalletProvider.tsx      # Wallet context
│   └── Navigation.tsx          # Navigation bar
├── lib/                        # Server-side utilities
│   ├── storage.ts              # File-based persistence
│   ├── stellar-utils.ts        # Stellar blockchain
│   ├── ipfs-utils.ts           # IPFS & watermarking
│   └── code-execution.ts       # Code sandbox
├── utils/                      # Client-side utilities
│   └── stellar-utils.ts        # Client Stellar ops
├── config/                     # Configuration
│   └── api.ts                  # API endpoints config
├── contract/                   # Soroban Smart Contract (Rust)
│   ├── src/
│   │   ├── lib.rs              # Main contract logic
│   │   └── test.rs             # Contract tests
│   └── Cargo.toml              # Rust dependencies
├── data/                       # Persistent storage
│   ├── jobs.json               # Job database
│   ├── files.json              # File metadata
│   ├── fraud.json              # Fraud flags
│   └── ipfs-cid.json           # Latest IPFS CID
├── build-contract.ps1          # Build script (Windows)
├── build-contract.sh           # Build script (Linux/Mac)
├── deploy-contract.ps1         # Deploy script (Windows)
├── deploy-contract.sh          # Deploy script (Linux/Mac)
├── CONTRACT_GUIDE.md           # Smart contract documentation
├── instrumentation.ts          # Server startup logic
├── next.config.js              # Next.js configuration
├── tsconfig.json               # TypeScript config
├── .env.local                  # Environment variables
└── package.json                # Dependencies

🔗 API Endpoints

All backend APIs are available at http://localhost:3000/api/*

Job Management

POST /api/jobs - Create new job
GET /api/jobs - List all jobs
GET /api/jobs/:jobId - Get job details
GET /api/jobs/:jobId/status - Get job status

Work Submission & Preview

POST /api/jobs/submit-work - Submit work files
GET /api/jobs/:jobId/preview - Get preview status
GET /api/jobs/:jobId/preview-content - View watermarked preview
GET /api/jobs/:jobId/download - Download original files (approved only)

Job Actions

POST /api/jobs/:jobId/release-initial-payment - Mark initial payment released
POST /api/jobs/:jobId/approve - Approve work & release funds
POST /api/jobs/:jobId/reject - Reject work or request revision
POST /api/jobs/:jobId/raise-fraud-flag - Raise fraud flag & refund

Utilities

GET /api/escrow-address - Get escrow public key
GET /api/freelancers/:address/fraud-flags - Get fraud history
POST /api/decrypt-file - Decrypt file
GET /api/ipfs/latest-cid - Get latest IPFS CID
GET /api/health - Health check

💰 How It Works

1. Client Creates Job

Connect wallet (Freighter)
Select "Client" role
Fill job details:
- Freelancer address
- Amount in XLM
- Initial payment % (10/20/30/50%)
- Deadline
- Description
Two payments executed:
- Initial % → Freelancer
- Remaining % → Escrow

2. Freelancer Submits Work

Connect wallet
Select "Freelancer" role
View assigned jobs
Upload work files (up to 50 files, 50MB)
Files automatically:
- Encrypted with AES-256-CBC
- Watermarked for preview
- Uploaded to IPFS

3. Client Reviews Work

View watermarked preview
For code projects: See execution results
Three options:
- Approve & Pay - Release remaining funds
- Request Revision - Allow resubmission
- Raise Fraud Flag - Terminate & refund

4. Fraud Protection

Clients can raise fraud flags
Fraud history tracked by freelancer address
Automatic refund on fraud flag
Job immediately terminated

🔐 Security Features

Encryption

AES-256-CBC encryption for all submitted files
Random 32-byte keys per file
Random 16-byte IVs per file
Keys stored encrypted in file metadata

Watermarking

"PREVIEW ONLY" text overlay on images
Opacity reduction for visual indication
Protects client's intellectual property

Code Execution Sandbox

Isolated temporary directories
30-second execution timeout
Automatic cleanup after execution
Supports: Node.js, Python, Java, HTML

Stellar Testnet

All transactions on testnet
Escrow account management
Transaction memos for tracking

📊 Job States

State	Description	Client Actions	Freelancer Actions
0	Created	Wait	Upload Work
1	Work Submitted	Approve/Reject/Fraud	Wait
2	Approved	Download Files	-
3	Rejected/Refunded	-	-
4	Revision Requested	Wait	Re-upload Work

🧪 Testing

Example Test Flow

Create Test Job (as Client)

Freelancer: GBT2EHJKQAWW46QRJUY343YGEJDEPIU3U77S2R7ZXLP4NYQFUTGY3PRP
Amount: 10 XLM
Initial Payment: 20% (2 XLM)
Deadline: 7 days
Description: "Create a calculator app"

Submit Work (as Freelancer)

Upload HTML/JS calculator files
Preview shows watermarked version
Code execution displays calculator

Review & Approve (as Client)

View preview
Test "Approve & Pay" (8 XLM released)
Verify transaction on Stellar testnet

🐛 Troubleshooting

Server won't start

# Delete .next cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Try again
npm run dev

Jobs not showing up

Check data/jobs.json exists
Check console for errors
Verify wallet connection

File upload fails

Check file size (max 50MB)
Check file count (max 50 files)
Verify PINATA keys in .env.local

Stellar transaction fails

Verify wallet has enough XLM
Check testnet friendbot if needed
Verify ESCROW_PUBLIC_KEY is correct

🚢 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set environment variables in Vercel dashboard

Environment Variables for Production

Add all .env.local variables in your hosting platform:

NEXT_PUBLIC_STELLAR_NETWORK
NEXT_PUBLIC_CONTRACT_ID
ESCROW_SECRET_KEY
ESCROW_PUBLIC_KEY
PINATA_API_KEY
PINATA_SECRET_API_KEY

📦 Tech Stack

Framework: Next.js 14 (App Router, TypeScript)
Smart Contract: Soroban (Rust) on Stellar
Blockchain: Stellar SDK (Testnet/Mainnet)
Wallet: Freighter API
Storage: IPFS (Pinata SDK)
Encryption: Node.js Crypto (AES-256-CBC)
Watermarking: Jimp
File Upload: Multer + FormData
Code Execution: Child Process with timeout
Persistence: JSON file-based storage + On-chain contract state

🎯 Smart Contract vs Backend Escrow

Current Implementation (Hybrid)

Smart Contract: Escrow logic, fund custody, deadline enforcement
Backend: IPFS uploads, file encryption, preview generation, metadata

Why Both?

Smart Contract: Trustless, automatic, transparent, secure
Backend: Off-chain heavy operations (file processing, watermarking)

Migration Path

The app currently uses backend escrow but is designed to integrate with the smart contract:

Phase 1 (Current): Backend escrow for MVP testing
Phase 2 (Production): Smart contract escrow for trustless operation

See CONTRACT_GUIDE.md for integration instructions.

📝 License

MIT License - Feel free to use this project for learning or building your own freelance platform.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

If you encounter issues:

Check the troubleshooting section above
Review error messages in browser console
Check server logs in terminal
Verify environment variables in .env.local

🎉 Credits

Built with ❤️ on Stellar blockchain for secure, transparent freelancing.

Happy freelancing on the blockchain! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
app		app
components		components
config		config
contract		contract
data		data
lib		lib
utils		utils
.gitignore		.gitignore
README.md		README.md
build-contract.ps1		build-contract.ps1
deploy-contract.ps1		deploy-contract.ps1
instrumentation.ts		instrumentation.ts
next-env.d.ts		next-env.d.ts
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

AyushmanGupta21/FairDeal

Folders and files

Latest commit

History

Repository files navigation