StellarEscrow

Production-ready Soroban smart contract for peer-to-peer marketplace escrow on Stellar blockchain, with a comprehensive event indexing service.

Overview

StellarEscrow is a decentralized escrow system that enables secure peer-to-peer trades using USDC stablecoin. The platform connects buyers and sellers with optional arbitrators who can resolve disputes, with the smart contract managing escrow, fee collection, and settlement.

The project includes:

• Smart Contract: Soroban contract written in Rust
• Event Indexer: High-performance indexing service for real-time event monitoring and querying

Features

• Escrow-Based Trading: Secure USDC deposits held in contract until trade completion
• Arbitrator Network: Registered arbitrators handle dispute resolution
• Automated Fee Collection: Platform fees calculated and accumulated automatically
• Multi-Status Tracking: Trades tracked through Created, Funded, Completed, Disputed, and Cancelled states
• Authorization Security: Role-based access control for all operations
• Event Emission: Comprehensive event logging for off-chain monitoring
• Dispute Resolution: Arbitrators can release funds to buyer or seller
• Cancellation Support: Sellers can cancel unfunded trades
• Admin Controls: Platform fee management and fee withdrawal capabilities
• Event Indexing: Real-time event monitoring, storage, and querying
• WebSocket Streaming: Live event updates for connected clients
• REST API: Efficient event querying and replay functionality

Architecture

Smart Contract (contract/)

Core Components

• lib.rs: Main contract implementation with all public functions
• types.rs: Data structures (Trade, TradeStatus, DisputeResolution)
• storage.rs: Persistent and instance storage management
• errors.rs: Custom error types for contract operations
• events.rs: Event emission functions for monitoring

Event Indexer (indexer/)

Core Components

• main.rs: Service entry point and server setup
• config.rs: Configuration management
• database.rs: PostgreSQL database operations
• event_monitor.rs: Stellar network event monitoring
• handlers.rs: REST API endpoint handlers
• websocket.rs: WebSocket connection management
• models.rs: Data structures and types
• error.rs: Error handling

Quick Start

Prerequisites

• Rust 1.70+
• PostgreSQL 13+
• Soroban CLI (for contract deployment)
• Stellar account with XLM for fees

1. Build the Contract

cd contract
cargo build --target wasm32-unknown-unknown --release

2. Deploy the Contract

# Using Soroban CLI
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/stellar_escrow_contract.wasm \
  --source <your-secret-key> \
  --network testnet

3. Setup the Indexer

cd indexer

# Install sqlx CLI
cargo install sqlx-cli

# Setup database
createdb stellar_escrow
sqlx migrate run

# Configure
cp config.toml config.local.toml
# Edit config.local.toml with your contract ID and database URL

4. Run the Indexer

cargo run -- --config config.local.toml

Contract Functions

Administrative Functions

• initialize(admin, usdc_token, fee_bps) - One-time contract initialization
• register_arbitrator(arbitrator) - Add arbitrator to approved list (admin only)
• remove_arbitrator_fn(arbitrator) - Remove arbitrator from approved list (admin only)
• update_fee(fee_bps) - Update platform fee percentage (admin only)
• withdraw_fees(to) - Withdraw accumulated fees (admin only)

User Functions

• create_trade(seller, buyer, amount, arbitrator) - Create new trade (seller auth required)
• fund_trade(trade_id) - Buyer funds the escrow (buyer auth required)
• complete_trade(trade_id) - Seller confirms delivery (seller auth required)
• confirm_receipt(trade_id) - Buyer confirms receipt and releases funds (buyer auth required)
• raise_dispute(trade_id) - Either party raises dispute (buyer/seller auth required)
• resolve_dispute(trade_id, resolution) - Arbitrator resolves dispute (arbitrator auth required)
• cancel_trade(trade_id) - Cancel unfunded trade (seller auth required)

Query Functions

• get_trade(trade_id) - Retrieve trade details
• get_accumulated_fees() - Check total platform fees collected
• is_arbitrator_registered(arbitrator) - Verify arbitrator registration status
• get_platform_fee_bps() - Get current fee percentage

Indexer API

REST Endpoints

Health Check

GET /health

Get Events

GET /events?limit=50&event_type=trade_created&trade_id=123

