# gmx-io/gmx-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/gmx-io/gmx-contracts
- Repository: https://github.com/gmx-io/gmx-contracts

## Overview

##### Main Components
- Smart Contracts – This is the core of the project and is split into multiple submodules:
- Core contracts (located under contracts/core) that manage the primary application logic for trading, positions, and vault operations.
- AMM and Oracle components (under contracts/amm, contracts/oracle, and contracts/oracle/interfaces) that provide trading automation and pricing data.
- Token and referral modules (contracts/gambit-token, contracts/referrals, contracts/tokens) which handle token issuance, rewards, and referral programs.
- Additional modules such as access control, staking, liquidity management, fee handling, order management, and fund routing spread out in their respective directories.
- Auxiliary libraries (contracts/libraries) including OpenZeppelin contracts (also retained in artifacts-v2/@openzeppelin) to handle common functionalities like security, math, and ERC standards.

- Artifacts & Testing – The “artifacts-v2” directory holds compiled contract data and possibly migration artifacts. The “test” directory contains extensive tests that exercise each module.

- Deployment & Scripts – The “scripts” folder includes deployment scripts and auxiliary operational tasks (e.g., fee distribution, updating access, and managing referrals). These scripts indicate that the deployment pipeline is sophisticated and modular.

- Configuration & Build – Files like hardhat.config.js and package.json denote that the project utilizes Hardhat for compiling, deploying, and testing, with npm modules handling dependencies.

##### Relationships and Interactions
- The individual contract modules interact with each other (e.g., the Vault contracts interact with Order Book and Price Feed contracts) to implement trading and risk management functions.
- Deployment scripts make use of Hardhat to compile, deploy, and configure interactions between these smart contracts.
- The testing suite in “test” validates the data flows and interactions, ensuring that components like core trading logic, fee processing, and access management work seamlessly.
- External libraries (such as those from OpenZeppelin, prb-math, and others) are integrated into the contracts to provide standardized security and mathematical foundations.

##### Architectural Patterns and Design Principles
- Modular Design – The contracts are segregated by functionalities (access control, core trading logic, token management, etc.), which aligns with a modular or microservices-like approach in smart contract development.
- Reuse of Established Libraries – By including OpenZeppelin contracts and other libraries, the system relies on well-tested building blocks to reduce risk.
- Clear Separation Between Deployment/Configuration and Business Logic – Deployment scripts in separate directories ensure that contract logic stays decoupled from deployment and configuration settings.
- Extensibility – With separate folders for interfaces and mocks, the design supports extension and testing isolation.

##### Technologies, Frameworks, and Libraries
- Solidity for smart contract development.
- Hardhat for the build, deployment, and testing processes.
- OpenZeppelin contracts (visible in artifacts-v2/@openzeppelin) for security standards.
- NPM for dependency management.
- Prb-math for precise mathematical operations in smart contracts.

##### Specific Elements
- Main Contract Groups: Highlight the “Core”, “AMM/Oracle”, “Token/Referral”, and “Access/Staking” modules.
- Deployment & Operational Layer: Represent Hardhat configuration, deployment scripts, and build artifacts.
- Testing and QA: Indicate the testing directories and their role in validating component interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    config["Config/Build Setup"]:::configStyle
    ds["Deployment Scripts"]:::deployStyle
    artifacts["Artifacts"]:::deployStyle
    test_suite["Test Suite"]:::testStyle

    config -->|"build_config"| ds
    ds -->|"deploy_contracts"| coreSC
    ds --> artifacts
    ds --> test_suite

    subgraph "Smart Contracts Deployment"
        subgraph "Core Contracts"
            coreSC["Core Contracts"]:::scStyle
        end
        subgraph "AMM Components"
            amm["AMM Component"]:::scStyle
        end
        subgraph "Oracle Components"
            oracle["Oracle Contract"]:::scStyle
            oracleInt["Oracle Interfaces"]:::scStyle
        end
        subgraph "Token Modules"
            gambit["Gambit Token"]:::scStyle
            ref["Referral Module"]:::scStyle
            tokenMgmt["Token Management"]:::scStyle
        end
        subgraph "Auxiliary Libraries"
            libs["Libraries"]:::libStyle
            openz["OpenZeppelin"]:::libStyle
        end
    end

    %% Relationships and interactions
    coreSC -->|"Interacts"| amm
    coreSC -->|"Interacts"| oracle
    coreSC -->|"Calls"| tokenMgmt
    coreSC -->|"Integrates"| ref
    amm -->|"Feeds"| oracle
    oracle -->|"Updates"| coreSC

    %% Testing validation
    test_suite -->|"tests"| coreSC
    test_suite -->|"tests"| amm
    test_suite -->|"tests"| oracle

    %% Styles
    classDef configStyle fill:#f4cccc,stroke:#000,stroke-width:2px;
    classDef deployStyle fill:#d9ead3,stroke:#000,stroke-width:2px;
    classDef scStyle fill:#d0e0e3,stroke:#000,stroke-width:2px;
    classDef testStyle fill:#fff2cc,stroke:#000,stroke-width:2px;
    classDef libStyle fill:#fce5cd,stroke:#000,stroke-width:2px;

    %% Click Events
    click config "https://github.com/gmx-io/gmx-contracts/blob/master/hardhat.config.js"
    click ds "https://github.com/gmx-io/gmx-contracts/tree/master/scripts"
    click coreSC "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/core"
    click amm "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/amm"
    click oracle "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/oracle"
    click oracleInt "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/oracle/interfaces"
    click gambit "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/gambit-token"
    click ref "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/referrals"
    click tokenMgmt "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/tokens"
    click libs "https://github.com/gmx-io/gmx-contracts/tree/master/contracts/libraries"
    click openz "https://github.com/gmx-io/gmx-contracts/tree/master/artifacts-v2/@openzeppelin"
    click artifacts "https://github.com/gmx-io/gmx-contracts/tree/master/artifacts-v2"
    click test_suite "https://github.com/gmx-io/gmx-contracts/tree/master/test"
```
