Trustless, milestone-based escrow on the Stellar blockchain.
A platform where clients lock funds into verifiable smart contracts, contractors deliver work in provable milestones, and every outcome — completion or dispute — builds an immutable on-chain reputation that follows both parties forever.
Traditional escrow platforms hold funds in centralised accounts — meaning you trust a company, not a contract. If the platform shuts down, gets hacked, or makes a unilateral call, your money can be frozen or lost. Dispute resolution is opaque, outcomes are non-transferable, and reputation is a database entry that can be deleted.
Trustchain Escrow replaces the intermediary with code.
- Funds are locked in a Soroban smart contract, not on a company server
- Milestone approval is on-chain — no one can override or delay it
- Reputation scores are contract-level state, not a row that can be deleted
- Anyone can audit the contract logic before trusting it with funds
| Role | How they use Trustchain |
|---|---|
| Clients / Funders | Lock XLM or any Stellar asset into a milestone contract; approve work incrementally; raise disputes with evidence if delivery fails |
| Contractors / Freelancers | Accept work under clear on-chain terms; submit milestones for review; build a verifiable reputation across all engagements |
| DAOs / Communities | Pool contributor funds into a single escrow; gate milestone approval to a multi-sig or governance vote |
| Arbiters | Resolve disputes with on-chain authority and an auditable decision trail |
| Developers | Self-host a tenant, integrate via REST API, or extend the Soroban contract |
Active → (all milestones approved) → Completed
Active → (either party raises dispute) → Disputed → (arbiter resolves) → Completed
Active → (mutual consent) → Cancelled
Active → (deadline passed) → Expired → (auto-refund to client)
Each state transition is a signed Stellar transaction — auditable by anyone, reversible by no one.
Funds are never released all at once. Each escrow is subdivided into milestones, each with its own amount and description hash. When the contractor submits a milestone and the client approves it, only that milestone's funds are released — the remainder stays locked.
This gives both parties checkpoints: clients can stop at any milestone if work is unsatisfactory; contractors are protected from non-payment once a milestone is approved.
Every escrow completion, dispute win, and dispute loss emits a ReputationEvent to the contract. Events accumulate into a score that is:
- Public — readable by any Stellar wallet or dApp
- Immutable — no one can delete or alter past events
- Portable — your score lives at your Stellar address, not on our servers
- Composable — other contracts and dApps can query it directly
┌─────────────────────────────────────────────────────────────────┐
│ Client Layer │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Web Dashboard │ │ Mobile App │ │
│ │ Next.js 14 + Tailwind │ │ Expo / React Native │ │
│ │ Freighter wallet │ │ Biometric auth │ │
│ │ Soroban transaction UI │ │ Offline SQLite cache │ │
│ └────────────┬─────────────┘ └────────────┬─────────────┘ │
└───────────────┼──────────────────────────────┼──────────────────┘
│ HTTPS + JWT │ HTTPS + JWT
┌───────────────▼──────────────────────────────▼──────────────────┐
│ API Layer (Express.js, Node 20+) │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Auth │ │ Escrow │ │ Dispute │ │ Admin │ │
│ │ MFA + JWT │ │ Milestone │ │ Evidence │ │ Audit log │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Tenant │ │ Search │ │ Webhooks │ │ Reputation│ │
│ │ Scoping │ │ (ES + PG) │ │ BullMQ │ │ Indexer │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└───────────┬───────────────────────────┬─────────────────────────┘
│ │
┌───────────▼──────────┐ ┌────────────▼──────────────────────────┐
│ Data Layer │ │ Blockchain Layer │
│ PostgreSQL (Prisma) │ │ Stellar Network (Testnet / Mainnet) │
│ Redis (cache+queues) │ │ Soroban RPC │
│ IPFS (evidence) │ │ Soroban Smart Contracts (Rust/Wasm) │
└──────────────────────┘ └───────────────────────────────────────┘
| Decision | Choice | Why |
|---|---|---|
| Smart contract runtime | Soroban (Rust → Wasm) | Stellar's native contract platform; deterministic, auditable, no EVM gas surprises |
| API framework | Express.js | Minimal surface area; easy to audit middleware chain |
| ORM | Prisma | Type-safe DB access; migration history lives in the repo |
| Cache | Redis + in-memory fallback | Sliding-window rate limits need atomic operations; fallback keeps dev setup simple |
| Job queue | BullMQ | Reliable webhook retry with exponential backoff; dead-letter visibility in Redis |
| Search | Elasticsearch + Prisma fallback | Full-text escrow search at scale; falls back gracefully if ES is unavailable |
| Mobile offline | SQLite (expo-sqlite) | Works without network; stale rows evicted by TTL |
| Pagination | Cursor-based | Stable across concurrent inserts; no skipped rows on fast-changing datasets |
1. CLIENT deposits funds
└─ create_escrow(contractor, amount, milestones[], timelock?)
└─ Stellar transaction locks funds in contract
2. CONTRACTOR delivers work
└─ submit_milestone(escrow_id, milestone_index, ipfs_hash)
└─ Deliverable hash stored on-chain
3. CLIENT reviews and approves
└─ approve_milestone(escrow_id, milestone_index)
└─ Soroban releases that milestone's funds to contractor
4. Repeat for each milestone until completion
└─ Final approval → escrow Completed
└─ ReputationEvent written for both parties
── OR ──
3b. Dispute raised
└─ raise_dispute(escrow_id, evidence_hashes[])
└─ SHA-256 hashes anchored on-chain
4b. Arbiter resolves
└─ submit_ruling(escrow_id, client_pct, contractor_pct)
└─ Funds split per ruling; ReputationEvent reflects outcome
trustchain-escrow/
│
├── contracts/ # Soroban smart contracts (Rust)
│ ├── escrow_contract/
│ │ └── src/
│ │ ├── lib.rs # Entry points & access control
│ │ ├── storage.rs # On-chain state definitions
│ │ ├── errors.rs # Typed error enum
│ │ └── types.rs # Shared types
│ └── governance/ # On-chain governance contract
│
├── backend/ # Node 20+ REST API
│ ├── api/
│ │ ├── controllers/
│ │ ├── middleware/ # Auth, rate-limit, cache, logging
│ │ └── routes/
│ ├── services/ # Business logic layer
│ ├── database/
│ │ ├── schema.prisma
│ │ └── migrations/
│ └── tests/ # Jest — 425 tests
│
├── frontend/ # Next.js 14 web dashboard
│ ├── app/ # App Router pages
│ ├── components/
│ └── lib/
│ ├── stellar.js # Stellar SDK + contract bindings
│ └── api/client.js # Axios client + JWT refresh
│
├── mobile/ # Expo / React Native app
│ ├── app/
│ ├── hooks/
│ ├── services/
│ │ ├── biometrics.ts
│ │ └── offlineCache.ts
│ └── lib/
│
├── CONTRIBUTING.md # Contributor guide (setup → first PR)
│
├── docs/
│ ├── CONTRIBUTING.md # → points at the root guide
│ ├── SECURITY.md
│ ├── configuration.md # All env vars & config options
│ ├── dispute-resolution-guide.md # End-to-end dispute resolution process
│ ├── escrow-creation-release-guide.md # Escrow creation & milestone release guide
│ ├── event-schema.md # On-chain event catalogue
│ ├── production-deployment-guide.md # Production deployment & setup guide
│ ├── security-model.md # System security model & threat matrix
│ └── webhooks.md # Webhook payloads & event types
│
├── scripts/
│ ├── deploy/
│ │ ├── testnet.sh
│ │ └── mainnet.sh
│ └── simulate/ # End-to-end lifecycle scripts
│
└── docker-compose.yml # PostgreSQL + Redis + Stellar node
| Dependency | Minimum |
|---|---|
| Node.js | 20 |
| Rust | stable (1.75+) |
| Docker | 24+ |
| Stellar CLI | latest |
# Clone
git clone git@github.com:KCEE0901/trustchain-escrow.git
cd trustchain-escrow
# Install dependencies
npm install
# Start infrastructure
docker compose up -d
# Configure environment
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local
# Run migrations
npm run db:migrate -w backend
npm run db:generate -w backend
# Start backend
npm run dev -w backend
# Start frontend (separate terminal)
npm run dev -w frontend# Backend
npm test -w backend
# Frontend
npm run test:unit -w frontend
# Contracts
cargo test --workspaceEvery environment variable and configuration option — backend, frontend, mobile, Docker Compose, and the ops scripts — is catalogued in docs/configuration.md, along with defaults, startup validation rules, and per-environment recommendations.
All endpoints are versioned under /api/v1/. Authentication uses Bearer JWT tokens.
| Method | Endpoint | Description |
|---|---|---|
POST |
/auth/login |
Authenticate and receive JWT |
GET |
/escrows |
List escrows for authenticated user |
POST |
/escrows |
Create a new escrow |
GET |
/escrows/:id |
Get escrow detail |
POST |
/escrows/:id/release |
Approve milestone release |
POST |
/escrows/:id/dispute |
Raise a dispute |
GET |
/escrows/:id/events |
Full event timeline |
GET |
/users/me/stats |
Account stats and volume |
POST |
/webhooks/subscribe |
Subscribe to on-chain event webhooks |
Full API reference: backend/openapi.yaml
Subscribe to indexed on-chain events and receive signed POST callbacks. See
docs/webhooks.md for subscription management, the delivery
envelope, payload schemas for every event type, signature verification, and retry
behaviour.
| Network | Contract ID |
|---|---|
| Testnet | deploy in progress |
| Mainnet | pending audit |
See docs/security-model.md for the complete security model and threat architecture, and docs/SECURITY.md for the vulnerability disclosure policy.
- REST API Reference — Comprehensive technical reference for all REST endpoints, request/response schemas, and code samples.
- Developer Onboarding & Local Setup Guide — Step-by-step developer setup, toolchain requirements, Docker stack, and troubleshooting.
- Smart Contract ABI & Function Reference — Detailed Soroban smart contract ABI signatures, data types, authorization, and event catalog.
- System Architecture Overview — High-level architecture diagram, component breakdowns, data flows, and security boundaries.
- Escrow Creation & Release Flow Guide — Step-by-step end-user guide for creating escrows and releasing milestone funds.
- Dispute Resolution Guide — End-to-end guide on raising disputes, IPFS evidence submission, and arbiter rulings.
- Security Model Documentation — System threat model, access control matrix, and smart contract invariants.
- Production Deployment Guide — Deploying Soroban contracts, backend API, databases, and Docker services to production.
- Configuration Reference — Detailed environment variables and system settings.
- Multi-Tenant Architecture — Tenant model, tenant resolution, data isolation guarantees, and audit chain integrity.
- Stellar Network Integration — Local sandbox, testnet, and mainnet setup with contract deployment and wallet management.
- Operational Runbook — Common operational tasks including health checks, service restarts, database maintenance, contract upgrades, and scaling.
- Changelog and Versioning Policy — SemVer policy, changelog format, and release process.
See CONTRIBUTING.md for local setup, the Soroban toolchain, how to test each layer, branch naming conventions, commit format, and the PR process. New pull requests are pre-filled with the PR template.