# lifinance/contracts architecture

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

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

## Overview

##### Project Type & Purpose
- This repository is dedicated to smart contracts using the EIP-2535 diamond standard. It is designed as a modular, multi-faceted contract system that aggregates bridging and DEX functionality for multi-chain asset swaps.
- The README makes it clear that LI.FI’s solution involves dynamic routing through different facets (e.g., HopFacet, StargateFacet, etc.) and helper facets (DiamondCutFacet, OwnershipFacet, etc.) to manage cross-chain bridging and token swapping operations.

##### Main Components
a. Core Contract (LiFiDiamond):
b. Business Logic Facets:
– Create separate nodes for each key facet (for example, HopFacet, AnySwapFacet, CBridgeFacet, HyphenFacet, StargateFacet) that the Diamond delegates to.
– Indicate that these facets handle the actual transaction logic for cross-chain swaps and bridge operations.
c. Diamond Helper Contracts:
– Include a separate group for helper facets such as DiamondCutFacet, DiamondLoupeFacet, OwnershipFacet, and WithdrawFacet. These are responsible for upgrades, introspection, ownership, and fund management.
d. Off-Chain & Auxiliary Components:
– Represent the deployment scripts (found under "deploy" and "script/deploy"), which show how facets and contracts are deployed and managed.
– Include a component for “Configuration & Auditing” (directories: config, audit) that influences runtime behavior and security assessments.
– Optionally, show the testing environment (test, foundry integration in README) as part of the continuous integration/continuous deployment (CI/CD) pipeline, reflected by the extensive GitHub workflows.
– Add an “External Services” node that symbolizes the external bridges or protocols (e.g., Hop Protocol) that interact with facets via DELEGATECALL.

##### Relationships & Interactions
- Facets by purpose: one cluster for transaction flows (bridges and DEX integrations) and another cluster for management operations (upgrades, look-ups, security).
- That external calls (user transactions) go to the LiFiDiamond contract which then routes the request to the appropriate facet(s).
- In the “off-chain” area, link the deployment and configuration scripts to the corresponding on-chain components, showing audit and testing pipelines that ensure the contracts’ integrity.

##### Architectural Patterns & Technologies
- Clearly label that the system adheres to the EIP-2535 (diamond standard) which enables modularity and upgradeability.
- Use of DELEGATECALL for routing calls to various facets.
- Separation of concerns: business logic vs. helper and management functionalities.
- That much of the configuration and deployment is automated via scripts (e.g., Foundry/Forge based tests and extensive GitHub workflows).

## Diagram (Mermaid)

```mermaid
graph TD
    %% On-Chain Components
    subgraph "On-Chain Components"
        LiFiDiamond["LiFiDiamond Contract"]:::core
        subgraph "Business Logic Facets"
            HopFacet["HopFacet"]:::business
            AnySwapFacet["AnySwapFacet"]:::business
            CBridgeFacet["CBridgeFacet"]:::business
            HyphenFacet["HyphenFacet"]:::business
            StargateFacet["StargateFacet"]:::business
        end
        subgraph "Helper Facets"
            DiamondCutFacet["DiamondCutFacet"]:::helper
            DiamondLoupeFacet["DiamondLoupeFacet"]:::helper
            OwnershipFacet["OwnershipFacet"]:::helper
            WithdrawFacet["WithdrawFacet"]:::helper
        end
    end

    %% Off-Chain & Auxiliary Components
    subgraph "Off-Chain Processes"
        DeploymentScripts["Deployment Scripts"]:::offchain
        ConfigAuditing["Configuration & Auditing"]:::offchain
        TestingCiCd["Testing & CI/CD"]:::offchain
        ExternalServices["External Services"]:::offchain
    end

    %% On-chain delegation relationships (DELEGATECALL)
    LiFiDiamond -->|"DELEGATECALL"| HopFacet
    LiFiDiamond -->|"DELEGATECALL"| AnySwapFacet
    LiFiDiamond -->|"DELEGATECALL"| CBridgeFacet
    LiFiDiamond -->|"DELEGATECALL"| HyphenFacet
    LiFiDiamond -->|"DELEGATECALL"| StargateFacet

    LiFiDiamond -->|"DELEGATECALL"| DiamondCutFacet
    LiFiDiamond -->|"DELEGATECALL"| DiamondLoupeFacet
    LiFiDiamond -->|"DELEGATECALL"| OwnershipFacet
    LiFiDiamond -->|"DELEGATECALL"| WithdrawFacet

    %% Off-chain interactions
    DeploymentScripts -->|"deploys"| LiFiDiamond
    DeploymentScripts -->|"deploys"| HopFacet
    DeploymentScripts -->|"deploys"| DiamondCutFacet

    ConfigAuditing -->|"configures"| LiFiDiamond
    ConfigAuditing -->|"audits"| DeploymentScripts

    TestingCiCd -->|"tests"| LiFiDiamond

    ExternalServices -->|"interacts"| HopFacet
    ExternalServices -->|"interacts"| StargateFacet

    %% Click Events
    click LiFiDiamond "https://github.com/lifinance/contracts/blob/main/deployments/abstract.diamond.json"
    click HopFacet "https://github.com/lifinance/contracts/tree/main/src/Facets"
    click AnySwapFacet "https://github.com/lifinance/contracts/tree/main/src/Facets"
    click CBridgeFacet "https://github.com/lifinance/contracts/tree/main/src/Facets"
    click HyphenFacet "https://github.com/lifinance/contracts/tree/main/src/Facets"
    click StargateFacet "https://github.com/lifinance/contracts/tree/main/src/Facets"
    click DiamondCutFacet "https://github.com/lifinance/contracts/blob/main/docs/DiamondCutFacet.md"
    click DiamondLoupeFacet "https://github.com/lifinance/contracts/blob/main/docs/DiamondLoupeFacet.md"
    click WithdrawFacet "https://github.com/lifinance/contracts/blob/main/docs/WithdrawFacet.md"
    click DeploymentScripts "https://github.com/lifinance/contracts/tree/main/script/deploy"
    click ConfigAuditing "https://github.com/lifinance/contracts/tree/main/config"
    click TestingCiCd "https://github.com/lifinance/contracts/tree/main/.github/workflows"
    click ExternalServices "https://github.com/lifinance/contracts/tree/main/script/demoScripts"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef business fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef helper fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef offchain fill:#fff3cd,stroke:#333,stroke-width:2px;
```
