🤝 FairDeal

Decentralized Freelance Marketplace on Stellar

No middlemen. No trust required. Just code.

FairDeal is a trustless escrow platform built on the Stellar blockchain. Clients lock funds in a Soroban smart contract, freelancers deliver work securely via encrypted IPFS uploads, and payments are released automatically — all without a central authority.

🚀 Live Demo | 🎥 Demo Video | 📊 Test Results

🌟 Demo & Testing

🎥 Demo Video

📹 Watch 1-Minute Demo Video

Full walkthrough showing:

✅ Client wallet connection & job creation
✅ Smart contract escrow locking funds
✅ Freelancer work submission with encryption
✅ Watermarked preview system
✅ Payment release & file decryption
✅ IPFS file storage verification

🚀 Live Deployment

Production URL: https://fairdeall.vercel.app/

Deployed on Vercel with:

Serverless API routes
Edge functions for optimal performance
Automatic HTTPS & CDN
CI/CD from GitHub

📊 Test Results

All core functionalities have been tested and verified:

✅ Smart contract deployment and interaction
✅ Wallet integration with Freighter
✅ Job creation and escrow locking
✅ File encryption and IPFS upload
✅ Watermarked preview generation
✅ Payment release workflow
✅ Fraud flag tracking system

Test Screenshots

Screenshot 1: Test Output

Screenshot 2: Test Results

Screenshot 3: Integration Tests

📝 Note: Add your test screenshots showing 3+ tests passing in the docs/screenshots/ folder with names: test-1.png, test-2.png, test-3.png

📖 What is FairDeal?

Freelancing platforms today take significant cuts, hold funds, and act as gatekeepers. FairDeal removes all of that.

Here's how it works in plain English:

A client posts a job and locks the payment into a smart contract on the Stellar blockchain. The money is held by code — not a company.
A freelancer picks up the job and uploads their completed work. Files are automatically encrypted with AES-256 before being stored on IPFS (a decentralized file network).
The client reviews a watermarked preview of the work to verify quality without receiving the full file.
The client approves, and the smart contract instantly releases the funds to the freelancer. The original, unencrypted file becomes available for download.
If something's wrong, the client can request a revision or cancel for a full refund — all enforced by the contract, not a support ticket.

No platform fees. No payment delays. No disputes with a helpdesk.

✨ Features

🔒 Trustless Escrow via Smart Contract

Client funds are locked in a Soroban smart contract on Stellar — not held by FairDeal
Payments are released only when the client explicitly approves the work
Cancellations trigger an automatic on-chain refund to the client
All fund movements require a Freighter wallet signature — the platform can never move your money

🗂️ Encrypted IPFS File Storage

Submitted work is encrypted with AES-256-CBC before leaving the freelancer's machine
Encrypted files are pinned to IPFS via Pinata — no central server holds your files
Encryption keys are only released after client approval
Even if someone gets the IPFS link, they cannot read the file without the key

🖼️ Watermarked Preview System

When a freelancer submits, a watermarked preview is generated automatically
Clients can verify the work is real and complete before releasing payment
The clean, watermark-free file is only accessible after funds are released
Prevents unauthorized use of deliverables before payment

🌐 Freighter Wallet Integration

Connect your Stellar Freighter wallet in one click — no account creation needed
Wallet signatures are only required for fund movements (create, approve, cancel)
Submitting work and requesting revisions require zero wallet popups
Works on Stellar Testnet for safe experimentation

📋 Full Job Lifecycle Management

The smart contract enforces a complete, tamper-proof workflow:

Created → Submitted → Approved ✅
                   ↘ Revision Requested 🔄
                   ↘ Rejected ❌
                   ↘ Fraud Flagged 🚩

🛡️ Fraud Protection

Clients can raise fraud flags against freelancers on-chain
Fraud flag counts are tracked per freelancer address in the contract
Reputation is transparent, immutable, and publicly verifiable

🚀 Deployed Smart Contract

The FairDeal escrow contract is live on Stellar Testnet.


Contract ID	`CBONHPWFT7D2USWDGC5G55LJNBCRRTN4YQE6O6CFJA3RROIQ4UIWUFDM`
Network	Stellar Testnet
Language	Rust (Soroban SDK)
Status	✅ Active

🔗 View on Stellar Expert
🔗 Interact on Stellar Lab

Contract Functions

Function	What it does	Requires Wallet?
`create_job`	Locks client funds in escrow, creates the job	✅ Yes
`submit_work`	Records the IPFS CID of submitted work on-chain	❌ No
`approve_work`	Releases escrowed funds to the freelancer	✅ Yes
`cancel_deal`	Refunds the client and cancels the job	✅ Yes
`request_revision`	Marks job for revision without touching funds	❌ No
`raise_fraud_flag`	Records a fraud flag against a freelancer	✅ Yes
`get_job`	Returns full job details by ID	❌ No
`get_job_count`	Returns total number of jobs created	❌ No

🏗️ Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), React 18, TypeScript
Blockchain	Stellar Testnet, Soroban Smart Contracts (Rust)
Wallet	Stellar Freighter
File Storage	IPFS via Pinata
Encryption	AES-256-CBC (Node.js `crypto`)
Watermarking	Jimp
Stellar SDK	`@stellar/stellar-sdk` v14
Deployment	Vercel (Serverless)

📁 Project Structure

