# archethic-foundation/bridge-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/archethic-foundation/bridge-contracts
- Repository: https://github.com/archethic-foundation/bridge-contracts

## Overview

##### Main Components
- EVM Smart Contracts & Ecosystem:
– Contains contracts for HTLC (both signed and chargeable) and liquidity pool mechanisms.
– Includes deployment scripts (in directories like evm/contracts, evm/scripts, evm/test) and configuration files (e.g., hardhat.config.js, .openzeppelin directory).
- Archethic Smart Contracts & Ecosystem:
– Contains similar smart contracts (HTLC, pool, factory contracts) and CLI commands (in directories such as archethic/commands, archethic/contracts, archethic/config.js, and the bridge.js script).
– Provides functions for deploying pools, provisioning HTLCs, and managing secret disclosures.
- Analytics Module:
– The analytics directory includes scripts that collect and process swap-related data from deployed HTLC contracts.
– It also provides views (like the Jade template in analytics/src/views) and controllers for metrics.
- Supporting Infrastructure and Guides:
– Documentation/guides that explain transaction flows and interoperability between EVM and Archethic chains.
– The wormhole_ntt_manager appears to be an additional module that might relate to cross-chain management or further integration.

##### Relationships and Interactions
- Data and Command Flows:
– Users interact with CLI tools (bridge.js) to deploy, update, or manage contracts on either chain.
– The EVM part uses Hardhat to compile, test, deploy smart contracts which then interact with the Archethic side via defined interfaces (e.g., factory functions and HTLC provisioning).
– Analytics scripts interact with deployed contracts to extract and update swap statistics.
- Interaction Between Components:
– The bridge relies on a contract factory on Archethic to generate HTLC code (via functions like get_chargeable_htlc and get_signed_htlc).
– Once deployed, HTLC contracts on both EVM and Archethic interact via secret revealing or provisioning mechanisms that are critical for atomic swaps.
- Architectural Patterns and Design Principles:
– A layered approach is evident (smart contracts at the blockchain layer, CLI and command scripts in an application layer, and analytics for monitoring).
– Modular separation: the file tree shows distinct directories for analytics, archethic, and evm, promoting separation of concerns.
– Use of CLI commands and configuration files (bridge.js, config.js, ecosystem configuration) for operational management.

##### Relevant Technologies
- Node.js is the runtime environment for JavaScript-based scripts.
- Hardhat is used for EVM development.
- The use of JSON configuration files for network settings (e.g., the .openzeppelin files, config files in analytics/config).
- Smart contract languages (likely Solidity for EVM and Elixir for Archethic contracts, judging by file conventions like .exs).
- Jade templating for analytics views (indicating a server-side rendered HTML component for metrics).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "EVM Environment"
        A1["HTLC Contracts"]:::contract
        A2["Pool Contracts"]:::contract
        A3["Deployment Scripts"]:::cli
        A4["Testing Suite"]:::test
        A5["Configuration (hardhat & .openzeppelin)"]:::config
    end

    subgraph "Archethic Environment"
        B1["Archethic Contracts & Factory"]:::contract
        B2["CLI & Deployment (bridge.js & commands)"]:::cli
        B3["Configuration (config.js)"]:::config
    end

    subgraph "Analytics Module"
        C1["Swap Analytics Controllers/Crons"]:::analytics
        C2["HTLC Registry & Metrics"]:::analytics
        C3["Views (Jade Templates)"]:::views
        C4["Analytics Configuration"]:::config
    end

    subgraph "Supporting Infrastructure"
        D1["Guides & Documentation"]:::doc
        D2["Wormhole NTT Manager"]:::manager
    end

    %% Interactions between components
    A3 -->|"deploy_contracts"| B2
    A1 -->|"provision_htlc"| B1
    B1 -->|"secret_revelation"| A1
    A1 -->|"data_for_analytics"| C2
    B1 -->|"data_for_analytics"| C2
    C2 -->|"metrics_update"| C1
    C3 -->|"render_views"| C1
    D1 -->|"guidance"| A3
    D1 -->|"guidance"| B2
    D2 -->|"cross_chain_management"| B1

    %% Click Events
    click A1 "https://github.com/archethic-foundation/bridge-contracts/tree/main/evm/contracts"
    click A3 "https://github.com/archethic-foundation/bridge-contracts/tree/main/evm/scripts"
    click A4 "https://github.com/archethic-foundation/bridge-contracts/tree/main/evm/test"
    click A5 "https://github.com/archethic-foundation/bridge-contracts/blob/main/evm/hardhat.config.js"
    click B1 "https://github.com/archethic-foundation/bridge-contracts/tree/main/archethic/contracts"
    click B2 "https://github.com/archethic-foundation/bridge-contracts/blob/main/archethic/bridge.js"
    click B3 "https://github.com/archethic-foundation/bridge-contracts/blob/main/archethic/config.js"
    click C1 "https://github.com/archethic-foundation/bridge-contracts/tree/main/analytics/src/crons"
    click C2 "https://github.com/archethic-foundation/bridge-contracts/tree/main/analytics/src/registry"
    click C3 "https://github.com/archethic-foundation/bridge-contracts/tree/main/analytics/src/views"
    click C4 "https://github.com/archethic-foundation/bridge-contracts/tree/main/analytics/config"
    click D1 "https://github.com/archethic-foundation/bridge-contracts/tree/main/guides/"
    click D2 "https://github.com/archethic-foundation/bridge-contracts/tree/main/wormhole_ntt_manager/"

    %% Styles
    classDef contract fill:#E6E6FA,stroke:#4B0082,stroke-width:2px;
    classDef cli fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef test fill:#98FB98,stroke:#008000,stroke-width:2px;
    classDef config fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px;
    classDef analytics fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px;
    classDef views fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef doc fill:#FFF5EE,stroke:#CD853F,stroke-width:2px;
    classDef manager fill:#E0FFFF,stroke:#008B8B,stroke-width:2px;
```