Get Event by ID

GET /events/{uuid}

Get Events by Trade ID

GET /events/trade/{trade_id}

Replay Events

POST /events/replay
{
  "from_ledger": 123456,
  "to_ledger": 123500
}

WebSocket Streaming

Connect to /ws for real-time event updates:

const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New event:', data);
};

Security Features

• Authorization Checks: All state-changing operations require proper authorization
• Status Validation: Prevents invalid state transitions
• Overflow Protection: Safe math operations with overflow checks
• Arbitrator Verification: Only registered arbitrators can resolve disputes
• Ownership Validation: Only trade parties can perform specific actions

Testing

Contract Tests

cd contract
cargo test

Indexer Tests

cd indexer
cargo test

The contract includes comprehensive tests covering: ✅ Initialization and configuration ✅ Arbitrator registration and removal ✅ Fee updates and validation ✅ Trade creation and funding ✅ Trade completion flow ✅ Dispute raising and resolution ✅ Cancellation logic ✅ Fee withdrawal by admin ✅ Authorization enforcement ✅ Error conditions ✅ Event emission verification ✅ Multiple trades handling ✅ Fee calculation accuracy

Deployment

Contract Deployment

1. Build optimized WASM:

cd contract
cargo build --target wasm32-unknown-unknown --release

2. Deploy using Soroban CLI or your preferred deployment tool

Indexer Deployment

1. Build release binary:

cd indexer
cargo build --release

2. Configure production settings in config.toml
3. Run migrations on production database
4. Start the service

Development

Project Structure

StellarEscrow/
├── contract/           # Soroban smart contract
│   ├── src/
│   │   ├── lib.rs      # Main contract logic
│   │   ├── types.rs    # Data structures
│   │   ├── storage.rs  # Storage operations
│   │   ├── errors.rs   # Error types
│   │   └── events.rs   # Event emission
│   └── Cargo.toml
├── indexer/            # Event indexing service
│   ├── src/
│   │   ├── main.rs     # Service entry point
│   │   ├── config.rs   # Configuration
│   │   ├── database.rs # DB operations
│   │   ├── event_monitor.rs # Stellar monitoring
│   │   ├── handlers.rs # HTTP handlers
│   │   ├── websocket.rs # WS connections
│   │   ├── models.rs   # Data models
│   │   └── error.rs    # Error handling
│   ├── migrations/     # DB migrations
│   ├── config.toml     # Default config
│   └── Cargo.toml
└── Cargo.toml          # Workspace config

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License.

Administrative Functions

• initialize(admin, usdc_token, fee_bps) - One-time contract initialization
• register_arbitrator(arbitrator) - Add arbitrator to approved list (admin only)
• remove_arbitrator_fn(arbitrator) - Remove arbitrator from approved list (admin only)
• update_fee(fee_bps) - Update platform fee percentage (admin only)
• withdraw_fees(to) - Withdraw accumulated fees (admin only)

User Functions

• create_trade(seller, buyer, amount, arbitrator) - Create new trade (seller auth required)
• fund_trade(trade_id) - Buyer funds the escrow (buyer auth required)
• complete_trade(trade_id) - Seller confirms delivery (seller auth required)
• confirm_receipt(trade_id) - Buyer confirms receipt and releases funds (buyer auth required)
• raise_dispute(trade_id) - Either party raises dispute (buyer/seller auth required)
• resolve_dispute(trade_id, resolution) - Arbitrator resolves dispute (arbitrator auth required)
• cancel_trade(trade_id) - Cancel unfunded trade (seller auth required)

Query Functions

• get_trade(trade_id) - Retrieve trade details
• get_accumulated_fees() - Check total platform fees collected
• is_arbitrator_registered(arbitrator) - Verify arbitrator registration status
• get_platform_fee_bps() - Get current fee percentage

Security Features

• Authorization Checks: All state-changing operations require proper authorization
• Status Validation: Prevents invalid state transitions
• Overflow Protection: Safe math operations with overflow checks
• Arbitrator Verification: Only registered arbitrators can resolve disputes
• Ownership Validation: Only trade parties can perform specific actions

Testing

The contract includes comprehensive tests covering:

