Web3 Freelancer Escrow Protocol (Solana / Anchor)

A PDA-based, milestone-driven escrow smart contract for Web3 freelance marketplaces, built on Solana using Anchor.

This protocol enables trustless job creation, milestone funding in USDC, automatic payouts with platform fees, and refunds on timeout - without centralized custody.

---

Features

• PDA-based Escrow
• USDC (SPL Token v1) Milestone Funding
• Milestone Approval with Platform Fee
• Timeout Refunds
• Full End-to-End Anchor Tests
• Rust Code Coverage (llvm-cov)
• Security Linting (cargo audit)
• CI-ready GitHub Actions

---

Architecture Overview

Core Concepts

Concept	Description
Job PDA	Represents a freelance job
Milestone PDA	Escrows funds per milestone
Escrow ATA	Token account owned by Milestone PDA
Employer	Funds and approves milestones
Freelancer	Receives milestone payout
Platform	Receives protocol fee

---

Escrow Flow

1. Create Job
   Employer creates a Job PDA bound to their wallet.

2. Fund Milestone
   Employer deposits USDC into an Escrow ATA owned by a Milestone PDA.

3. Approve Milestone
   Funds are released to the Freelancer with a protocol fee deducted.

4. Cancel Milestone (Timeout)
   If the deadline passes without approval, the Employer can reclaim funds.

---

Tech Stack

• Solana
• Anchor v0.32
• Rust
• SPL Token v1 (USDC)
• TypeScript (Mocha + Chai)

Testing

Run Tests Locally

rm -rf test-ledger
anchor test

PDA-based programs must reset the local validator between runs.

---

Code Coverage

This project uses cargo llvm-cov to measure Rust smart contract coverage.

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov

anchor test
cargo llvm-cov report --html

Output:

target/llvm-cov/html/index.html

Target coverage: ≥ 80% (audit-grade)

---

Security

Dependency Auditing

We use cargo audit to scan Rust dependencies against RustSec advisories.

cargo install cargo-audit
cargo audit --severity high

• CI fails on HIGH / CRITICAL vulnerabilities
• Allowlisting supported via .cargo/audit.toml

---

Continuous Integration

GitHub Actions automatically run:

• anchor build
• anchor test
• cargo llvm-cov
• cargo audit

Local validator state is reset on every CI run to avoid PDA reuse.

---

Security Model

• No custodial wallets
• Funds always held by PDA-owned escrow accounts
• Explicit CPI program IDs
• No init_if_needed on critical state
• No admin backdoors

---

Audit Notes

• Inline PDA seeds (no lifetime bugs)
• Deterministic escrow logic
• Explicit system & token program passing
• No unsafe Rust

---

Roadmap

• Dispute DAO (milestone-level arbitration)
• Reputation System (Soulbound Token-2022)
• Reputation-weighted voting
• Frontend (Next.js + Wallet Adapter)

---

Contributing

Pull requests welcome.
All contributions must include tests.

---

License

MIT License