# dlc-link/dlc-solidity architecture

> Architecture diagram of the GitHub repository dlc-link/dlc-solidity, 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/dlc-link/dlc-solidity
- Repository: https://github.com/dlc-link/dlc-solidity

## Overview

##### Project Type and Purpose
- The project is a smart contract repository for launching and managing DLCs along with the iBTC token. Its purpose is to enable conditional bitcoin transactions on EVM chains without a bridge by leveraging a trust‑minimized attestation layer.
- The README emphasizes DLCs, timelocked upgrades, and the integration with external data (like Chainlink oracles), making it clear that the architecture must capture both on-chain contracts and support workflows for deployment/testing.

##### Analyzing the File Structure
- Key directories include:
– “contracts”: contains the Solidity source code for the core smart contracts (including mocks).
– “deploymentFiles”: holds JSON files for contract deployment on multiple networks (e.g., arbitrum, avax, bsc, mainnet, etc.), indicating multi-network deployment capabilities.
– “scripts”: a rich set of JavaScript/node scripts for deployment, configuration, and administrative tasks (e.g., contract administration and migrations).
– “test”: unit tests for verifying contract behavior.
– “docker” and related files (e.g., docker-compose.yml, Dockerfile): containerization for easy development and deployment of hardhat nodes and services.
– “.github/workflows”: CI config files for testing and docker image builds.
- This structure is reflective of a modern smart contract project that supports full-cycle development, integration testing, continuous deployment, and multi-network configuration.

##### Major System Components
a. Smart Contracts Layer:
– Core contracts: DLC contracts (e.g., DLCBTC, DLCManager), iBTC token, TimelockController, TokenManager, and others.
– Upgradability via timelocked upgrade design, where a multisig (or attestor set) governs upgrades that are delayed by a set period.
b. Deployment & Configuration:
– “deploymentFiles” for each network (arbitrum, sepolia, mainnet, etc.) represent how the contracts are instantiated on different chains.
– Environment configuration via .env files and Hardhat configuration.
c. Developer and Operational Tools:
– “scripts” for managing contract roles, setups, and various admin tasks.
– “test” directory for automated testing.
– Dockerized development environment to standardize builds and tests.
– Continuous Integration workflows in “.github/workflows” automate tests and builds.
d. External Dependencies:
– Connection to oracles such as Chainlink (for off-chain data).
– Integration with external monitoring (audit reports in the “audits” directory).
– Timelock and multisig configurations to ensure safe upgrades and governance.

##### Relationships and Interactions
– DLCManager coordinating between contracts.
– The iBTC token being minted and burned as DLCs are initiated and settled.
– The TimelockController governing the upgrade process.
- Development cycle: Source code (contracts, scripts) → Testing (Hardhat tests, static analysis using Slither) → CI/CD (GitHub workflows) → Containerized builds (Docker) → Deployment (using deploymentFiles).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contracts Layer
    subgraph "Smart Contracts Layer"
        SC1["DLCManager"]:::contract
        SC2["DLCBTC"]:::contract
        SC3["IBTC Token"]:::contract
        SC4["TimelockController"]:::contract
        SC5["TokenManager"]:::contract
        Mocks["Mock Contracts"]:::contract
    end

    %% Deployment & Infrastructure Layer
    subgraph "Deployment & Infrastructure Layer"
        Dep["Deployment Files (Multi-Network)"]:::deployment
        Net1["Arbitrum"]:::deployment
        Net2["Mainnet"]:::deployment
        Net3["Avalanche (Avax)"]:::deployment
        Net4["BSC"]:::deployment
    end

    %% Developer & Operations Layer
    subgraph "Developer & Operations Layer"
        Scripts["Deployment & Admin Scripts"]:::developer
        Tests["Automated Testing"]:::developer
        DockerDev["Docker Environment"]:::developer
        CI["CI/CD Workflows"]:::developer
        Audits["Audit Reports"]:::developer
    end

    %% External Dependency
    Oracle["Chainlink Oracle"]:::external

    %% Relationships between layers and components
    %% Smart Contracts interactions
    SC1 -->|"manages"| SC2
    SC1 -->|"controls"| SC3
    SC1 -->|"upgrades via"| SC4
    SC1 -->|"utilizes"| SC5
    SC1 -->|"queries"| Oracle

    %% Deployment relationships
    Dep -->|"contains"| Net1
    Dep -->|"contains"| Net2
    Dep -->|"contains"| Net3
    Dep -->|"contains"| Net4
    SC1 -->|"deployed via"| Dep
    SC2 -->|"deployed via"| Dep
    SC3 -->|"deployed via"| Dep
    SC4 -->|"deployed via"| Dep
    SC5 -->|"deployed via"| Dep

    %% Developer & Operations interactions
    Scripts -->|"deploys/contracts"| Dep
    Scripts -->|"manages contracts"| SC1
    Tests -->|"verifies"| SC1
    Tests -->|"verifies"| SC2
    Tests -->|"verifies"| SC3
    Tests -->|"verifies"| SC4
    Tests -->|"verifies"| SC5
    CI -->|"runs"| Tests
    CI -->|"triggers"| Scripts
    DockerDev -->|"hosts local blockchain"| Tests
    Audits -->|"reviews"| SC1
    Audits -->|"reviews"| SC2
    Audits -->|"reviews"| SC3
    Audits -->|"reviews"| SC4
    Audits -->|"reviews"| SC5

    %% Click Events
    click SC1 "https://github.com/dlc-link/dlc-solidity/tree/dev/contracts"
    click Mocks "https://github.com/dlc-link/dlc-solidity/tree/dev/contracts/mocks"
    click Dep "https://github.com/dlc-link/dlc-solidity/tree/dev/deploymentFiles"
    click Net1 "https://github.com/dlc-link/dlc-solidity/tree/dev/deploymentFiles/arbitrum"
    click Net2 "https://github.com/dlc-link/dlc-solidity/tree/dev/deploymentFiles/mainnet"
    click Net3 "https://github.com/dlc-link/dlc-solidity/tree/dev/deploymentFiles/avax"
    click Net4 "https://github.com/dlc-link/dlc-solidity/tree/dev/deploymentFiles/bsc"
    click Scripts "https://github.com/dlc-link/dlc-solidity/tree/dev/scripts"
    click Tests "https://github.com/dlc-link/dlc-solidity/tree/dev/test"
    click DockerDev "https://github.com/dlc-link/dlc-solidity/tree/dev/docker"
    click CI "https://github.com/dlc-link/dlc-solidity/tree/dev/.github/workflows"
    click Audits "https://github.com/dlc-link/dlc-solidity/tree/dev/audits"

    %% Styles
    classDef contract fill:#FFCCCB,stroke:#FF0000,stroke-width:2px;
    classDef deployment fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef developer fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef external fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
```
