Yield-X - Yield-Powered Freelance Escrow on Stellar

🎯 The Problem

In traditional freelance platforms and escrow services, client funds sit completely idle during project execution. Whether it's a 1-month or 6-month project, the money locked in escrow earns zero interest while waiting for milestone approvals.

Real-World Impact

$10,000 locked for 3 months → $0 earned in traditional escrow
Lost opportunity cost → Clients could have earned 5% APY elsewhere
Inefficient capital allocation → Billions locked globally earning nothing
Trust barriers → Freelancers worry about payment delays while client funds earn nothing

This creates a lose-lose scenario where both parties sacrifice earning potential for security.

💡 The Solution: Yield-X

Yield-X is a modular, yield-generating escrow protocol on the Stellar blockchain that applications can plug into to automatically invest escrowed funds into Real World Assets (RWA) while maintaining full security and trustless execution.

How Yield-X Solves This

✅ Automatic Yield Generation - Escrowed funds are automatically deposited into OUSG (tokenized US Treasury bonds) earning 5% APY
✅ Win-Win Model - Freelancers receive full payment + clients keep 100% of yield earned
✅ Zero Trust Required - Smart contracts enforce milestone-based payments with blockchain security
✅ Instant Settlement - No bank delays, near-zero transaction fees
✅ Multi-Currency Support - Pay in XLM, USDC, or fiat tokens (INR, KES, NGN)

The Yield Advantage

Example: You create a 3-month project worth $10,000 USDC

Traditional Escrow	Yield-X
$10,000 locked, earning $0	$10,000 → OUSG earning 5% APY
After 3 months: $0 interest	After 3 months: $125 yield earned
Freelancer gets: $10,000	Freelancer gets: $10,000
Client gets: $0	Client keeps: $125

Everyone wins! Freelancers get paid securely and on time, clients earn passive income while waiting.

🔌 Use as a Plugin in Your App

Yield-X is designed as a protocol you can plug into any application (web, mobile, backend) to escrow funds, earn yield, and release payments trustlessly. Below are two simple integration paths.

Option A: React integration (hooks)

If you're building with React, you can wire directly into the existing hooks and helpers.

Connect Freighter in your app startup

// frontend/src/hooks/useWallet.ts
const { address, connect } = useWallet();
useEffect(() => {
  if (!address) connect();
}, [address]);

Import contract hooks and call protocol methods

// Example: create a job and start yield
import { useContracts } from "./src/hooks/useContracts";

export function CreateJobButton() {
  const {
    createJob,
    releasePayment,
    requestWithdrawPrincipal,
    claimYield,
    getYieldClaimTimeRemaining,
  } = useContracts();

  async function handleCreate() {
    const tx = await createJob({
      freelancer: "GAUCMH7KIOUZBPA5K4I7HMZV63XHSD36J7E5DH7TJXACWNWAROUMPRZZ",
      amount: "10000000", // 10 XLM (7-decimal)
      milestones: 3,
      asset: "XLM",
    });
    // tx.id can be shown in a success modal
  }

  async function handleRelease(milestoneIndex: number) {
    await releasePayment({ jobId: "<job_id_bytes32>", milestoneIndex });
  }

  async function handleTwoPhaseWithdraw() {
    await requestWithdrawPrincipal({ jobId: "<job_id_bytes32>" });
    // Poll lockup until 0, then claim yield
    const remaining = await getYieldClaimTimeRemaining({
      jobId: "<job_id_bytes32>",
    });
    if (remaining === 0) await claimYield({ jobId: "<job_id_bytes32>" });
  }

  return (
    <div>
      <button onClick={handleCreate}>Create Job</button>
      <button onClick={() => handleRelease(0)}>Release Milestone 1</button>
      <button onClick={handleTwoPhaseWithdraw}>Claim Yield</button>
    </div>
  );
}

Listen for yield events and persist state
- The UI dispatches a custom yieldPending event when the lockup starts.
- Persist using localStorage keys (e.g., yieldx_pending_yield) for countdown continuity.

See frontend/src/hooks/useContracts.ts and frontend/src/lib/contracts.ts for ready-to-use wrappers.

Option B: Backend or non-React integration

Call the Soroban contracts directly from your server or CLI.

