SecureFlow

Trustless Freelancer Escrow on Stellar

A decentralized freelancer marketplace built on Stellar (Soroban) that provides secure, trustless escrow services for freelance work agreements.

Live Demo · Documentation · Contributing · Open Issues

---

🏆 Hackathon Recognition

SecureFlow was built for and won the Stellar Scaffold Hackathon — a global competition challenging builders to ship production-grade dApps using the Stellar Scaffold CLI toolchain on Soroban.

The project stood out for its complete end-to-end implementation: a Soroban smart contract handling real on-chain escrow logic, a React frontend auto-wired to contract clients via stellar-scaffold, and a gasless relay backend that makes blockchain interactions seamless for users.

"SecureFlow demonstrates exactly what Scaffold is meant to enable — a full-stack Stellar dApp with contract, client, and UI wired together from day one." — Hackathon Judges

---

What is SecureFlow?

SecureFlow solves the freelance trust problem. When you hire someone online today, you either pay upfront (and risk getting nothing) or pay after (and the freelancer risks getting stiffed). SecureFlow puts funds into a Soroban smart contract that neither party controls — it releases payment automatically when milestones are approved, or triggers dispute resolution when they're not.

Key properties:

• Trustless — no intermediary holds funds, the contract does
• Transparent — all state is on-chain and auditable
• Fair — multi-arbiter dispute resolution with on-chain reputation
• Fast & cheap — Stellar settles in ~5 seconds for fractions of a cent

---

Features

Core

Feature	Description
Smart Contract Escrow	Funds locked in Soroban until milestone approval
Milestone Payments	Break projects into chunks; each unlocks individually
Open Job Marketplace	Freelancers browse and apply; clients pick the best fit
Direct Contracts	Skip the marketplace and contract a known freelancer
Dispute Resolution	Multi-arbiter voting with admin oversight
Reputation System	On-chain star ratings and badge tiers (Beginner → Expert)
Multi-Token Support	Native XLM or any whitelisted Stellar asset
Gasless Relay	Backend relay lets users transact without holding XLM
Rating Notifications	Real-time notification center for ratings and milestone events

Security

• All write operations require Stellar account authorization
• Token whitelist — only approved assets accepted
• Arbiter authorization gating
• Configurable platform fees sent to designated collector
• Emergency deadline-based refunds built into contract

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                      SecureFlow                         │
├─────────────┬──────────────────┬────────────────────────┤
│  Frontend   │     Backend      │   Soroban Contract     │
│  React 19   │  Express (Node)  │   Rust / Soroban SDK   │
│  Vite       │  Supabase        │                        │
│  Zustand    │  Groq AI         │   Admin Module         │
│  Radix UI   │  Gasless Relay   │   Escrow Core          │
│  shadcn/ui  │                  │   Marketplace          │
│             │                  │   Work Lifecycle       │
│             │                  │   Refund System        │
│             │                  │   Dispute Resolution   │
└─────────────┴──────────────────┴────────────────────────┘
         ↓                ↓                   ↓
    Stellar Wallets Kit        Stellar SDK / Horizon
                    ↓
             Stellar Network

Contract Modules

contracts/secureflow/src/
├── admin.rs              # Platform config, pause, fee management
├── escrow_core.rs        # Core data model and state machine
├── escrow_management.rs  # Escrow creation and lifecycle
├── marketplace.rs        # Job listings and applications
├── work_lifecycle.rs     # Milestone submit/approve/reject
├── refund_system.rs      # Refund and emergency mechanisms
├── storage_types.rs      # All on-chain data structures
└── lib.rs                # Contract entrypoint

---

Tech Stack

Layer	Technology
Smart Contract	Rust, Soroban SDK
Frontend Framework	React 19, TypeScript, Vite
UI	Tailwind CSS, Radix UI, shadcn/ui
State	Zustand
Routing	React Router v7
Forms	React Hook Form + Zod
Backend	Node.js, Express, Supabase
AI	Groq (cover letter analysis)
Wallet	@creit.tech/stellar-wallets-kit
Toolchain	Stellar Scaffold CLI
CI/CD	GitHub Actions, Vercel, Railway

---

Getting Started

Prerequisites

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32v1-none

# Node.js 22+
node --version  # v22 or higher

# Stellar CLI + Scaffold plugin
cargo install stellar-scaffold-cli

Local Development

# 1. Clone
git clone https://github.com/HyperSafeD/SecureFlow-scaffold.git
cd SecureFlow-scaffold

# 2. Install frontend dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env — see Environment Variables section below

# 4. Start Stellar local network (Docker required)
docker run --rm -p 8000:8000 stellar/quickstart:testing --local

# 5. Build contract and auto-generate TypeScript clients
stellar scaffold build --build-clients

# 6. Start frontend
npm run dev
# → http://localhost:5173

# 7. (Optional) Start backend
cd backend && npm install && npm run dev

Environment Variables

Frontend (.env)

