# layerzero-labs/layerzero-v1 architecture

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

- Interactive diagram: https://gitdiagram.com/layerzero-labs/layerzero-v1
- Repository: https://github.com/layerzero-labs/layerzero-v1

## Overview

##### Project type and purpose
- This is a blockchain-focused, backend-only repository implementing LayerZero Endpoints as a set of gas-efficient, non-upgradable smart contracts.
- Purpose: provide an Omnichain Interoperability Protocol for lightweight, authenticated, and guaranteed cross-chain message passing.

##### File structure
- Top-level folders:
- contracts/ – Solidity source organized by feature (chainlink integration, interfaces, mocks, proof utilities)
- constants/ – JSON configs for oracle addresses, job IDs, chain-specific parameters (Chainlink, Flux, endpoints)
- deploy/ – JavaScript scripts that deploy individual contracts to a network via Hardhat
- tasks/ – Hardhat task definitions for operations (deploy, configure, send, poll)
- scripts/ – Shell scripts automating multi-step workflows (deploy.sh, send.sh, poll.sh)
- utils/ – Helper modules for reading address files, network mappings, type definitions
- configuration files – hardhat.config.ts, tsconfig.json, .env.example, package.json

##### README for additional insights
- Describes key components (Endpoints), development commands, Hardhat usage, multi-network support, and how to add new chains.
- Emphasizes separation between local dev (“yarn dev”), testnets, and mainnet configurations.

##### Main components
a. Developer Machine & Tooling
- Hardhat (local node, task runner)
- Shell scripts & Hardhat tasks
- Environment files (.env)
b. Smart Contracts Layer
- Endpoint contracts (OmniCounter, UltraLightNode, Endpoint, Relayer, Treasury, etc.)
- Proof library utilities (contracts/proof)
- Interface contracts & mocks (for testing)
c. Configuration Layer
- constants/endpoints.json & chain-specific JSON files (oracle addresses, job IDs, signing keys)
- hardhat.config.ts (network URLs, chain IDs, staging map)
d. External Networks
- Local Hardhat network
- Ethereum testnets (Rinkeby, Goerli, Ropsten, sandbox)
- Production networks (Ethereum mainnet and any additional chains)
e. Oracle Integrations
- Chainlink nodes (oracle addresses, job IDs)
- Flux nodes (oracles.json)
- Oracle whitelister for permission control
f. External Services
- RPC providers (Infura, Alchemy, custom)
- Chainlink / Flux off-chain oracles

##### Relationships and data flows
- Developer invokes a deploy script or Hardhat task → Hardhat reads constants and configuration → connects to selected network RPC → deploys smart contracts.
- User or another contract sends a cross-chain message to an Endpoint → Endpoint emits message proof → UltraLightNode on target chain verifies proof → message delivered to destination contract (e.g., OmniCounter).
- Oracles feed external data or signatures into the system via configured Chainlink or Flux nodes → Relayer contract validates and forwards messages.

##### Architectural patterns and design principles
- Modular contract design: each contract has a single responsibility (e.g., Relayer, Treasury, Proof utilities).
- Configuration-driven deployment: constants folder drives behavior per environment.
- Hardhat tasks as an extensibility point for custom workflows.
- Separation of concerns between on-chain logic and off-chain scripts.