Configure contract addresses
- Escrow Core: CCK5VICBIWM245Q5TLB2FXCJYKVPTLIIB4HO2QPESG7TOF3ZPCZRKCVA
- Yield Harvester: CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC
- Liquidity Router: CDTDGS22DS33NPH2GNE4UWPYEJD57MJN6DTPDZXLD46SIKNNCYNKNA3A

Invoke contract methods

# Create job (Escrow Core)
stellar contract invoke \
   --id CCK5VICBIWM245Q5TLB2FXCJYKVPTLIIB4HO2QPESG7TOF3ZPCZRKCVA \
   --source <CLIENT_ADDRESS> --network testnet -- create_job \
   --arg freelancer:<ADDR> --arg amount:10000000 --arg milestones:3 --arg asset:XLM

# Release payment for milestone
stellar contract invoke \
   --id CCK5VICBIWM245Q5TLB2FXCJYKVPTLIIB4HO2QPESG7TOF3ZPCZRKCVA \
   --source <CLIENT_ADDRESS> --network testnet -- release_payment \
   --arg job_id:<BYTES32> --arg milestone_index:0

# Two-phase yield claim (Yield Harvester)
stellar contract invoke \
   --id CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC \
   --source <CLIENT_ADDRESS> --network testnet -- request_withdraw_principal \
   --arg job_id:<BYTES32>

# After lockup expiry
stellar contract invoke \
   --id CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC \
   --source <CLIENT_ADDRESS> --network testnet -- claim_yield \
   --arg job_id:<BYTES32>

Optional: Multi-currency deposits
- Swap into the escrow asset via the Liquidity Router before create_job.
- Example: swap(from_asset, to_asset, amount) to convert INR/KES/NGN → USDC/XLM.

Integration checklist:

Connect wallet or signing key management
Provide freelancer address, amount, milestones, and asset
Handle two-phase withdrawals (principal now, yield after lockup)
Persist job and yield state for UX continuity
✅ Automatic Yield Generation - Escrowed funds are automatically deposited into OUSG (tokenized US Treasury bonds) earning 5% APY
✅ Win-Win Model - Freelancers receive full payment + clients keep 100% of yield earned
✅ Zero Trust Required - Smart contracts enforce milestone-based payments with blockchain security
✅ Instant Settlement - No bank delays, near-zero transaction fees
✅ Multi-Currency Support - Pay in XLM, USDC, or fiat tokens (INR, KES, NGN)

The Yield Advantage

Example: You create a 3-month project worth $10,000 USDC

Traditional Escrow	Yield-X
$10,000 locked, earning $0	$10,000 → OUSG earning 5% APY
After 3 months: $0 interest	After 3 months: $125 yield earned
Freelancer gets: $10,000	Freelancer gets: $10,000
Client gets: $0	Client keeps: $125

Everyone wins! Freelancers get paid securely and on time, clients earn passive income while waiting.

🏗️ Implementation Architecture

Yield-X uses a three-layer smart contract system on Stellar/Soroban:

┌─────────────────────────────────────────────────────────────┐
│                      CLIENT CREATES JOB                      │
│          (e.g., $10,000 USDC, 3 milestones, 3 months)       │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
         ┌────────────────────────────────────┐
         │    1. ESCROW CORE CONTRACT         │
         │  - Validates job parameters        │
         │  - Creates milestone structure     │
         │  - Transfers USDC from client      │
         │  - Calls Yield Harvester           │
         └────────────────────────────────────┘
                             │
                             ▼
         ┌────────────────────────────────────┐
         │   2. YIELD HARVESTER CONTRACT      │
         │  - Receives $10,000 USDC           │
         │  - Swaps USDC → OUSG via DEX       │
         │  - Tracks principal + yield        │
         │  - Earns 5% APY automatically      │
         └────────────────────────────────────┘
                             │
                             ▼
         ┌────────────────────────────────────┐
         │   3. LIQUIDITY ROUTER CONTRACT     │
         │  - Enables multi-currency swaps    │
         │  - Uses Stellar DEX liquidity      │
         │  - Supports XLM, USDC, fiat tokens │
         └────────────────────────────────────┘

Contract Details

1. Escrow Core (`escrow_core`)

