TrustMarket Docs

What is TrustMarket?

TrustMarket DEX is a decentralized peer-to-peer (P2P) marketplace built on the Stellar network using Soroban smart contracts. It enables trustless trading between parties with:

System Architecture

TrustMarket uses a modular smart contract architecture with 5 core contracts working together:

Trade Flow

Every trade on TrustMarket follows a structured lifecycle managed by smart contracts:

Escrow System

Each trade has its own isolated TradeEscrow contract. This ensures fund security — no single point of failure and no pool of user funds.

Escrow States

Key Functions

// Initialize escrow with trade details
fn init(trade_id, buyer, seller, token, amount, ...)

// Buyer locks funds into escrow
fn lock_funds() -> Result<(), EscrowError>

// Seller marks delivery complete
fn mark_delivered() -> Result<(), EscrowError>

// Buyer confirms, triggers payout (99% seller + 1% fee)
fn confirm_delivery() -> Result<(), EscrowError>

// Raise a dispute (buyer or seller)
fn initiate_dispute(caller, reason) -> Result<u64, EscrowError>

// Cancel trade (buyer only, before funding)
fn cancel() -> Result<(), EscrowError>

// Refund if trade expired (7 day timeout)
fn claim_expired() -> Result<(), EscrowError>

Marketplace Factory

The MarketplaceFactory is the central hub of TrustMarket. It deploys new escrow contracts and maintains a registry of all trades.

Capabilities

• Deploy new TradeEscrow contracts per trade
• Track all trades with unique IDs
• Map user addresses to their trade history
• Store trade metadata (buyer, seller, amount, status, escrow address)
• Admin can pause/unpause the factory
• Admin can update the escrow WASM hash for upgrades

// Create a new trade (deploys escrow contract)
fn create_trade(
    buyer: Address,
    seller: Address,
    token: Address,
    amount: i128,
    description: Symbol,
) -> Result<(trade_id, escrow_address), FactoryError>

// Get trade info by ID
fn get_trade(trade_id: u64) -> TradeInfo

// Get all trade IDs for a user
fn get_user_trades(user: Address) -> Vec<u64>

// Get total number of trades
fn get_trade_count() -> u64

Dispute Resolution

The DisputeOracle contract provides a decentralized arbitration system. When a trade dispute is raised, trusted arbitrators review the case and vote on the outcome.

How Disputes Work

Resolution Outcomes

Arbitrator Panel

The Arbitrator Panel (/arbitrate) is where trusted community members manage disputes. To become an arbitrator, you must earn 100+ TRUST tokens through successful trading.

How to Become an Arbitrator

Arbitrator Selection Algorithm

fn select_arbitrators(env, buyer, seller) -> Vec<Address> {
    // 1. Get ALL registered arbitrators
    let all_arbitrators = storage.get(Arbitrators);

    // 2. Filter: remove buyer & seller, check active status & min TRUST
    let eligible = all_arbitrators.filter(|a| {
        a != buyer &&
        a != seller &&
        a.is_active &&
        reputation.balance(a) >= MIN_TRUST_THRESHOLD  // 100 TRUST
    });

    // 3. Random selection using ledger timestamp as seed
    let seed = ledger.timestamp() ^ ledger.sequence();
    let selected = pick_n_random(eligible, PANEL_SIZE, seed);
    // PANEL_SIZE = 1 (testnet) | 3 (production)

    return selected;
}

TRUST Rewards & Penalties

Voting Flow on /arbitrate

Reputation System

TrustMarket features an on-chain reputation system using soulbound TRUST tokens. These tokens are non-transferable and serve as proof of successful trading history.

Trust Levels

How It Works

• TRUST tokens are minted by the escrow contract automatically on trade completion.
• TRUST tokens are soulbound — they cannot be transferred or sold.
• Your TRUST balance represents your on-chain trading reputation.
• 100+ TRUST qualifies you to register as an arbitrator.
• Dispute losers are penalized with TRUST burns (-50 or -25).

// Mint reputation tokens (called by escrow on completion)
fn mint(to: Address, amount: i128)

// Check reputation balance (two aliases)
fn balance(owner: Address) -> i128      // called by dispute_oracle
fn balance_of(owner: Address) -> i128  // standard interface

// Register as arbitrator (requires 100+ TRUST)
fn register_arbitrator(user: Address)

// Check if user is a registered arbitrator
fn is_arbitrator(user: Address) -> bool

// Soulbound — transfer is DISABLED
fn transfer() -> Error::NotAllowed

Staking & Fee Vault

The FeeVault contract collects platform fees from every completed trade. Users can stake their tokens to earn a share of platform revenue.

Fee Collection

How Staking Works

• Users can stake XLM tokens into the FeeVault.
• Stakers earn a proportional share of the collected platform fees.
• Staking helps secure the network and aligns incentives.
• Users can unstake at any time and claim their rewards.

Fee Structure

Smart Contracts Reference

All contracts are written in Rust using the Soroban SDK and deployed on Stellar Testnet.

Deployed Addresses (Testnet)

Contract Functions

Frequently Asked Questions