# polymarket/ctf-exchange architecture

> Architecture diagram of the GitHub repository polymarket/ctf-exchange, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polymarket/ctf-exchange
- Repository: https://github.com/polymarket/ctf-exchange

## Overview

##### Project Type & Purpose
- The project is a smart contract-based protocol for enabling atomic swaps between ERC1155 Conditional Tokens and an ERC20 collateral asset.
- Its hybrid-decentralized exchange model involves on-chain settlement while an offchain operator performs matching services.
- Key uses include providing non-custodial exchange settlement with modular, reusable components for conditional asset trading.

##### Analyzing the File Structure
- Top-Level Directories:
– docs: Contains in-depth documentation, including overviews and detailed mixin explanations (e.g., Auth, Fees, Trading).
– src: Houses the Solidity source code, segmented into subdirectories:
▪ src/common: Common functionality such as authentication modules, interfaces, and libraries that can be shared across contracts.
▪ src/exchange: Contains the core exchange protocol code including interfaces, libraries, mixins (which modularize contract behavior), scripts, and tests.
▪ src/dev: Dedicated to development utilities, such as mocks, test scripts, and helper libraries.
– lib: External Solidity libraries and dependencies (e.g., OpenZeppelin, Solmate, forge-std) that form key building blocks for secure and standardized contract development.
– deploy & broadcast: Deployment scripts (like deploy_exchange.sh) are used to manage on-chain deployments.
– audit & artifacts: Contain the audit report and compiled contract artifacts respectively.

##### Architectural Components & Relationships
- Smart Contracts (On-Chain Components):
– Exchange Core Contracts: Located within src/exchange, these implement the atomic swap mechanism, including mixins that add specialized functionality (e.g., signature handling, fee management, trading logic).
– Common Modules: Found in src/common, these provide shared functionality like authentication and library support.
– Interfaces & Libraries: Define standard interactions and reusable code blocks.
– External Dependencies: Contracts from OpenZeppelin, Solmate, and forge-std which provide standardized functionality (e.g., access control, math libraries).

- Offchain/Operational Tools (Supporting Components):
– Deployment Scripts: In deploy and broadcast directories, these scripts handle contract deployment on networks such as Polygon/Mumbai.
– Testing Framework: Foundry is set up (with foundry.toml, package.json, and related scripts) to run tests using forge, ensuring contract correctness.
– Audit Artifacts: Linking to the audit report emphasizes security assessments and external validations.

##### Key Architectural Patterns and Principles
- Modularity through Mixins: The use of mixins in src/exchange/mixins enables functionality to be compartmentalized, improving security and making the contract easier to audit.
- Separation of Concerns: There is a clear division between common functionality (auth, interfaces, libraries) and exchange-specific logic.
- Use of External Libraries: Integration with well-established libraries like OpenZeppelin and Solmate indicates security best practices and reuse of battle-tested components.
- Hybrid Model: The design separates the on-chain settlement (handled by smart contracts) from offchain matching operations managed by an operator.

## Diagram (Mermaid)

```mermaid
graph TD
    %% On-Chain Components
    subgraph "On-Chain Components"
        EC["Exchange Core Contracts"] 
        CC["Common Contracts"]
        ED["External Dependencies & Libraries"]
        ET["External Token Contracts (ERC1155 & ERC20)"]
    end

    %% Offchain/Operational Components
    subgraph "Offchain/Operational Components"
        DS["Deployment Scripts"]
        TD["Testing & Development Tools"]
        OS["Operator Service (Offchain Matching)"]
        AA["Audit Artifacts"]
        DC["Documentation"]
    end

    %% Relationships
    OS -->|"triggers_settlement"| EC
    DS -->|"deploys"| EC
    TD -->|"tests"| EC
    EC -->|"calls"| ET
    EC -->|"utilizes"| CC
    EC -->|"relies_on"| ED
    CC -->|"supports"| EC
    ED -->|"secures"| EC

    %% Classes for styling
    class EC,CC onchain
    class DS,TD,OS,AA,DC offchain
    class ED,ET external

    %% Class Definitions
    classDef onchain fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef offchain fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;

    %% Click Events
    click EC "https://github.com/polymarket/ctf-exchange/tree/main/src/exchange"
    click CC "https://github.com/polymarket/ctf-exchange/tree/main/src/common"
    click DS "https://github.com/polymarket/ctf-exchange/blob/main/deploy/scripts/deploy_exchange.sh"
    click TD "https://github.com/polymarket/ctf-exchange/blob/main/foundry.toml"
    click ED "https://github.com/polymarket/ctf-exchange/tree/main/lib"
    click AA "https://github.com/polymarket/ctf-exchange/blob/main/audit/ChainSecurity_Polymarket_Exchange_audit.pdf"
    click DC "https://github.com/polymarket/ctf-exchange/tree/main/docs"
```
