🌟 StellarTrustEscrow

A decentralized, milestone-based escrow platform with an on-chain reputation system — built on the Stellar blockchain using Soroban smart contracts.

---

📖 Overview

StellarTrustEscrow allows clients and freelancers to create trustless payment agreements secured by Soroban smart contracts. Funds are locked on-chain and released milestone by milestone — no intermediaries, no trust required.

Every completed milestone builds an immutable, on-chain reputation score for freelancers and clients, creating a trustworthy track record that persists across all future engagements.

---

✨ Features

Feature	Status
Milestone-based escrow contract	🚧 In Progress
On-chain reputation system	🚧 In Progress
Dispute resolution mechanism	🚧 In Progress
REST API + event indexer	🚧 In Progress
Next.js dashboard	🚧 In Progress
Wallet connection (Freighter)	🚧 In Progress
Public escrow explorer	🚧 In Progress

This project is actively seeking contributors! See CONTRIBUTING.md and the Issues tab.

---

🏗️ Tech Stack

Layer	Technology
Smart Contracts	Rust + Soroban SDK
Backend	Node.js + Express
Database	PostgreSQL + Prisma
Frontend	Next.js 14 + Tailwind CSS
Blockchain	Stellar (Testnet / Mainnet)
Wallet	Freighter Browser Extension

---

🔄 How It Works

Client                Contract              Freelancer
  │                      │                      │
  ├─── create_escrow() ──►│                      │
  │    (funds locked)     │                      │
  │                       │◄── add_milestone() ──┤
  │                       │                      │
  │◄── milestone done ────┤─── notify client ────┤
  │                       │                      │
  ├─── approve_milestone()►│                      │
  │                       ├─── release_funds() ──►│
  │                       │    (partial payout)   │
  │                       │                       │
  │              [dispute raised]                 │
  │                       │                       │
  ├─── raise_dispute() ───►│◄── raise_dispute() ──┤
  │                       │                       │
  │            [arbiter resolves]                 │
  │                       ├─── resolve_dispute() ─►│
  │                       │                       │
  └── reputation updated ─┴── reputation updated ─┘

---

🚀 Quick Start

Prerequisites

• Node.js >= 18
• Rust >= 1.74
• Soroban CLI >= 21.0.0
• PostgreSQL >= 14
• Freighter Wallet (browser extension)

1. Clone the Repository

git clone https://github.com/your-org/stellar-trust-escrow
cd stellar-trust-escrow

2. Install Dependencies

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

3. Set Up Environment Variables

# Backend
cp backend/.env.example backend/.env
# Edit backend/.env with your database URL, Stellar keys, etc.

# Frontend
cp frontend/.env.example frontend/.env.local
# Edit with your API URL and Stellar network config

4. Set Up the Database

cd backend
npx prisma migrate dev
npx prisma generate

5. Build the Smart Contract

cd contracts/escrow_contract
cargo build --release --target wasm32-unknown-unknown

6. Run the Development Server

# Terminal 1 — Backend
cd backend && npm run dev

# Terminal 2 — Frontend
cd frontend && npm run dev

Visit http://localhost:3000 to see the app.

---

🧪 Local Soroban Sandbox (Docker)

Prerequisites

• Docker & Docker Compose installed and running
• Soroban CLI available on your host (for contract deployment)

Start the Sandbox

# From the repository root
docker compose up -d soroban-sandbox

# Or use the helper script to start the sandbox, deploy contracts,
# generate dev wallets and wire the frontend config:
./scripts/start-sandbox.sh

The helper script will:

• Start a local Stellar Quickstart node in Soroban mode (standalone, no public testnet)
• Deploy core smart contracts to the local network
• Generate and fund a development account
• Write contract IDs and Soroban RPC settings into frontend/.env.local

Verify It Is Running

# Check the container
docker ps --filter name=stellar-sandbox

# Check Soroban RPC health
curl -sf http://localhost:8000/soroban/rpc | jq .

If the RPC endpoint responds and the container is healthy, the sandbox is ready.

Hot Reloading Contracts

When you change a contract:

# Rebuild and redeploy only the changed contract to the existing sandbox
./scripts/start-sandbox.sh

The script is idempotent and will:

• Rebuild the contract Wasm
• Upload and redeploy to the already-running sandbox
• Refresh the contract IDs in frontend/.env.local

No full network teardown is required for rapid iteration.

Teardown

# Stop and remove the local Soroban sandbox container
docker compose down soroban-sandbox

This stops the local network cleanly without touching your database or other services.

---

📁 Project Structure

stellar-trust-escrow/
├── contracts/
│   └── escrow_contract/       # Soroban smart contract (Rust)
├── backend/
│   ├── api/
│   │   ├── controllers/       # Route handler logic
│   │   └── routes/            # Express route definitions
│   ├── services/              # Business logic & indexers
│   └── database/              # Prisma models & migrations
├── frontend/
│   ├── app/                   # Next.js 14 App Router pages
│   └── components/            # Reusable React components
├── docs/                      # Architecture & guides
├── scripts/                   # Deployment & utility scripts
├── README.md
├── CONTRIBUTING.md
└── ARCHITECTURE.md

---

🤝 Contributing

We welcome contributions of all kinds! This repository is designed to be beginner-friendly with clearly scoped issues.

See CONTRIBUTING.md for the full guide, or jump straight to open issues.

---

🔒 Security

• Security Model: docs/SECURITY.md
• Privacy Policy: docs/PRIVACY.md
• Bug Bounty: docs/BUG_BOUNTY.md

Report vulnerabilities to security@stellartrustescrow.example.com.

---

📄 License

MIT — see LICENSE.