##### Final advice
- Layer distinctly but show how they interconnect.
- Do not overwhelm with every single file; group related contracts and configs.
- Flow of a message (deploy, send, verify, deliver) is prominently featured.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        HardhatNode["Hardhat (Local Node)"]:::tool
        HardhatTasks["Hardhat Tasks"]:::tool
        ShellScripts["Shell Scripts"]:::tool
        EnvFile[".env.example"]:::tool
        HardhatConfig["hardhat.config.ts"]:::tool
        PackageJSON["package.json"]:::tool
        TSConfig["tsconfig.json"]:::tool
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        Constants["Constants (JSON configs)"]:::db
        ChainlinkParams["constants/chainlink/"]:::db
        FluxOracles["constants/flux/"]:::db
        OracleWhitelist["constants/oracleWhitelister.json"]:::db
        FundingConfig["funding.json"]:::db
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Utils["utils/"]:::tool
        AddrMgmt["utils/getAddresses.js"]:::tool
        NetMap["utils/network.js"]:::tool
        FileReader["utils/readStatic.js"]:::tool
        UAConfigTypes["utils/uaConfigTypes.ts"]:::tool
    end

    %% Deployment Scripts
    subgraph "Deployment Scripts"
        direction TB
        DeployScripts["deploy/"]:::tool
        DeployOC["deploy/OmniCounter.js"]:::tool
        DeployULN["deploy/UltraLightNode.js"]:::tool
        DeployEP["deploy/Endpoint.js"]:::tool
        DeployRelayer["deploy/Relayer.js"]:::tool
        DeployTreasury["deploy/Treasury.js"]:::tool
        DeployMocks["deploy/LayerZeroOracleMock.js<br/>deploy/LayerZeroTokenMock.js<br/>deploy/MockLinkToken.js"]:::tool
    end

    %% Smart Contracts Layer
    subgraph "Smart Contracts Layer"
        direction TB
        Contracts["contracts/"]:::onchain
        ChainlinkContracts["contracts/chainlink/"]:::onchain
        InterfaceContracts["contracts/interfaces/"]:::onchain
        MockContracts["contracts/mocks/"]:::onchain
        ProofLib["contracts/proof/"]:::onchain
    end

    %% External Networks & Services
    subgraph "External Systems"
        direction TB
        LocalNet["Local Hardhat Network"]:::network
        Rinkeby["Rinkeby Testnet"]:::network
        Goerli["Goerli Testnet"]:::network
        Mainnet["Ethereum Mainnet"]:::network
        RPC["RPC Providers (Infura/Alchemy)"]:::external
        ChainlinkNode["Chainlink Oracles"]:::external
        FluxNode["Flux Oracles"]:::external
    end

    %% Flows and Relationships
    HardhatNode -->|runs tasks| HardhatTasks
    HardhatNode -->|executes| ShellScripts
    ShellScripts -->|invoke| DeployScripts
    HardhatTasks -->|invoke| DeployScripts
    DeployScripts -->|read| HardhatConfig
    DeployScripts -->|use| EnvFile
    DeployScripts -->|use| Constants
    DeployScripts -->|use| Utils
    DeployScripts -->|deploy to| LocalNet
    DeployScripts -->|deploy to| Rinkeby
    DeployScripts -->|deploy to| Goerli
    DeployScripts -->|deploy to| Mainnet

    DeployScripts --> DeployOC
    DeployScripts --> DeployULN
    DeployScripts --> DeployEP
    DeployScripts --> DeployRelayer
    DeployScripts --> DeployTreasury
    DeployScripts --> DeployMocks

    DeployOC -->|deploys| Contracts
    DeployULN -->|deploys| Contracts
    DeployEP -->|deploys| Contracts
    DeployRelayer -->|deploys| Contracts
    DeployTreasury -->|deploys| Contracts
    DeployMocks -->|deploys| Contracts

    Contracts --> ChainlinkContracts
    Contracts --> InterfaceContracts
    Contracts --> MockContracts
    Contracts --> ProofLib

    %% Oracle Data Flow
    ChainlinkNode -.->|feeds data| DeployRelayer
    FluxNode -.->|feeds data| DeployRelayer
    ChainlinkNode -.->|feeds data| ProofLib
    FluxNode -.->|feeds data| ProofLib

    %% Click Events
    click HardhatConfig "https://github.com/layerzero-labs/layerzero-v1/blob/main/hardhat.config.ts"
    click EnvFile "https://github.com/layerzero-labs/layerzero-v1/blob/main/.env.example"
    click ShellScripts "https://github.com/layerzero-labs/layerzero-v1/tree/main/scripts/"
    click HardhatTasks "https://github.com/layerzero-labs/layerzero-v1/tree/main/tasks/"
    click Contracts "https://github.com/layerzero-labs/layerzero-v1/tree/main/contracts/"
    click ChainlinkContracts "https://github.com/layerzero-labs/layerzero-v1/tree/main/contracts/chainlink/"
    click InterfaceContracts "https://github.com/layerzero-labs/layerzero-v1/tree/main/contracts/interfaces/"
    click MockContracts "https://github.com/layerzero-labs/layerzero-v1/tree/main/contracts/mocks/"
    click ProofLib "https://github.com/layerzero-labs/layerzero-v1/tree/main/contracts/proof/"
    click DeployScripts "https://github.com/layerzero-labs/layerzero-v1/tree/main/deploy/"
    click DeployOC "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/OmniCounter.js"
    click DeployULN "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/UltraLightNode.js"
    click DeployEP "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/Endpoint.js"
    click DeployRelayer "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/Relayer.js"
    click DeployTreasury "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/Treasury.js"
    click DeployMocks "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/LayerZeroOracleMock.js"
    click DeployMocks "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/LayerZeroTokenMock.js"
    click DeployMocks "https://github.com/layerzero-labs/layerzero-v1/blob/main/deploy/MockLinkToken.js"
    click Constants "https://github.com/layerzero-labs/layerzero-v1/tree/main/constants/"
    click ChainlinkParams "https://github.com/layerzero-labs/layerzero-v1/tree/main/constants/chainlink/"
    click FluxOracles "https://github.com/layerzero-labs/layerzero-v1/tree/main/constants/flux/"
    click OracleWhitelist "https://github.com/layerzero-labs/layerzero-v1/blob/main/constants/oracleWhitelister.json"
    click Utils "https://github.com/layerzero-labs/layerzero-v1/tree/main/utils/"
    click AddrMgmt "https://github.com/layerzero-labs/layerzero-v1/blob/main/utils/getAddresses.js"
    click NetMap "https://github.com/layerzero-labs/layerzero-v1/blob/main/utils/network.js"
    click FileReader "https://github.com/layerzero-labs/layerzero-v1/blob/main/utils/readStatic.js"
    click UAConfigTypes "https://github.com/layerzero-labs/layerzero-v1/blob/main/utils/uaConfigTypes.ts"
    click FundingConfig "https://github.com/layerzero-labs/layerzero-v1/blob/main/funding.json"
    click PackageJSON "https://github.com/layerzero-labs/layerzero-v1/blob/main/package.json"
    click TSConfig "https://github.com/layerzero-labs/layerzero-v1/blob/main/tsconfig.json"

    %% Styles
    classDef tool fill:#e3f2fd,stroke:#42a5f5,color:#0d47a1;
    classDef onchain fill:#e8f5e9,stroke:#66bb6a,color:#1b5e20;
    classDef db fill:#fff3e0,stroke:#ffa726,color:#e65100;
    classDef external fill:#ffebee,stroke:#ef5350,color:#b71c1c;
    classDef network fill:#ede7f6,stroke:#ab47bc,color:#4a148c;
```