VITE_STELLAR_NETWORK=testnet           # local | testnet | mainnet
VITE_SECUREFLOW_CONTRACT_ID=           # deployed contract address
VITE_OWNER_ADDRESS=                    # admin stellar address
VITE_API_URL=http://localhost:3001     # backend URL

Backend (backend/.env)

SUPABASE_URL=
SUPABASE_SERVICE_KEY=
GROQ_API_KEY=
PORT=3001

Building for Production

npm run build       # frontend → dist/
cd backend && npm run build   # backend → backend/dist/

---

How It Works

The Full Flow

Client creates job  →  Funds locked in escrow contract
Freelancers apply   →  Client selects best applicant
Freelancer starts   →  start_work() changes status to InProgress
Milestone done      →  submit_milestone() notifies client
Client reviews      →  approve (pay) / reject (revise) / dispute
On dispute          →  Arbiters vote → Admin resolves → XLM released
All done            →  Contract marked Completed, reputation updated

Escrow State Machine

Pending ──start_work──▶ InProgress ──all approved──▶ Released
   │                        │
refund()              dispute raised
   │                        │
   ▼                        ▼
Refunded               Disputed ──admin resolves──▶ Resolved

Milestone States

NotStarted → Submitted → Approved (payment released)
Submitted → Rejected → (freelancer resubmits)
Submitted → Disputed → Resolved

---

Smart Contract API

Core Functions (click to expand)

// Create a new escrow job
pub fn create_escrow(
    depositor: Address,
    beneficiary: Option<Address>,   // None = open marketplace job
    arbiters: Vec<Address>,
    required_confirmations: u32,
    milestones: Vec<(i128, String)>,
    token: Option<Address>,         // None = native XLM
    total_amount: i128,
    duration: u32,
    project_title: String,
    project_description: String,
) -> Result<u32, Error>

// Marketplace
pub fn apply_to_job(escrow_id: u32, cover_letter: String, proposed_timeline: u32, freelancer: Address) -> Result<(), Error>
pub fn accept_freelancer(escrow_id: u32, freelancer: Address, depositor: Address) -> Result<(), Error>

// Work lifecycle
pub fn start_work(escrow_id: u32, beneficiary: Address) -> Result<(), Error>
pub fn submit_milestone(escrow_id: u32, milestone_index: u32, description: String, beneficiary: Address) -> Result<(), Error>
pub fn approve_milestone(escrow_id: u32, milestone_index: u32, depositor: Address) -> Result<(), Error>
pub fn reject_milestone(escrow_id: u32, milestone_index: u32, reason: String, depositor: Address) -> Result<(), Error>

// Refunds
pub fn refund_escrow(escrow_id: u32, depositor: Address) -> Result<(), Error>
pub fn emergency_refund_after_deadline(escrow_id: u32, depositor: Address) -> Result<(), Error>

// Reputation
pub fn rate_freelancer(escrow_id: u32, rating: u32, review: String, depositor: Address) -> Result<(), Error>

---

Project Structure

SecureFlow-scaffold/
├── contracts/
│   └── secureflow/           # Soroban smart contract (Rust)
│       └── src/
├── src/                      # React frontend
│   ├── components/
│   │   ├── admin/
│   │   ├── approvals/
│   │   ├── chat/
│   │   ├── create/
│   │   ├── dashboard/
│   │   ├── jobs/
│   │   └── ui/               # shadcn/ui components
│   ├── contexts/             # Web3 + wallet context
│   ├── contracts/            # Auto-generated Soroban clients
│   ├── hooks/
│   ├── lib/                  # API client, utils
│   ├── pages/
│   └── providers/
├── backend/                  # Express API + Supabase
│   └── src/
│       ├── routes/
│       ├── lib/              # Supabase, Groq clients
│       └── middleware/
├── packages/                 # npm workspace packages
├── supabase/                 # DB migrations
├── environments.toml         # Stellar network configs
├── Cargo.toml
└── package.json

---

Contributing

SecureFlow is an open-source project growing beyond the hackathon. We welcome contributors at every level — Rust contract devs, React engineers, and everything in between.

Getting Involved

1. Check the open issues — they're labelled and scoped to be tackled solo
2. Fork the repo and create a branch: git checkout -b feat/your-feature
3. Make your changes (run npm run lint and npm test before pushing)
4. Open a PR against main

Labels

Label	Meaning
good first issue	Small, well-scoped — great entry point
contract	Soroban / Rust smart contract work
frontend	React / TypeScript UI work
backend	Node.js / Express / Supabase work
security	Security-critical changes
enhancement	New features
bug	Something broken
performance	Speed / cost improvements
testing	Test coverage
documentation	Docs and guides

Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting.

---

Deployment

Service	Purpose	Status
Vercel	Frontend hosting
Railway	Backend API	Active
Stellar Testnet	Smart contract	Active

---

License

MIT — see LICENSE.

---

🏆 Stellar Scaffold Hackathon Winner

Built with Rust, React, and the Stellar ecosystem.
Open source under HyperSafeD — contributions welcome.

Stellar · Soroban Docs · Scaffold CLI · HyperSafeD