FairDeal(stellar)/
├── app/                        # Next.js App Router pages & API routes
│   ├── api/
│   │   ├── jobs/               # Create, fetch, and manage jobs
│   │   ├── ipfs/               # IPFS upload & CID tracking
│   │   ├── decrypt-file/       # Decrypt & deliver files post-approval
│   │   ├── escrow-address/     # Escrow account helper
│   │   └── freelancers/        # Fraud flag endpoints
│   ├── create-job/             # Client: post a new job
│   ├── jobs/[jobId]/           # Job detail & action page
│   ├── submit-work/[jobId]/    # Freelancer: upload work
│   ├── login/                  # Wallet connect page
│   └── profile/                # User profile page
├── contract/
│   ├── src/lib.rs              # Soroban smart contract (Rust)
│   └── Cargo.toml
├── components/
│   └── WalletProvider.tsx      # Freighter wallet context
├── utils/
│   ├── contract-utils.ts       # Contract interaction helpers
│   └── stellar-utils.ts        # Stellar SDK utilities
├── lib/
│   ├── ipfs-utils.ts           # Pinata upload/download
│   ├── stellar-utils.ts        # Server-side Stellar helpers
│   └── storage.ts              # Data storage abstraction
└── data/                       # Local job & IPFS metadata storage

⚡ Getting Started

What you'll need

Node.js 18+
Rust & Cargo
Stellar CLI
Freighter Wallet browser extension
A free Pinata account for IPFS

1. Clone & install

git clone https://github.com/Debjanimandal/FairDeal.git
cd FairDeal
npm install

2. Set up environment variables

Create a .env.local file in the root:

# Stellar
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_CONTRACT_ID=CBONHPWFT7D2USWDGC5G55LJNBCRRTN4YQE6O6CFJA3RROIQ4UIWUFDM

# Escrow account (Stellar keypair for the platform escrow)
ESCROW_SECRET_KEY=your_escrow_secret_key
ESCROW_PUBLIC_KEY=your_escrow_public_key

# IPFS via Pinata
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_API_KEY=your_pinata_secret

💡 Tip: Get free Pinata API keys at pinata.cloud. For the escrow key, generate a Stellar keypair at laboratory.stellar.org and fund it on Testnet.

3. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

4. (Optional) Build & deploy your own contract

cd contract
cargo build --target wasm32-unknown-unknown --release
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/fairdeal_escrow.wasm
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/fairdeal_escrow.optimized.wasm \
  --source-account default \
  --network testnet

Then update NEXT_PUBLIC_CONTRACT_ID in .env.local with your new contract address.

💼 How to Use

As a Client

Open the app and click Connect Wallet — approve the Freighter popup
Click Post a Job, fill in the details and payment amount
Confirm the transaction — your XLM is now locked in the smart contract
Wait for a freelancer to submit work
Review the watermarked preview
Approve to pay and unlock the file, Request Revision if changes are needed, or Cancel for a refund

As a Freelancer

Connect Wallet with Freighter
Browse open jobs and pick one
Upload your work on the Submit Work page — files are encrypted automatically
Wait for the client to review your watermarked preview
Once approved, payment lands in your Stellar wallet automatically

🔐 Security Model

Client deposits payment
        ↓
Smart Contract holds funds (trustless)
        ↓
Freelancer uploads work
        ↓  AES-256-CBC encryption
IPFS stores encrypted file (Pinata)
        ↓
Client sees watermarked preview
        ↓
Client approves → Contract releases funds
        ↓
Decryption key released → Client downloads clean file

No single point of failure — Funds are on-chain, files are on IPFS
Platform cannot steal funds — Smart contract enforces all rules
Files are private — Encrypted before upload; key only released on approval

📝 Environment Variables

Variable	Description	Required
`NEXT_PUBLIC_STELLAR_NETWORK`	`testnet` or `mainnet`	✅
`NEXT_PUBLIC_CONTRACT_ID`	Deployed Soroban contract address	✅
`ESCROW_SECRET_KEY`	Stellar secret key for platform escrow account	✅
`ESCROW_PUBLIC_KEY`	Stellar public key for platform escrow account	✅
`PINATA_API_KEY`	Pinata API key	✅
`PINATA_SECRET_API_KEY`	Pinata secret API key	✅

🚧 Roadmap

USDC payment support (Stellar anchor assets)
On-chain dispute resolution with arbitration
Freelancer reputation & review system
Multi-milestone payment schedules
Mainnet deployment
Mobile app (React Native)

🤝 Contributing

Contributions are welcome!

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -m 'Add your feature'
Push to the branch: git push origin feature/your-feature
Open a Pull Request

📄 License

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

🙏 Acknowledgments

Stellar Development Foundation — Blockchain infrastructure
Soroban — Smart contract platform for Stellar
Pinata — IPFS pinning service
Freighter — Stellar browser wallet

Built with ❤️ for the Stellar ecosystem

Report Bug · Request Feature · View Docs

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
app		app
components		components
config		config
contract		contract
data		data
docs		docs
lib		lib
public		public
utils		utils
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
build-contract.ps1		build-contract.ps1
deploy-contract.ps1		deploy-contract.ps1
deployment-output.txt		deployment-output.txt
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
react-three-fiber.d.ts		react-three-fiber.d.ts
test-contract.js		test-contract.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🤝 FairDeal

Decentralized Freelance Marketplace on Stellar

🌟 Demo & Testing

🎥 Demo Video

🚀 Live Deployment

📊 Test Results

Test Screenshots

📖 What is FairDeal?

✨ Features

🔒 Trustless Escrow via Smart Contract

🗂️ Encrypted IPFS File Storage

🖼️ Watermarked Preview System

🌐 Freighter Wallet Integration

📋 Full Job Lifecycle Management

🛡️ Fraud Protection

🚀 Deployed Smart Contract

Contract Functions

🏗️ Tech Stack

📁 Project Structure

⚡ Getting Started

What you'll need

1. Clone & install

2. Set up environment variables

3. Run the development server

4. (Optional) Build & deploy your own contract

💼 How to Use

As a Client

As a Freelancer

🔐 Security Model

📝 Environment Variables

🚧 Roadmap

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages