A programmable payments and contract management platform for global freelancers and the clients who hire them, built on Arc with USDC settlement.
Submitted to the Circle Arc "Programmable Money" Hackathon — DeFi Track.
Cross-border freelance work has two layers of friction, and most products only address one of them.
Getting paid is slow, expensive, and opaque. PayPal does not support receiving payments in several major freelance-supply countries. Payoneer and Wise cost 2–5% in combined fees and FX spread, and settlement to a local bank account commonly takes 3–5 business days. Freelancers rarely know the real exchange rate they are getting until the money lands.
There is no enforceable link between what was agreed and what gets paid. Contract terms live in email threads. Milestones are tracked informally. A client can stall on paying for finished work. A freelancer can be asked to deliver more before being paid for what is done. Disputes happen because there is no shared, agreed-upon record both sides trust.
Existing crypto remittance tools address the first problem — move money fast — while leaving the second unsolved. Existing freelance marketplaces address the second but bolt it onto slow, expensive payment rails and lock both sides into ecosystem fees.
FreelancerOS addresses both layers together: the contract and milestone structure is what triggers the payment, and the payment settles in seconds because it runs on Arc.
FreelancerOS collapses the fragmented freelance workflow — contract in email, milestones in a spreadsheet, invoice in a Google Doc, payment via wire — into one product with on-chain guarantees.
A client and freelancer agree on a contract and its milestones inside the platform. The client funds each milestone into an on-chain USDC escrow up front. The moment a milestone is approved, payment is final and automatic — no separate payment step, no 3–5 day wait, no FX spread.
Circle's Programmable Wallets handle onboarding: no seed phrases, no browser extensions, no gas fees. Paymaster sponsors transactions so neither side ever sees a gas cost. The entire on-chain layer is invisible to the end user — it is a SaaS product that happens to run on a blockchain, not a wallet demo dressed as a product.
Milestone-based escrow — Projects are structured as one to ten milestones. Clients fund each milestone independently. Funds are locked in the EscrowManager contract until the milestone reaches a terminal state.
Automatic release — If a client fails to respond to a submitted deliverable within the configured review window, any address can trigger the release. Freelancers cannot be indefinitely blocked by client inaction.
Dispute resolution — Either party may raise a dispute. Both sides submit evidence during an open window. An arbitrator issues a resolution — full release, full refund, or a configured split. If no resolution is issued within the arbitration window, a default 50/50 split is enforced permissionlessly.
Mutual cancellation — Either party may initiate cancellation with a minimum response delay. All funded milestones are refunded to the client on confirmation.
Gas abstraction — Circle Paymaster sponsors gas for fund, deliver, approve, and release transactions. End users never hold or spend Arc's native token.
Non-custodial wallets — Circle Programmable Wallets give every user a self-custodied wallet through a standard email signup. No wallet extension required.
Stable settlement — All value is held and transferred in USDC. No price volatility exposure during an active project.
Cross-chain funding — Clients can fund escrows with USDC held on other chains via Circle's Cross-Chain Transfer Protocol. The protocol settles on Arc regardless of the source chain.
Immutable audit trail — Every state change emits an indexed on-chain event. The complete project lifecycle is reconstructable from contract logs independently of any backend database.
| Layer | Technology |
|---|---|
| Frontend | Next.js 14 (App Router), Tailwind CSS, shadcn/ui, TanStack Query |
| Backend | Fastify, Node.js, TypeScript |
| Database | Supabase, PostgreSQL, Row Level Security |
| Smart Contracts | Solidity, Hardhat |
| Blockchain | Circle Arc (EVM-compatible L1) |
| Settlement | USDC |
| Circle Services | Programmable Wallets, Paymaster, CCTP, Gateway |
| Auth | Supabase Auth, JWT |
| Realtime | Supabase Realtime |
| Monorepo | Turborepo, npm workspaces |
| Language | TypeScript throughout |
| Hosting | Vercel (frontend), Railway (backend) |
| Error tracking | Sentry |
| Analytics | PostHog |
FreelancerOS is a five-layer modular monolith monorepo. The frontend never communicates with the blockchain or with Circle directly — it only talks to the backend API and to Supabase Realtime for live updates. All sensitive logic — signing transactions, holding API keys, deciding when funds move — lives in the backend, which is the only layer with access to signing credentials.
Browser / Mobile Client
|
v
Next.js Frontend <-- Supabase Realtime (live updates)
(App Router, Vercel)
|
v
Fastify REST API + Background Worker
| |
| (chain listener,
| timeout scheduler)
_____|_____________________________
| | |
v v v
Supabase Circle API Arc Blockchain
Postgres Wallets (EVM-compatible)
Auth Paymaster
Realtime CCTP / Gateway
|
___________|___________
| | |
v v v
EscrowManager Dispute FeeVault
(holds USDC, Arbitrator (platform
owns state (isolated, fee sink)
machine) holds no
funds)
Contract layer — Three contracts, each with a single responsibility. EscrowManager is the only contract that holds user funds and owns the complete agreement lifecycle. DisputeArbitrator manages evidence and resolution in complete isolation from the funds. FeeVault is a passive accumulator for the 2.5% platform fee, collected only on successful releases.
Application layer — A Fastify modular monolith organized into domain modules: auth, projects, escrow, and wallets. A separate background worker process listens continuously for on-chain events and runs the milestone timeout check on a schedule. All state-changing endpoints require an idempotency key.
Data layer — Supabase PostgreSQL serves as a cache of on-chain events. The contracts are the authoritative source of truth. Row Level Security policies are enforced at the database layer, scoped to the involved users, independent of what the API layer does.
freelanceros/
├── .github/
│ └── workflows/
│ ├── ci-frontend.yml
│ ├── ci-backend.yml
│ ├── ci-contracts.yml
│ └── cd-production.yml
├── apps/
│ ├── backend/ # Fastify API + background worker
│ │ └── src/
│ │ ├── modules/
│ │ │ ├── auth/
│ │ │ ├── escrow/
│ │ │ ├── projects/
│ │ │ └── wallets/
│ │ └── shared/
│ └── frontend/ # Next.js App Router
│ └── src/
│ ├── app/
│ ├── components/
│ ├── hooks/
│ ├── lib/
│ └── modules/
├── packages/
│ ├── contracts/ # Hardhat project, Solidity contracts
│ └── core-types/ # Shared TypeScript types and schemas
├── supabase/
│ ├── migrations/
│ └── config.toml
├── docs/
├── .editorconfig
├── .env.example
├── .gitignore
├── docker-compose.yml
├── package.json
├── tsconfig.base.json
└── turbo.json
The project is under active development as a hackathon submission. All planning and architectural decisions are finalized. Implementation is in progress.
| Deliverable | Status |
|---|---|
| Product Requirements Document | Complete |
| Technical Architecture | Complete |
| UI/UX Specification | Complete |
| Smart Contract Blueprint | Complete |
| API Specification | Complete |
| Database Schema | Complete |
| Engineering Rules Handbook | Complete |
| Monorepo configuration | Complete |
| Root tooling (tsconfig, turbo, lint, editorconfig) | Complete |
| Smart contract implementation | In progress |
| Backend API implementation | Planned |
| Frontend implementation | Planned |
| Circle Wallet and Paymaster integration | Planned |
| CCTP cross-chain flow | Planned |
| Arc testnet deployment | Planned |
| End-to-end test suite | Planned |
Phase 1 — Foundation (Complete) Finalize all planning documents. Configure the monorepo, TypeScript, Turborepo, CI/CD pipeline scaffolding, and root tooling.
Phase 2 — Smart Contracts (In Progress)
Implement FeeVault, DisputeArbitrator, and EscrowManager in Solidity. Full test suite covering unit, integration, fuzz, and invariant tests. Deploy to Arc testnet.
Phase 3 — Backend API Implement the Fastify modular monolith. Configure Supabase schema, migrations, and Row Level Security policies. Integrate Circle Programmable Wallets, Paymaster, and webhook handling. Build the on-chain event indexer and milestone timeout worker.
Phase 4 — Frontend Build the Next.js App Router UI. Implement the client and freelancer dashboards, milestone management flows, dispute interface, and wallet onboarding. Role-aware routing: clients see fund and approve actions; freelancers see deliver actions.
Phase 5 — Integration and Testing End-to-end testing on Arc testnet with real USDC. Circle Paymaster configuration. CCTP cross-chain flow validation. Sentry error tracking. Full happy-path Playwright test covering signup through payment landing.
Phase 6 — Submission Live demo deployment. Video walkthrough. Hackathon submission.
Post-hackathon
- Full dispute arbitration system with an external arbitrator marketplace
- Streaming payments (continuous USDC release over time)
- On-chain reputation scores derived from payment history
- Multi-chain client support via CCTP expansion
- Agency and team accounts
- White-label escrow API for freelance marketplaces to embed directly
- Mainnet deployment after professional smart contract audit
Live demo and video walkthrough will be published before the submission deadline.
This project is proprietary and currently unlicensed.
Copyright (c) 2026 FreelancerOS. All rights reserved.