Purpose: Manages job lifecycle, milestone tracking, and payment releases
Key Functions:
- create_job() - Creates job with milestones, transfers funds to Yield Harvester
- approve_milestone() - Client approves completed work
- release_payment() - Triggers payment from Yield Harvester to freelancer
- cancel_job() - Refunds client if project cancelled
Contract Address: CCK5VICBIWM245Q5TLB2FXCJYKVPTLIIB4HO2QPESG7TOF3ZPCZRKCVA

2. RWA Yield Harvester (`rwa_yield_harvester`)

Purpose: Manages yield generation via OUSG Real World Asset tokens
Key Functions:
- track_deposit() - Records principal amount deposited
- withdraw_to() - Withdraws principal + yield, sends to freelancer and client
- request_withdraw_principal() - Initiates 30-second lockup for yield claim
- claim_yield() - Transfers accrued yield to client after lockup
Yield Calculation: 5% APY with daily compounding
Contract Address: CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC

3. Liquidity Router (`liquidity_router`)

Purpose: Multi-currency support via Stellar DEX integration
Key Functions:
- swap() - Converts between XLM, USDC, and other assets
- get_best_path() - Finds optimal swap route
Contract Address: CDTDGS22DS33NPH2GNE4UWPYEJD57MJN6DTPDZXLD46SIKNNCYNKNA3A

🔄 Complete Payment Flow

Phase 1: Job Creation & Deposit

1. Client creates job via UI (e.g., $10,000 USDC, 3 milestones)
2. Client signs transaction in Freighter Wallet
3. Escrow Core contract executes:
   - Validates inputs (client, freelancer, amount, asset)
   - Creates job metadata with 3 milestones ($3,333 each)
   - Calls token.transfer() via env.invoke_contract()
   - Transfers $10,000 USDC: Client → Yield Harvester
4. Yield Harvester receives funds:
   - Records principal: $10,000
   - Swaps USDC → OUSG
   - Begins earning 5% APY

Phase 2: Milestone Approval & Payment

1. Freelancer submits proof of work for Milestone 1
2. Client approves milestone via UI
3. Client clicks "Release Payment"
4. Escrow Core executes:
   - Validates milestone is approved
   - Calls YieldHarvester.withdraw_to()
   - Passes: principal ($3,333), freelancer address, client address
5. Yield Harvester calculates:
   - Principal: $3,333
   - Accrued yield (prorated): ~$33.33 (1% for 1 month)
   - Total: $3,366.33
6. Transfers execute:
   - Freelancer receives: $3,333 (principal)
   - Client receives: $33.33 (yield earned)
7. Remaining balance continues earning yield

🛠️ Technical Implementation

Frontend (React + TypeScript)

Tech Stack:

React 18 with TypeScript for type safety
Vite as build tool for fast development
Tailwind CSS for modern styling
Framer Motion for smooth animations
React Router DOM for navigation
Freighter Wallet integration for Stellar transactions

Key Components:

ClientDashboard.tsx - Job management, yield tracking, milestone approval
FreelancerDashboard.tsx - Job browsing, proposal submission, payment history
CreateJob.tsx - Multi-step job creation form with asset selection
JobDetails.tsx - Real-time milestone tracking and payment releases

Contract Integration:

lib/contracts.ts - Contract function wrappers (create job, release payment, claim yield)
hooks/useContracts.ts - React hooks for contract interactions
config/contracts.ts - Contract addresses and network configuration

Smart Contracts (Rust + Soroban)

