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.
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.
- 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
- 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
- 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
- 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
The smart contract enforces a complete, tamper-proof workflow:
Created → Submitted → Approved ✅
↘ Revision Requested 🔄
↘ Rejected ❌
The FairDeal escrow contract is live on Stellar Testnet.
| Network | Stellar Testnet |
| Language | Rust (Soroban SDK) |
| Deploy Tx | 286021c7... |
🔗 View on Stellar Expert
🔗 Interact on Stellar Lab
| 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 |
flag_fraud |
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 |
| 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 |
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 # JSON file-based data store
└── data/ # Local job & IPFS metadata storage
- Node.js 18+
- Rust & Cargo
- Stellar CLI
- Freighter Wallet browser extension
- A free Pinata account for IPFS
git clone https://github.com/yourusername/fairdeal.git
cd fairdeal
npm installCreate a .env.local file in the root:
# Stellar
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_CONTRACT_ID=your_ContractID
# Escrow account (Stellar keypair for the platform escrow)
ESCROW_SECRET_KEY=your_escrow_secret_key
# IPFS via Pinata
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_API_KEY=your_pinata_secret
PINATA_JWT=your_pinata_jwt💡 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.
npm run devOpen http://localhost:3000 in your browser.
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 testnetThen update NEXT_PUBLIC_CONTRACT_ID in .env.local with your new contract address.
- 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
- 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
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
| 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 | ✅ |
PINATA_API_KEY |
Pinata API key | ✅ |
PINATA_SECRET_API_KEY |
Pinata secret API key | ✅ |
PINATA_JWT |
Pinata JWT for uploads | ✅ |
- USDC payment support (Stellar anchor assets)
- On-chain dispute resolution with arbitration
- Freelancer reputation & review system
- Multi-milestone payment schedules
- Mainnet deployment
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
- Stellar Development Foundation — Blockchain infrastructure
- Soroban — Smart contract platform for Stellar
- Pinata — IPFS pinning service
- Freighter — Stellar browser wallet