✅ Initialization and configuration
✅ Arbitrator registration and removal
✅ Fee updates and validation
✅ Trade creation and funding
✅ Trade completion flow
✅ Dispute raising and resolution
✅ Cancellation logic
✅ Fee withdrawal by admin
✅ Authorization enforcement
✅ Error conditions
✅ Event emission verification
✅ Multiple trades handling
✅ Fee calculation accuracy

Run tests with:

cargo test

Quick Start

1. Build the Contract

cd StellarEscrow
cargo build --target wasm32-unknown-unknown --release
soroban contract optimize --wasm target/wasm32-unknown-unknown/release/stellar_escrow.wasm

2. Deploy to Testnet

soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/stellar_escrow.optimized.wasm \
  --source deployer \
  --network testnet

3. Initialize

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source deployer \
  --network testnet \
  -- \
  initialize \
  --admin <ADMIN_ADDRESS> \
  --usdc_token <USDC_TOKEN_ADDRESS> \
  --fee_bps 100

See DEPLOYMENT.md for complete deployment instructions.

Usage Flow

Admin Setup

1. Deploy contract
2. Initialize with admin address, USDC token, and fee percentage
3. Register trusted arbitrators

Create Trade

1. Seller creates trade with buyer address, amount, and optional arbitrator
2. Trade ID returned for tracking

Fund Trade

1. Buyer approves USDC transfer to contract
2. Buyer calls fund_trade with trade ID
3. Contract transfers USDC from buyer to escrow

Complete Trade (Happy Path)

1. Seller delivers goods/services off-chain
2. Seller calls complete_trade
3. Buyer calls confirm_receipt
4. Contract transfers USDC minus fee to seller
5. Fee added to accumulated platform fees

Dispute Resolution

1. Either party calls raise_dispute
2. Arbitrator investigates off-chain
3. Arbitrator calls resolve_dispute with resolution (ReleaseToBuyer or ReleaseToSeller)
4. Contract transfers funds accordingly minus arbitration fee

Fee Management

1. Admin monitors accumulated fees
2. Admin calls withdraw_fees to collect platform revenue

Error Codes

Code	Error	Description
1	AlreadyInitialized	Contract already initialized
2	NotInitialized	Contract not initialized
3	InvalidAmount	Amount must be greater than 0
4	InvalidFeeBps	Fee must be between 0-10000 bps
5	ArbitratorNotRegistered	Arbitrator not in approved list
6	TradeNotFound	Trade ID does not exist
7	InvalidStatus	Operation not allowed in current status
8	Overflow	Arithmetic overflow detected
9	NoFeesToWithdraw	No accumulated fees available
10	Unauthorized	Caller not authorized for this operation

Events

The contract emits events for monitoring:

• created - New trade created
• funded - Buyer funded escrow
• complete - Seller marked as delivered
• confirm - Buyer confirmed receipt and settled
• dispute - Dispute initiated
• resolved - Arbitrator resolved dispute
• cancel - Trade cancelled
• arb_reg - Arbitrator registered
• arb_rem - Arbitrator removed
• fee_upd - Platform fee updated
• fees_out - Fees withdrawn by admin

Dependencies

• soroban-sdk = "21.7.0" - Latest Soroban SDK

Documentation

• ARCHITECTURE.md - Technical architecture and design decisions
• DEPLOYMENT.md - Complete deployment guide
• CONTRIBUTING.md - Contribution guidelines

License

MIT

Support

For issues and questions:

• GitHub Issues: Create an issue
• Stellar Discord: https://discord.gg/stellar
• Soroban Docs: https://soroban.stellar.org

Contributing

Contributions welcome! Please ensure:

• All tests pass: cargo test
• Code follows Rust best practices
• New features include tests
• Documentation is updated

See CONTRIBUTING.md for detailed guidelines.

Roadmap

• Multi-currency support
• Batch trade processing
• Arbitrator reputation system
• Time-locked escrow options
• Partial release mechanism
• Multi-signature arbitration
• Integration with decentralized identity

---

StellarEscrow is a Soroban smart contract built in Rust that enables secure, escrow-based peer-to-peer trading on the Stellar network.

This project demonstrates production-ready patterns for escrow systems, dispute resolution, and fee management on Stellar blockchain.