# trustless-work/trustless-work-smart-escrow architecture

> Architecture diagram of the GitHub repository trustless-work/trustless-work-smart-escrow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trustless-work/trustless-work-smart-escrow
- Repository: https://github.com/trustless-work/trustless-work-smart-escrow

## Overview

##### Project type and purpose
- This is a Rust-based smart-contract project targeting Stellar’s Soroban environment.
- It provides a “trustless escrow” system: clients deposit stablecoins (e.g., USDC) into an escrow contract; funds are released to freelancers upon milestone approval or returned/refunded in case of disputes.
- A second “test-token” contract exists purely for development/demo, modeling standard token behavior.

##### File structure
Top-level files:
- Cargo.toml/lock – Rust project manifests.
- README, guidelines, GitHub templates.
contracts/escrow:
- src/lib.rs, contract.rs – entry point defining contract interface.
- core/ – business logic modules: escrow.rs, milestone.rs, dispute.rs.
- core/validators – input/state validation.
- events/handler.rs – emitting on-chain events.
- modules/fee, math, token – submodules for fee calculation, safe arithmetic, token transfer.
- storage/types.rs – data schema for on-chain storage.
- tests/ – unit tests.
contracts/test-token:
- Standard token modules (balance, allowance, metadata, admin, etc.).

##### README for additional insights
- No frontend in this repo—interaction is via Stellar CLI or external API layer (docs at docs.trustlesswork.com).
- Deployment steps: build → install → deploy to Testnet, using wasm32 target.
- External dependencies: stellar-cli, Soroban testnet RPC.

##### Elements
- Another for off-chain tools/actors (CLI, API, users)
– Annotations for technologies (e.g., Rust, wasm, Soroban CLI, Stellar Testnet RPC URL).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-chain Tools and Actors
    subgraph "Off-Chain Environment"
        direction TB
        DEV["Developer Environment\n(Rust + Cargo)"]:::offchain
        COMPILE["Compile to wasm32-unknown-unknown"]:::offchain
        CLI["Soroban CLI"]:::offchain
        RPC["Stellar Testnet RPC"]:::offchain
        CLIENT["Client"]:::actor
        FREELANCER["Freelancer"]:::actor
    end

    %% On-chain Environment
    subgraph "Stellar Network (Testnet)" 
        direction TB
        ENGINE["Soroban Engine\n(On-chain Runtime)"]:::onchain
    end

    %% Escrow Contract Modules
    subgraph "Escrow Smart Contract" 
        direction TB
        LIB["lib.rs\n(entry point)"]:::contract
        INTERFACE["contract.rs\n(interface)"]:::contract
        subgraph "Core Logic" 
            direction TB
            ESCROW_CORE["escrow.rs"]:::module
            MILESTONE_CORE["milestone.rs"]:::module
            DISPUTE_CORE["dispute.rs"]:::module
        end
        subgraph "Validators"
            direction TB
            VAL_ESCROW["validators/escrow.rs"]:::module
            VAL_MILESTONE["validators/milestone.rs"]:::module
            VAL_DISPUTE["validators/dispute.rs"]:::module
        end
        HANDLER["events/handler.rs"]:::module
        subgraph "Helper Modules"
            direction TB
            FEE["modules/fee/calculator.rs"]:::module
            MATH_BASIC["modules/math/basic.rs"]:::module
            MATH_SAFE["modules/math/safe.rs"]:::module
            TOKEN_HANDLER["modules/token/transfer_handler.rs"]:::module
        end
        STORAGE["storage/types.rs"]:::module
        TESTS["tests/test.rs"]:::test
    end

    %% Test Token Contract (dashed)
    subgraph "Test-Token Smart Contract" 
        direction TB
        TT_LIB["lib.rs\n(entry point)"]:::testtoken
        TT_LOGIC["token.rs"]:::testtoken
        TT_ADMIN["admin.rs"]:::testtoken
        TT_BALANCE["balance.rs"]:::testtoken
        TT_ALLOWANCE["allowance.rs"]:::testtoken
        TT_META["metadata.rs"]:::testtoken
        TT_STORAGE["storage/types.rs"]:::testtoken
    end

    %% Flows
    DEV --> COMPILE
    COMPILE --> CLI
    CLI --> RPC
    RPC --> ENGINE
    CLIENT -->|"createEscrow, approveMilestone, dispute"| RPC
    FREELANCER -->|"approveMilestone"| RPC
    ENGINE --> ESCROW_CONTRACT[Escrow Smart Contract]
    ENGINE --> TESTTOKEN_CONTRACT[Test-Token Smart Contract]

    ESCROW_CONTRACT -->|calls transfer| TOKEN_HANDLER
    TOKEN_HANDLER -->|invoke| TT_LIB
    ESCROW_CONTRACT --> HANDLER
    HANDLER --> STORAGE

    %% Click Events
    click LIB "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/lib.rs"
    click INTERFACE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/contract.rs"
    click ESCROW_CORE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/escrow.rs"
    click MILESTONE_CORE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/milestone.rs"
    click DISPUTE_CORE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/dispute.rs"
    click VAL_ESCROW "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/validators/escrow.rs"
    click VAL_MILESTONE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/validators/milestone.rs"
    click VAL_DISPUTE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/core/validators/dispute.rs"
    click HANDLER "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/events/handler.rs"
    click FEE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/modules/fee/calculator.rs"
    click MATH_BASIC "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/modules/math/basic.rs"
    click MATH_SAFE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/modules/math/safe.rs"
    click TOKEN_HANDLER "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/modules/token/transfer_handler.rs"
    click STORAGE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/storage/types.rs"
    click TESTS "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/escrow/src/tests/test.rs"
    click TT_LIB "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/lib.rs"
    click TT_LOGIC "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/token.rs"
    click TT_ADMIN "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/admin.rs"
    click TT_BALANCE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/balance.rs"
    click TT_ALLOWANCE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/allowance.rs"
    click TT_META "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/metadata.rs"
    click TT_STORAGE "https://github.com/trustless-work/trustless-work-smart-escrow/blob/develop/contracts/test-token/src/storage/types.rs"

    %% Styles
    classDef offchain fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef onchain fill:#D5F5E3,stroke:#186A3B,color:#0B5345
    classDef actor fill:#F9E79F,stroke:#7D6608,color:#7D6608
    classDef contract fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef module fill:#FDEBD0,stroke:#BA4A00,color:#78281F
    classDef test fill:#FADBD8,stroke:#C0392B,color:#641E16,stroke-dasharray: 5 5
    classDef testtoken fill:#EBDEF0,stroke:#6C3483,color:#4A235A,stroke-dasharray: 5 5
```