Language: Rust
Platform: Stellar Soroban (Stellar's smart contract platform)

Contract Structure:

// escrow_core/src/lib.rs
pub struct Job {
    pub job_id: BytesN<32>,
    pub client: Address,
    pub freelancer: Address,
    pub total_amount: i128,
    pub asset_address: Address,
    pub milestones: Vec<Milestone>,
    pub status: JobStatus,
    pub yield_earned: i128,
}

pub struct Milestone {
    pub milestone_id: u32,
    pub amount: i128,
    pub proof_url: String,
    pub status: MilestoneStatus, // Pending, Approved, Paid
}

🚧 Technical Challenges & Solutions

Challenge 1: Token Transfer Authorization

Problem: Initial implementation used TokenClient::transfer() which failed silently because client signature didn't authorize token transfers.

Solution: Switched to env.invoke_contract() which properly handles authorization chains:

// BEFORE (Failed)
let token_client = token::TokenClient::new(&env, &asset_address);
token_client.transfer(&client, &yield_harvester, &total_amount);

// AFTER (Fixed)
let mut transfer_args = Vec::new(&env);
transfer_args.push_back(client.clone().into_val(&env));
transfer_args.push_back(yield_harvester.clone().into_val(&env));
transfer_args.push_back(total_amount.into_val(&env));
env.invoke_contract::<()>(
    &asset_address,
    &Symbol::new(&env, "transfer"),
    transfer_args,
);

Reference: PAYMENT_FLOW_FIX.md

Challenge 2: Yield Claim Lockup Period

Problem: OUSG redemptions require a 30-second lockup period for RWA compliance.

Solution: Implemented two-phase withdrawal:

request_withdraw_principal() - Releases principal immediately, locks yield for 30 seconds
claim_yield() - Transfers yield after lockup expires

Reference: YIELD_CLAIM_INTEGRATION.md

Challenge 3: Multi-Currency Support

Problem: Needed to support XLM, USDC, and future fiat tokens without redeploying contracts.

Solution: Liquidity Router contract with dynamic routing via Stellar DEX:

pub fn swap(
    env: &Env,
    from_asset: Address,
    to_asset: Address,
    amount: i128,
    min_output: i128,
) -> i128

🚀 Getting Started

Prerequisites

Freighter Wallet browser extension
Stellar testnet account with XLM (Get from Friendbot)
Node.js 18+ and npm

Installation

# Clone repository
git clone https://github.com/sukrit-89/Flowpay.git
cd Flowpay

# Install frontend dependencies
cd frontend
npm install

# Configure environment (optional - testnet contracts pre-configured)
cp .env.example .env

# Start development server
npm run dev

Visit http://localhost:3000

Testing the Complete Flow

Connect Wallet - Click "Connect Wallet" and approve Freighter
Create Job:
- Navigate to "Create Job"
- Enter freelancer address (e.g., GAUCMH7KIOUZBPA5K4I7HMZV63XHSD36J7E5DH7TJXACWNWAROUMPRZZ)
- Amount: 10 XLM
- Milestones: 3
- Click "Create Job" and sign transaction

Verify Deposit:

stellar contract invoke --id CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC \
  --source deployer --network testnet -- get_total_deposits
# Should show deposited amount

Approve Milestone - Navigate to job details, click "Approve Milestone 1"
Release Payment - Click "Release Payment" and sign transaction
Verify Freelancer Received Funds - Check freelancer balance on Stellar Expert

🌐 Deployed Contracts (Stellar Testnet)

Contract	Address
Escrow Core	`CCK5VICBIWM245Q5TLB2FXCJYKVPTLIIB4HO2QPESG7TOF3ZPCZRKCVA`
Yield Harvester	`CBMU2XVMEJWJTXZBACTBJRGCFPXJCGUNT2VEENSVPN63G4MSMUDRBSMC`
Liquidity Router	`CDTDGS22DS33NPH2GNE4UWPYEJD57MJN6DTPDZXLD46SIKNNCYNKNA3A`

Token Addresses:

XLM (Wrapped Native): CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC
USDC: CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA

🔍 Test Accounts for Verification

IMPORTANT: These are the primary test accounts used for demonstrations. Check these addresses on Stellar testnet to verify transactions.

Role	Account Address
🔷 Client Account	`GD2LJQHARPMQXTNP2CVGMAZ7SROW3O46K77JEZPPTLT4QXHLE7XI5VFC`
🔶 Freelancer Account	`GAUCMH7KIOUZBPA5K4I7HMZV63XHSD36J7E5DH7TJXACWNWAROUMPRZZ`

Quick Links:

View All Contracts on Stellar Expert

🎨 Design & UI Features

🎨 Modern Animated UI - Smooth transitions with Framer Motion
💾 Wallet Persistence - Auto-reconnect on page reload
📊 Live Statistics - Animated counters with CountUp.js
🎯 Role-Based Navigation - Sleek sidebar adapts to user role
🌈 Gradient Effects - Dynamic background animations
📱 Responsive Design - Optimized for mobile, tablet, desktop
🔔 Toast Notifications - Real-time feedback for all actions

Color Scheme:

Primary: Orange/Coral (#F97316)
Background: Pure Black (#000000)
Surface: Dark Gray (#0F0F0F)
Text: White (#FFFFFF) with gray variations

🎯 Roadmap

🌍 Supported Currencies

Currency	Symbol	Type	Status
Stellar Lumens	XLM	Native	✅ Live
USD Coin	USDC	Stablecoin	✅ Live
OUSG	OUSG	RWA Token	✅ Live
Indian Rupee	INR	Fiat Token	🔜 Coming Soon
Kenyan Shilling	KES	Fiat Token	🔜 Coming Soon
Nigerian Naira	NGN	Fiat Token	🔜 Coming Soon

🔐 Security

✅ Milestone-based escrow prevents payment disputes
✅ Smart contract authorization ensures only authorized parties can execute actions
✅ Trustless execution - no centralized party controls funds
✅ Battle-tested Stellar blockchain infrastructure
✅ Real World Assets (OUSG) backed by US Treasury bonds
⚠️ Testnet only - full security audit required before mainnet deployment

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Make your changes with clear commit messages
Add tests if applicable
Push to branch (git push origin feature/amazing-feature)
Open Pull Request with detailed description

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Stellar Development Foundation - For Soroban smart contract platform
Ondo Finance - For OUSG tokenization and RWA infrastructure
Freighter Wallet Team - For seamless wallet integration
Stellar Community - For feedback and support

📞 Contact & Links

Website: yield-x.io
Twitter: @yieldx
Discord: Join our community
Email: hello@yield-x.io
GitHub: github.com/sukrit-89/Flowpay

📚 Additional Documentation

Payment Flow Fix Details - How we solved authorization issues
Yield Claim Integration - 30-second lockup implementation
Contract Addresses - All deployed contract addresses
Deployment Guide - How to deploy contracts
Add USDC Guide - How to add USDC to your wallet

Built with ❤️ on Stellar

Earn while you pay. That's the Yield-X difference.

Fun Fact: If all freelance escrow platforms globally ($10B+ locked annually) used Yield-X, clients would collectively earn $500M+ per year in passive yield while still paying freelancers the exact same amount. 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
contracts		contracts
frontend		frontend
scripts		scripts
.gitignore		.gitignore
ADD_USDC_GUIDE.md		ADD_USDC_GUIDE.md
CONTRACT_ADDRESSES.md		CONTRACT_ADDRESSES.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
LIQUIDITY_ROUTER_EXAMPLE.rs		LIQUIDITY_ROUTER_EXAMPLE.rs
PAYMENT_FLOW_FIX.md		PAYMENT_FLOW_FIX.md
README.md		README.md
YIELD_CLAIM_INTEGRATION.md		YIELD_CLAIM_INTEGRATION.md

Folders and files

Latest commit

History

Repository files navigation

Yield-X - Yield-Powered Freelance Escrow on Stellar

🎯 The Problem

Real-World Impact

💡 The Solution: Yield-X

How Yield-X Solves This

The Yield Advantage

🔌 Use as a Plugin in Your App

Option A: React integration (hooks)

Option B: Backend or non-React integration

The Yield Advantage

🏗️ Implementation Architecture

Contract Details

1. Escrow Core (escrow_core)

2. RWA Yield Harvester (rwa_yield_harvester)

3. Liquidity Router (liquidity_router)

🔄 Complete Payment Flow

Phase 1: Job Creation & Deposit

Phase 2: Milestone Approval & Payment

🛠️ Technical Implementation

Frontend (React + TypeScript)

Smart Contracts (Rust + Soroban)

🚧 Technical Challenges & Solutions

Challenge 1: Token Transfer Authorization

Challenge 2: Yield Claim Lockup Period

Challenge 3: Multi-Currency Support

🚀 Getting Started

Prerequisites

Installation

Testing the Complete Flow

🌐 Deployed Contracts (Stellar Testnet)

🔍 Test Accounts for Verification

🎨 Design & UI Features

🎯 Roadmap

🌍 Supported Currencies

🔐 Security

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Contact & Links

📚 Additional Documentation

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Escrow Core (`escrow_core`)

2. RWA Yield Harvester (`rwa_yield_harvester`)

3. Liquidity Router (`liquidity_router`)

Packages