# centrifuge/liquidity-pools architecture

> Architecture diagram of the GitHub repository centrifuge/liquidity-pools, 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/centrifuge/liquidity-pools
- Repository: https://github.com/centrifuge/liquidity-pools

## Overview

Based on our analysis of the file tree and README, this project is a smart contract codebase for deploying and managing liquidity pools on any EVM-compatible blockchain. Its purpose is to tokenize real-world assets (RWAs) into ERC20 tokens using modular and gas‑efficient permissioning strategies. The project leverages Foundry for testing and development, contains detailed audit reports, and has multiple components that interact to manage investments, tranches, and onchain tokenized vaults (ERC-7540).

##### Main Components
- Core Contract Modules:
- ERC7540Vault: Implements deposit/withdraw logic for investors and is based on the ERC-7540 standard (extension of ERC-4626).
- Tranche Token: An ERC-20 token with integrated restrictions managed via the RestrictionManager.
- Investment Manager: Contains the primary business logic for pool creation, tranche deployment, and distribution of funds toward an escrow contract.
- Pool Manager: Manages bookkeeping for assets and handles the transferring of tranche tokens.
- Gateway: Implements the Multi-Message Aggregation (MMA) mechanism to interface with various adapters.
- Adapters: Specific implementations (located in src/gateway/adapters and src/interfaces/gateway/adapters) that facilitate messaging and possibly external integrations.

##### Out Supporting Infrastructure
- Deployment Files: Note "deployments" for different networks (mainnet and testnet) to understand which environments are supported.
- Testing and Auditing: The extensive "test" directory, along with testing configurations (Echidna, Medusa, and Foundry), showcases the emphasis on security and behavior verification.
- External Libraries & Utilities: The "lib" folder includes additional modules like “forge-gas-snapshot” and “forge-std” that are integral for testing and deployment.

##### Relationships and Interactions
- Data Flow:
- Investors interact with the ERC7540Vault to deposit and redeem stablecoins.
- The Investment Manager and Pool Manager work together to create pools and manage the distribution/transfer of assets and tokens.
- The Gateway receives, aggregates, and forwards messages from managers to adapt different messaging protocols, interfacing with multiple Adapters.
- Communication Paths:
- Flow from the Gateway to the different Adapters, illustrating both messaging (commands and proofs) and responses back to the managers.
- External Entities:
- Depicting governance and external audits (as these are vital for immutable and audited smart contracts).
- Acknowledge onchain governance that ultimately controls the deployed contracts.

##### Architectural Patterns & Design Principles
- Modularity: The separation of contracts into clear concerns (vaults, tokens, managers, gateways, adapters) which supports reusability and maintainability.
- Security & Auditing: Explicit audit reports and dedicated testing configurations (e.g., echidna, medusa) emphasize formal verification and runtime safety.
- Deployability Across Chains: With different configuration files for mainnet (Ethereum, Arbitrum, Celo, Base) and testnet variants, it’s crucial to illustrate the multi-chain support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Investor["Investor"]:::external
    Governance["Onchain Governance"]:::external

    subgraph "Smart Contract Modules"
        subgraph "Token Mechanics"
            ERC7540Vault["ERC7540Vault"]:::vault
            TrancheToken["Tranche Token"]:::token
        end
        subgraph "Business Logic"
            InvestmentManager["Investment Manager"]:::manager
            PoolManager["Pool Manager"]:::manager
            Escrow["Escrow Contract"]:::escrow
        end
        subgraph "Communication Layer"
            Gateway["Gateway"]:::gateway
            subgraph "Adapters"
                AdapterImpl["Adapter Implementations"]:::adapter
                AdapterIntf["Adapter Interfaces"]:::adapter
            end
        end
    end

    subgraph "Infrastructure"
        Deployments["Deployments & Config"]:::infra
        Testing["Testing"]:::infra
        Audits["Audit Reports"]:::infra
        Libraries["External Libraries"]:::infra
    end

    Investor -->|"deposit/withdraw"| ERC7540Vault
    ERC7540Vault -->|"triggers_logic"| InvestmentManager
    InvestmentManager -->|"coordinates"| PoolManager
    InvestmentManager -->|"distributes_funds"| Escrow
    PoolManager -->|"transfers_tokens"| Escrow
    InvestmentManager -->|"sends_messages"| Gateway
    PoolManager -->|"sends_messages"| Gateway
    Gateway <-->|"aggregates_messages"| AdapterImpl
    Gateway <-->|"aggregates_messages"| AdapterIntf
    Governance -->|"controls"| InvestmentManager
    Governance -->|"controls"| PoolManager
    Governance -->|"controls"| ERC7540Vault

    Deployments --- InvestmentManager
    Testing --- PoolManager
    Audits --- Gateway
    Libraries --- TrancheToken

    click ERC7540Vault "https://github.com/centrifuge/liquidity-pools/tree/main/src/token"
    click TrancheToken "https://github.com/centrifuge/liquidity-pools/tree/main/src/token"
    click InvestmentManager "https://github.com/centrifuge/liquidity-pools/tree/main/src/factories"
    click Gateway "https://github.com/centrifuge/liquidity-pools/tree/main/src/gateway"
    click AdapterImpl "https://github.com/centrifuge/liquidity-pools/tree/main/src/gateway/adapters"
    click AdapterIntf "https://github.com/centrifuge/liquidity-pools/tree/main/src/interfaces/gateway/adapters"
    click Deployments "https://github.com/centrifuge/liquidity-pools/tree/main/deployments"
    click Testing "https://github.com/centrifuge/liquidity-pools/tree/main/test"
    click Audits "https://github.com/centrifuge/liquidity-pools/tree/main/audits"
    click Libraries "https://github.com/centrifuge/liquidity-pools/tree/main/lib"

    classDef vault fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef token fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef manager fill:#ccffcc,stroke:#00aa00,stroke-width:2px;
    classDef gateway fill:#ccffff,stroke:#00aaaa,stroke-width:2px;
    classDef adapter fill:#e0ccff,stroke:#aa00aa,stroke-width:2px;
    classDef escrow fill:#ffe0cc,stroke:#ff6600,stroke-width:2px;
    classDef external fill:#f0f0f0,stroke:#000000,stroke-width:2px;
    classDef infra fill:#d9d9d9,stroke:#808080,stroke-width:2px;
```
