Hire work. Lock payment. Approve proof. Crypto freelance escrow with an AI delivery-review layer — payment is locked on-chain before work starts and released only after the delivery is reviewed.
Overview · Hackathon focus · User flow · Screens · Tech stack · Getting started · Smart contract
⚠️ Hackathon / demo project. It runs on the Sepolia testnet and the screenshots below use demo data. Do not use it with real funds or a main wallet.
Smart Jobs was built as a hackathon portfolio project to explore how a real freelance marketplace flow could combine Web3 payments, AI-assisted review, and automation into one product experience.
What we practiced and learned:
- Web3 product design — mapping a familiar freelance workflow to wallet actions, escrow states, and Sepolia testnet transactions.
- Smart contract development — writing and testing a Solidity escrow contract with fund, lock, release, refund, and payout paths.
- On-chain UX — connecting frontend state to wallet-native actions while keeping the buyer and freelancer roles understandable.
- AI automation — using OpenAI to review submitted work against the original brief and turn the result into a practical buyer recommendation.
- Content verification — exploring Swarm-based delivery evidence and client-side verified fetches.
- Full-stack delivery — combining Next.js, TypeScript, API routes, contract helpers, test coverage, and a demo-ready UI into one end-to-end prototype.
Hiring a freelancer with crypto has two trust gaps:
- The buyer doesn't want to pay before seeing the work.
- The freelancer doesn't want to do the work before knowing the money exists.
Smart Jobs closes both gaps with a single escrow flow:
- The buyer funds an escrow contract on-chain when the job is created — the money is provably locked, but held by the contract, not the platform.
- The freelancer accepts the funded job and binds it to their own wallet.
- On delivery, an AI reviewer scores the work against the brief and gives the buyer a clear recommendation.
- The buyer makes the final call — release the payment or refund — directly from the escrow.
Buyer funds escrow ──► Freelancer locks job ──► Work submitted ──► AI review ──► Buyer releases / refunds
on-chain on-chain + preview scored on-chain payout
Three layers do the work:
| Layer | Responsibility |
|---|---|
| 🔒 Smart contract (Solidity, Sepolia) | Secures the payment — fund, lock, request release, release, refund. |
| 🐝 Swarm verified fetch | Secures content integrity — delivery evidence can be fetched from any gateway and verified client-side. |
| 🤖 AI review (OpenAI) | Interprets the verified evidence and recommends a decision to the buyer. |
Smart Jobs verifies not only who gets paid, but also what content was actually reviewed.
The buyer writes a brief, attaches reference files, and sets a budget. The summary shows the ETH escrow target and the network fee before funding.
Only funded jobs appear on the board, so freelancers never start work that isn't backed by locked escrow. They accept the job and lock it to their wallet.
After the freelancer submits a watermarked preview and the source package, the AI scores the work against the brief and recommends an action. The buyer releases the escrow or refunds — and only then is the high-quality source unlocked.
When the buyer approves, the contract pays the freelancer and emits a release event. The flow ends with a clear payout confirmation.
| How it works | My jobs | Connect wallet |
|---|---|---|
 |
 |
 |
- On-chain escrow — fund, lock, request-release, release and refund handled by the
SmartJobsEscrowcontract on Sepolia. - Wallet-native flow — the freelancer accepts with their own wallet (
lockEscrow); only the buyer canrelease. - AI delivery review — every submission is scored against the brief with a verdict (
pass/needs revision/fail), a confidence score, matched requirements and open issues. - Gated source access — the buyer sees a watermarked preview; the original deliverable unlocks only after release.
- Swarm verified fetch — a standalone TS/JS library that fetches from any Swarm gateway and cryptographically verifies the content client-side, in the browser or Node, with no full node required.
- Demo-ready UX — a single, linear job lifecycle that's easy to walk through end to end.
- Framework: Next.js 16 (App Router, Turbopack) + React 19
- Styling: Tailwind CSS v4 (monospace brutalist theme, light/dark)
- Language: TypeScript, validated with Zod
- Contracts: Solidity + Hardhat 3 + Hardhat Ignition, viem
- AI: OpenAI API (delivery review)
- Storage: Swarm via
@ethersphere/bee-js+ a custom verified-fetch library - Network: Ethereum Sepolia testnet
- Node.js 20+ (developed on Node 22)
- npm
- A browser wallet (MetaMask) on the Sepolia network for the on-chain steps
- (Optional) an OpenAI API key to run live AI reviews
npm installCopy the example file and fill in your values:
cp .env.example .env.local# AI review (server-only — never expose client-side)
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini
# Sepolia deployment (use a funded throwaway deployer key, never a main wallet)
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
SEPOLIA_PRIVATE_KEY=0xYOUR_FUNDED_DEPLOYER_PRIVATE_KEY
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_API_KEY
# Filled after deploying SmartJobsEscrow
NEXT_PUBLIC_SMARTJOBS_ESCROW_ADDRESS=The app reads
NEXT_PUBLIC_SMARTJOBS_ESCROW_ADDRESSat boot. Restart the dev server after changing.env.local, or the frontend may keep using an old contract address.
npm run devOpen http://localhost:3000.
The job board starts empty — create a job from Post a Job, or POST seed jobs to the /jobs API to populate the demo.
The escrow logic lives in contracts/SmartJobsEscrow.sol.
| Action | Who | Effect |
|---|---|---|
createEscrow |
Buyer | Funds the escrow; funds held by the contract. |
lockEscrow |
Freelancer | Accepts a funded job from their own wallet. |
requestRelease |
Freelancer | Requests payout review. |
release |
Buyer | Pays the freelancer bidAmount, returns any remainder. |
refund |
Buyer | Refunds from Funded, Locked, ReleaseRequested or Disputed. |
Current Sepolia deployment: 0x81dfFC433dcE76dB8915726a476d97E19Af96557
(view on Sepolia Etherscan).
npm run contracts:compile # compile
npm run contracts:test # run contract tests
npm run contracts:deploy:sepolia:verify # deploy + verify on Sepolia| Script | Description |
|---|---|
npm run dev |
Start the Next.js dev server. |
npm run build / npm run start |
Production build / serve. |
npm run lint |
Lint the project. |
npm test |
Run the app test suite. |
npm run contracts:compile |
Compile the Solidity contracts. |
npm run contracts:test |
Run the contract tests. |
npm run contracts:deploy:sepolia |
Deploy SmartJobsEscrow to Sepolia. |
app/ Next.js App Router pages + API routes (/jobs, /api/review, /api/swarm, …)
components/ UI: job cards, review console, wallet connect, workflow stepper, …
lib/
contracts/ Escrow ABI + on-chain action helpers
review/ AI review prompt, schema, and service
swarm/ Swarm client + verified-fetch library
workflow/ Domain schema + in-memory job/escrow store
contracts/ SmartJobsEscrow.sol + deployment log
ignition/ Hardhat Ignition deployment modules
docs/screenshots/ Screenshots used in this README
This is a hackathon build for demonstration. It runs on the Sepolia testnet, the UI carries an optimistic confirmation gap (it records local state on a tx hash before the receipt is mined), and the screenshots use generated demo data. Verify any transaction on Sepolia Explorer before trusting the UI state. Do not use real funds.