# othentic-labs/core-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/othentic-labs/core-contracts
- Repository: https://github.com/othentic-labs/core-contracts

## Overview

##### Project type and purpose
– This is a Solidity-based “distributed systems” framework built with Foundry, targeting Ethereum-style Layer 1 (L1) and Layer 2 (L2) networks.
– Its purpose is to provide on‐chain governance (AvsGovernance on L1) and task/attestation coordination (AttestationCenter on L2), with cross‐chain messaging powered by LayerZero.

##### File structure
– Top-level:
- foundry.toml, remappings.txt – Foundry build/test config
- lib/ – Git submodules for dependencies (LayerZero, OpenZeppelin, eigenlayer, etc.)
- src/ – project contracts, subdivided into NetworkManagement and lz (LayerZero) packages
- audits/ – security reports
– Under src/:
- NetworkManagement/Common – shared interfaces/types
- NetworkManagement/L1 & L2 – on‐chain logic for each layer
- lz/ – LayerZero v1 & v2 abstraction, message handlers, utils, and interfaces

##### Key insights from README
– Package breakdown:
- L1: AvsGovernance + l1MessageHandler
- L2: AttestationCenter, OBLS, BN256G2 + l2MessageHandler
- lz: cross-chain messaging layer
– Contracts talk to each other only via LayerZero endpoints to overcome on-chain isolation

a. Main components
1. Layer 1 chain node and AvsGovernance (L1 smart contract)
2. L1MessageHandler (LayerZero endpoint on L1)
3. LayerZero Relayer / Endpoint (off-chain infrastructure)
4. Layer 2 chain node and AttestationCenter (L2 smart contract)
5. L2MessageHandler (LayerZero endpoint on L2)
6. Ancillary L2 contracts: OBLS, BN256G2
7. Shared on‐chain libraries (OpenZeppelin, Forge-std) shown as external dependencies

b. Relationships and interactions
- AvsGovernance ↔ L1MessageHandler (internal call)
- L1MessageHandler → LayerZero Endpoint → L2MessageHandler → AttestationCenter (cross‐chain message)
- AttestationCenter ↔ OBLS/BN256G2 (task validation & multisig)
- L2MessageHandler → LayerZero Endpoint → L1MessageHandler → AvsGovernance (return messages)

c. Architectural patterns and design principles
– Layered separation: governance vs. attestation
– Modular contracts with clear interfaces under Common/NetworkManagement
– Cross‐chain “adapter” pattern (message handlers) isolating protocol logic from messaging
– Use of industry-standard libs via git submodules

d. Technologies, frameworks, and libraries
– Foundry (forge) build/test
– Solidity (contracts under src/)
– LayerZero v1/v2 (in lib/LayerZero-v2) for messaging
– OpenZeppelin contracts (in lib/)
– EigenLayer, onchain-firewall, OBLS, BN256G2

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1
    subgraph "Layer 1 Chain" 
        direction TB
        L1Chain[(Ethereum L1)]:::l1
        AvsGovernance["AvsGovernance"]:::l1
        L1MessageHandler["L1MessageHandler"]:::l1
    end

    %% LayerZero Relayer
    Relayer((LayerZero Relayer/Endpoint)):::ext

    %% Layer 2
    subgraph "Layer 2 Chain"
        direction TB
        L2Chain[(Ethereum L2)]:::l2
        AttestationCenter["AttestationCenter"]:::l2
        OBLS["OBLS"]:::lib
        BN256G2["BN256G2"]:::lib
        L2MessageHandler["L2MessageHandler"]:::l2
    end

    %% Shared Interfaces
    subgraph "Shared NetworkManagement Interfaces"
        direction TB
        CommonInterfaces["Common Interfaces/Types"]:::ext
    end

    %% LayerZero On-Chain App Framework
    subgraph "LayerZero v2 On-Chain App"
        direction TB
        OAppCore["OApp Core Abstractions"]:::ext
        OAppInterfaces["OApp Interfaces"]:::ext
        OAppLibs["OApp Libs"]:::ext
    end

    %% LayerZero v1 Compatibility
    subgraph "LayerZero v1 Compatibility"
        direction TB
        V1AppBase["App Base"]:::ext
        V1Interfaces["V1 Interfaces"]:::ext
        V1Utils["V1 Utils"]:::ext
    end

    %% Connections L1 internal
    L1Chain --> AvsGovernance
    AvsGovernance -->|"internal call"| L1MessageHandler

    %% Cross-chain L1 to L2
    L1MessageHandler -->|"sendMessage(payload)"| Relayer
    Relayer -->|"deliverMessage"| L2MessageHandler
    L2MessageHandler -->|"receiveMessages"| AttestationCenter

    %% L2 internal
    AttestationCenter -->|"uses"| OBLS
    AttestationCenter -->|"uses"| BN256G2

    %% Cross-chain return
    AttestationCenter -->|"sendMessage(response)"| Relayer
    Relayer -->|"deliverMessage"| L1MessageHandler
    L1MessageHandler -->|"receiveMessages"| AvsGovernance

    %% Shared and libs connections
    AvsGovernance --> CommonInterfaces
    AttestationCenter --> CommonInterfaces
    L1MessageHandler --> V1AppBase
    V1AppBase --> V1Interfaces
    V1AppBase --> V1Utils
    L2MessageHandler --> OAppCore
    OAppCore --> OAppInterfaces
    OAppCore --> OAppLibs

    %% Styles
    classDef l1 fill:#cce5ff,stroke:#0056b3,color:#004085
    classDef l2 fill:#d4edda,stroke:#155724,color:#155724
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef lib fill:#f8d7da,stroke:#721c24,color:#721c24

    %% Click Events
    click AvsGovernance "https://github.com/othentic-labs/core-contracts/tree/main/src/NetworkManagement/L1"
    click L1MessageHandler "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/lzApp"
    click Relayer "https://github.com/othentic-labs/core-contracts/tree/main/lib/LayerZero-v2"
    click AttestationCenter "https://github.com/othentic-labs/core-contracts/tree/main/src/NetworkManagement/L2"
    click L2MessageHandler "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/v2/oapp"
    click OBLS "https://github.com/othentic-labs/core-contracts/tree/main/lib/eigenlayer-contracts"
    click BN256G2 "https://github.com/othentic-labs/core-contracts/tree/main/lib/eigenlayer-middleware"
    click CommonInterfaces "https://github.com/othentic-labs/core-contracts/tree/main/src/NetworkManagement/Common/interfaces"
    click OAppCore "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/v2/oapp"
    click OAppInterfaces "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/v2/oapp/interfaces"
    click OAppLibs "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/v2/oapp/libs"
    click V1AppBase "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/lzApp"
    click V1Interfaces "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/interfaces"
    click V1Utils "https://github.com/othentic-labs/core-contracts/tree/main/src/lz/util"
```
